00001 /*============================================================================ 00002 00003 WCSLIB 4.10 - an implementation of the FITS WCS standard. 00004 Copyright (C) 1995-2012, 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.10 2012/02/05 23:41:44 cal103 Exp $ 00032 *============================================================================= 00033 * 00034 * WCSLIB 4.10 - 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 */