NAME:
 atmospheric_density

 PURPOSE:
 Calculate the atmospheric density of air at the supplied conditions
 EXPLANATION:
 This procedure will take as inputs a set of physical conditions
 (temperature, density, humidity, and CO2 concentration) and
 calculate the refractivity (the index of refraction minus 1)
 of air at a specific wavelength.
 CALLING SEQUENCE:
 r = refractivity(wavelength, temp, pressure, humidity, xc)

 INPUTS:
 temperature = temperature of air, in Celsius (C)
 (default = 20)
 pressure_pa = local air pressure, in pascals (P)
 (default = 100000)
 humidity = relative humidity, in percent (%)
 (default = 75)
 xc = concentration of CO2, in parts per million (ppm)
 (default = 380)

 OPTIONAL INPUT KEYWORDS:
 force_xw = use the value of this keyword as the molar fraction
 of water vapor instead of calculating x_w from the
 supplied conditions
 water_vapor = if supplied, then calculated the partial pressure
 of pure water vapor
 dry_air = if supplied, then calculated the partial pressure
 of completely dry air
 verbose = indicates level of output information
 0 = no output
 1 = standard output
 2 = extended output

 OPTIONAL OUTPUT KEYWORD:
 atmosphere_values = structure containing calculated atmospheric
 parameters for given conditions
 R = the gas constant
 Z = compressibility of moist air
 Ma = molar mass of dry air (at a given xc)
 Mw = molar mass of water vapor
 svp = saturation vapor pressure of water vapor in air
 at temperature TT_K
 f = enhancement factor of water vapor in air
 density = calculated density
 TT_C = temperature of air, in Celsius (C)
 TT_K = temperature of air, in Kelvin (K) = TT_C + 273.15
 pressure_Pa = local air pressure, in pascals (P)
 humidity = relative humidity, in percent (%)
 xw = concentration of CO2, in parts per million (ppm)

 RESULTS:
 density = calculated density

 CALLED BY:
	refractivity
 EXAMPLE:
 density_a = atmospheric_density(12, 70000, 35, 400, /dry_air)
 COMMON BLOCKS:
 none

 PROCEDURE:
 Ciddor, P.E., 1996, "Refractive index of air: new equations for
 the visible and near infrared", Applied Optics LP, vol. 35,
 Issue 9, p.1566

 MODIFICATION HISTORY:
 Written, Kevin Reardon, INAF/Osservatorio Astrofisico di Arcetri, 2005

 NAME:
 atmospheric_refraction

 PURPOSE:
 Calculate the refraction of the Sun at different wavelengths
 EXPLANATION:
 This program calculates the refractivity of the air for a given set
 of atmospheric conditions and the position of the Sun for an array
 of input times.

 CALLING SEQUENCE:
 atm_ref_struct = atmospheric_refraction(wavelengths, input_times)

 INPUTS:
 wavelength = wavelengths at which to calculate refractivity,
 in nanometers (nm)
 (default = [400, 500, 600, 700, 800])
 input_times = times for which to calculate the position of the Sun
 and the related atmospheric refraction (in Julian days)
 (default = current time)

 OPTIONAL INPUT KEYWORDS
 latitude = latitude of observation location, in decimal degrees,
 positive for north latitudes (default = 20.71)
 longitude = longitude of observation location, in decimal degrees,
 positive for east longitudes (default = -156.25)
 altitude = altitude of observation location, in meters
 (default = 3055)
 air_temp = temperature of air, in Celsius (C)
 (default = 20)
 air_pressure = local air pressure, in pascals (P)
 (default = 100000)
 humidity = relative humidity, in percent (%)
 (default = 75)
 co2_conc = concentration of CO2, in parts per million (ppm)
 (default = 380)
 verbose = indicates level of output information
 0 = no output
 1 = standard output
 2 = extended output

 OPTIONAL OUTPUT KEYWORD:

 RESULTS:
 Program returns a structure containing refraction magnitude for each
 input time and wavelength, and the parallactic angle for each
 input time. The structure also contains descriptors of the units
 used for each array.

 ** Structure <574550>, 4 tags, length=52, data length=52, refs=1:
 REFRACTION_MAG FLOAT Array[1, 5]
 PARALLACTIC_ANGLE DOUBLE -13.435534
 REFRACTION_MAG_UNIT STRING 'arcsec'
 PARALLACTIC_ANGLE_UNIT STRING 'degrees'

 EXAMPLE:

 CALLS: ***
	EQ2HOR, HLP, SUNPOS, refractivity
 COMMON BLOCKS:
 none

 REQUIRES:
 Requires the following program from the IDL Standard Library.
 poly.pro
 Requires the following programs from the IDL Astronomy User's Library.
 (http://idlastro.gsfc.nasa.gov/homepage.html )
 Note: there is a precess.pro also in the JHU/APL IDL Library, but
 this version from the Astronomy User's Library should be used.
 cirrange.pro
 co_aberration.pro
 co_nutate.pro
 ct2lst.pro
 eq2hor.pro
 hadec2altaz.pro
 nutate.pro
 precess.pro
 sunpos.pro
 premat.pro
 Requires the following program from the JHU/APL IDL Library (also included
 in the IDL Astronomy User's Library).
 (http://fermi.jhuapl.edu/s1r/idl/s1rlib/local_idl.html )
 isarray.pro
 Requires the following program that should accompany this file.
 refractivity.pro

 NOTES:

 Example:
 Calculates the atmospheric refraction at five different wavelengths
 for 22 UTC (near local noon at Haleakala) for each day during the year.

 times_noon_1year = FINDGEN(365) + JULDAY(01,01,2006,22.,0.,0.)
 wavelengths = [400,525,630,850,1600]
 atm_ref_struct = atmospheric_refraction(wavelengths, times_noon_1year)
 help,atm_ref_struct,/st
 ** Structure <560540>, 4 tags, length=10244, data length=10244, refs=1:
 REFRACTION_MAG FLOAT Array[365, 5]
 PARALLACTIC_ANGLE DOUBLE Array[365]
 REFRACTION_MAG_UNIT STRING 'arcsec'
 PARALLACTIC_ANGLE_UNIT STRING 'degrees'

 Dispersion is calculated by simply taking the difference between
 the refraction at two different wavelengths
 PRINT,MIN(atm_ref_struct.REFRACTION_MAG(*,0) - atm_ref_struct.REFRACTION_MAG(*,3),MAX=max),max
 0.125757 1.37185

 Calculates the atmospheric refraction at five different wavelengths
 for an entire day, 21 March, 2006

 times_1day = FINDGEN(1440)/1440. + JULDAY(03,21,2006,0.,0.,0.)
 wavelengths = [400,525,630,850,1600]
 atm_ref_struct = atmospheric_refraction(wavelengths, times_1day)
 PLOT,(atm_ref_struct.REFRACTION_MAG(*,0) - atm_ref_struct.REFRACTION_MAG(*,3))>(-20)<20

 This program takes a selection of wavelengths and the four parameters
 describing the atmospheric conditions and calculates the refractivity
 of the air at each wavelength.
 The position of the Sun is calculated for each input time. These two
 values are then combined to provide the magnitude and direction of the
 atmospheric refraction for the Sun.

 The atmospheric conditions are those at the telescope aperture. The
 calculated absolute refraction is probably accurate only for zenith
 distances less than 75 degrees. The atmospheric dispersion may be
 accurate up to zenith distances of 80 degrees.

 The refraction is calculated only for the Sun, but it would be relatively
 trivial to change the program to allow calculations for any position
 on the celestial sphere.

 Haleakala Coordinates: -156.25, 20.71, 3055.
 longitude = -156.25, latitude = 20.71, altitude = 3055.

 La Palma Coordinates: -17.88, 28.76, 2350.
 longitude = -17.88, latitude = 28.76, altitude = 2350.

 Sac Peak Coordinates: -105.8, 32.8, 2900.
 longitude = -105.8, latitude = 32.8, altitude = 2900.

 Default location is Haleakala, Maui, Hawai`i

 see "Reardon, K.P.: 2006, Solar Physics, in press" for more details

 MODIFICATION HISTORY:
 Written, Kevin Reardon, INAF/Osservatorio Astrofisico di Arcetri, 2006