SuperNOVAS v1.5
The NOVAS C library, made better
Loading...
Searching...
No Matches
Atmospheric refraction

Macros

#define NOVAS_DEFAULT_WAVELENGTH   0.55
 [μm] Default wavelength, e.g.
 

Typedefs

typedef double(* RefractionModel) (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
 A function that returns a refraction correction for a given date/time of observation at the given site on earth, and for a given astrometric source elevation.
 

Enumerations

enum  novas_refraction_model {
  NOVAS_NO_ATMOSPHERE = 0 , NOVAS_STANDARD_ATMOSPHERE , NOVAS_WEATHER_AT_LOCATION , NOVAS_RADIO_REFRACTION ,
  NOVAS_WAVE_REFRACTION
}
 Constants that determine whether what model (if any) to use for implicit refraction calculations. More...
 
enum  novas_refraction_type { NOVAS_REFRACT_OBSERVED = -1 , NOVAS_REFRACT_ASTROMETRIC }
 The type of elevation value for which to calculate a refraction. More...
 

Functions

double novas_inv_refract (RefractionModel model, double jd_tt, const on_surface *restrict loc, enum novas_refraction_type type, double el0)
 Computes the reverse atmospheric refraction for a given refraction model.
 
double novas_optical_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
 Returns an optical refraction correction using the weather parameters defined for the observer location.
 
double novas_radio_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
 Atmospheric refraction model for radio wavelengths (Berman & Rockwell 1976).
 
int novas_refract_wavelength (double microns)
 Sets the observing wavelength for which refraction is to be calculated when using a wavelength-depenendent model, such as novas_wave_refraction().
 
double novas_standard_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
 Returns an optical refraction correction for a standard atmosphere.
 
double novas_wave_refraction (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)
 The wavelength-dependent IAU atmospheric refraction model, based on the SOFA iauRefco() function, in compliance to the 'SOFA Software License' terms of the original source.
 
double refract (const on_surface *restrict location, enum novas_refraction_model model, double zd_obs)
 Computes atmospheric optical refraction for an observed (already refracted!) zenith distance through the atmosphere.
 
double refract_astro (const on_surface *restrict location, enum novas_refraction_model model, double zd_astro)
 Computes atmospheric optical refraction for a source at an astrometric zenith distance (e.g.
 

Detailed Description

Macro Definition Documentation

◆ NOVAS_DEFAULT_WAVELENGTH

#define NOVAS_DEFAULT_WAVELENGTH   0.55

[μm] Default wavelength, e.g.

for wavelength-dependent refraction models. It is set to the median wavelength of visible light.

Since
1.4
See also
novas_refract_wavelength()

Typedef Documentation

◆ RefractionModel

typedef double(* RefractionModel) (double jd_tt, const on_surface *loc, enum novas_refraction_type type, double el)

A function that returns a refraction correction for a given date/time of observation at the given site on earth, and for a given astrometric source elevation.

Parameters
jd_tt[day] Terrestrial Time (TT) based Julian data of observation
locPointer to structure defining the observer's location on earth, and local weather
typeWhether the input elevation is observed or astrometric: REFRACT_OBSERVED (-1) or REFRACT_ASTROMETRIC (0).
el[deg] Astrometric (unrefracted) source elevation
Returns
[arcsec] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error).
Since
1.1
See also
novas_app_to_hor(), novas_hor_to_app()

Enumeration Type Documentation

◆ novas_refraction_model

Constants that determine whether what model (if any) to use for implicit refraction calculations.

See also
on_surface, novas_app_to_hor(), novas_hor_to_app(), refract(), refract_astro()
Enumerator
NOVAS_NO_ATMOSPHERE 

Do not apply atmospheric refraction correction.

NOVAS_STANDARD_ATMOSPHERE 

Uses a standard atmospheric model, ignoring any weather values defined for the specific observing location.

See also
novas_standard_refraction(), novas_set_default_weather()
NOVAS_WEATHER_AT_LOCATION 

Uses the weather parameters that are specified together with the observing location.

See also
novas_optical_refraction()
NOVAS_RADIO_REFRACTION 

Uses the Berman & Rockwell 1976 refraction model for Radio wavelengths with the weather parameters specified together with the observing location.

Since
1.4
See also
novas_radio_refraction()
NOVAS_WAVE_REFRACTION 

Uses the IAU / SOFA wavelength-depended refraction model with the weather parameters specified together with the observing location.

The wavelength can be specified via novas_refract_wavelength() or else it is assumed to be 550 nm (visible light).

Since
1.4
See also
novas_wave_refraction(), novas_refract_wavelength()

◆ novas_refraction_type

The type of elevation value for which to calculate a refraction.

See also
RefractionModel, novas_app_to_hor(), novas_hor_to_app()
Since
1.1
Enumerator
NOVAS_REFRACT_OBSERVED 

Refract observed elevation value.

NOVAS_REFRACT_ASTROMETRIC 

Refract astrometric elevation value.

Function Documentation

◆ novas_inv_refract()

double novas_inv_refract ( RefractionModel model,
double jd_tt,
const on_surface *restrict loc,
enum novas_refraction_type type,
double el0 )

Computes the reverse atmospheric refraction for a given refraction model.

Thus if a refraction model takes observed elevation as an input, the reverse refraction takes astrometric elevation as its input, and vice versa.

Parameters
modelThe original refraction model
jd_tt[day] Terrestrial Time (TT) based Julian data of observation
locPointer to structure defining the observer's location on earth, and local weather
typeRefraction type to use for the original model: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
el0[deg] input elevation for the inverse refraction model.
Returns
[deg] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error).
See also
refract_astro(), itrs_to_hor()
Since
1.1
Author
Attila Kovacs

