WCSLIB: spx.h File Reference

WCSLIB 8.9

Loading...
Searching...
No Matches
Data Structures | Macros | Enumerations | Functions | Variables
spx.h File Reference

Go to the source code of this file.

## Data Structures
struct | spxprm
| Spectral variables and their derivatives. More...

## Macros
#define | SPXLEN (sizeof(struct spxprm)/sizeof(int))
| Size of the spxprm struct in int units.
#define | SPX_ARGS
| For use in declaring spectral conversion function prototypes.

## Enumerations
enum | spx_errmsg { SPXERR_SUCCESS = 0 , SPXERR_NULL_POINTER = 1 , SPXERR_BAD_SPEC_PARAMS = 2 , SPXERR_BAD_SPEC_VAR = 3 , SPXERR_BAD_INSPEC_COORD = 4 }
| Status return messages. More...

## Functions
int | specx (const char *type, double spec, double restfrq, double restwav, struct spxprm *specs)
| Spectral cross conversions (scalar).
int | spxperr (const struct spxprm *spx, const char *prefix)
| Print error messages from a spxprm struct.
int | freqafrq (SPX_ARGS)
| Convert frequency to angular frequency (vector).
int | afrqfreq (SPX_ARGS)
| Convert angular frequency to frequency (vector).
int | freqener (SPX_ARGS)
| Convert frequency to photon energy (vector).
int | enerfreq (SPX_ARGS)
| Convert photon energy to frequency (vector).
int | freqwavn (SPX_ARGS)
| Convert frequency to wave number (vector).
int | wavnfreq (SPX_ARGS)
| Convert wave number to frequency (vector).
int | freqwave (SPX_ARGS)
| Convert frequency to vacuum wavelength (vector).
int | wavefreq (SPX_ARGS)
| Convert vacuum wavelength to frequency (vector).
int | freqawav (SPX_ARGS)
| Convert frequency to air wavelength (vector).
int | awavfreq (SPX_ARGS)
| Convert air wavelength to frequency (vector).
int | waveawav (SPX_ARGS)
| Convert vacuum wavelength to air wavelength (vector).
int | awavwave (SPX_ARGS)
| Convert air wavelength to vacuum wavelength (vector).
int | velobeta (SPX_ARGS)
| Convert relativistic velocity to relativistic beta (vector).
int | betavelo (SPX_ARGS)
| Convert relativistic beta to relativistic velocity (vector).
int | freqvelo (SPX_ARGS)
| Convert frequency to relativistic velocity (vector).
int | velofreq (SPX_ARGS)
| Convert relativistic velocity to frequency (vector).
int | freqvrad (SPX_ARGS)
| Convert frequency to radio velocity (vector).
int | vradfreq (SPX_ARGS)
| Convert radio velocity to frequency (vector).
int | wavevelo (SPX_ARGS)
| Conversions between wavelength and velocity types (vector).
int | velowave (SPX_ARGS)
| Convert relativistic velocity to vacuum wavelength (vector).
int | awavvelo (SPX_ARGS)
| Convert air wavelength to relativistic velocity (vector).
int | veloawav (SPX_ARGS)
| Convert relativistic velocity to air wavelength (vector).
int | wavevopt (SPX_ARGS)
| Convert vacuum wavelength to optical velocity (vector).
int | voptwave (SPX_ARGS)
| Convert optical velocity to vacuum wavelength (vector).
int | wavezopt (SPX_ARGS)
| Convert vacuum wavelength to redshift (vector).
int | zoptwave (SPX_ARGS)
| Convert redshift to vacuum wavelength (vector).

## Variables
const char * | spx_errmsg []

## Detailed Description

Routines in this suite implement the spectral coordinate systems recognized by the FITS World Coordinate System (WCS) standard, as described in

"Representations of world coordinates in FITS",
Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
"Representations of spectral coordinates in FITS",
Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
2006, A&A, 446, 747 (WCS Paper III)

specx() is a scalar routine that, given one spectral variable (e.g. frequency), computes all the others (e.g. wavelength, velocity, etc.) plus the required derivatives of each with respect to the others. The results are returned in the spxprm struct.

spxperr() prints the error message(s) (if any) stored in a spxprm struct.

The remaining routines are all vector conversions from one spectral variable to another. The API of these functions only differ in whether the rest frequency or wavelength need be supplied.

Non-linear:

- freqwave() frequency -> vacuum wavelength

- wavefreq() vacuum wavelength -> frequency

- freqawav() frequency -> air wavelength

- awavfreq() air wavelength -> frequency

- freqvelo() frequency -> relativistic velocity

- velofreq() relativistic velocity -> frequency

- waveawav() vacuum wavelength -> air wavelength

