The p3d logo. a general data-reduction tool for fiber-fed integral-field spectrographs
About p3d

Readme

Download

References

Documentation & Tutorials

Links

Screenshots

Authors & Thanks

Sourceforge project page

Category: differential atmospheric refraction

Summary

PROp3d_darc_amplitude_iag
Calculates the amplitude of the differential atmospheric refraction.
PROp3d_darc_parangle
Calculates the parallactic angle, the elevation above the horizon, and the azimuthal angle from the declination, the hour angle, and the latitude of the observations.
FUNCTIONp3d_misc_sla_airmas
Calculates the airmass at given zenith distance (double precision).
FUNCTIONp3d_misc_sla_drange
Normalize angle into range ± pi (double precision).
PROp3d_misc_sla_pda2h
Converts latitude, declination, and azimuth to hour angle.
PROp3d_misc_sla_pdq2h
Converts parallactic angle to hour angle.
PROp3d_misc_sla_refro
Atmospheric refraction for radio and optical/IR wavelengths.
FUNCTIONp3d_misc_sla_zd
Converts hour angle (HA) and declination (DEC) to zenith distance.

Copyright

p3d: a general data-reduction tool for fiber-fed IFSs

Copyright 2009-2015 Leibniz Institute for Astrophysics Potsdam (AIP)

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <http://www.gnu.org/licenses>.

Additional permission under GNU GPL version 3 section 7

If you modify this Program, or any covered work, by linking or combining it with IDL (or a modified version of that library), containing parts covered by the terms of the IDL license, the licensors of this Program grant you additional permission to convey the resulting work.

Routine Documentation

routines/p3d_darc_amplitude_iag.pro, line 145, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_darc_amplitude_iag, zenithdistance, lambda, temperature, relhumidity, pressure, refraction, refraction2, lambda0=, topwid=, logunit=, verbose=, error=, /debug, /help

Calculates the amplitude of the differential atmospheric refraction.

The index of refraction is calculated according to the formalism of Ciddor (1996) and Edlén (1966). The equation in the first paper has also been adopted by the International Association of Geodesy (IAG) as the standard equation for calculating index of refraction in air.

All equation references refer to the NIST web-page.

References

Edlén, B. 1966, Metrologia 2, 71, "The refractive index of air".

Birch, K.P., Reinboth, F., Ward, R.E., and Wilkening, G. 1993, Metrologia 30, 7, "The effect of variations in the refractive index of industrial air upon the uncertainty of precision length measurement".

Ciddor, P.E. 1996, Appl. Optics, 35, 1566, "Refractive index of air: new equations for the visible and near infrared".

Huang, P.H. 1998, in: Papers and abstracts from the third international symposium on humidity and moisture, 1, 69, National Physical Laboratory, Teddington, Middlesex, UK, April 1998, "New equations for water vapor pressure in the temperature range -100 °C to 100 °C for use with the 1997 NIST/ASME steam tables".

Links

Everything is well documented at the NIST web-page: http://emtoolbox.nist.gov/Wavelength/Documentation.asp

Input parameters:
zenithdistanceA scalar decimal value that specifies the Zenith distance. The unit is degrees [°].
lambdaA decimal value array that specifies the wavelengths where the amplitude is calculated [Å].
temperatureA scalar decimal value that specifies the temperature [°C].
relhumidityA scalar decimal value that specifies the relative humidity [%].
pressureA scalar decimal value that specifies the pressure [mbar].
Keyword parameters:
lambda0A scalar decimal value that specifies the reference (pivot) wavelength [Å]. The default value is: 5000
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_darc_parangle.pro, line 113, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_darc_parangle, declination, hourangle, latitude, parangle, elevation, azimuth, topwid=, logunit=, verbose=, error=, /debug, /help

Calculates the parallactic angle, the elevation above the horizon, and the azimuthal angle from the declination, the hour angle, and the latitude of the observations.

Input parameters:
declinationA scalar decimal value that specifies the declination of the observations. This value must be specified in degrees.
hourangleA scalar decimal value that specifies the hour angle of the observations. This value must be specified in degrees.
latitudeA scalar decimal value that specifies the latitude of the observatory where the observations were done. This value must be specified in degrees.
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_sla_airmas.pro, line 130, last changed at 2015-10-19 by christersandin (revision 3628)

