WCSLIB 8.2.2
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
}
 

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:

Linear:

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
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]typeThe type of spectral variable given by spec, FREQ, AFRQ, ENER, WAVN, VRAD, WAVE, VOPT, ZOPT, AWAV, VELO, or BETA (case sensitive).
[in]specThe spectral variable given, in SI units.
[in]restfrq,restwavRest 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]specsData 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]spxSpectral variables and their derivatives.
[in]prefixIf 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]paramIgnored.
[in]nspecVector length.
[in]instep,outstepVector strides.
[in]inspecInput spectral variables, in SI units.
[out]outspecOutput spectral variables, in SI units.
[out]statStatus 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]paramRest frequency [Hz].
[in]nspecVector length.
[in]instep,outstepVector strides.
[in]inspecInput spectral variables, in SI units.
[out]outspecOutput spectral variables, in SI units.
[out]statStatus 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]paramRest wavelength in vacuo [m].
[in]nspecVector length.
[in]instep,outstepVector strides.
[in]inspecInput spectral variables, in SI units.
[out]outspecOutput spectral variables, in SI units.
[out]statStatus 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