Loading...
Searching...
No Matches
Atmospheric refraction

Accounting for atmopheric refraction for observers on or above Earth's surface. More...

## Classes

class | supernovas::Horizontal
| Horizontal (azimuth, elevation = Az/El) sky coordinates at a geodetic observing location, such as an observatory site, an aircraft, or a balloon. More...
class | supernovas::Weather
| Weather data, mainly for atmospheric refraction correction for Earth-based (geodetic) observers. More...

## Macros

#define | NOVAS_DEFAULT_WAVELENGTH 0.55
| [μm] Default wavelength, for wavelength-dependent refraction models.

## 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.

## Functions

Weather | supernovas::Site::average_weather () const
| Returns a default mean annual weather for this site based on a simple global 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.
Horizontal | supernovas::Horizontal::to_refracted (RefractionModel ref, const Weather &weather=Weather::standard(), const Time &time=Time::undefined())
| Applies atmospheric refraction correction for these coordinates, returning the result.
Horizontal | supernovas::Horizontal::to_unrefracted (RefractionModel ref, const Weather &weather=Weather::standard(), const Time &time=Time::undefined())
| Undoes atmospheric refraction correction for these coordinates, returning the result.

## Detailed Description

Accounting for atmopheric refraction for observers on or above Earth's surface.

SuperNOVAS provides various atmopsheric refraction models. Some use the specified weather parameters, while others use a standard weather for the observer location. Some models are wavelength dependent, so user's can (should) specify a observing wavelength when using them.

## Macro Definition Documentation

## NOVAS_DEFAULT_WAVELENGTH

#define NOVAS_DEFAULT_WAVELENGTH 0.55

[μm] Default wavelength, 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
  loc | Pointer to structure defining the observer's location on earth, and local weather
  type | Whether 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).

Since
  1.1

See also
  novas_app_to_hor(), novas_hor_to_app()

## Function Documentation

## average_weather()

Weather supernovas::Site::average_weather | ( |  | ) | const

Returns a default mean annual weather for this site based on a simple global model.

It is best to use actual weather parameters, but as a blind default these represent something that is 'typical' for the observing site.

Returns
  the 'typical' mean annual weather at this site, based on a very simple global model.

Since
  1.6

References novas_on_surface::humidity, supernovas::Unit::mbar, novas_set_default_weather(), novas_on_surface::pressure, and novas_on_surface::temperature.

## 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)
  loc | Pointer to structure defining the observer's location on earth, and local weather values (temperature and pressure are used by this call).
  type | Whether 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_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)
  loc | Pointer 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.
  type | Whether the input elevation is observed or astrometric: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
  el | [deg] source elevation angle 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 novas_on_surface::humidity, novas_inv_refract(), novas_radio_refraction(), NOVAS_REFRACT_ASTROMETRIC, NOVAS_REFRACT_OBSERVED, novas_on_surface::pressure, and novas_on_surface::temperature.

Referenced by novas_radio_refraction(), refract(), and refract_astro().

## 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)
  loc | Pointer to structure defining the observer's location on earth, and local weather
  type | Whether the input elevation is observed or astrometric: NOVAS_REFRACT_OBSERVED (-1) or NOVAS_REFRACT_ASTROMETRIC (0).
  el | [deg] Source elevation angle 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).

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)
  loc | Pointer 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.
  type | Whether 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 novas_on_surface::humidity, novas_inv_refract(), NOVAS_REFRACT_ASTROMETRIC, NOVAS_REFRACT_OBSERVED, novas_wave_refraction(), novas_on_surface::pressure, and novas_on_surface::temperature.

Referenced by novas_wave_refraction(), and refract().

## to_refracted()

Horizontal supernovas::Horizontal::to_refracted | ( | RefractionModel | ref,
|  | const Weather & | weather = Weather::standard(),
|  | const Time & | time = Time::undefined() )

Applies atmospheric refraction correction for these coordinates, returning the result.

Parameters

  ref | refraction model to use, or NULL to skip refraction correction
  weather | (optional) local weather parameters to use for the refraction correction. (default: standard atmopshere).
  time | (optional) Time of observation, for time-dependent refraction models.

Returns
  refracted horizontal coordinates.

Since
  1.6

See also
  to_unrefracted()

References supernovas::Unit::deg, elevation(), supernovas::Validating::is_valid(), supernovas::Time::jd(), supernovas::Spherical::latitude(), supernovas::Spherical::longitude(), and NOVAS_REFRACT_ASTROMETRIC.

## to_unrefracted()

Horizontal supernovas::Horizontal::to_unrefracted | ( | RefractionModel | ref,
|  | const Weather & | weather = Weather::standard(),
|  | const Time & | time = Time::undefined() )

Undoes atmospheric refraction correction for these coordinates, returning the result.

Parameters

  ref | refraction model to use, or NULL to skip refraction correction
  weather | (optional) local weather parameters to use for the refraction correction. (default: standard atmopshere).
  time | (optional) Time of observation, for time-dependent refraction models.

Returns
  refracted horizontal coordinates.
  unrefracted (astrometric) horizontal coordinates.

Since
  1.6

See also
  to_refracted()

References supernovas::Unit::deg, elevation(), supernovas::Validating::is_valid(), supernovas::Time::jd(), supernovas::Spherical::latitude(), supernovas::Spherical::longitude(), and NOVAS_REFRACT_OBSERVED.