From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 noao/obsutil/src/doc/sptime.hlp | 1218 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 1218 insertions(+)
 create mode 100644 noao/obsutil/src/doc/sptime.hlp

(limited to 'noao/obsutil/src/doc/sptime.hlp')

diff --git a/noao/obsutil/src/doc/sptime.hlp b/noao/obsutil/src/doc/sptime.hlp
new file mode 100644
index 00000000..a2c0f242
--- /dev/null
+++ b/noao/obsutil/src/doc/sptime.hlp
@@ -0,0 +1,1218 @@
+.help sptime Nov01 noao.obsutil
+.ih
+NAME
+sptime -- spectroscopic exposure time calculator
+.ih
+USAGE
+sptime
+.ih
+PARAMETERS
+The parameters in this task have certain common features.
+.ls (1)
+All parameters, except \fIspectrograph\fR and \fIsearch\fR, may be
+specified as spectrograph table parameters of the same name.  Some
+parameters may also be specified in other tables.  The tables in which the
+paramters may be specified are shown in brackets.  Table values are used
+only if a string parameter is "" or a numeric parameter is INDEF.
+Therefore parameter set values override values in the tables.  To override
+a table specified in the spectrograph file by no file the special value
+"none" is used.  This task also uses default values, shown below in
+parenthesis, for parameters that have no value specified either in the
+parameter set or in a table.
+.le
+.ls (2)
+Parameters that specify a table take the value of a file or a numeric
+constant.  A constant is like a table with the same values for all value
+of the independent variable(s).
+.le
+.ls (3)
+Tables which are specified as filenames are sought first in the current
+working directory, then in one of the directories given by the
+\fIsearch\fR parameter, and finally in the package library directory
+sptimelib$.
+.le
+
+
+.ls time = INDEF (INDEF) [spectrograph]
+Total exposure time in seconds.  This time may be divided into shorter
+individual exposure times as defined by the \fImaxexp\fR parameter.  If
+the value is INDEF then the exposure time needed to achieve the
+signal-to-noise per pixel specified by the \fIsn\fR parameter is computed.
+.le
+.ls sn = 25. (25.) [spectrograph]
+Desired signal-to-noise per pixel at the central wavelength if the
+exposure \fItime\fR parameter is not specified.
+.le
+
+
+The following parameters define the source and sky/atmosphere background
+spectra.
+.ls spectrum = "blackbody"
+Source spectrum.  This may be a table or one of the following  special words:
+.ls blackbody
+Blackbody spectrum with temperature given by the \fItemperature\fR
+parameter.
+.le
+.ls flambda_power
+Power law in f(lambda) with index given by the \fIindex\fR parameter;
+f(lambda) proportional to lambda^(index).
+.le
+.ls fnu_power
+Power law in f(nu) with index given by the \fIindex\fR parameter;
+f(nu) proportional to nu^(index).
+.le
+
+The table is a two column text file of wavelength in Angstroms and flux in
+ergs/s/cm^2/A.
+.le
+.ls spectitle = "" [spectrum|spectrograph]
+Spectrum title.
+.le
+.ls E = 0. (0.) [spectrum|spectrograph]
+The E(B-V) color excess to apply a reddening to the source spectrum.  The
+reddening maintains the same table or reference flux at the reference
+wavelength.  A value of zero corresponds to no reddening.
+.le
+.ls R = 3.1 (3.1) [spectrum|spectrograph]
+The R(V) = A(V)/E(B-V) for the extinction law.  The extinction law is that
+of Cardelli, Clayton, and Mathis, \fBApJ 345:245\fR, 1989.  The default
+R(V) is typical of the interstellar medium.
+.le
+.ls sky = "" ("none") [spectrograph]
+Sky or background table.  The table is a two or three column text file
+consisting of wavelength in Angstroms, optional moon phase between 0 (new
+moon) and 14 (full moon), and flux in ergs/s/cm^2/A/arcsec^2.
+.le
+.ls skytitle = "" [sky|spectrograph]
+Sky title.
+.le
+.ls extinction = "" ("none") [spectrograph]
+Extinction table.  The table is a two column text file consisting of
+wavelength in Angstroms and extinction in magnitudes per airmass.
+.le
+.ls exttitle = "" [spectrograph]
+Extinction title.
+.le
+
+
+The following parameters are used with the source spectrum is specified
+by the special functions.
+.ls refwave = INDEF (INDEF) [spectrum|spectrograph]
+Reference wavelength, in units given by the \fIunits\fR parameter, defining
+the flux of the source.  This is also used as the wavelength where
+reddening does not change the spectrum flux.  A value of INDEF uses the
+observation central wavelength.
+.le
+.ls refflux = 10. (10.) [spectrograph]
+Reference source flux or magnitude at the reference wavelength for the
+model spectral distributions.  The units are specified by the funits parameter.
+.le
+.ls funits = "AB" ("AB") [spectrograph]
+Flux units for the reference flux.  The values are "AB" for monochromatic
+magnitude, "F_lambda" for ergs/s/cm^2/A, "F_nu" for ergs/s/cm^2/Hz,
+and standard bandpasses of U, B, V, R, I, J, H, Ks, K, L, L' and M.
+.le
+.ls temperature = 6000. (6000.) [spectrograph]
+Blackbody temperature for a blackbody source spectrum in degrees Kelvin.
+.le
+.ls index = 0. (0.) [spectrograph]
+Power law index for the power law source spectrum.
+.le
+
+
+The following parameters are observational parameters describing either
+the observing conditions or spectrograph setup.
+.ls seeing = 1. (1.) [spectrograph]
+The full width at half maximum (FWHM) of a point source in arc seconds.
+.le
+.ls airmass = 1. (1.) [spectrograph]
+The airmass of the observation.  This is only used if an extinction table
+is specified.
+.le
+.ls phase = 0. (0.) [spectrograph]
+The moon phase running from 0 for new moon to 14 for full moon.  This is
+used if the sky spectrum is given as a function of the moon phase.
+.le
+.ls thermal = 0. (0.) [telescope|spectrograph]
+Temperature in degress Kelvin for the thermal background of the telescope
+and spectrograph.  If greater than zero a blackbody surface brightness
+background is computed and multiplied by an emissivity specified by
+the \fIemissivity\fR table.
+.le
+.ls wave = INDEF (INDEF) [spectrograph]
+Central wavelength of observation in units given by the \fIunits\fR
+parameter.  If the value is INDEF it is determined from the efficiency peak
+of the disperser.
+.le
+.ls order = INDEF (INDEF) [spectrograph]
+Order for grating or grism dispersers.  If the value is INDEF it is
+determined from the order nearest the desired central wavelength.  If both
+the order and central wavelength are undefined the first order is used.
+.le
+.ls xorder = INDEF (INDEF) [spectrograph]
+Order for grating or grism cross dispersers.  If the value is INDEF it
+is determined from the order nearest the desired central wavelength.  If
+both the order and central wavelength are undefined the first order is
+used.
+.le
+.ls width = INDEF (-2.) [aperture|spectrograph]
+The aperture width (dispersion direction) for rectangular apertures
+such as slits.  Values may be positive to specify in arc seconds or
+negative to specify in projected pixels on the detector.
+.le
+.ls length = INDEF (-100.) [aperture|spectrograph]
+The aperture length (cross dispersion direction) for rectangular
+apertures such as slits.  Values may be positive to specify in arc seconds
+or negative to specify in projected pixels on the detector.
+.le
+.ls diameter = INDEF (-2.) [fiber|aperture|spectrograph]
+The aperture diameter for circular apertures.  Values
+may be positive to specify in arc seconds or negative to specify in
+projected pixels on the detector.  If it is found in the fiber table,
+positive values are treated as mm at the focal plane instead of arc seconds.
+.le
+.ls xbin = 1 (1) [detector|spectrograph]
+Detector binning along the dispersion direction.
+.le
+.ls ybin = 1 (1) [detector|spectrograph]
+Detector binning along the spatial direction.
+.le
+
+
+The following parameters a miscellaneous parameters for the task.
+.ls search = "spectimedb$"
+List of directories to search for the various table files.  The current
+direction is always searched first and the directory sptimelib$ is searched
+last so it is not necessary to include these directories.  The list may be
+a comma delimited list of directories, an @file, or a template.
+.le
+.ls minexp = 0.01 (0.01) [spectrograph]
+Minimumm time in seconds per individual exposure time.  This only applies
+when \fItime\fR is INDEF.  Adjustment of the exposure time for saturation
+will not allow the exposure time to fall below this value.
+.le
+.ls maxexp = 3600. (3600.) [spectrograph]
+Maximum time in seconds per individual exposure.  The minimum exposure time
+has precedence over this value.  If the total exposure time exceeds this
+amount by more than 1% then the total exposure time will be divided up into
+the fewest individual exposures with equal exposure time that are less than
+this amount.  Note that by making the minimum and maximum times the same a
+fixed integration time can be defined.
+.le
+.ls units = "Angstroms" ("Angstroms") [spectrograph]
+Dispersion units for input and output dispersion coordinates.  The
+units syntax is described in the UNITS section.  The most common units
+are "Angstroms", "nm", "micron", and "wn".  Note that this does not
+apply to the dispersion units in the tables which are always in Angstroms.
+.le
+.ls skysub = "" (default based on context) [spectrograph]
+Type of sky and background subtraction.  The values are "none" for no
+background subtraction, "longslit" for subtraction using pixels in the
+aperture, "multiap" for background determined from a number of other
+apertures, and "shuffle" for shuffled observations.  The multiap case is
+typical for fiber spectrographs.  For shuffle the duty cycle is 50% and the
+exposure times are the sum of both sky and object.  If no sky or thermal
+background is specified then the default is "none".  If a fiber table or
+circular aperture is specified the default is "multiap" otherwise the
+default is "longslit".
+.le
+.ls nskyaps = 10  (10) [spectrograph]
+Number of sky apertures when using "multiap" sky subtraction.
+.le
+.ls subpixels = 1 (1) [spectrograph]
+Number of subpixels within each computed pixel.
+The dispersion pixel width is divided into this number of equal
+width subpixels.  The flux at the dispersions represented by the subpixels
+are computed and then summed to form the full pixel flux.  This option is used
+when there is structure in the tables, such as the sky and filter tables to
+simulate instrumental masking of sky lines, which is finer than a pixel
+dispersion width.
+.le
+.ls sensfunc = "" [spectrograph]
+Sensitivity function table.  This is a two column text file consisting
+of wavelength in Angstroms and sensitivity defined as
+2.5*(log(countrate)-log(flambda)),
+where countrate is the count rate (without extinction) in counts/s/A
+and flambda is the source flux in ergs/s/cm^2/A.  This table is used
+to compute an efficiency correction given a measurement of the
+sensitivity function from standard stars for the instrument.
+.le
+
+
+The following parameters control the output of the task.  The task
+always prints a result page at the central wavelength but additional
+graphical and text output may be produced at a set of equally spaced
+points across the size of the detector.
+.ls output = "object" ("") [spectrograph]
+List of quantities to output as graphs and/or in a text file.  These are
+given as a function of dispersion (as specified by units parameters)
+sampled across the dispersion coverage of the detector.  The choices are:
+.ls counts
+Object and background counts per individual exposure.
+.le
+.ls snr
+Signal-to-noise ratio per pixel per individual exposure.
+.le
+.ls object
+Object counts per individual exposure.  This includes contribution
+from other orders if there is no cross dispersion and the blocking
+filters do not completely exclude other orders.
+.le
+.ls rate
+Photons/second/A per individual exposure for the object and background.
+.le
+.ls atmosphere
+Percent transmission of the atmosphere.
+.le
+.ls telescope
+Percent transmission of the telescope.
+.le
+.ls adc
+Percent transmission of the ADC if one is used.
+.le
+.ls aperture
+Percent transmission of the aperture.
+.le
+.ls fiber
+Percent transmission of the fiber if one is used.
+.le
+.ls filter
+Percent transmission of the first filter if one is used.
+.le
+.ls filter2
+Percent transmission of the second filter if one is used.
+.le
+.ls collimator
+Percent transmission of the collimator.
+.le
+.ls disperser
+Percent efficiency of the disperser.
+.le
+.ls xdisperser
+Percent efficiency of the cross disperser if one is used.
+.le
+.ls corrector
+Percent transmission of the corrector if one is used.
+.le
+.ls camera
+Percent transmission of the camera.
+.le
+.ls detector
+Percent DQE of the detector.
+.le
+.ls spectrograph
+Percent transmission of the spectrograph if a transmission
+function is defined.
+.le
+.ls emissivity
+Emissivity of the telescope/spectrograph if an emissivity function
+is defined.
+.le
+.ls thruput
+Percent system thruput from telescope to detected photons.
+.le
+.ls sensfunc
+Sensitivity function values given as 2.5*(log(countrate)-log(flambda)),
+where countrate is the count rate (without extinction) in counts/s/A
+and flambda is the source flux in ergs/s/cm^2/A.
+.le
+.ls correction
+Multiplicative correction factor needed to convert the computed
+count rate to that given by an input sensitivity function.
+.le
+.ls ALL  
+All of the above.
+.le
+.le
+.ls nw = 101 (101) [spectrograph]
+Number of dispersion points to use in the output graphs and text
+file.  Note that this is generally less than the number of pixels in
+the detector for execution speed.
+.le
+.ls list = "" [spectrograph]
+Filename for list output of the selected quantities.  The output
+will be appended if the file already exists.
+.le
+.ls graphics = "stdgraph" ("stdgraph") [spectrograph]
+Graphics output device for graphs of the output quantities.
+.le
+.ls interactive = "yes" ("yes") [spectrograph]
+Interactive pause after each graph?  If "yes" then cursor input is
+enabled after each graph otherwise all the graphs will be drawn without
+pause.  When viewing the graphs interactively this should be "yes" otherwise
+the graphs will flash by rapidly leaving the last graph on the screen.
+When outputing only one graph or when redirecting the graphs to a
+printer or file then setting this parameter to "no" is suggested.
+.le
+
+The last parameter is a "parameter set" ("pset") containing all the
+spectrograph parameters.
+.ls specpars = ""
+Spectrograph parameter set.  If "" then the default pset \fBspecpars\fR
+is used otherwise the named pset is used.
+.le
+
+
+
+SPECPARS PARAMETERS
+.ls spectrograph = ""
+Spectrograph efficiency table.  This text file may contain parameters and an
+efficiency table.  The table consists of two columns containing
+wavelengths and efficiencies.  The efficiencies are for all elements
+which are not accounted for by other tables.
+.le
+.ls title = "" [spectrograph]
+Title for the spectrograph.
+.le
+.ls apmagdisp = INDEF (1.), apmagxdisp = INDEF (1.) [spectrograph]
+Magnification between the entrance aperture and the detector along and
+across the dispersion direction.  This describes any magnification (or
+demagnification) in the spectrograph other than that produced by the ratio
+of the collimator and camera focal lengths and anamorphic magnification
+from the disperser.  The may consist of actual magnification optics or
+projection effects such as tilted aperture plates (when the aperture size
+is specified in the untilted plate).
+.le
+.ls inoutangle = INDEF (INDEF) [spectrograph]
+Incident to diffracted grating angle in degrees for grating dispersers.
+For typical spectrographs which are not cross dispersed this is the
+collimator to camera angle.  If the value is INDEF derived from the grating
+parameters.
+.le
+.ls xinoutangle = INDEF (INDEF) [spectrograph]
+Incident to diffracted grating angle in degrees for grating cross
+dispersers.  If the value is INDEF it is derived from the grating
+parameters.
+.le
+
+
+.ls telescope = "" [spectrograph]
+Telescope efficiency table as a function of wavelength.  
+.le
+.ls teltitle = "" [telescope|spectrograph]
+Telescope title.
+.le
+.ls area = INDEF (1.) [telescope|spectrograph]
+Effective collecting area of the telescope in m^2.  The effective area
+includes reductions in the primary area due to obstructions.
+.le
+.ls scale = INDEF (10.) [telescope|spectrograph]
+Telescope plate scale, in arcsec/mm, at the entrance aperture of the
+spectrograph.
+.le
+.ls emissivity = "" [telescope|spectrograph]
+Emissivity table.  The emissivity is for all elements in the telescope
+and spectrograph.  If an emissivity is specified and an the \fIthermal\fR
+temperature parameter is greater than zero then a thermal background
+is added to the calculation.
+.le
+.ls emistitle = "" [emissivity|spectrograph]
+Title for the emissivity table used.
+.le
+
+
+.ls corrector = "" [spectrograph]
+Efficiency table for one or more correctors.
+.le
+.ls cortitle = "" [corrector|spectrograph]
+Title for corrector table used.
+.le
+.ls adc = "" [spectrograph]
+Efficiency table for atmospheric dispersion compensator.
+.le
+.ls adctitle = "" [adc|spectrograph]
+Title for ADC table used.
+.le
+
+
+.ls disperser = "" [spectrograph]
+Disperser table.  If this file contains an efficiency table it applies
+only to first order.  An alternate first order table and tables for
+other orders are given by table parameters "effN", where N is the order.
+.le
+.ls disptitle = "" [disperser|spectrograph]
+Title for disperser.
+.le
+.ls disptype = "" ("grating") [disperser|spectrograph]
+Type of disperser element.  The chocies are "grating", "grism", or "generic".
+The generic setting will simply use the desired central wavelength and
+dispersion without a grating or grism model.  One effect of this is that
+the mapping between detector pixel and wavelength is linear; i.e. a constant
+dispersion per pixel.
+.le
+.ls gmm = INDEF (300.) [disperser|spectrograph]
+Ruling in lines per mm.  If not specified it will be derived from the
+other disperser parameters.  If there is not enough information to
+derive the ruling then an ultimate default of 300 lines/mm is used.
+.le
+.ls blaze = INDEF (6.) [disperser|spectrograph]
+Blaze (grating) or prism (grism) angle in degrees.  If not specified it
+will be derived from the other disperser parameters.  If there is not
+enough information to derive the angle then an ultimate default of 6
+degrees is used.
+.le
+.ls oref = INDEF (1) [disperser|spectrograph]
+When a central (blaze) wavelength is specified this parameter indicates
+which order it is for.
+.le
+.ls wavelength = INDEF (INDEF) [disperser|spectrograph]
+Central (blaze) wavelength in Angstroms for the reference order.  This
+parameter only applies to gratings.  If it is not specified it will
+be derived from the other disperser parameters.
+.le
+.ls dispersion = INDEF (INDEF) [disperser|spectrograph]
+Central dispersion in A/mm for the reference order.  This parameter only
+applies to gratings.  If it is not specified it will be derived from the
+other disperser parameters.
+.le
+.ls indexref = INDEF (INDEF) [disperser|spectrograph]
+Grism index of refraction for the reference order.  This parameter only
+applies to grisms.  If it is not specified it will be derived from
+the other disperser parameters.
+.le
+.ls eff = INDEF (1.) [disperser|spectrograph]
+Peak efficiency for the theoretical disperser efficiency function.
+When an efficiency table is not specified then a theoretical efficiency
+is computed for the disperser.  This theoretical efficiency is scaled
+to peak efficiency given by this parameter.
+.le
+
+
+.ls xdisperser = "" [spectrograph]
+Crossdisperser table.  If this file contains an efficiency table it applies
+only to first order.  An alternate first order table and tables for
+other orders are given by table parameters "xeffN", where N is the order.
+.le
+.ls xdisptitle = "" [xdisperser|spectrograph]
+Title for crossdisperser.
+.le
+.ls disptype = "" ("grating") [xdisperser|spectrograph]
+Type of crossdisperser element.  The chocies are "", "grating", "grism",
+or "generic".  The empty string eliminates use of a cross disperser.
+The generic setting will simply use the desired central wavelength and
+dispersion without a grating or grism model.  One effect of this is that
+the mapping between detector pixel and wavelength is linear; i.e. a constant
+dispersion per pixel.
+.le
+.ls gmm = INDEF (INDEF) [xdisperser|spectrograph]
+Ruling in lines per mm.  If not specified it will be derived from the
+other crossdisperser parameters.
+.le
+.ls xblaze = INDEF (6.) [xdisperser|spectrograph]
+Blaze (grating) or prism (grism) angle in degrees.  If not specified it
+will be derived from the other crossdisperser parameters.
+.le
+.ls xoref = INDEF (1) [xdisperser|spectrograph]
+When a central (blaze) wavelength is specified this parameter indicates
+which order it is for.
+.le
+.ls xwavelength = INDEF (INDEF) [xdisperser|spectrograph]
+Central (blaze) wavelength in Angstroms for the reference order.  This
+parameter only applies to gratings.  If it is not specified it will
+be derived from the other crossdisperser parameters.
+.le
+.ls xdispersion = INDEF (INDEF) [xdisperser|spectrograph]
+Central dispersion in A/mm for the reference order.  This parameter only
+applies to gratings.  If it is not specified it will be derived from the
+other crossdisperser parameters.
+.le
+.ls xindexref = INDEF (INDEF) [xdisperser|spectrograph]
+Grism index of refraction for the reference order.  This parameter only
+applies to grisms.  If it is not specified it will be derived from
+the other crossdisperser parameters.
+.le
+.ls xeff = INDEF (1.) [xdisperser|spectrograph]
+Peak efficiency for the theoretical crossdisperser efficiency function.
+When an efficiency table is not specified then a theoretical efficiency
+is computed for the crossdisperser.  This theoretical efficiency is scaled
+to peak efficiency given by this parameter.
+.le
+
+
+.ls aperture = "" (default based on context) [spectrograph]
+Aperture table.  The text file gives aperture thruput as a function of the
+aperture size in units of seeing FWHM.  For rectangular apertures there are
+two independent variables corresponding to the width and length while for
+circular apertures there is one independent variable corresponding to the
+diameter.  If not specified a default table is supplied.  If a fiber table
+or a diameter is specified then the table "circle" is used otherwise the
+table "slit" is used.  Because "sptimelib$" is the last directory searched
+there are default files with these names in this directory for Gaussian
+seeing profiles passing through a circular or slit aperture.
+.le
+.ls aptitle = "" [aperture|spectrograph]
+Title for aperture used.
+.le
+.ls aptype = "" (default based on context) [aperture|spectrograph]
+The aperture types are "rectangular" or "circular".  If the
+parameter is not specified then if the aperture table has two columns the
+type is "circular" otherwise it is "rectangular".
+.le
+
+
+.ls fiber = "" [spectrograph]
+Fiber transmission table.  The transmission is a function of wavelength
+in Angstroms.  If no fiber transmission is specified then no fiber
+component is included.
+.le
+.ls fibtitle = "" [fiber|spectrograph]
+Title for fiber transmission used.
+.le
+
+
+.ls filter = "" [spectrograph]
+Filter transmission table.  The transmission is a function of wavelength
+in Angstroms.  If no filter transmission is specified then no filter
+component is included.
+.le
+.ls ftitle = "" [filter|spectrograph]
+Title for filter transmission used.
+.le
+.ls filter2 = "" [spectrograph]
+Filter transmission table.  The transmission is a function of wavelength
+in Angstroms.  If no filter transmission is specified then no filter
+component is included.
+.le
+.ls f2title = "" [filter|spectrograph]
+Title for filter transmission used.
+.le
+.ls block = "" ("no") [filter|spectrograph]
+If "yes" then no check will be made for other orders.
+.le
+
+
+.ls collimator = "" (1.) [spectrograph]
+Collimator transmission table.  The transmission is a function of
+wavelength in Angstroms.  If no collimator is specified then a unit
+transmission is used.
+.le
+.ls coltitle = "" [collimator|spectrograph]
+Title for collimator.
+.le
+.ls colfl = INDEF (1.) [collimator|spectrograph]
+Collimator focal length in meters.  The ratio of the collimator to camera
+focal lengths determines the magnification between the aperture and the
+detector.
+.le
+
+.ls camera = "" (1.) [spectrograph]
+Camera transmission table.  The transmission is a function of wavelength
+in Angstroms.  If no camera is specified then a unit transmission
+is used.
+.le
+.ls camtitle = "" [camera|spectrograph]
+Title for camera.
+.le
+.ls camfl = "" (1.) [camera|spectrograph]
+Camera focal length in meters.  The ratio of the collimator to
+camera focal lengths determines the magnification between the aperture
+and the detector.  The camera focal length also determines the dispersion
+scale at the detector.
+.le
+.ls resolution = "" (2 pixels) [camera|spectrograph]
+Camera resolution on the detector in mm.
+.le
+.ls vignetting = "" (1.) [camera|spectrograph]
+Vignetting table.  The independent variable is distance from the center
+of the detector in mm.  The value is the fraction the light transmitted.
+If no vignetting table is specified then no vignetting effect is applied.
+.le
+
+
+.ls detector = "" (1.) [spectrograph]
+Detector DQE table.  The DQE is a function of wavelength in Angstroms.
+.le
+.ls dettitle = "" [detector|spectrograph]
+Title for detector.
+.le
+.ls ndisp = INDEF (2048) [detector|spectrograph]
+Number of pixels along the dispersion.
+.le
+.ls pixsize = INDEF (0.02) [detector|spectrograph]
+Pixel size (assumed square) in mm.
+.le
+.ls gain = INDEF (1.) [detector|spectrograph]
+The conversion between photons and detector data numbers or counts.
+This is given as photons/ADU where ADU is analog-to-digital unit.
+.le
+.ls rdnoise = INDEF (0.) [detector|spectrograph]
+Readout noise in photons.
+.le
+.ls dark = INDEF (0.) [detector|spectrograph]
+Dark count rate in photons/s.
+.le
+.ls saturation = INDEF [detector|spectrograph]
+Number of detected photons in a pixel resulting in saturation.
+The default is no saturation.  The time per exposure will be reduced,
+but no lower than the minimum time per exposure,
+and the number of exposures increased to try and avoid saturation.
+.le
+.ls dnmax = INDEF [detector|spectrograph]
+Maximum data number or ADU allowed.  The default is no maximum.
+The time per exposure will be reduced,
+but no lower than the minimum time per exposure,
+and the number of exposures increased to try and avoid overflow.
+.le
+.ls xbin = 1 (1) [detector|spectrograph]
+Detector binning along the dispersion direction.
+.le
+.ls ybin = 1 (1) [detector|spectrograph]
+Detector binning along the spatial direction.
+.le
+.ih
+DISCUSSION
+
+
+OVERVIEW
+
+The spectroscopic exposure time package, \fBSPECTIME\fR, consists of a
+general calculation engine, \fBSPTIME\fR, and a collection of user or
+database defined IRAF scripts.  The scripts are one type of user interface
+for \fBSPTIME\fR.  Other user interfaces are Web-based forms and IRAF
+graphics/window applications.  The user interfaces customize the general
+engine to specific spectrographs by hiding components and parameters not
+applicable to that spectrograph and guiding the user, through menus or
+other facilities, in the choice of filters, gratings, etc.  However,
+\fBSPTIME\fR is a standard IRAF task that can be executed directly.
+
+\fBSPTIME\fR takes an input source spectrum (either a reference blackbody,
+a power law, or a user spectrum), a background "sky" spectrum and a
+instrumental thermal background, reddening to apply to the spectrum,
+observing parameters such as exposure time, central wavelength, seeing,
+airmass, and moon phase, instrument parameters such as aperture sizes and
+detector binning, a description of the spectrograph, and produces
+information about the expected signal and signal-to-noise ratio in the
+extracted one-dimensional spectrum.  The output consists of a description
+of the observation, signal-to-noise statistics, and optional graphs and
+tables of various quantities as a function of wavelength over the
+spectrograph wavelength coverage.
+
+\fBSPTIME\fR models a spectroscopic system as a flow of photons from a
+source to the detector through various optical components.  Background
+photons from the sky, atmosphere, and the thermal emission from the
+telescope and spectrograph are added.  It then computes signal-to-noise
+ratios from the detected photons of the source and background and the
+instrumental noise characteristics.  The spectroscopic system components
+are defined at a moderate level of detail.  It is not so detailed that
+every optical element has to be described and modeled and not so coarse
+that a single throughput function is used (though one is free to put all
+the thruput information into one component).  Not all components modeled by
+the task occur in all spectroscopic systems.  Therefore many of the
+components can be left out of the calculation.
+
+The components currently included in \fBSPTIME\fR are:
+
+.nf
+    - the atmosphere (extinction and IR transmission)
+    - the telescope (all elements considered as a unit)
+    - an optional atmospheric dispersion compensator
+    - the entrance aperture (slits, fibers, masks, etc.)
+    - an optional fiber feed
+    - a spectrograph (for components not represented elsewhere)
+    - filters
+    - a collimator
+    - a disperser (grating, grism, prism, etc)
+    - a optional cross disperser (grating, grism, prism, etc)
+    - a corrector (either in the telescope of spectrograph)
+    - a camera
+    - a detector
+.fi
+
+Each of these components represent a transmission function specifying the
+fraction of incident light transmitted or detected as a function of some
+parameter or parameters.  Except for the aperture, which is a function of
+the incident source profile (typically the seeing profile) relative to the
+aperture size, the transmissions of the components listed above are all
+functions of wavelength.
+
+All the component transmission functions may be specified as either numeric
+values or as tables.  A numeric value is considered to be a special type of
+table which has the same value at all values of the independent parameters.
+By specifying only numeric values the task may be run without any table
+files.  To obtain information at a single wavelength this is all that is
+needed.
+
+To specify a dependence on wavelength or other parameter a text file table
+with two or more columns may be specified.  The tables are interpolated in
+the parameter columns to find the desired value in the last column.  The
+tables are searched for in the current directory and then in a list of user
+specified directories.  Thus, users may place files in their work area to
+override system supplied files and observatories can organize the data
+files in a database directory tree.
+
+In addition to transmission or DQE functions the spectrograph is described
+by various parameters.  All the parameters are described in the PARAMETERS
+section.  For flexibility parameters may be defined either in the
+parameter set or in one or more table files.  In all cases the parameter
+set values have precedence.   But if the values are "" for string  parameters
+or INDEF for numeric parameters the values are found either in the
+spectrograph table or in a table that is associated with the parameter.
+
+Therefore table files provide for interchangeable components, each with
+their own transmission curves, and for organizing parameters for different
+instruments.  Note that a table file may contain only parameters, only
+a table, or both.
+
+There is also another way to maintain a separate file for different
+instruments.  The \fIspecpars\fR parameter is a "parameter set" or "pset".
+The default value of "" corresponds to the pset task \fBspecpars\fR.
+However, using \fBeparam\fR one can edit this pset and then save the
+parameters to a named parameter file with ":e <name>.par".  This
+pset can be edited with \fBeparam\fR and specified in the
+\fIspecpars\fR parameter.  One other point about pset parameters is that
+they can also be included as command line arguments just as any other
+parameter in the main task parameters.
+
+Many spectrographs provide a wide variety of wavelength regions and
+dispersions.  For gratings (and to some extent for grisms) this means use
+of different gratings, orders, tilts, and possibly camera angles in the
+spectrograph.  The transmission as a function of wavelength (the grating
+efficiency) changes with these different setups.  If the transmission
+function is given as an interpolation table this would require data files
+for each setup of each disperser.  The structure of \fBSPTIME\fR allows
+for this.
+
+However, it is also possible to specify the grating and spectrograph
+parameters and have the task predict the grating efficiency in any
+particular setup.  In many cases it may be easier to use the calculated
+efficiencies rather than measure them.  Depending on the level of accuracy
+desired this may be adequate or deviations from the analytic blaze function
+can be accounted for in another component.
+
+
+TABLES
+
+\fBSPTIME\fR uses text files to provide parameters and interpolation
+tables.  The files may contain comments, parameters, and tables.
+
+Comment lines begin with '#' and may contain any text.  They can occur
+anywhere in the file, though normally they are at the beginning of the file.
+
+Parameters are comment lines of the form
+
+.nf
+    # [parameter] = [value]
+.fi
+
+where whitespace is required between each field, [parameter] is a single
+word parameter name, and [value] is a single word value.  A quoted string
+is a single word so if the value field contains whitespace, such as in
+titles, it must be quoted.  Any text following the value is ignored and may
+be used for units (not read or used by the program) or comments.
+
+The parameters are those described in the PARAMETERS section.  The tables
+in which the parameters may be included are identified in that section
+in the square brackets.  Note that it is generally true that any parameter
+may appear in the spectrograph table.
+
+The table data is a multicolumn list of numeric values.  The list must be
+in increasing order in the independent columns.  Only 1D (two columns) and
+2D (three columns) tables are currently supported.  2D tables must form a
+regular grid.  This means that any particular value from column one must
+occur for all values of column 2 and vice versa.   The table is
+interpolated as needed.  The interpolation is linear or bi-linear.
+Extrapolation outside of the table consists of the taking the nearest
+value; thus, a single line may be used to define a constant value for all
+values of the independent variable(s).
+
+Normally the table values, the dependent variable in the last column, are
+in fractional transmission or DQE.  There is a special parameter,
+"tablescale", which may be specified to multiply the dependent variable
+column.  This would mainly be used to provide tables in percent rather
+than fraction.
+
+The independent variable columns depend on the type of table.  Most tables
+are a function of wavelength.  Currently wavelengths must be in Angstroms.
+
+The types of tables and the units of the columns are listed below.
+
+.nf
+        spectrum - Angstroms ergs/s/cm^2/A
+             sky - Angstroms ergs/s/cm^2/A/arcsec^2
+      extinction - Angstroms mag/airmass
+    spectrograph - Angstroms transmission
+       telescope - Angstroms transmission
+      emissivity - Angstroms emissivity
+             adc - Angstroms transmission
+           fiber - Angstroms transmission
+      collimator - Angstroms transmission
+          filter - Angstroms transmission
+       disperser - Angstroms transmission
+      xdisperser - Angstroms transmission
+       corrector - Angstroms transmission
+          camera - Angstroms transmission
+        detector - Angstroms transmission
+     sensitivity - Angstroms 2.5*(log(countrate)-log(flambda)),
+
+             sky - Angstroms moonphase ergs/s/cm^2/A/arcsec^2
+        aperture - diameter/FWHM transmission
+        aperture - width/FWHM length/FWHM transmission
+      vignetting - mm transmission
+.fi
+
+The disperser and crossdisperser files have an additional feature to allow
+for efficiency curves at different orders.  The parameter "effN" (or "xeffN
+for crossdispersers), where N is the order, may be specified whose value is
+a separate table (or constant).  If there is no "eff1/xeff1" (efficiency in
+first order) then any efficiency table in the disperser table is used.  In
+other words, any table in the disperser file applies only to first order
+and only if there is no "eff1/xeff1" parameter defining a separate first
+order efficiency file.
+
+DISPERSION UNITS
+
+The output results, text file, and graphs are presented in dispersion
+units defined by the \fIunits\fR parameter.  In addition the \fIwave\fR
+and \fIrefwave\fR input parameters are specified in the selected units.
+All other dispersion values must currently be specified in Angstroms.
+
+The dispersion units are specified by strings having a unit type from the
+list below along with the possible preceding modifiers, "inverse", to
+select the inverse of the unit and "log" to select logarithmic units. For
+example "log angstroms" to select the logarithm of wavelength in Angstroms
+and "inv microns" to select inverse microns.  The various identifiers may
+be abbreviated as words but the syntax is not sophisticated enough to
+recognize standard scientific abbreviations except for those given
+explicitly below.
+
+.nf
+	   angstroms - Wavelength in Angstroms
+	  nanometers - Wavelength in nanometers
+	millimicrons - Wavelength in millimicrons
+	     microns - Wavelength in microns
+	 millimeters - Wavelength in millimeters
+	  centimeter - Wavelength in centimeters
+	      meters - Wavelength in meters
+	       hertz - Frequency in hertz (cycles per second)
+	   kilohertz - Frequency in kilohertz
+	   megahertz - Frequency in megahertz
+	    gigahertz - Frequency in gigahertz
+	         m/s - Velocity in meters per second
+	        km/s - Velocity in kilometers per second
+	          ev - Energy in electron volts
+	         kev - Energy in kilo electron volts
+	         mev - Energy in mega electron volts
+
+	          nm - Wavelength in nanometers
+	          mm - Wavelength in millimeters
+	          cm - Wavelength in centimeters
+	           m - Wavelength in meters
+	          Hz - Frequency in hertz (cycles per second)
+	         KHz - Frequency in kilohertz
+	         MHz - Frequency in megahertz
+	         GHz - Frequency in gigahertz
+		  wn - Wave number (inverse centimeters)
+.fi
+
+The velocity units require a trailing value and unit defining the
+velocity zero point.  For example to transform to velocity relative to
+a wavelength of 1 micron the unit string would be:
+
+.nf
+	km/s 1 micron
+.fi
+
+
+CALCULATIONS
+
+This section describes the calculations, and assumptions behind the
+calculations, performed by \fBSPTIME\fR.  These include the dispersion and
+efficiencies of gratings and grisms, the dispersion resolution, the spatial
+resolution and how it applies to the number of object and sky pixels in the
+apertures, the object and sky detected photons/counts, the signal-to-noise
+ratio , and the exposure time for a given S/N.
+
+
+Gratings
+
+Gratings are assumed to tilted only around the axis parallel to the
+groves and with the incident angle greater than the blaze angle.  The
+grating equation is then
+
+.nf
+    g * m * w = sin(tilt+phi/2) + sin(beta)
+.fi
+
+where g is the number of groves per wavelength unit, m is the order, w is
+the wavelength, tilt is the grating tilt measured from the grating normal,
+phi is the angle between the incident and diffracted rays, and beta is the
+diffracted angle.  Phi is a spectrograph parameter and g is a grating
+parameter.  At the desired central wavelength beta is tilt-phi/2 and at the
+blaze peak it is 2*blaze-tilt-phi/2 where blaze is the blaze angle.
+
+The tilt is computed from the desired central wavelength.  It is
+also used to compute the grating magnification
+
+.nf
+    magnification = cos(tilt-phi/2) / cos(tilt+phi/2)
+.fi
+
+which is used in calculating the projected slit size at the detector.
+This number is less than zero so the aperture is actually demagnified.
+
+The dispersion, treated as constant over the spectrum for the sake of
+simplicity, is given by the derivative of the grating equation at
+the blaze peak,
+
+.nf
+    dispersion = cos(blaze-phi/2) / (g * m * f)
+.fi
+
+where f is the camera focal length.
+
+The grating efficiency or blaze function is computed as described by
+Schroeder and Hilliard (Applied Optics, vol 19, 1980, p. 2833).  The
+requirements on the grating noted previously correspond to their case A.
+As they show, use of incident angles less than the blaze angle, their case
+B, significantly degrades the efficiency due to back reflection which is
+why this case is not included.  The efficiency formulation includes
+variation in the peak efficiency due light diffracted into other orders,
+shadowing of the groves, and a reflectance parameter.  The reflectance
+parameter is basically the blaze peak normalization and does not currently
+include a wavelength dependence.  Thus the peak efficiency is near the
+reflectance value but somewhat lower and is order dependent due to the other
+effects.
+
+
+Grisms
+
+Grisms are assumed to have a prism angle equal to the blaze angle of
+the inscribed grating.  The index of refraction is treated as constant
+over the wavelength range of an order, though different index of refraction
+values can be specified for each order.
+
+The grism formula used is a variation on the grating equation.
+
+.nf
+    g * m * w = n * sin (theta+prism) - sin (beta+prism)
+.fi
+
+where n is the index of refraction, prism is the prism or blaze angle,
+theta is the incident angle relative to the prism face, and beta is the
+refracted angle relative to the prism face.  Theta and beta are defined so
+that at the undeviated wavelength they are zero.  In other words at the
+undeviated wavelength the light path is a straight through transmission.
+
+The efficiency is also computed in an analogous manner to the
+reflection grating except that shadowing is not included (a consequence of
+the blaze face being parallel to the prism face and theta being near
+zero).  Instead of a reflectance value normalizing the blaze function a
+transmission value is used.
+
+
+Scales and Sizes
+
+The scale between arc seconds on the sky and millimeters at the
+aperture(s) of the spectrograph is specified by the \fIscale\fR parameter.
+This parameter is used to convert aperture sizes between arc seconds and
+millimeters.
+
+The aperture sizes are magnified or demagnified by three possible factors.
+The basic magnification is given by the ratio of the collimator focal
+length to the camera focal length.  This magnification applies both along
+and across the dispersion.
+
+The camera focal length also determines the dispersion scale on the detector.
+It converts radians of dispersion to mm at the detector.
+
+For grating dispersers there is a demagnification along the dispersion
+due to the tilt of the grating(s).  The demagnification is computed (as
+given previously) from the grating parameters and the spectrograph
+parameter giving the angle between the incident and diffracted rays at the
+detector center.
+
+The last magnification factor is given by the spectrograph parameters
+"apmagdisp" and apxmagdisp".  These define magnifications of the aperture
+along and across the dispersion apart from the other two magnifications.
+These parameters are often missing which means no additional
+magnifications.
+
+One use for the last magnification parameters is to correct aperture
+sizes given as millimeters or arc seconds on a plane tilted with respect to
+the focal plane.  Such tilted apertures occur with aperture mechanisms
+(usually slits) that reflect light for acquisition and guiding.  Note that
+one only needs to use these terms if users are expected to define the
+apertures sizes on the tilted plane.  If instead the projection factors are
+handled by the spectrograph system and users specify aperture size as
+millimeters or arc seconds on the sky then these terms are not needed.
+
+The above scale factors map arc seconds on the sky and aperture sizes
+in millimeter to arc seconds and millimeters projected on the detector.  To
+convert to pixels on the detector requires the pixel size.
+One option in \fBSPTIME\fR is to specify aperture
+sizes as projected pixels on the detector (either in the user parameters or
+in the aperture description file).  Using the detector pixel size and the
+scale factors allows conversion of aperture sizes specified in this way
+back to the actual aperture size.
+
+
+Resolution
+
+A camera resolution parameter may be set in the camera description.  If
+a resolution value is not given it is taken to be 2 pixels.  This parameter
+is used to define the dispersion resolution element and the number of
+pixels across the dispersion imaged by the detector for the aperture and
+the object.  The latter usage is discussed in the next section.
+
+The dispersion resolution element, in pixels, is given by
+
+.nf
+				 |  2 pixels
+    disp resolution = maximum of |  camera resolution
+				 |  1 + min (seeing, apsize)
+.fi
+
+where seeing is the FWHM seeing diameter in pixels and apsize is the
+aperture size in pixels.  For circular apertures the aperture size is
+the diameter and for rectangular apertures it is the width.  The first term
+comes from sampling considerations, the second from the camera resolution,
+and the third from the finite resolution of a pixel (the factor of 1) and
+the spread of wavelengths across the aperture or seeing disk.  The
+dispersion resolution is printed for information and the S/N per dispersion
+resolution element is given in addition to the per pixel value.
+
+
+Object and Sky Pixels Across the Dispersion
+
+The number of pixels across the dispersion in the object and the sky
+are required to compute the S/N statistics.  The number of pixels
+in the projected aperture image is taken to be
+
+.nf
+		       | diameter + resolution  (circular apertures)
+    aperture pixels =  |
+		       | length + resolution    (rectangular apertures)
+.fi
+
+where resolution is the camera resolution discussed previously.  The value
+is rounded up to an integer.
+
+Objects are assumed to fill circular (fiber) apertures.  Therefore the
+number of object pixels is the same as the number of pixels in the
+aperture.  In rectangular (slit) apertures the number of object pixels is
+taken to be
+
+.nf
+				| 3*seeing + resolution
+    object pixels = minimum of  |
+				| number of aperture pixels
+.fi
+
+where seeing is the FWHM seeing diameter converted to pixels.  The values
+are rounded up to an integer.
+
+The number of sky pixels depends on the type of sky subtraction.
+For "longslit" sky subtraction the number of sky pixels is given
+by the difference of the number of aperture pixels and the number of
+object pixels.  For circular apertures this always comes out to zero so
+it does not make sense to use longslit sky subtraction.  For rectangular
+apertures the number of sky pixels in the aperture depends on the
+aperture size and the seeing.  If the number of sky pixels comes out to
+zero a warning is printed.
+
+For "multiap" sky subtraction the number of sky pixels is the
+number of sky apertures times the number of pixels per aperture.
+
+
+Source Counts
+
+The source spectrum flux at each wavelength, either given in a spectrum
+table or as a model distribution, is in units of
+photons per second per Angstrom per square centimeter.  This is multiplied
+by the telescope effective area, the exposure time, and the pixel size in
+Angstroms to give the source photons per dispersion pixel per exposure.
+This is then multiplied by any of the following terms that apply to arrive
+at the number of source photons detected over all spatial pixels.  The
+spatial integration is implicit in the aperture function.
+
+.nf
+    - the extinction using the specified airmass
+    - the telescope transmission
+    - the ADC transmission
+    - the aperture transmission based on the aperture size relative
+      to the seeing
+    - the fiber transmission
+    - the filter transmission (one or two filters)
+    - the collimator transmission
+    - the disperser efficiency (one or two dispersers)
+    - the corrector transmission
+    - the camera transmission
+    - the detector DQE
+.fi
+
+
+Background Counts
+
+The sky or atmospheric background spectrum, if one is given, defines a
+photon flux per square arc second.  When it is given as a function of the
+moon phase it is interpolated to the specified moon phase.  In addition
+if a thermal temperature and an emissivity are given then a thermal
+background is computed and added to the sky/atmospheric background.
+
+The surface brightness of the background is multiplied by the area of the
+aperture occupied by the object (in arc seconds) and divided by the
+aperture transmission of the source.  This is the quantity reported in the
+output for the sky photon flux.  It is comparable to the source photon
+flux.
+
+Next this flux is multiplied by the telescope effective area, the
+exposure time, and the pixel size in Angstroms.  Finally it is multiplied
+by the same transmission terms as the object except for the extinction.
+Note that this removes the aperture transmission term included earlier
+giving the background photons as the number passing through the aperture per
+object profile.  The final value is the number of background photons from the
+object.  To get the background photons per spatial pixel the value is divided by
+the number of spatial pixels occupied by the source.
+
+If no background subtraction is specified then the background counts are added
+to the source counts to define the final source counts and the background
+counts are set to zero.
+
+
+Signal-to-Noise Ratio
+
+The noise attributed to the source and background is based on Poisson
+statistics; namely the noise is the square root of the number of photons.
+The detector noise is given by a dark count component and a readout noise
+component.  The noise from the dark counts is obtain by multiplying the
+dark count rate by the exposure time and the number of spatial pixels used
+in extracting the source and taking the square root.  The readout noise is
+the detector readout noise parameter multiplied by the square root of the
+number of spatial source pixels.
+
+If background subtraction is selected and the number of available
+background pixels is greater than zero then the uncertainty in the
+background estimation is computed.  The uncertainty in a single pixel is
+the square root of the background photons per pixel, the dark counts per
+pixel, and the readout noise per pixel.  This is divided by the square root
+of the number of background pixels to get the uncertainty in the background
+estimation for subtraction from the source.
+
+The total noise is the combination of the source, background, dark count,
+and readout noise values and the background subtraction uncertainty added
+in quadrature.
+
+The signal-to-noise ratio per pixel per exposure is the source counts
+divided by total noise.  This value is multiplied by the square root of
+number of pixels per resolution element to get the S/N per resolution
+element.  If multiple exposures are used to make up the total exposure time
+then the single exposure S/N is multiplied by the square root of the number
+of exposures.
+
+
+Exposure Time From Signal-to-Noise Ratio
+
+If no exposure time is specified, that is a value of INDEF, then
+the exposure time required to reach a desired signal-to-noise ratio
+per pixel is determined.  The computation is done at the specified central
+wavelength.  The task iterates, starting with the specified maximum time per
+exposure, by computing the S/N and adjusting the exposure time
+(possibly breaking the total exposure up into subexposures) until
+the computed S/N matches the desired S/N to 0.1%.
+
+In addition to breaking the exposure time into individual exposure less
+than the maximum per exposure, the task will break single exposures that
+exceed the specified saturation and maximum data number values at the
+reference wavelength.  If other wavelengths are then saturated or exceed
+the data maximum a warning is printed.
+.endhelp
-- 
cgit 