References novas_inv_max_iter, and NOVAS_REFRACT_OBSERVED.

◆ novas_optical_refraction()

double novas_optical_refraction ( double jd_tt,
const on_surface * loc,
enum novas_refraction_type type,
double el )

Returns an optical refraction correction using the weather parameters defined for the observer location.

As such, make sure that temperature and pressure are defined, e.g. set after calling e.g. make_gps_site(), make_itrf_site(),make_xyz_site()`, or similar call that initializes the observing site.

Parameters
jd_tt[day] Terrestrial Time (TT) based Julian data of observation (unused in this implementation of RefractionModel)
locPointer to structure defining the observer's location on earth, and local weather values (temperature and pressure are used by this call).
typeWhether the input elevation is observed or astrometric: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
el[deg] Astrometric (unrefracted) source elevation
Returns
[arcsec] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error).
See also
novas_wave_refraction(), novas_radio_refraction(), novas_standard_refraction()
refract(), refract_astro()

References NOVAS_WEATHER_AT_LOCATION.

◆ novas_radio_refraction()

double novas_radio_refraction ( double jd_tt,
const on_surface * loc,
enum novas_refraction_type type,
double el )

Atmospheric refraction model for radio wavelengths (Berman & Rockwell 1976).

It uses the weather parameters defined for the location, including humidity. As such, make sure the weather data is fully defined, and that the humidity was explicitly set after calling e.g. make_gps_site(), make_itrf_site(),make_xyz_site()`, or similar call that initializes the observing site.

Adapted from FORTAN code provided by Berman & Rockwell 1976.

REFERENCES:

  1. Berman, Allan L., and Rockwell, Stephen T. (1976), NASA JPL Technical Report 32-1601
Parameters
jd_tt[day] Terrestrial Time (TT) based Julian data of observation (unused in this implementation of RefractionModel)
locPointer to structure defining the observer's location on earth, and local weather. Make sure all weather values, including humidity (added in v1.1), are fully populated.
typeWhether the input elevation is observed or astrometric: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
el[deg] source elevation of the specified type.
Returns
[deg] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error). An error is returned if the location is NULL, or if the weather parameters are way outside of their resonable ranges, or if the elevation is outside the supported [-1:90] range.
See also
novas_optical_refraction(), novas_wave_refraction(), novas_standard_refraction()
make_itrf_site(), make_gps_site(), make_xyz_site(), make_itrf_observer(), make_gps_observer()

References on_surface::humidity, novas_inv_refract(), novas_radio_refraction(), NOVAS_REFRACT_ASTROMETRIC, NOVAS_REFRACT_OBSERVED, on_surface::pressure, and on_surface::temperature.

◆ novas_refract_wavelength()