- awavwave() air wavelength -> vacuum wavelength

- wavevelo() vacuum wavelength -> relativistic velocity

- velowave() relativistic velocity -> vacuum wavelength

- awavvelo() air wavelength -> relativistic velocity
- veloawav() relativistic velocity -> air wavelength

Linear:

- freqafrq() frequency -> angular frequency

- afrqfreq() angular frequency -> frequency

- freqener() frequency -> energy

- enerfreq() energy -> frequency

- freqwavn() frequency -> wave number

- wavnfreq() wave number -> frequency

- freqvrad() frequency -> radio velocity

- vradfreq() radio velocity -> frequency

- wavevopt() vacuum wavelength -> optical velocity

- voptwave() optical velocity -> vacuum wavelength

- wavezopt() vacuum wavelength -> redshift

- zoptwave() redshift -> vacuum wavelength

- velobeta() relativistic velocity -> beta ( )
- betavelo() beta ( ) -> relativistic velocity

These are the workhorse routines, to be used for fast transformations. Conversions may be done "in place" by calling the routine with the output vector set to the input.

Air-to-vacuum wavelength conversion:
The air-to-vacuum wavelength conversion in early drafts of WCS Paper III cites Cox (ed., 2000, Allen’s Astrophysical Quantities, AIP Press, Springer-Verlag, New York), which itself derives from Edlén (1953, Journal of the Optical Society of America, 43, 339). This is the IAU standard, adopted in 1957 and again in 1991. No more recent IAU resolution replaces this relation, and it is the one used by WCSLIB.

However, the Cox relation was replaced in later drafts of Paper III, and as eventually published, by the IUGG relation (1999, International Union of Geodesy and Geophysics, comptes rendus of the 22nd General Assembly, Birmingham UK, p111). There is a nearly constant ratio between the two, with IUGG/Cox = 1.000015 over most of the range between 200nm and 10,000nm.

The IUGG relation itself is derived from the work of Ciddor (1996, Applied Optics, 35, 1566), which is used directly by the Sloan Digital Sky Survey. It agrees closely with Cox; longwards of 2500nm, the ratio Ciddor/Cox is fixed at 1.000000021, decreasing only slightly, to 1.000000018, at 1000nm.

The Cox, IUGG, and Ciddor relations all accurately provide the wavelength dependence of the air-to-vacuum wavelength conversion. However, for full accuracy, the atmospheric temperature, pressure, and partial pressure of water vapour must be taken into account. These will determine a small, wavelength-independent scale factor and offset, which is not considered by WCS Paper III.

WCS Paper III is also silent on the question of the range of validity of the air-to-vacuum wavelength conversion. Cox's relation would appear to be valid in the range 200nm to 10,000nm. Both the Cox and the Ciddor relations have singularities below 200nm, with Cox's at 156nm and 83nm. WCSLIB checks neither the range of validity, nor for these singularities.

Argument checking:
The input spectral values are only checked for values that would result in floating point exceptions. In particular, negative frequencies and wavelengths are allowed, as are velocities greater than the speed of light. The same is true for the spectral parameters - rest frequency and wavelength.

Accuracy:
No warranty is given for the accuracy of these routines (refer to the copyright notice); intending users must satisfy for themselves their adequacy for the intended purpose. However, closure effectively to within double precision rounding error was demonstrated by test routine tspec.c which accompanies this software.

## Macro Definition Documentation

## ◆ SPXLEN

#define SPXLEN (sizeof(struct spxprm)/sizeof(int))

Size of the spxprm struct in int units.

Size of the spxprm struct in int units, used by the Fortran wrappers.

## ◆ SPX_ARGS

#define SPX_ARGS

Value:
double param, int nspec, int instep, int outstep, \
const double inspec[], double outspec[], int stat[]

For use in declaring spectral conversion function prototypes.

Preprocessor macro used for declaring spectral conversion function prototypes.

## Enumeration Type Documentation

## ◆ spx_errmsg

enum spx_errmsg

Status return messages.

Error messages to match the status value returned from each function.

Enumerator
SPXERR_SUCCESS |
SPXERR_NULL_POINTER |
SPXERR_BAD_SPEC_PARAMS |
SPXERR_BAD_SPEC_VAR |
SPXERR_BAD_INSPEC_COORD |

## Function Documentation

## ◆ specx()

int specx | ( | const char * | type,
|  | double | spec,
|  | double | restfrq,
|  | double | restwav,
|  | struct spxprm * | specs )

Spectral cross conversions (scalar).

Given one spectral variable specx() computes all the others, plus the required derivatives of each with respect to the others.