airmass = p3d_misc_sla_airmas(zenithdistance, topwid=, logunit=, verbose=, error=, /debug, /help)

Calculates the airmass at given zenith distance (double precision).

This routine was adapted from the Starlink project SLA AIRMAS FORTRAN routine (GPLv2); the used version of the original routine is dated 18 March 1999, P.T.Wallace. Original code by P.W. Hill, St Andrews.

Notes from the original routine:

1

The "observed" zenith distance referred to above means "as affected by refraction".

2

Uses Hardie's (1962) polynomial fit to Bemporad's data for the relative air mass, X, in units of thickness at the zenith as tabulated by Schoenberg (1929). This is adequate for all normal needs as it is accurate to better than 0.1% up to X=6.8 and better than 1% up to X=10. Bemporad's tabulated values are unlikely to be trustworthy to such accuracy because of variations in density, pressure and other conditions in the atmosphere from those assumed in his work.

3

The sign of the Zenith distance is ignored.

4

At zenith distances greater than about zenithdistance=87 degrees the air mass is held constant to avoid arithmetic overflows.

== References ==

Hardie, R.H., 1962, in "Astronomical Techniques" ed. W.A. Hiltner, University of Chicago Press, 180.

Schoenberg, E., 1929, Hdb. d. Ap., Berlin, Julius Springer, 2, 268.

Input parameters:
zenithdistanceA scalar decimal value that specifies the zenith distance in degrees.
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
airmassA scalar decimal value that specifies the normalized angle.

routines/p3d_misc_sla_drange.pro, line 106, last changed at 2015-10-19 by christersandin (revision 3628)

oangle = p3d_misc_sla_drange(angle, topwid=, logunit=, verbose=, error=, /debug, /help)

Normalize angle into range ± pi (double precision).

This routine was adapted from the Starlink project SLA DRANGE FORTRAN routine (GPLv2). The used version of the original routine is dated: 23 November 1995, P.T.Wallace.

Input parameters:
angleA scalar decimal value that specifies an angle in radians. of the observatory where the observations were done. This value must be specified in degrees.
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
oangleA scalar decimal value that specifies the normalized angle.

routines/p3d_misc_sla_pda2h.pro, line 112, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_sla_pda2h, latitude, declination, azimuth, hourangle, topwid=, logunit=, verbose=, error=, /debug, /help

Converts latitude, declination, and azimuth to hour angle.

This routine is a modified version of the SLA PDA2H FORTRAN routine of the Starlink project (pda2h.f).

Notes of the original routine: P.T.Wallace, Starlink, 6 October 1994

Input parameters:
latitudeA scalar decimal value that specifies the latitude of the observatory where the observations were done. This value must be specified in degrees.
eclinationA scalar decimal value that specifies the declination of the observations. This value must be specified in degrees.
azimuthA scalar decimal value that specifies the azimuth. This value must be specified in degrees.
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
hourangleA scalar decimal value that specifies both, one or no value. Only the calculated valid hour angles of the observations are returned. The unit is degrees.

routines/p3d_misc_sla_pdq2h.pro, line 112, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_sla_pdq2h, latitude, declination, parangle, hourangle, topwid=, logunit=, verbose=, error=, /debug, /help

Converts parallactic angle to hour angle.

This routine is a modified version of the SLA PDQ2H FORTRAN routine of the Starlink project (pdq2h.f). The used version of the original routine is dated: P.T.Wallace, Starlink, 6 October 1994.

Input parameters:
latitudeA scalar decimal value that specifies the latitude of the observatory where the observations were done. This value must be specified in degrees.
eclinationA scalar decimal value that specifies the declination of the observations. This value must be specified in degrees.
parangleA scalar decimal value that specifies the parallactic angle. This value must be specified in degrees.
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_sla_refro.pro, line 322, last changed at 2015-10-19 by christersandin (revision 3628)

