Initial commit

1 files changed, 354 insertions, 0 deletions

diff --git a/noao/astutil/doc/ccdtime.hlp b/noao/astutil/doc/ccdtime.hlp
new file mode 100644
index 00000000..318c89b6
--- /dev/null
+++ b/noao/astutil/doc/ccdtime.hlp
@@ -0,0 +1,354 @@
+.help ccdtime Aug98 noao.astutil
+.ih
+NAME
+ccdtime -- compute time, magnitude, and signal-to-noise for CCDs
+.ih
+USAGE
+ccdtime
+.ih
+PARAMETERS
+.ls time = INDEF
+Time in seconds for output of magnitude at the specified signal-to-noise and
+signal-to-noise at the specified magnitude.  This time applies to all
+filters.  If specified as INDEF then no output at fixed exposure time will
+be produced.  If the value is not greater than zero or less than 100000
+an error is reported.
+.le
+.ls magnitude = 20.
+Magnitude for output of time at the specified signal-to-noise and
+signal-to-noise at the specified time.  This magnitude applies to all
+filters. If specified as INDEF then no output at fixed magnitude will
+be produced.  If the absolute value of the magnitude is greater than 40
+an error will be reported.
+.le
+.ls snr = 20.
+Signal-to-noise ratio for output of time at the specified magnitude and
+magnitude at the specified time.  This signal-to-noise ratio applies to all
+filters. If specified as INDEF then no output at fixed signal-to-noise
+ratio will be produced.  If the value is not greater than zero or less than
+100000 an error is reported.
+.le
+
+.ls database = "ccdtime$kpno.dat"
+Database file for telescope, filter, and detector information.  The format
+of this file is described elsewhere.  This file is typically a standard
+file from the logical directory "ccdtime$" or a personal copy in a
+user's directory.
+.le
+.ls telescope = "?"
+Telescope entry from the database.  If "?" a list of telescopes in the
+database is produced.  The name must match the entry name in the database
+but ignoring case.  If the same telescope has multiple focal ratios then
+there must be multiple entries in the database.
+.le
+.ls detector = ""
+Detector entry from the database.  If "?" a list of detectors in the
+database is produced.  The name must match the entry name in the database
+but ignoring case.
+.le
+.ls sum = 1
+CCD on-chip summing or binning factor.
+.le
+.ls seeing = 1.5
+Expected seeing (FWHM) in arc seconds.  The number of pixels used for computing
+the total star counts and the signal-to-noise is given by 1.4 times the square
+of the seeing converted to pixels and rounded up.
+.le
+.ls airmass = 1.2
+Airmass for observation.
+.le
+.ls phase = 0.
+Moon phase in days (0-28) for the estimation of sky brightness.  A
+phase of zero is new moon or dark sky conditions and a phase of 14
+is full moon.
+.le
+
+.ls f1 = "U", f2 = "B", f3 = "V", f4 = "R", f5 = "I"
+Filters for which to compute the CCD information.  If given as "?"
+a list of filters in the database is produced.  If the name (ignoring
+case) is not found then it is ignored.  A null name, that is "",
+is used to eliminate listing of a filter.  There may be many filters
+in the database but the task is currently limited to displaying no
+more than five.
+.le
+.ih
+DESCRIPTION
+A telescope, CCD detector, and list of filters is selected from a database
+to define the expected photon/electron count rates.  These rates along with
+a specified seeing and airmass are used to estimate the signal-to-noise
+ratio (SNR) for a stellar observation in each filter.  The output provides
+three results per filter; the exposure time to achieve a desired SNR for a
+given magnitude, the magnitude to achieve a desired SNR in a given time, and
+the SNR at a specified magnitude and exposure time.  With each of these,
+the number of star photons (or CCD electrons) in an area 1.4 times the
+square of the seeing, the number of sky photons per pixel, and the RMS noise
+contributions from photon noise in the star, the sky, and the detector
+noise from dark current and read out noise are given.  Note that least two
+of the time, magnitude, and signal-to-noise ratio must be specified but if
+one is INDEF then output with that quantity fixed will be skipped or, in
+other words, only the output where the quantity is computed is produced.
+
+The calibration information needed to define the count rates are
+taken from a database file.  This file may be standard ones given in
+the logical directory "ccdtime$" or the user may create their own.
+The database contains entries organized by telescope name (which may
+include a focal ratio if there are multiple ones), detector name,
+and filter name.  One of the standard files may be used as a template.
+
+The file is actually in free format with whitespace and comments ignored.
+However, following the template formatting makes it easy to see the logical
+structure.  All lines, except the "end" line which separates the different
+categories of entries, consist of a keyword an equal sign, and a value
+separated by whitespace.  An entry begins with one of the keywords
+"telescope", "detector", or "filter" and ends with the beginning of
+a new entry or the "end" separator.
+
+A keyword is one of the words shown in the example below.  These keywords
+can also be indexed by the name of a telescope, filter, and/or detector
+entry.  This allows having different transmissions in different filters
+due to correctors, different scales for different detectors which may
+have fore-optics, etc.
+
+Specifically a keyword in the telescope section may have arguments
+from the filter or detector entries, a keyword in the filter section may
+have arguments from the telescope and detector entries, and a keyword
+in the detector section may have arguments from the telescope and filter
+entries.  The formats are keyword, keyword(arg), and keyword(arg,arg).
+The arg fields must match an entry name exactly (without the quotes)
+and there can be no whitespace between the keyword and (, between (
+and the argument, between the arguments and the comma, and between the
+last argument and the closing ).  The software will first look for
+keywords with both arguments in either order, then for keywords with
+one argument, and then for keywords with no arguments.
+
+Below is an example of each type of entry:
+
+.nf
+    telescope = "0.9m"
+	    aperture = 0.91
+	    scale = 30.2
+	    transmission = 1.0
+	    transmission(U) = 0.8
+	    transmission(U,T1KA) = 0.7
+
+    filter = "U"
+	    mag = 20
+	    star = 18.0
+	    extinction = 0.2
+	    sky0 = 22.0
+	    sky1 = -0.2666
+	    sky2 = -.00760
+
+    detector = "T1KA"
+	    rdnoise = 3.5
+	    dark = 0.001
+	    pixsize = 24
+	    U = 0.36
+	    B = 0.61
+	    V = 0.71
+	    R = 0.78
+	    I = 0.60
+.fi
+
+In the example, a transmission of 0.7 will be used if the filter is U
+and the detector is T1KA, a value of 0.8 if the filter is U and the
+detector is not T1KA, and a value of 1 for all other cases.
+
+The telescope entry contains the aperture diameter in meters, the
+scale in arcsec/mm, and a transmission factor.  The transmission factor is
+mostly a fudge factor but may be useful if a telescope has various
+configurations with additional mirrors and optics.
+
+The filter entry contains a fiducial magnitude and the total photon count
+rate for a star of that magnitude.  The units are photons per second
+per square meter of aperture.  An effective extinction in magnitudes/airmass is
+given here.  The sky is defined by a quadratic
+function of lunar phase in days:
+
+.nf
+	if (phase < 14)
+	    sky = sky0 + sky1 * phase + sky2 * phase**2
+	else
+	    sky = sky0 + sky1 * (14 - phase) + sky2 * (14 - phase)**2
+.fi
+
+One may set the higher order terms to zero if the moon contribution
+is to be ignored.  The units are magnitudes per square arc second.
+
+The detector entry contains the read out noise in electrons, the
+dark current rate in electrons per second, the pixel size in
+microns, and the detective quantum efficiency (DQE); the fraction of
+detected photons converted to electrons.  Note that the actual
+values used are the DQE times the rates given by the filter entries.
+Thus, one may set the DQE values to 1 and adjust the filter values
+or set the star count rates to 1 in the filter and set the actual
+count rates in the DQE values.
+
+The computed quantities are formally given as follows.  The
+star count rates for the specified telescope/detector/filter are:
+
+.nf
+	r(star) = star * aperture**2 * transmission *
+	    10**(0.4*(1-airmass)*extinction) * dqe
+.fi
+
+where the "star", "aperture", "transmission", "extinction", are those
+in the database and the "dqe" is the appropriate filter value.  The sky
+rate per pixel is:
+
+.nf
+	r(sky) = r(star) * 10 ** (0.4 * (mag - sky)) * pixel**2
+	pixel = pixsize * scale * sum
+.fi
+
+where mag is the fiducial magnitude, sky is the value computed using
+the quadratic formula for the specified moon phase and the database
+coefficients, the "pixel" size is computed using the CCD pixel size and
+the telescope scale from the database, and sum is the
+specified CCD binning factor.
+
+The number of pixels per star is computed from the seeing as:
+
+.nf
+	npix = 1.4 * (seeing / pixel) ** 2
+.fi
+
+where the number is rounded up to the next integer and a minimum of 9
+pixels is enforced.  This number is a compromise between a large aperture
+for high SNR stars and a smaller aperture for fainter stars.
+
+The number of star photons/electrons per star of magnitude m,
+the number of sky photons per pixel, and the number of dark current
+electrons, all in exposure time t, are given by:
+
+.nf
+	nstar = r(star) * 10 ** (0.4 * (mag - m)) * t
+	nsky = r(sky) * t
+	ndark = dark * t
+.fi
+
+where dark is taken from the detector database entry.
+
+Finally the noise contributions, total noise, and signal-to-noise are
+given by:
+
+.nf
+	noise star = nstar ** 1/2
+	noise sky = (npix * nsky) ** 1/2
+	noise ccd = (npix * (ndark + rdnoise**2)) ** 1/2
+	noise total = (nstar+npix*(nsky+ndark+rdnoise**2)) ** 1/2
+	SNR = nstar / noise total
+.fi
+.ih
+EXAMPLES
+1.  To get a list of the telescopes, filters, and detectors in a database:
+
+.nf
+    cl> ccdtime telescope=? detector=? f1=?
+    Entries for telescope in database ccdtime$kpno.dat:
+	    0.9m
+	    ...
+	    4m
+    Entries for detector in database ccdtime$kpno.dat:
+	    T1KA
+	    T2KA
+	    T2KB
+	    TI2
+	    TI3
+	    T5HA
+	    S2KA
+    Entries for filter in database ccdtime$kpno.dat:
+	    U
+	    B
+	    V
+	    R
+	    I
+.fi
+
+2.  The following is for the default magnitude and SNR and with
+a 1 second exposure time specified.  The output has some
+whitespace removed to fit on this page.
+
+.nf
+    cl> ccdtime time=1
+    Telescope: 0.9m
+    Detector: t1ka
+    Database: ccdtime$kpno.dat Telescope: 0.9m    Detector: t1ka
+      Sum: 1 Arcsec/pixel: 0.72  Pixels/star: 6.0
+      Seeing: 1.5  Airmass: 1.20  Phase: 0.0
+
+
+     Filter  Time   Mag   SNR   Star Sky/pix Noise contributions
+					      Star    Sky    CCD
+
+	  U  70.2  20.0  10.0  196.6    8.8  14.02   8.90  10.53
+	  B  13.0  20.0  10.0  208.8   13.0  14.45  10.82  10.51
+	  V  13.2  20.0  10.0  250.7   29.8  15.83  16.37  10.51
+	  R  17.3  20.0  10.0  365.8   95.9  19.13  29.38  10.51
+	  I 126.4  20.0  10.0 1259.2 1609.8  35.49 120.37  10.55
+
+	  U   1.0  15.6  10.0  166.6    0.1  12.91   1.06  10.50
+	  B   1.0  17.4  10.0  170.0    1.0  13.04   3.00  10.50
+	  V   1.0  17.6  10.0  174.6    2.3  13.21   4.50  10.50
+	  R   1.0  17.6  10.0  186.0    5.5  13.64   7.06  10.50
+	  I   1.0  16.7  10.0  207.9   12.7  14.42  10.71  10.50
+
+	  U   1.0  20.0   0.3    2.8    0.1   1.67   1.06  10.50
+	  B   1.0  20.0   1.4   16.0    1.0   4.00   3.00  10.50
+	  V   1.0  20.0   1.6   19.0    2.3   4.36   4.50  10.50
+	  R   1.0  20.0   1.6   21.1    5.5   4.59   7.06  10.50
+	  I   1.0  20.0   0.7   10.0   12.7   3.16  10.71  10.50
+
+.fi
+
+Note that the default of 1 second in the last section
+gives the count rates per second for star and sky.
+
+3.  Sometimes one may want to vary one parameter easily on the command
+line or query.  This can be done by changing the parameter to query
+mode.  In the following example we want to change the magnitude.
+
+.nf
+    cl> ccdtime.magnitude.p_mode=query
+    cl> ccdtime.telescope="0.9m"
+    cl> ccdtime.detector="t1ka"
+    cl> ccdtime.f1=""; ccdtime.f5=""
+    cl> ccdtime
+    Magnitude (20.):
+    Database: ccdtime$kpno.dat   Telescope: 0.9m     Detector: t1ka
+      Sum: 1 Arcsec/pixel: 0.72  Pixels/star: 6.0
+      Seeing: 1.5  Airmass: 1.20  Phase: 0.0
+
+     Filter  Time   Mag   SNR  Star Sky/pix  Noise contributions
+					       Star   Sky    CCD
+
+	  B  13.0  20.0  10.0 208.8    13.0  14.45  10.82  10.51
+	  V  13.2  20.0  10.0 250.7    29.8  15.83  16.37  10.51
+	  R  17.3  20.0  10.0 365.8    95.9  19.13  29.38  10.51
+
+    cl> ccdtime 21
+    ...
+    cl> ccdtime 22
+    ...
+.fi
+.ih
+REVISIONS
+.ls CCDTIME V2.11.4
+A error will be reported if the requested time or SNR is not greater
+than zero and less than 100000., or if the absolute value
+of the magnitude is greater than 40.
+.le
+.ls CCDTIME V2.11.2
+The incorrect usage of a 1 mag/airmass extinction was fixed by adding an
+expected "extinction" entry in the filter entries.  Note that old files
+will still give the same result by using an extinction of 1 if the keyword
+is not found.
+
+The database keywords can not be indexed by telescope, filter, and/or
+detector.
+
+The number of pixels per aperture now has a minimum of 9 pixels.
+.le
+.ih
+SEE ALSO
+.endhelp