#include "wcserr.h"

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

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.

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.

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

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

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

#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

enum spx_errmsg

Enumerator
SPXERR_SUCCESS
SPXERR_NULL_POINTER
SPXERR_BAD_SPEC_PARAMS
SPXERR_BAD_SPEC_VAR
SPXERR_BAD_INSPEC_COORD

Function Documentation

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.

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.

int afrqfreq ( SPX_ARGS )

afrqfreq() converts angular frequency to frequency.