p3d_misc_sla_refro, zenithdistance, obselevation, temperature, pressure, relhumidity, lambda, latitude, dr, templapserate=, eps=, lambda0=, topwid=, logunit=, verbose=, error=, /debug, /help

Atmospheric refraction for radio and optical/IR wavelengths.

This routine is a modified version of the Starlink project SLA REFRO FORTRAN routine (GPLv2). The routine has been translated to IDL, in order to work with p3d. Last revision of the original file is dated: 5 December 2005, P.T.Wallace.

Here are the notes from the original routine:

1

A suggested value for the TEMPLAPSERATE argument is 0.0065d0. The refraction is significantly affected by TEMPLAPSERATE, and if studies of the local atmosphere have been carried out a better TEMPLAPSERATE value may be available. The sign of the supplied TEMPLAPSERATE value is ignored.

2

A suggested value for the EPS argument is 1D-8. The result is usually at least two orders of magnitude more computationally precise than the supplied EPS value.

3

The routine computes the refraction for zenith distances up to to and a little beyond 90 deg using the method of Hohenkerk and Sinclair (NAO Technical Notes 59 and 63, subsequently adopted in the Explanatory Supplement, 1992 edition – see section 3.281).

4

The code is a development of the optical/IR refraction subroutine AREF of C.Hohenkerk (HMNAO, September 1984), with extensions to support the radio case. Apart from merely cosmetic changes, the following modifications to the original HMNAO optical/IR refraction code have been made:

  • Any value of ZENITHDISTANCE is allowed (see note 6, below).

  • Other argument values have been limited to safe values.

  • Murray's values for the gas constants have been used (Vectorial Astrometry, Adam Hilger, 1983).

  • The numerical integration phase has been rearranged for extra clarity.

  • A better model for Ps(T) has been adopted (taken from Gill, Atmosphere-Ocean Dynamics, Academic Press, 1982).

  • More accurate expressions for Pwo have been adopted (again from Gill 1982).

  • The formula for the water vapour pressure, given the saturation pressure and the relative humidity, is from Crane (1976), expression 2.5.5.

  • Provision for radio wavelengths has been added using expressions devised by A.T.Sinclair, RGO (priv. comm. 1989). The refractivity model currently used is from J.M.Rueger, "Refractive Index Formulae for Electronic Distance Measurement with Radio and Millimetre Waves", in Unisurv Report S-68 (2002), School of Surveying and Spatial Information Systems, University of New South Wales, Sydney, Australia.

  • The optical refractivity for dry air is from Resolution 3 of the International Association of Geodesy adopted at the XXIIth General Assembly in Birmingham, UK, 1999.

  • Various small changes have been made to gain speed.

5

The radio refraction is chosen by specifying WL>100 micrometres. Because the algorithm takes no account of the ionosphere, the accuracy deteriorates at low frequencies, below about 30 MHz.

6

Before use, the value of ZENITHDISTANCE is expressed in the range +/– pi. If this ranged ZENITHDISTANCE is -ve, the result REF is computed from its absolute value before being made -ve to match. In addition, if it has an absolute value greater than 93 deg, a fixed REF value equal to the result for ZENITHDISTANCE=93 deg is returned, appropriately signed.

7

As in the original Hohenkerk and Sinclair algorithm, fixed values of the water vapour polytrope exponent, the height of the tropopause, and the height at which refraction is negligible are used.

8

The radio refraction has been tested against work done by Iain Coulson, JACH, (priv. comm. 1995) for the James Clerk Maxwell Telescope, Mauna Kea. For typical conditions, agreement at the 0.1 arcsec level is achieved for moderate ZENITHDISTANCE, worsening to perhaps 0.5-1.0 arcsec at ZENITHDISTANCE 80 deg. At hot and humid sea-level sites the accuracy will not be as good.

9

It should be noted that the relative humidity RELHUMIDITY is formally defined in terms of "mixing ratio" rather than pressures or densities as is often stated. It is the mass of water per unit mass of dry air divided by that for saturated air at the same temperature and pressure (see Gill 1982).

10

