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 ( $\beta = v/c$ )
betavelo() beta ( $\beta = v/c$ ) -> 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.