int novas_refract_wavelength ( double microns)

Sets the observing wavelength for which refraction is to be calculated when using a wavelength-depenendent model, such as novas_wave_refraction().

Parameters
microns[μm] Observed wavelength to assume in refraction calculations
Returns
0 if successful, or else -1 (errno set to EINVAL) if the wavelength invalid (zero, negative, or NaN).
Since
1.4
Author
Attila Kovacs
See also
novas_wave_refraction(), NOVAS_DEFAULT_WAVELENGTH

◆ novas_standard_refraction()

double novas_standard_refraction ( double jd_tt,
const on_surface * loc,
enum novas_refraction_type type,
double el )

Returns an optical refraction correction for a standard atmosphere.

Parameters
jd_tt[day] Terrestrial Time (TT) based Julian data of observation (unused in this implementation of RefractionModel)
locPointer to structure defining the observer's location on earth, and local weather
typeWhether the input elevation is observed or astrometric: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
el[deg] Astrometric (unrefracted) source elevation
Returns
[deg] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error).
See also
novas_optical_refraction(), novas_radio_refraction(), novas_wave_refraction()
refract(), refract_astro()

References NOVAS_STANDARD_ATMOSPHERE.

◆ novas_wave_refraction()

double novas_wave_refraction ( double jd_tt,
const on_surface * loc,
enum novas_refraction_type type,
double el )

The wavelength-dependent IAU atmospheric refraction model, based on the SOFA iauRefco() function, in compliance to the 'SOFA Software License' terms of the original source.

Our implementation is not provided nor it is endorsed by SOFA. The original function has been modified slightly, such as:

  1. Out-of-range weather parameters will return with an error (errno set to EINVAL), unlike the SOFA implementation, which sets minimal or maximal allowed values for these.
  2. The algorithm has been simplified to use fewer variables and simpler logic.
  3. The SOFA function this implementation is based on returns A/B coefficients, whereas this implementation returns the refraction correction angle.

The refraction is calculated for the observing wavelenth previously set via novas_refract_wavelength(), or for visible light at 550 nm by default.

