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