The algorithm is designed for observers in the troposphere. The supplied temperature, pressure and lapse rate are assumed to be for a point in the troposphere and are used to define a model atmosphere with the tropopause at 11km altitude and a constant temperature above that. However, in practice, the refraction values returned for stratospheric observers, at altitudes up to 25km, are quite usable.

Input parameters:
zenithdistanceA scalar decimal value that specifies the zenith distance of the source. The unit is degrees [°].
obselevationA scalar decimal value that specifies the elevation of the telescope/observer. The unit is meters. The elevation must be > -1000.
temperatureA scalar decimal value that specifies the ambient temperature at the observer. The unit is degrees Celcius [°C].
pressureA scalar decimal value that specifies the pressure at the observer. The unit is millibar [mbar||hPa].
relhumidityA scalar decimal value that specifies the relative humidity at the observer. The unit is per cent [%].
lambdaA decimal value array that specifies the wavelengths where the amplitude is calculated [Å].
latitudeA scalar decimal value that specifies the latitude of the observer. The unit is degrees [°].
Keyword parameters:
templapserate- A scalar decimal value that specifies the temperature lapse rate in the troposphere. The unit is degrees Celcius per meter [°C/m]. The default value is: 0.0065
epsA scalar decimal value that specifies the precision that is required to terminate the iteration. The default value is: 1.0d-8
lambda0A scalar decimal value that specifies the reference wavelength [Å]. The default value is: 5000
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
helpSet this keyword to show this routine documentation, and then exit.

routines/p3d_misc_sla_zd.pro, line 132, last changed at 2015-10-19 by christersandin (revision 3628)

zenithdistance = p3d_misc_sla_zd(hourangle, declination, latitude, topwid=, logunit=, verbose=, error=, /debug, /help)

Converts hour angle (HA) and declination (DEC) to zenith distance.

The result is in the range 0 to 90 degrees. The used version of the original routine is dated: P.T.Wallace, Starlink, 3 April 1994.

This routine is a modified version of the SLA ZD FORTRAN routine of the Starlink project (zd.f).

Notes of the original routine:

1

The latitude must be geodetic. In critical applications, corrections for polar motion should be applied.

2

In some applications it will be important to specify the correct type of hour angle and declination in order to produce the required type of zenith distance. In particular, it may be important to distinguish between the zenith distance as affected by refraction, which would require the "observed" HA,Dec, and the zenith distance in vacuo, which would require the "topocentric" HA,Dec. If the effects of diurnal aberration can be neglected, the "apparent" HA,Dec may be used instead of the topocentric HA,Dec.

3

No range checking of arguments is done.

4

In applications which involve many zenith distance calculations, rather than calling the present routine it will be more efficient to use inline code, having previously computed fixed terms such as sine and cosine of latitude, and perhaps sine and cosine of declination.

Input parameters:
hourangleA scalar decimal value that specifies the hour angle. The unit is degrees [°].
declinationA scalar decimal value that specifies the declination. The unit is degrees [°].
latitudeA scalar decimal value that specifies the latitide of the observer. The unit is degrees [°].
Keyword parameters:
topwidIf set, then error messages are displayed using DIALOG_MESSAGE, using this widget id as DIALOG_PARENT, instead of MESSAGE.
logunitMessages are saved to the file pointed to by this logical file unit, if it is defined.
verboseSet this parameter to a positive scalar integer to make p3d write some information on STDOUT about what is going on. The following four values are acknowledged:

0

Writes no information at all. This is the default.

1

Writes the more important information; regarding subroutine configurations, mostly.

2

Writes most information; includes a more verbose output than 1.

3

Writes all information, including information on the execution state of GUI subroutines. This may be a useful mode when debugging the code.

errorThis scalar integer returns an error code if set. Any value different from zero means that an error has occurred.
debugNo error handler is setup if this keyword is set. The default is otherwise to setup an error handler (using the routine CATCH), which makes each subroutine exit quietly in case a bug is encountered. Use this keyword when debugging p3d.
helpSet this keyword to show this routine documentation, and then exit.
Output parameters:
zenithdistanceThe Zenith distance, in degrees [°].

page last updated on: Wednesday June 28, 2017 11:06:27; retrieved on: Tuesday September 26, 2017 03:36:15