WCSLIB 4.17: spx.h Source File

- Main Page
- Related Pages
- Data Structures
- Files

# spx.h

Go to the documentation of this file.

    00001 /*============================================================================
    00002
    00003   WCSLIB 4.17 - an implementation of the FITS WCS standard.
    00004   Copyright (C) 1995-2013, Mark Calabretta
    00005
    00006   This file is part of WCSLIB.
    00007
    00008   WCSLIB is free software: you can redistribute it and/or modify it under the
    00009   terms of the GNU Lesser General Public License as published by the Free
    00010   Software Foundation, either version 3 of the License, or (at your option)
    00011   any later version.
    00012
    00013   WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
    00014   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
    00015   FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for
    00016   more details.
    00017
    00018   You should have received a copy of the GNU Lesser General Public License
    00019   along with WCSLIB.  If not, see http://www.gnu.org/licenses.
    00020
    00021   Direct correspondence concerning WCSLIB to mark@calabretta.id.au
    00022
    00023   Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
    00024   http://www.atnf.csiro.au/people/Mark.Calabretta
    00025   $Id: spx.h,v 4.17 2013/01/29 05:29:20 cal103 Exp $
    00026 *=============================================================================
    00027 *
    00028 * WCSLIB 4.17 - C routines that implement the spectral coordinate systems
    00029 * recognized by the FITS World Coordinate System (WCS) standard.  Refer to
    00030 *
    00031 *   "Representations of world coordinates in FITS",
    00032 *   Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
    00033 *
    00034 *   "Representations of spectral coordinates in FITS",
    00035 *   Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
    00036 *   2006, A&A, 446, 747 (Paper III)
    00037 *
    00038 * Refer to the README file provided with WCSLIB for an overview of the
    00039 * library.
    00040 *
    00041 *
    00042 * Summary of the spx routines
    00043 * ---------------------------
    00044 * specx() is a scalar routine that, given one spectral variable (e.g.
    00045 * frequency), computes all the others (e.g. wavelength, velocity, etc.) plus
    00046 * the required derivatives of each with respect to the others.  The results
    00047 * are returned in the spxprm struct.
    00048 *
    00049 * The remaining routines are all vector conversions from one spectral
    00050 * variable to another.  The API of these functions only differ in whether the
    00051 * rest frequency or wavelength need be supplied.
    00052 *
    00053 * Non-linear:
    00054 *   - freqwave()    frequency              ->  vacuum wavelength
    00055 *   - wavefreq()    vacuum wavelength      ->  frequency
    00056 *
    00057 *   - freqawav()    frequency              ->  air wavelength
    00058 *   - awavfreq()    air wavelength         ->  frequency
    00059 *
    00060 *   - freqvelo()    frequency              ->  relativistic velocity
    00061 *   - velofreq()    relativistic velocity  ->  frequency
    00062 *
    00063 *   - waveawav()    vacuum wavelength      ->  air wavelength
    00064 *   - awavwave()    air wavelength         ->  vacuum wavelength
    00065 *
    00066 *   - wavevelo()    vacuum wavelength      ->  relativistic velocity
    00067 *   - velowave()    relativistic velocity  ->  vacuum wavelength
    00068 *
    00069 *   - awavvelo()    air wavelength         ->  relativistic velocity
    00070 *   - veloawav()    relativistic velocity  ->  air wavelength
    00071 *
    00072 * Linear:
    00073 *   - freqafrq()    frequency              ->  angular frequency
    00074 *   - afrqfreq()    angular frequency      ->  frequency
    00075 *
    00076 *   - freqener()    frequency              ->  energy
    00077 *   - enerfreq()    energy                 ->  frequency
    00078 *
    00079 *   - freqwavn()    frequency              ->  wave number
    00080 *   - wavnfreq()    wave number            ->  frequency
    00081 *
    00082 *   - freqvrad()    frequency              ->  radio velocity
    00083 *   - vradfreq()    radio velocity         ->  frequency
    00084 *
    00085 *   - wavevopt()    vacuum wavelength      ->  optical velocity
    00086 *   - voptwave()    optical velocity       ->  vacuum wavelength
    00087 *
    00088 *   - wavezopt()    vacuum wavelength      ->  redshift
    00089 *   - zoptwave()    redshift               ->  vacuum wavelength
    00090 *
    00091 *   - velobeta()    relativistic velocity  ->  beta (= v/c)
    00092 *   - betavelo()    beta (= v/c)           ->  relativistic velocity
    00093 *
    00094 * These are the workhorse routines, to be used for fast transformations.
    00095 * Conversions may be done "in place" by calling the routine with the output
    00096 * vector set to the input.
    00097 *
    00098 * Argument checking:
    00099 * ------------------
    00100 * The input spectral values are only checked for values that would result
    00101 * in floating point exceptions.  In particular, negative frequencies and
    00102 * wavelengths are allowed, as are velocities greater than the speed of
    00103 * light.  The same is true for the spectral parameters - rest frequency and
    00104 * wavelength.
    00105 *
    00106 * Accuracy:
    00107 * ---------
    00108 * No warranty is given for the accuracy of these routines (refer to the
    00109 * copyright notice); intending users must satisfy for themselves their
    00110 * adequacy for the intended purpose.  However, closure effectively to within
    00111 * double precision rounding error was demonstrated by test routine tspec.c
    00112 * which accompanies this software.
    00113 *
    00114 *
    00115 * specx() - Spectral cross conversions (scalar)
    00116 * ---------------------------------------------
    00117 * Given one spectral variable specx() computes all the others, plus the
    00118 * required derivatives of each with respect to the others.
    00119 *
    00120 * Given:
    00121 *   type      const char*
    00122 *                       The type of spectral variable given by spec, FREQ,
    00123 *                       AFRQ, ENER, WAVN, VRAD, WAVE, VOPT, ZOPT, AWAV, VELO,
    00124 *                       or BETA (case sensitive).
    00125 *
    00126 *   spec      double    The spectral variable given, in SI units.
    00127 *
    00128 *   restfrq,
    00129 *   restwav   double    Rest frequency [Hz] or rest wavelength in vacuo [m],
    00130 *                       only one of which need be given.  The other should be
    00131 *                       set to zero.  If both are zero, only a subset of the
    00132 *                       spectral variables can be computed, the remainder are
    00133 *                       set to zero.  Specifically, given one of FREQ, AFRQ,
    00134 *                       ENER, WAVN, WAVE, or AWAV the others can be computed
    00135 *                       without knowledge of the rest frequency.  Likewise,
    00136 *                       VRAD, VOPT, ZOPT, VELO, and BETA.
    00137 *
    00138 * Given and returned:
    00139 *   specs     struct spxprm*
    00140 *                       Data structure containing all spectral variables and
    00141 *                       their derivatives, in SI units.
    00142 *
    00143 * Function return value:
    00144 *             int       Status return value:
    00145 *                         0: Success.
    00146 *                         1: Null spxprm pointer passed.
    00147 *                         2: Invalid spectral parameters.
    00148 *                         3: Invalid spectral variable.
    00149 *
    00150 *                       For returns > 1, a detailed error message is set in
    00151 *                       spxprm::err if enabled, see wcserr_enable().
    00152 *
    00153 * freqafrq(), afrqfreq(), freqener(), enerfreq(), freqwavn(), wavnfreq(),
    00154 * freqwave(), wavefreq(), freqawav(), awavfreq(), waveawav(), awavwave(),
    00155 * velobeta(), and betavelo() implement vector conversions between wave-like
    00156 * or velocity-like spectral types (i.e. conversions that do not need the rest
    00157 * frequency or wavelength).  They all have the same API.
    00158 *
    00159 *
    00160 * freqafrq() - Convert frequency to angular frequency (vector)
    00161 * ------------------------------------------------------------
    00162 * freqafrq() converts frequency to angular frequency.
    00163 *
    00164 * Given:
    00165 *   param     double    Ignored.
    00166 *
    00167 *   nspec     int       Vector length.
    00168 *
    00169 *   instep,
    00170 *   outstep   int       Vector strides.
    00171 *
    00172 *   inspec    const double[]
    00173 *                       Input spectral variables, in SI units.
    00174 *
    00175 * Returned:
    00176 *   outspec   double[]  Output spectral variables, in SI units.
    00177 *
    00178 *   stat      int[]     Status return value for each vector element:
    00179 *                         0: Success.
    00180 *                         1: Invalid value of inspec.
    00181 *
    00182 * Function return value:
    00183 *             int       Status return value:
    00184 *                         0: Success.
    00185 *                         2: Invalid spectral parameters.
    00186 *                         4: One or more of the inspec coordinates were
    00187 *                            invalid, as indicated by the stat vector.
    00188 *
    00189 *
    00190 * freqvelo(), velofreq(), freqvrad(), and vradfreq() implement vector
    00191 * conversions between frequency and velocity spectral types.  They all have
    00192 * the same API.
    00193 *
    00194 *
    00195 * freqvelo() - Convert frequency to relativistic velocity (vector)
    00196 * ----------------------------------------------------------------
    00197 * freqvelo() converts frequency to relativistic velocity.
    00198 *
    00199 * Given:
    00200 *   param     double    Rest frequency [Hz].
    00201 *
    00202 *   nspec     int       Vector length.
    00203 *
    00204 *   instep,
    00205 *   outstep   int       Vector strides.
    00206 *
    00207 *   inspec    const double[]
    00208 *                       Input spectral variables, in SI units.
    00209 *
    00210 * Returned:
    00211 *   outspec   double[]  Output spectral variables, in SI units.
    00212 *
    00213 *   stat      int[]     Status return value for each vector element:
    00214 *                         0: Success.
    00215 *                         1: Invalid value of inspec.
    00216 *
    00217 * Function return value:
    00218 *             int       Status return value:
    00219 *                         0: Success.
    00220 *                         2: Invalid spectral parameters.
    00221 *                         4: One or more of the inspec coordinates were
    00222 *                            invalid, as indicated by the stat vector.
    00223 *
    00224 *
    00225 * wavevelo(), velowave(), awavvelo(), veloawav(), wavevopt(), voptwave(),
    00226 * wavezopt(), and zoptwave() implement vector conversions between wavelength
    00227 * and velocity spectral types.  They all have the same API.
    00228 *
    00229 *
    00230 * wavevelo() - Conversions between wavelength and velocity types (vector)
    00231 * -----------------------------------------------------------------------
    00232 * wavevelo() converts vacuum wavelength to relativistic velocity.
    00233 *
    00234 * Given:
    00235 *   param     double    Rest wavelength in vacuo [m].
    00236 *
    00237 *   nspec     int       Vector length.
    00238 *
    00239 *   instep,
    00240 *   outstep   int       Vector strides.
    00241 *
    00242 *   inspec    const double[]
    00243 *                       Input spectral variables, in SI units.
    00244 *
    00245 * Returned:
    00246 *   outspec   double[]  Output spectral variables, in SI units.
    00247 *
    00248 *   stat      int[]     Status return value for each vector element:
    00249 *                         0: Success.
    00250 *                         1: Invalid value of inspec.
    00251 *
    00252 * Function return value:
    00253 *             int       Status return value:
    00254 *                         0: Success.
    00255 *                         2: Invalid spectral parameters.
    00256 *                         4: One or more of the inspec coordinates were
    00257 *                            invalid, as indicated by the stat vector.
    00258 *
    00259 *
    00260 * spxprm struct - Spectral variables and their derivatives
    00261 * --------------------------------------------------------
    00262 * The spxprm struct contains the value of all spectral variables and their
    00263 * derivatives.   It is used solely by specx() which constructs it from
    00264 * information provided via its function arguments.
    00265 *
    00266 * This struct should be considered read-only, no members need ever be set nor
    00267 * should ever be modified by the user.
    00268 *
    00269 *   double restfrq
    00270 *     (Returned) Rest frequency [Hz].
    00271 *
    00272 *   double restwav
    00273 *     (Returned) Rest wavelength [m].
    00274 *
    00275 *   int wavetype
    00276 *     (Returned) True if wave types have been computed, and ...
    00277 *
    00278 *   int velotype
    00279 *     (Returned) ... true if velocity types have been computed; types are
    00280 *     defined below.
    00281 *
    00282 *     If one or other of spxprm::restfrq and spxprm::restwav is given
    00283 *     (non-zero) then all spectral variables may be computed.  If both are
    00284 *     given, restfrq is used.  If restfrq and restwav are both zero, only wave
    00285 *     characteristic xor velocity type spectral variables may be computed
    00286 *     depending on the variable given.   These flags indicate what is
    00287 *     available.
    00288 *
    00289 *   double freq
    00290 *     (Returned) Frequency [Hz] (wavetype).
    00291 *
    00292 *   double afrq
    00293 *     (Returned) Angular frequency [rad/s] (wavetype).
    00294 *
    00295 *   double ener
    00296 *     (Returned) Photon energy [J] (wavetype).
    00297 *
    00298 *   double wavn
    00299 *     (Returned) Wave number [/m] (wavetype).
    00300 *
    00301 *   double vrad
    00302 *     (Returned) Radio velocity [m/s] (velotype).
    00303 *
    00304 *   double wave
    00305 *     (Returned) Vacuum wavelength [m] (wavetype).
    00306 *
    00307 *   double vopt
    00308 *     (Returned) Optical velocity [m/s] (velotype).
    00309 *
    00310 *   double zopt
    00311 *     (Returned) Redshift [dimensionless] (velotype).
    00312 *
    00313 *   double awav
    00314 *     (Returned) Air wavelength [m] (wavetype).
    00315 *
    00316 *   double velo
    00317 *     (Returned) Relativistic velocity [m/s] (velotype).
    00318 *
    00319 *   double beta
    00320 *     (Returned) Relativistic beta [dimensionless] (velotype).
    00321 *
    00322 *   double dfreqafrq
    00323 *     (Returned) Derivative of frequency with respect to angular frequency
    00324 *     [/rad] (constant, = 1 / 2*pi), and ...
    00325 *   double dafrqfreq
    00326 *     (Returned) ... vice versa [rad] (constant, = 2*pi, always available).
    00327 *
    00328 *   double dfreqener
    00329 *     (Returned) Derivative of frequency with respect to photon energy
    00330 *     [/J/s] (constant, = 1/h), and ...
    00331 *   double denerfreq
    00332 *     (Returned) ... vice versa [Js] (constant, = h, Planck's constant,
    00333 *     always available).
    00334 *
    00335 *   double dfreqwavn
    00336 *     (Returned) Derivative of frequency with respect to wave number [m/s]
    00337 *     (constant, = c, the speed of light in vacuuo), and ...
    00338 *   double dwavnfreq
    00339 *     (Returned) ... vice versa [s/m] (constant, = 1/c, always available).
    00340 *
    00341 *   double dfreqvrad
    00342 *     (Returned) Derivative of frequency with respect to radio velocity [/m],
    00343 *     and ...
    00344 *   double dvradfreq
    00345 *     (Returned) ... vice versa [m] (wavetype && velotype).
    00346 *
    00347 *   double dfreqwave
    00348 *     (Returned) Derivative of frequency with respect to vacuum wavelength
    00349 *     [/m/s], and ...
    00350 *   double dwavefreq
    00351 *     (Returned) ... vice versa [m s] (wavetype).
    00352 *
    00353 *   double dfreqawav
    00354 *     (Returned) Derivative of frequency with respect to air wavelength,
    00355 *     [/m/s], and ...
    00356 *   double dawavfreq
    00357 *     (Returned) ... vice versa [m s] (wavetype).
    00358 *
    00359 *   double dfreqvelo
    00360 *     (Returned) Derivative of frequency with respect to relativistic
    00361 *     velocity [/m], and ...
    00362 *   double dvelofreq
    00363 *     (Returned) ... vice versa [m] (wavetype && velotype).
    00364 *
    00365 *   double dwavevopt
    00366 *     (Returned) Derivative of vacuum wavelength with respect to optical
    00367 *     velocity [s], and ...
    00368 *   double dvoptwave
    00369 *     (Returned) ... vice versa [/s] (wavetype && velotype).
    00370 *
    00371 *   double dwavezopt
    00372 *     (Returned) Derivative of vacuum wavelength with respect to redshift [m],
    00373 *     and ...
    00374 *   double dzoptwave
    00375 *     (Returned) ... vice versa [/m] (wavetype && velotype).
    00376 *
    00377 *   double dwaveawav
    00378 *     (Returned) Derivative of vacuum wavelength with respect to air
    00379 *     wavelength [dimensionless], and ...
    00380 *   double dawavwave
    00381 *     (Returned) ... vice versa [dimensionless] (wavetype).
    00382 *
    00383 *   double dwavevelo
    00384 *     (Returned) Derivative of vacuum wavelength with respect to relativistic
    00385 *     velocity [s], and ...
    00386 *   double dvelowave
    00387 *     (Returned) ... vice versa [/s] (wavetype && velotype).
    00388 *
    00389 *   double dawavvelo
    00390 *     (Returned) Derivative of air wavelength with respect to relativistic
    00391 *     velocity [s], and ...
    00392 *   double dveloawav
    00393 *     (Returned) ... vice versa [/s] (wavetype && velotype).
    00394 *
    00395 *   double dvelobeta
    00396 *     (Returned) Derivative of relativistic velocity with respect to
    00397 *     relativistic beta [m/s] (constant, = c, the speed of light in vacuu0),
    00398 *     and ...
    00399 *   double dbetavelo
    00400 *     (Returned) ... vice versa [s/m] (constant, = 1/c, always available).
    00401 *
    00402 *   struct wcserr *err
    00403 *     (Returned) If enabled, when an error status is returned this struct
    00404 *     contains detailed information about the error, see wcserr_enable().
    00405 *
    00406 *   void *padding
    00407 *     (An unused variable inserted for alignment purposes only.)
    00408 *
    00409 * Global variable: const char *spx_errmsg[] - Status return messages
    00410 * ------------------------------------------------------------------
    00411 * Error messages to match the status value returned from each function.
    00412 *
    00413 *===========================================================================*/
    00414
    00415 #ifndef WCSLIB_SPEC
    00416 #define WCSLIB_SPEC
    00417
    00418 #ifdef __cplusplus
    00419 extern "C" {
    00420 #endif
    00421
    00422 #include "wcserr.h"
    00423
    00424 extern const char *spx_errmsg[];
    00425
    00426 enum spx_errmsg {
    00427   SPXERR_SUCCESS          = 0,  /* Success. */
    00428   SPXERR_NULL_POINTER     = 1,  /* Null spxprm pointer passed. */
    00429   SPXERR_BAD_SPEC_PARAMS  = 2,  /* Invalid spectral parameters. */
    00430   SPXERR_BAD_SPEC_VAR     = 3,  /* Invalid spectral variable. */
    00431   SPXERR_BAD_INSPEC_COORD = 4   /* One or more of the inspec coordinates were
    00432                                    invalid. */
    00433 };
    00434
    00435 struct spxprm {
    00436   double restfrq, restwav;      /* Rest frequency [Hz] and wavelength [m].  */
    00437
    00438   int wavetype, velotype;       /* True if wave/velocity types have been    */
    00439                                 /* computed; types are defined below.       */
    00440
    00441   /* Spectral variables computed by specx().                                */
    00442   /*------------------------------------------------------------------------*/
    00443   double freq,                  /* wavetype: Frequency [Hz].                */
    00444          afrq,                  /* wavetype: Angular frequency [rad/s].     */
    00445          ener,                  /* wavetype: Photon energy [J].             */
    00446          wavn,                  /* wavetype: Wave number [/m].              */
    00447          vrad,                  /* velotype: Radio velocity [m/s].          */
    00448          wave,                  /* wavetype: Vacuum wavelength [m].         */
    00449          vopt,                  /* velotype: Optical velocity [m/s].        */
    00450          zopt,                  /* velotype: Redshift.                      */
    00451          awav,                  /* wavetype: Air wavelength [m].            */
    00452          velo,                  /* velotype: Relativistic velocity [m/s].   */
    00453          beta;                  /* velotype: Relativistic beta.             */
    00454
    00455   /* Derivatives of spectral variables computed by specx().                 */
    00456   /*------------------------------------------------------------------------*/
    00457   double dfreqafrq, dafrqfreq,  /* Constant, always available.              */
    00458          dfreqener, denerfreq,  /* Constant, always available.              */
    00459          dfreqwavn, dwavnfreq,  /* Constant, always available.              */
    00460          dfreqvrad, dvradfreq,  /* wavetype && velotype.                    */
    00461          dfreqwave, dwavefreq,  /* wavetype.                                */
    00462          dfreqawav, dawavfreq,  /* wavetype.                                */
    00463          dfreqvelo, dvelofreq,  /* wavetype && velotype.                    */
    00464          dwavevopt, dvoptwave,  /* wavetype && velotype.                    */
    00465          dwavezopt, dzoptwave,  /* wavetype && velotype.                    */
    00466          dwaveawav, dawavwave,  /* wavetype.                                */
    00467          dwavevelo, dvelowave,  /* wavetype && velotype.                    */
    00468          dawavvelo, dveloawav,  /* wavetype && velotype.                    */
    00469          dvelobeta, dbetavelo;  /* Constant, always available.              */
    00470
    00471   /* Error handling                                                         */
    00472   /*------------------------------------------------------------------------*/
    00473   struct wcserr *err;
    00474
    00475   /* Private                                                                */
    00476   /*------------------------------------------------------------------------*/
    00477   void   *padding;              /* (Dummy inserted for alignment purposes.) */
    00478 };
    00479
    00480 /* Size of the spxprm struct in int units, used by the Fortran wrappers. */
    00481 #define SPXLEN (sizeof(struct spxprm)/sizeof(int))
    00482
    00483
    00484 int specx(const char *type, double spec, double restfrq, double restwav,
    00485           struct spxprm *specs);
    00486
    00487
    00488 /* For use in declaring function prototypes, e.g. in spcprm. */
    00489 #define SPX_ARGS double param, int nspec, int instep, int outstep, \
    00490     const double inspec[], double outspec[], int stat[]
    00491
    00492 int freqafrq(SPX_ARGS);
    00493 int afrqfreq(SPX_ARGS);
    00494
    00495 int freqener(SPX_ARGS);
    00496 int enerfreq(SPX_ARGS);
    00497
    00498 int freqwavn(SPX_ARGS);
    00499 int wavnfreq(SPX_ARGS);
    00500
    00501 int freqwave(SPX_ARGS);
    00502 int wavefreq(SPX_ARGS);
    00503
    00504 int freqawav(SPX_ARGS);
    00505 int awavfreq(SPX_ARGS);
    00506
    00507 int waveawav(SPX_ARGS);
    00508 int awavwave(SPX_ARGS);
    00509
    00510 int velobeta(SPX_ARGS);
    00511 int betavelo(SPX_ARGS);
    00512
    00513
    00514 int freqvelo(SPX_ARGS);
    00515 int velofreq(SPX_ARGS);
    00516
    00517 int freqvrad(SPX_ARGS);
    00518 int vradfreq(SPX_ARGS);
    00519
    00520
    00521 int wavevelo(SPX_ARGS);
    00522 int velowave(SPX_ARGS);
    00523
    00524 int awavvelo(SPX_ARGS);
    00525 int veloawav(SPX_ARGS);
    00526
    00527 int wavevopt(SPX_ARGS);
    00528 int voptwave(SPX_ARGS);
    00529
    00530 int wavezopt(SPX_ARGS);
    00531 int zoptwave(SPX_ARGS);
    00532
    00533
    00534 #ifdef __cplusplus
    00535 }
    00536 #endif
    00537
    00538 #endif /* WCSLIB_SPEC */