WCSLIB: spx.h File Reference

WCSLIB 6.2

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. More...
#define | SPX_ARGS
| For use in declaring spectral conversion function prototypes. More...

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

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

## 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, 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[]

Preprocessor macro used for declaring spectral conversion function prototypes.

## Enumeration Type Documentation

## ◆ spx_errmsg

enum spx_errmsg

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
| ) |  |

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
| ) |  |

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 |  | ) |

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 |  | ) |

afrqfreq() converts angular frequency to frequency.

See freqafrq() for a description of the API.

## ◆ freqener()

int freqener | ( | SPX_ARGS |  | ) |

freqener() converts frequency to photon energy.

See freqafrq() for a description of the API.

## ◆ enerfreq()

int enerfreq | ( | SPX_ARGS |  | ) |

enerfreq() converts photon energy to frequency.

See freqafrq() for a description of the API.

## ◆ freqwavn()

int freqwavn | ( | SPX_ARGS |  | ) |

freqwavn() converts frequency to wave number.

See freqafrq() for a description of the API.

## ◆ wavnfreq()

int wavnfreq | ( | SPX_ARGS |  | ) |

wavnfreq() converts wave number to frequency.

See freqafrq() for a description of the API.

## ◆ freqwave()

int freqwave | ( | SPX_ARGS |  | ) |

freqwave() converts frequency to vacuum wavelength.

See freqafrq() for a description of the API.

## ◆ wavefreq()

int wavefreq | ( | SPX_ARGS |  | ) |

wavefreq() converts vacuum wavelength to frequency.

See freqafrq() for a description of the API.

## ◆ freqawav()

int freqawav | ( | SPX_ARGS |  | ) |

freqawav() converts frequency to air wavelength.

See freqafrq() for a description of the API.

## ◆ awavfreq()

int awavfreq | ( | SPX_ARGS |  | ) |

awavfreq() converts air wavelength to frequency.

See freqafrq() for a description of the API.

## ◆ waveawav()

int waveawav | ( | SPX_ARGS |  | ) |

waveawav() converts vacuum wavelength to air wavelength.

See freqafrq() for a description of the API.

## ◆ awavwave()

int awavwave | ( | SPX_ARGS |  | ) |

awavwave() converts air wavelength to vacuum wavelength.

See freqafrq() for a description of the API.

## ◆ velobeta()

int velobeta | ( | SPX_ARGS |  | ) |

velobeta() converts relativistic velocity to relativistic beta.

See freqafrq() for a description of the API.

## ◆ betavelo()

int betavelo | ( | SPX_ARGS |  | ) |

betavelo() converts relativistic beta to relativistic velocity.

See freqafrq() for a description of the API.

## ◆ freqvelo()

int freqvelo | ( | SPX_ARGS |  | ) |

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 |  | ) |

velofreq() converts relativistic velocity to frequency.

See freqvelo() for a description of the API.

## ◆ freqvrad()

int freqvrad | ( | SPX_ARGS |  | ) |

freqvrad() converts frequency to radio velocity.

See freqvelo() for a description of the API.

## ◆ vradfreq()

int vradfreq | ( | SPX_ARGS |  | ) |

vradfreq() converts radio velocity to frequency.

See freqvelo() for a description of the API.

## ◆ wavevelo()

int wavevelo | ( | SPX_ARGS |  | ) |

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 |  | ) |

velowave() converts relativistic velocity to vacuum wavelength.

See freqvelo() for a description of the API.

## ◆ awavvelo()

int awavvelo | ( | SPX_ARGS |  | ) |

awavvelo() converts air wavelength to relativistic velocity.

See freqvelo() for a description of the API.

## ◆ veloawav()

int veloawav | ( | SPX_ARGS |  | ) |

veloawav() converts relativistic velocity to air wavelength.

See freqvelo() for a description of the API.

## ◆ wavevopt()

int wavevopt | ( | SPX_ARGS |  | ) |

wavevopt() converts vacuum wavelength to optical velocity.

See freqvelo() for a description of the API.

## ◆ voptwave()

int voptwave | ( | SPX_ARGS |  | ) |

voptwave() converts optical velocity to vacuum wavelength.

See freqvelo() for a description of the API.

## ◆ wavezopt()

int wavezopt | ( | SPX_ARGS |  | ) |

wavevopt() converts vacuum wavelength to redshift.

See freqvelo() for a description of the API.

## ◆ zoptwave()

int zoptwave | ( | SPX_ARGS |  | ) |

zoptwave() converts redshift to vacuum wavelength.

See freqvelo() for a description of the API.

## Variable Documentation

## ◆ spx_errmsg

const char* spx_errmsg[]