% @(#)computairm.hlq	19.1 (ESO-IPG) 02/25/03 14:03:02 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1992 European Southern Observatory
%.IDENT      computairm.hlq
%.AUTHOR     DB, IPG/ESO
%.KEYWORDS   MIDAS, help files, COMPUTE/AIRMASS
%.PURPOSE    On-line help file for the command: COMPUTE/AIRMASS
%.VERSION    1.0  26-FEB-1987 : Creation, DB
%.VERSION    1.1  02-SEP-1992 : Change to eastern longitude, PJG
%----------------------------------------------------------------
\se
SECTION./AIRM
\es\co
COMPUTE/AIRMASS						02-SEP-1992  DB
\oc\su
COMPUTE/AIRMASS frame [long] [lat]
COMPUTE/AIRMASS alpha delta ST [exptime] [long] [lat] [date] [UT]
	compute airmass (from sec z)
\us\pu
Purpose:     
           Calculate airmass (from sec z). There are two options:
\\
           a) if a frame is used, the parameters are taken from the
              descriptors of the frame.
\\
           b) Parameters are given directly
\up\sub
Subject:     
           Spectroscopy, Photometry, Airmass, Flux Calibration
\bus\sy
Syntax:     
           a) COMPUTE/AIRMASS frame [long] [lat]
           b) COMPUTE/AIRMASS alpha delta ST [exptime] [long] [lat] [date] [UT]
\ys\pa
           frame = name of frame with the following descriptors set:
\\
                   O_TIME/R/1/3     date (year,month,date)
\\
                   O_TIME(5)        UT (real hours)
\\
                   O_TIME(7)        exposure time (seconds
\\
                   O_POS(1)         right ascension (real DEGREES!)
\\
                   O_POS(2)         declination (real degrees)
\\
                   (use WRITE/DESC to complete info block if necessary)
\ap\pa
           alpha = right ascension (hour,min,sec)
\ap\pa
           delta = declination (degree,min,sec)
\ap\pa
           ST = local mean sidereal time for start of exposure (decimal hour)
\\
                (if less than 0, the program will supply it, which is also the
                default; if .GT. 25, airmass will be calculated for object
                 on meridian, i.e. longitude, UT, and date are meaningless)
\ap\pa
           exptime = duration of exposure (seconds), defaulted to 0.0
\ap\pa
           long = EAST longitude of observatory (degree,min,sec)
                  default: -70,43,55.35 (= Schmidt telescope, La Silla)
                  (can be omitted if ST is given),  must be negative !
                  NOTE: Eastern longitudes are used conforming to IAU.
\ap\pa
           lat = latitude of observatory (degree,min,sec)
                 default: -29,15,25.8 (= Schmidt telescope, La Silla)
\ap\pa
           date = civil date (year,month,day), can be omitted if ST is given
\ap\pa
           UT = universal time (hour,min,sec), can be omitted if ST is given
\ap\out
Output:  
           a)  Output will be written to the following descriptors:
\\
               O_TIME(4)         Julian date - 2,400,000.5 (days)
\\
               O_TIME(6)         local mean sidereal time (hours)
\\
               O_AIRM            airmass
\\
           b)  Output is written to the following keywords:
\\
               OUTPUTR(1) - airmass, OUTPUTD(19) - ST (in real hours)
\\
               OUTPUTD(1) - Julian date
\\
           ra   = right ascension in HH,MM,SS
\\
           dec  = declination in DD,MM,SS
\\
           sid  = sidereal time in HH,MM,SS (DEFAULT: = RA)
\\
                  at half exposure (sid >= 25 --> sid = ra)
\tuo\sa
See also: 
           COMPUTE/ST, COMPUTE/UT
\tuo\no
Note:        
           All input is of type REAL so that, e.g., the date can also be
           entered as 1987.767,0,0 or just 1987.767 . However, parameters
           must not be combined. That is, the example given the fraction
           of the year may contain only the number of elapsed full days,
           not also UT.
           For non-zero exposure times, the airmass is calculated as
           the weighted average according to the following formula
           (suggested by P. Stetson, Dominion Astrophyical Observatory
           Preprint, 1988 September):
\\
                        AM = (AM(ts) + 4 AM(tm) + AM(te))/6,
\\
           where AM denotes airmass, and ts, tm, te are the times
           of start, middle and end of exposure, respectively.
\\
           Eastern longitudes are positive and western counted
           negative conforming to IAU recommendations.
\on\exs
Examples:
\ex
           COMPUTE/AIRMASS  ntt1992 
             Compute airmass for image `ntt1992.bdf', longitude and latitude
	     will be taken from descriptors ESO.TEL.GEOLON and ESO.TEL.GEOLAT.
	     If these are not present, the default (La Silla) will be used. 
\xe\ex
           COMPUTE/AIRMASS  00,43,11 03,54,41 23.789
             Compute airmass for an object at coordinates alpha = 00h43m11s 
             and delta = 03d54'41"  observed at sidereal time 23h47m20.4s .
\xe\ex
           COMPUTE/AIRMASS  13,24,32  -11,05,47  ?  ?  ?  ?  1965,4,1 5,27,20
             Compute airmass, JD, and ST for an observation of Spica
             obtained on La Silla on April 1st, 1965 at 5:27:20 hrs UT.
\xe\ex
           COMPUTE/AIRMASS  eso_garching_1 -349,26,0 48,08,0
             Compute airmass for image `eso_garching_1', longitude and latitude
	     will be taken as entered above: long = -349,26,0 and lat = 48,08,0.
	     However: note that these values will be ignored, if the frame 
	     eso_garching_1 has descriptors ESO.TEL.GEOLON and ESO.TEL.GEOLAT!
	     Then, the values which are in ESO.TEL.GEOLON and ESO.TEL.GEOLAT
	     will be used!
\xe \sxe