The function uses the weather parameters defined for the location, including humidity. As such, make sure the weather data is fully defined, and that the humidity was explicitly set after calling e.g. make_gps_site(), make_itrf_site(),make_xyz_site()`, or similar call that initializes the observing site.

According to the documentation of SOFA's iauRefco() function, the model has the following accuracy for elevation angles between 15 and 75 degrees, under a range of typical surface conditions:

worst RMS
optical/IR 62 mas 8 mas
radio 319 mas 49 mas

NOTES:

  1. From the SOFA documentation: "The model balances speed and accuracy to give good results in applications where performance at low altitudes is not paramount. Performance is maintained across a range of conditions, and applies to both optical/IR and radio."
  2. The model is divergent in the observed direction of the horizon. As such, it should not be used for calculating refraction at or below the horizon itself.

REFERENCES:

  1. Crane, R.K., Meeks, M.L. (ed), "Refraction Effects in the Neutral Atmosphere", Methods of Experimental Physics: Astrophysics 12B, Academic Press, 1976.
  2. Gill, Adrian E., "Atmosphere-Ocean Dynamics", Academic Press, 1982.
  3. Green, R.M., "Spherical Astronomy", Cambridge University Press, 1987.
  4. Hohenkerk, C.Y., & Sinclair, A.T., NAO Technical Note No. 63, 1985.
  5. Rueger, J.M., "Refractive Index Formulae for Electronic Distance Measurement with Radio and Millimetre Waves", in Unisurv Report S-68, School of Surveying and Spatial Information Systems, University of New South Wales, Sydney, Australia, 2002.
  6. Stone, Ronald C., P.A.S.P. 108, 1051-1058, 1996.
Parameters
jd_tt[day] Terrestrial Time (TT) based Julian data of observation (unused in this implementation of RefractionModel)
locPointer to structure defining the observer's location on earth, and local weather. Make sure all weather values, including humidity (added in v1.1), are fully populated.
typeWhether the input elevation is observed or astrometric: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
el[deg] observed source elevation of the specified type.
Returns
[deg] Estimated refraction, or NAN if there was an error (it should also set errno to indicate the type of error), e.g. because the location is NULL, or because the weather parameters are outside of the supported (sensible) range, or because the elevation is outside of the supported (0:90] range, or because the wavelength set is below 100 nm (0.1 μm);
Since
1.4
Author
Attila Kovacs
See also
novas_refract_wavelength(), novas_optical_refraction(), novas_radio_refraction()
make_gps_site(), make_itrf_site(), make_xyz_site(), make_gps_observer(), make_itrf_observer()

References on_surface::humidity, novas_inv_refract(), NOVAS_REFRACT_ASTROMETRIC, NOVAS_REFRACT_OBSERVED, novas_wave_refraction(), on_surface::pressure, and on_surface::temperature.

◆ refract()

double refract ( const on_surface *restrict location,
enum novas_refraction_model model,
double zd_obs )

Computes atmospheric optical refraction for an observed (already refracted!) zenith distance through the atmosphere.

In other words this is suitable to convert refracted zenith angles to astrometric (unrefracted) zenith angles. For the reverse, see refract_astro().

The returned value is the approximate refraction for optical wavelengths. This function can be used for planning observations or telescope pointing, but should not be used for precise positioning.

NOTES:

  1. The standard temeperature model includes a very rough estimate of the mean annual temeprature for the ovserver's latitude and elevation, rather than the 10 C everywhere assumption in NOVAS C 3.1.<.li>

REFERENCES:

  1. Explanatory Supplement to the Astronomical Almanac, p. 144.
  2. Bennett, G. (1982), Journal of Navigation (Royal Institute) 35, pp. 255-259.
Parameters
locationPointer to structure containing observer's location. It may also contains weather data (optional) for the observer's location. Some, but not all, refraction models will use location-based (e.g. weather) information. For models that do not need it, it may be NULL.
modelThe built in refraction model to use. E.g. NOVAS_STANDARD_ATMOSPHERE (1), or NOVAS_WEATHER_AT_LOCATION (2)...
zd_obs[deg] Observed (already refracted!) zenith distance through the atmosphere.
Returns
[deg] the calculated optical refraction or 0.0 if the location is NULL or the option is invalid or the 'zd_obs' is invalid (<90°).
See also
refract_astro(), hor_to_itrs()

References NOVAS_NO_ATMOSPHERE, NOVAS_RADIO_REFRACTION, novas_radio_refraction(), NOVAS_REFRACT_OBSERVED, NOVAS_REFRACTION_MODELS, novas_set_default_weather(), NOVAS_WAVE_REFRACTION, novas_wave_refraction(), NOVAS_WEATHER_AT_LOCATION, on_surface::pressure, and on_surface::temperature.

◆ refract_astro()

double refract_astro ( const on_surface *restrict location,
enum novas_refraction_model model,
double zd_astro )

Computes atmospheric optical refraction for a source at an astrometric zenith distance (e.g.

calculated without accounting for an atmosphere). This is suitable for converting astrometric (unrefracted) zenith angles to observed (refracted) zenith angles. See refract() for the reverse correction.

The returned value is the approximate refraction for optical wavelengths. This function can be used for planning observations or telescope pointing, but should not be used for precise positioning.

REFERENCES:

  1. Explanatory Supplement to the Astronomical Almanac, p. 144.
  2. Bennett, G. (1982), Journal of Navigation (Royal Institute) 35, pp. 255-259.
Parameters
locationPointer to structure containing observer's location. It may also contains weather data (optional) for the observer's location. Some, but not all, refraction models will use location-based (e.g. weather) information. For models that do not need it, it may be NULL.
modelThe built in refraction model to use. E.g. NOVAS_STANDARD_ATMOSPHERE (1), or NOVAS_WEATHER_AT_LOCATION (2)...
zd_astro[deg] Astrometric (unrefracted) zenith distance angle of the source.
Returns
[deg] the calculated optical refraction. (to ~0.1 arcsec accuracy), or 0.0 if the location is NULL or the option is invalid.
See also
refract(), itrs_to_hor()
Since
1.0
Author
Attila Kovacs

References novas_inv_max_iter, NOVAS_RADIO_REFRACTION, novas_radio_refraction(), NOVAS_REFRACT_ASTROMETRIC, and refract().