# spx.h File Reference

`#include "wcserr.h"`

Go to the source code of this file.

## Data Structures
struct | spxprm
| Spectral variables and their derivatives. More...
## Defines
#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 | 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

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

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.

## Define 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.

See freqafrq() for a description of the API.

int freqener | ( | SPX_ARGS |  | ) |

freqener() converts frequency to photon energy.

See freqafrq() for a description of the API.

int enerfreq | ( | SPX_ARGS |  | ) |

enerfreq() converts photon energy to frequency.

See freqafrq() for a description of the API.

int freqwavn | ( | SPX_ARGS |  | ) |

freqwavn() converts frequency to wave number.

See freqafrq() for a description of the API.

int wavnfreq | ( | SPX_ARGS |  | ) |

wavnfreq() converts wave number to frequency.

See freqafrq() for a description of the API.

int freqwave | ( | SPX_ARGS |  | ) |

freqwave() converts frequency to vacuum wavelength.

See freqafrq() for a description of the API.

int wavefreq | ( | SPX_ARGS |  | ) |

wavefreq() converts vacuum wavelength to frequency.

See freqafrq() for a description of the API.

int freqawav | ( | SPX_ARGS |  | ) |

freqawav() converts frequency to air wavelength.

See freqafrq() for a description of the API.

int awavfreq | ( | SPX_ARGS |  | ) |

awavfreq() converts air wavelength to frequency.

See freqafrq() for a description of the API.

int waveawav | ( | SPX_ARGS |  | ) |

waveawav() converts vacuum wavelength to air wavelength.

See freqafrq() for a description of the API.

int awavwave | ( | SPX_ARGS |  | ) |

awavwave() converts air wavelength to vacuum wavelength.

See freqafrq() for a description of the API.

int velobeta | ( | SPX_ARGS |  | ) |

velobeta() converts relativistic velocity to relativistic beta.

See freqafrq() for a description of the API.

int betavelo | ( | SPX_ARGS |  | ) |

betavelo() converts relativistic beta to relativistic velocity.

See freqafrq() for a description of the API.

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.

int velofreq | ( | SPX_ARGS |  | ) |

velofreq() converts relativistic velocity to frequency.

See freqvelo() for a description of the API.

int freqvrad | ( | SPX_ARGS |  | ) |

freqvrad() converts frequency to radio velocity.

See freqvelo() for a description of the API.

int vradfreq | ( | SPX_ARGS |  | ) |

vradfreq() converts radio velocity to frequency.

See freqvelo() for a description of the API.

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.

int velowave | ( | SPX_ARGS |  | ) |

velowave() converts relativistic velocity to vacuum wavelength.

See freqvelo() for a description of the API.

int awavvelo | ( | SPX_ARGS |  | ) |

awavvelo() converts air wavelength to relativistic velocity.

See freqvelo() for a description of the API.

int veloawav | ( | SPX_ARGS |  | ) |

veloawav() converts relativistic velocity to air wavelength.

See freqvelo() for a description of the API.

int wavevopt | ( | SPX_ARGS |  | ) |

wavevopt() converts vacuum wavelength to optical velocity.

See freqvelo() for a description of the API.

int voptwave | ( | SPX_ARGS |  | ) |

voptwave() converts optical velocity to vacuum wavelength.

See freqvelo() for a description of the API.

int wavezopt | ( | SPX_ARGS |  | ) |

wavevopt() converts vacuum wavelength to redshift.

See freqvelo() for a description of the API.

int zoptwave | ( | SPX_ARGS |  | ) |

zoptwave() converts redshift to vacuum wavelength.

See freqvelo() for a description of the API.

## Variable Documentation

const char* spx_errmsg[]