Parameters

  [in] | type | The type of spectral variable given by spec, FREQ, AFRQ, ENER, WAVN, VRAD, WAVE, VOPT, ZOPT, AWAV, VELO, or BETA (case sensitive).
  [in] | spec | The spectral variable given, in SI units.
  [in] | restfrq,restwav | Rest frequency [Hz] or rest wavelength in vacuo [m], only one of which need be given. The other should be set to zero. If both are zero, only a subset of the spectral variables can be computed, the remainder are set to zero. Specifically, given one of FREQ, AFRQ, ENER, WAVN, WAVE, or AWAV the others can be computed without knowledge of the rest frequency. Likewise, VRAD, VOPT, ZOPT, VELO, and BETA.
  [in,out] | specs | Data structure containing all spectral variables and their derivatives, in SI units.

Returns
  Status return value:
  - 0: Success.
  - 1: Null spxprm pointer passed.
  - 2: Invalid spectral parameters.
  - 3: Invalid spectral variable.
  For returns > 1, a detailed error message is set in spxprm::err if enabled, see wcserr_enable().

freqafrq(), afrqfreq(), freqener(), enerfreq(), freqwavn(), wavnfreq(), freqwave(), wavefreq(), freqawav(), awavfreq(), waveawav(), awavwave(), velobeta(), and betavelo() implement vector conversions between wave-like or velocity-like spectral types (i.e. conversions that do not need the rest frequency or wavelength). They all have the same API.

## ◆ spxperr()

int spxperr | ( | const struct spxprm * | spx,
|  | const char * | prefix )

Print error messages from a spxprm struct.

spxperr() prints the error message(s) (if any) stored in a spxprm struct. If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.

Parameters

  [in] | spx | Spectral variables and their derivatives.
  [in] | prefix | If non-NULL, each output line will be prefixed with this string.

Returns
  Status return value:
  - 0: Success.
  - 1: Null spxprm pointer passed.

## ◆ freqafrq()

int freqafrq | ( | SPX_ARGS |  | ) |

Convert frequency to angular frequency (vector).

freqafrq() converts frequency to angular frequency.

Parameters

  [in] | param | Ignored.
  [in] | nspec | Vector length.
  [in] | instep,outstep | Vector strides.
  [in] | inspec | Input spectral variables, in SI units.
  [out] | outspec | Output spectral variables, in SI units.
  [out] | stat | Status return value for each vector element: 0: Success. 1: Invalid value of inspec.

Returns
  Status return value:
  - 0: Success.
  - 2: Invalid spectral parameters.
  - 4: One or more of the inspec coordinates were invalid, as indicated by the stat vector.

## ◆ afrqfreq()

int afrqfreq | ( | SPX_ARGS |  | ) |

Convert angular frequency to frequency (vector).

afrqfreq() converts angular frequency to frequency.

See freqafrq() for a description of the API.

## ◆ freqener()

int freqener | ( | SPX_ARGS |  | ) |

Convert frequency to photon energy (vector).

freqener() converts frequency to photon energy.

See freqafrq() for a description of the API.

## ◆ enerfreq()

int enerfreq | ( | SPX_ARGS |  | ) |

Convert photon energy to frequency (vector).

enerfreq() converts photon energy to frequency.

See freqafrq() for a description of the API.

## ◆ freqwavn()

int freqwavn | ( | SPX_ARGS |  | ) |

Convert frequency to wave number (vector).

freqwavn() converts frequency to wave number.

See freqafrq() for a description of the API.

## ◆ wavnfreq()

int wavnfreq | ( | SPX_ARGS |  | ) |

Convert wave number to frequency (vector).

wavnfreq() converts wave number to frequency.

See freqafrq() for a description of the API.

## ◆ freqwave()

int freqwave | ( | SPX_ARGS |  | ) |

Convert frequency to vacuum wavelength (vector).

freqwave() converts frequency to vacuum wavelength.

See freqafrq() for a description of the API.

## ◆ wavefreq()

int wavefreq | ( | SPX_ARGS |  | ) |

Convert vacuum wavelength to frequency (vector).

wavefreq() converts vacuum wavelength to frequency.

See freqafrq() for a description of the API.

## ◆ freqawav()

int freqawav | ( | SPX_ARGS |  | ) |

Convert frequency to air wavelength (vector).

freqawav() converts frequency to air wavelength.

See freqafrq() for a description of the API.

## ◆ awavfreq()

int awavfreq | ( | SPX_ARGS |  | ) |

Convert air wavelength to frequency (vector).

awavfreq() converts air wavelength to frequency.

See freqafrq() for a description of the API.

## ◆ waveawav()

int waveawav | ( | SPX_ARGS |  | ) |

Convert vacuum wavelength to air wavelength (vector).

waveawav() converts vacuum wavelength to air wavelength.

See freqafrq() for a description of the API.

## ◆ awavwave()

int awavwave | ( | SPX_ARGS |  | ) |

Convert air wavelength to vacuum wavelength (vector).

awavwave() converts air wavelength to vacuum wavelength.

See freqafrq() for a description of the API.

## ◆ velobeta()

int velobeta | ( | SPX_ARGS |  | ) |

Convert relativistic velocity to relativistic beta (vector).

velobeta() converts relativistic velocity to relativistic beta.

See freqafrq() for a description of the API.

## ◆ betavelo()

int betavelo | ( | SPX_ARGS |  | ) |

Convert relativistic beta to relativistic velocity (vector).

betavelo() converts relativistic beta to relativistic velocity.

See freqafrq() for a description of the API.

## ◆ freqvelo()

int freqvelo | ( | SPX_ARGS |  | ) |

Convert frequency to relativistic velocity (vector).

freqvelo() converts frequency to relativistic velocity.

Parameters

  [in] | param | Rest frequency [Hz].
  [in] | nspec | Vector length.
  [in] | instep,outstep | Vector strides.
  [in] | inspec | Input spectral variables, in SI units.
  [out] | outspec | Output spectral variables, in SI units.
  [out] | stat | Status return value for each vector element: 0: Success. 1: Invalid value of inspec.

Returns
  Status return value:
  - 0: Success.
  - 2: Invalid spectral parameters.
  - 4: One or more of the inspec coordinates were invalid, as indicated by the stat vector.

## ◆ velofreq()

int velofreq | ( | SPX_ARGS |  | ) |

Convert relativistic velocity to frequency (vector).

velofreq() converts relativistic velocity to frequency.

See freqvelo() for a description of the API.

## ◆ freqvrad()

int freqvrad | ( | SPX_ARGS |  | ) |

Convert frequency to radio velocity (vector).

freqvrad() converts frequency to radio velocity.

See freqvelo() for a description of the API.

## ◆ vradfreq()

int vradfreq | ( | SPX_ARGS |  | ) |

Convert radio velocity to frequency (vector).

vradfreq() converts radio velocity to frequency.

See freqvelo() for a description of the API.

## ◆ wavevelo()

int wavevelo | ( | SPX_ARGS |  | ) |

Conversions between wavelength and velocity types (vector).

wavevelo() converts vacuum wavelength to relativistic velocity.

Parameters

  [in] | param | Rest wavelength in vacuo [m].
  [in] | nspec | Vector length.
  [in] | instep,outstep | Vector strides.
  [in] | inspec | Input spectral variables, in SI units.
  [out] | outspec | Output spectral variables, in SI units.
  [out] | stat | Status return value for each vector element: 0: Success. 1: Invalid value of inspec.

Returns
  Status return value:
  - 0: Success.
  - 2: Invalid spectral parameters.
  - 4: One or more of the inspec coordinates were invalid, as indicated by the stat vector.

## ◆ velowave()

int velowave | ( | SPX_ARGS |  | ) |

Convert relativistic velocity to vacuum wavelength (vector).

velowave() converts relativistic velocity to vacuum wavelength.

See freqvelo() for a description of the API.

## ◆ awavvelo()

int awavvelo | ( | SPX_ARGS |  | ) |

Convert air wavelength to relativistic velocity (vector).

awavvelo() converts air wavelength to relativistic velocity.

See freqvelo() for a description of the API.

## ◆ veloawav()

int veloawav | ( | SPX_ARGS |  | ) |

Convert relativistic velocity to air wavelength (vector).

veloawav() converts relativistic velocity to air wavelength.

See freqvelo() for a description of the API.

## ◆ wavevopt()

int wavevopt | ( | SPX_ARGS |  | ) |

Convert vacuum wavelength to optical velocity (vector).

wavevopt() converts vacuum wavelength to optical velocity.

See freqvelo() for a description of the API.

## ◆ voptwave()

int voptwave | ( | SPX_ARGS |  | ) |

Convert optical velocity to vacuum wavelength (vector).

voptwave() converts optical velocity to vacuum wavelength.

See freqvelo() for a description of the API.

## ◆ wavezopt()

int wavezopt | ( | SPX_ARGS |  | ) |

Convert vacuum wavelength to redshift (vector).

wavevopt() converts vacuum wavelength to redshift.

See freqvelo() for a description of the API.

## ◆ zoptwave()

int zoptwave | ( | SPX_ARGS |  | ) |

Convert redshift to vacuum wavelength (vector).

zoptwave() converts redshift to vacuum wavelength.

See freqvelo() for a description of the API.

## Variable Documentation

## ◆ spx_errmsg

const char* spx_errmsg[]
| extern