WCSLIB 4.20
spx.h
Go to the documentation of this file.
1 /*============================================================================
2 
3  WCSLIB 4.20 - an implementation of the FITS WCS standard.
4  Copyright (C) 1995-2013, Mark Calabretta
5 
6  This file is part of WCSLIB.
7 
8  WCSLIB is free software: you can redistribute it and/or modify it under the
9  terms of the GNU Lesser General Public License as published by the Free
10  Software Foundation, either version 3 of the License, or (at your option)
11  any later version.
12 
13  WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
14  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15  FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
16  more details.
17 
18  You should have received a copy of the GNU Lesser General Public License
19  along with WCSLIB. If not, see http://www.gnu.org/licenses.
20 
21  Direct correspondence concerning WCSLIB to mark@calabretta.id.au
22 
23  Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
24  http://www.atnf.csiro.au/people/Mark.Calabretta
25  $Id: spx_8h_source.html,v 1.1 2014/02/12 21:11:37 irby Exp $
26 *=============================================================================
27 *
28 * WCSLIB 4.20 - C routines that implement the spectral coordinate systems
29 * recognized by the FITS World Coordinate System (WCS) standard. Refer to
30 *
31 * "Representations of world coordinates in FITS",
32 * Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (Paper I)
33 *
34 * "Representations of spectral coordinates in FITS",
35 * Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
36 * 2006, A&A, 446, 747 (Paper III)
37 *
38 * Refer to the README file provided with WCSLIB for an overview of the
39 * library.
40 *
41 *
42 * Summary of the spx routines
43 * ---------------------------
44 * specx() is a scalar routine that, given one spectral variable (e.g.
45 * frequency), computes all the others (e.g. wavelength, velocity, etc.) plus
46 * the required derivatives of each with respect to the others. The results
47 * are returned in the spxprm struct.
48 *
49 * The remaining routines are all vector conversions from one spectral
50 * variable to another. The API of these functions only differ in whether the
51 * rest frequency or wavelength need be supplied.
52 *
53 * Non-linear:
54 * - freqwave() frequency -> vacuum wavelength
55 * - wavefreq() vacuum wavelength -> frequency
56 *
57 * - freqawav() frequency -> air wavelength
58 * - awavfreq() air wavelength -> frequency
59 *
60 * - freqvelo() frequency -> relativistic velocity
61 * - velofreq() relativistic velocity -> frequency
62 *
63 * - waveawav() vacuum wavelength -> air wavelength
64 * - awavwave() air wavelength -> vacuum wavelength
65 *
66 * - wavevelo() vacuum wavelength -> relativistic velocity
67 * - velowave() relativistic velocity -> vacuum wavelength
68 *
69 * - awavvelo() air wavelength -> relativistic velocity
70 * - veloawav() relativistic velocity -> air wavelength
71 *
72 * Linear:
73 * - freqafrq() frequency -> angular frequency
74 * - afrqfreq() angular frequency -> frequency
75 *
76 * - freqener() frequency -> energy
77 * - enerfreq() energy -> frequency
78 *
79 * - freqwavn() frequency -> wave number
80 * - wavnfreq() wave number -> frequency
81 *
82 * - freqvrad() frequency -> radio velocity
83 * - vradfreq() radio velocity -> frequency
84 *
85 * - wavevopt() vacuum wavelength -> optical velocity
86 * - voptwave() optical velocity -> vacuum wavelength
87 *
88 * - wavezopt() vacuum wavelength -> redshift
89 * - zoptwave() redshift -> vacuum wavelength
90 *
91 * - velobeta() relativistic velocity -> beta (= v/c)
92 * - betavelo() beta (= v/c) -> relativistic velocity
93 *
94 * These are the workhorse routines, to be used for fast transformations.
95 * Conversions may be done "in place" by calling the routine with the output
96 * vector set to the input.
97 *
98 * Argument checking:
99 * ------------------
100 * The input spectral values are only checked for values that would result
101 * in floating point exceptions. In particular, negative frequencies and
102 * wavelengths are allowed, as are velocities greater than the speed of
103 * light. The same is true for the spectral parameters - rest frequency and
104 * wavelength.
105 *
106 * Accuracy:
107 * ---------
108 * No warranty is given for the accuracy of these routines (refer to the
109 * copyright notice); intending users must satisfy for themselves their
110 * adequacy for the intended purpose. However, closure effectively to within
111 * double precision rounding error was demonstrated by test routine tspec.c
112 * which accompanies this software.
113 *
114 *
115 * specx() - Spectral cross conversions (scalar)
116 * ---------------------------------------------
117 * Given one spectral variable specx() computes all the others, plus the
118 * required derivatives of each with respect to the others.
119 *
120 * Given:
121 * type const char*
122 * The type of spectral variable given by spec, FREQ,
123 * AFRQ, ENER, WAVN, VRAD, WAVE, VOPT, ZOPT, AWAV, VELO,
124 * or BETA (case sensitive).
125 *
126 * spec double The spectral variable given, in SI units.
127 *
128 * restfrq,
129 * restwav double Rest frequency [Hz] or rest wavelength in vacuo [m],
130 * only one of which need be given. The other should be
131 * set to zero. If both are zero, only a subset of the
132 * spectral variables can be computed, the remainder are
133 * set to zero. Specifically, given one of FREQ, AFRQ,
134 * ENER, WAVN, WAVE, or AWAV the others can be computed
135 * without knowledge of the rest frequency. Likewise,
136 * VRAD, VOPT, ZOPT, VELO, and BETA.
137 *
138 * Given and returned:
139 * specs struct spxprm*
140 * Data structure containing all spectral variables and
141 * their derivatives, in SI units.
142 *
143 * Function return value:
144 * int Status return value:
145 * 0: Success.
146 * 1: Null spxprm pointer passed.
147 * 2: Invalid spectral parameters.
148 * 3: Invalid spectral variable.
149 *
150 * For returns > 1, a detailed error message is set in
151 * spxprm::err if enabled, see wcserr_enable().
152 *
153 * freqafrq(), afrqfreq(), freqener(), enerfreq(), freqwavn(), wavnfreq(),
154 * freqwave(), wavefreq(), freqawav(), awavfreq(), waveawav(), awavwave(),
155 * velobeta(), and betavelo() implement vector conversions between wave-like
156 * or velocity-like spectral types (i.e. conversions that do not need the rest
157 * frequency or wavelength). They all have the same API.
158 *
159 *
160 * freqafrq() - Convert frequency to angular frequency (vector)
161 * ------------------------------------------------------------
162 * freqafrq() converts frequency to angular frequency.
163 *
164 * Given:
165 * param double Ignored.
166 *
167 * nspec int Vector length.
168 *
169 * instep,
170 * outstep int Vector strides.
171 *
172 * inspec const double[]
173 * Input spectral variables, in SI units.
174 *
175 * Returned:
176 * outspec double[] Output spectral variables, in SI units.
177 *
178 * stat int[] Status return value for each vector element:
179 * 0: Success.
180 * 1: Invalid value of inspec.
181 *
182 * Function return value:
183 * int Status return value:
184 * 0: Success.
185 * 2: Invalid spectral parameters.
186 * 4: One or more of the inspec coordinates were
187 * invalid, as indicated by the stat vector.
188 *
189 *
190 * freqvelo(), velofreq(), freqvrad(), and vradfreq() implement vector
191 * conversions between frequency and velocity spectral types. They all have
192 * the same API.
193 *
194 *
195 * freqvelo() - Convert frequency to relativistic velocity (vector)
196 * ----------------------------------------------------------------
197 * freqvelo() converts frequency to relativistic velocity.
198 *
199 * Given:
200 * param double Rest frequency [Hz].
201 *
202 * nspec int Vector length.
203 *
204 * instep,
205 * outstep int Vector strides.
206 *
207 * inspec const double[]
208 * Input spectral variables, in SI units.
209 *
210 * Returned:
211 * outspec double[] Output spectral variables, in SI units.
212 *
213 * stat int[] Status return value for each vector element:
214 * 0: Success.
215 * 1: Invalid value of inspec.
216 *
217 * Function return value:
218 * int Status return value:
219 * 0: Success.
220 * 2: Invalid spectral parameters.
221 * 4: One or more of the inspec coordinates were
222 * invalid, as indicated by the stat vector.
223 *
224 *
225 * wavevelo(), velowave(), awavvelo(), veloawav(), wavevopt(), voptwave(),
226 * wavezopt(), and zoptwave() implement vector conversions between wavelength
227 * and velocity spectral types. They all have the same API.
228 *
229 *
230 * wavevelo() - Conversions between wavelength and velocity types (vector)
231 * -----------------------------------------------------------------------
232 * wavevelo() converts vacuum wavelength to relativistic velocity.
233 *
234 * Given:
235 * param double Rest wavelength in vacuo [m].
236 *
237 * nspec int Vector length.
238 *
239 * instep,
240 * outstep int Vector strides.
241 *
242 * inspec const double[]
243 * Input spectral variables, in SI units.
244 *
245 * Returned:
246 * outspec double[] Output spectral variables, in SI units.
247 *
248 * stat int[] Status return value for each vector element:
249 * 0: Success.
250 * 1: Invalid value of inspec.
251 *
252 * Function return value:
253 * int Status return value:
254 * 0: Success.
255 * 2: Invalid spectral parameters.
256 * 4: One or more of the inspec coordinates were
257 * invalid, as indicated by the stat vector.
258 *
259 *
260 * spxprm struct - Spectral variables and their derivatives
261 * --------------------------------------------------------
262 * The spxprm struct contains the value of all spectral variables and their
263 * derivatives. It is used solely by specx() which constructs it from
264 * information provided via its function arguments.
265 *
266 * This struct should be considered read-only, no members need ever be set nor
267 * should ever be modified by the user.
268 *
269 * double restfrq
270 * (Returned) Rest frequency [Hz].
271 *
272 * double restwav
273 * (Returned) Rest wavelength [m].
274 *
275 * int wavetype
276 * (Returned) True if wave types have been computed, and ...
277 *
278 * int velotype
279 * (Returned) ... true if velocity types have been computed; types are
280 * defined below.
281 *
282 * If one or other of spxprm::restfrq and spxprm::restwav is given
283 * (non-zero) then all spectral variables may be computed. If both are
284 * given, restfrq is used. If restfrq and restwav are both zero, only wave
285 * characteristic xor velocity type spectral variables may be computed
286 * depending on the variable given. These flags indicate what is
287 * available.
288 *
289 * double freq
290 * (Returned) Frequency [Hz] (wavetype).
291 *
292 * double afrq
293 * (Returned) Angular frequency [rad/s] (wavetype).
294 *
295 * double ener
296 * (Returned) Photon energy [J] (wavetype).
297 *
298 * double wavn
299 * (Returned) Wave number [/m] (wavetype).
300 *
301 * double vrad
302 * (Returned) Radio velocity [m/s] (velotype).
303 *
304 * double wave
305 * (Returned) Vacuum wavelength [m] (wavetype).
306 *
307 * double vopt
308 * (Returned) Optical velocity [m/s] (velotype).
309 *
310 * double zopt
311 * (Returned) Redshift [dimensionless] (velotype).
312 *
313 * double awav
314 * (Returned) Air wavelength [m] (wavetype).
315 *
316 * double velo
317 * (Returned) Relativistic velocity [m/s] (velotype).
318 *
319 * double beta
320 * (Returned) Relativistic beta [dimensionless] (velotype).
321 *
322 * double dfreqafrq
323 * (Returned) Derivative of frequency with respect to angular frequency
324 * [/rad] (constant, = 1 / 2*pi), and ...
325 * double dafrqfreq
326 * (Returned) ... vice versa [rad] (constant, = 2*pi, always available).
327 *
328 * double dfreqener
329 * (Returned) Derivative of frequency with respect to photon energy
330 * [/J/s] (constant, = 1/h), and ...
331 * double denerfreq
332 * (Returned) ... vice versa [Js] (constant, = h, Planck's constant,
333 * always available).
334 *
335 * double dfreqwavn
336 * (Returned) Derivative of frequency with respect to wave number [m/s]
337 * (constant, = c, the speed of light in vacuo), and ...
338 * double dwavnfreq
339 * (Returned) ... vice versa [s/m] (constant, = 1/c, always available).
340 *
341 * double dfreqvrad
342 * (Returned) Derivative of frequency with respect to radio velocity [/m],
343 * and ...
344 * double dvradfreq
345 * (Returned) ... vice versa [m] (wavetype && velotype).
346 *
347 * double dfreqwave
348 * (Returned) Derivative of frequency with respect to vacuum wavelength
349 * [/m/s], and ...
350 * double dwavefreq
351 * (Returned) ... vice versa [m s] (wavetype).
352 *
353 * double dfreqawav
354 * (Returned) Derivative of frequency with respect to air wavelength,
355 * [/m/s], and ...
356 * double dawavfreq
357 * (Returned) ... vice versa [m s] (wavetype).
358 *
359 * double dfreqvelo
360 * (Returned) Derivative of frequency with respect to relativistic
361 * velocity [/m], and ...
362 * double dvelofreq
363 * (Returned) ... vice versa [m] (wavetype && velotype).
364 *
365 * double dwavevopt
366 * (Returned) Derivative of vacuum wavelength with respect to optical
367 * velocity [s], and ...
368 * double dvoptwave
369 * (Returned) ... vice versa [/s] (wavetype && velotype).
370 *
371 * double dwavezopt
372 * (Returned) Derivative of vacuum wavelength with respect to redshift [m],
373 * and ...
374 * double dzoptwave
375 * (Returned) ... vice versa [/m] (wavetype && velotype).
376 *
377 * double dwaveawav
378 * (Returned) Derivative of vacuum wavelength with respect to air
379 * wavelength [dimensionless], and ...
380 * double dawavwave
381 * (Returned) ... vice versa [dimensionless] (wavetype).
382 *
383 * double dwavevelo
384 * (Returned) Derivative of vacuum wavelength with respect to relativistic
385 * velocity [s], and ...
386 * double dvelowave
387 * (Returned) ... vice versa [/s] (wavetype && velotype).
388 *
389 * double dawavvelo
390 * (Returned) Derivative of air wavelength with respect to relativistic
391 * velocity [s], and ...
392 * double dveloawav
393 * (Returned) ... vice versa [/s] (wavetype && velotype).
394 *
395 * double dvelobeta
396 * (Returned) Derivative of relativistic velocity with respect to
397 * relativistic beta [m/s] (constant, = c, the speed of light in vacuo),
398 * and ...
399 * double dbetavelo
400 * (Returned) ... vice versa [s/m] (constant, = 1/c, always available).
401 *
402 * struct wcserr *err
403 * (Returned) If enabled, when an error status is returned this struct
404 * contains detailed information about the error, see wcserr_enable().
405 *
406 * void *padding
407 * (An unused variable inserted for alignment purposes only.)
408 *
409 * Global variable: const char *spx_errmsg[] - Status return messages
410 * ------------------------------------------------------------------
411 * Error messages to match the status value returned from each function.
412 *
413 *===========================================================================*/
414 
415 #ifndef WCSLIB_SPEC
416 #define WCSLIB_SPEC
417 
418 #ifdef __cplusplus
419 extern "C" {
420 #endif
421 
422 #include "wcserr.h"
423 
424 extern const char *spx_errmsg[];
425 
426 enum spx_errmsg {
427  SPXERR_SUCCESS = 0, /* Success. */
428  SPXERR_NULL_POINTER = 1, /* Null spxprm pointer passed. */
429  SPXERR_BAD_SPEC_PARAMS = 2, /* Invalid spectral parameters. */
430  SPXERR_BAD_SPEC_VAR = 3, /* Invalid spectral variable. */
431  SPXERR_BAD_INSPEC_COORD = 4 /* One or more of the inspec coordinates were
432  invalid. */
433 };
434 
435 struct spxprm {
436  double restfrq, restwav; /* Rest frequency [Hz] and wavelength [m]. */
437 
438  int wavetype, velotype; /* True if wave/velocity types have been */
439  /* computed; types are defined below. */
440 
441  /* Spectral variables computed by specx(). */
442  /*------------------------------------------------------------------------*/
443  double freq, /* wavetype: Frequency [Hz]. */
444  afrq, /* wavetype: Angular frequency [rad/s]. */
445  ener, /* wavetype: Photon energy [J]. */
446  wavn, /* wavetype: Wave number [/m]. */
447  vrad, /* velotype: Radio velocity [m/s]. */
448  wave, /* wavetype: Vacuum wavelength [m]. */
449  vopt, /* velotype: Optical velocity [m/s]. */
450  zopt, /* velotype: Redshift. */
451  awav, /* wavetype: Air wavelength [m]. */
452  velo, /* velotype: Relativistic velocity [m/s]. */
453  beta; /* velotype: Relativistic beta. */
454 
455  /* Derivatives of spectral variables computed by specx(). */
456  /*------------------------------------------------------------------------*/
457  double dfreqafrq, dafrqfreq, /* Constant, always available. */
458  dfreqener, denerfreq, /* Constant, always available. */
459  dfreqwavn, dwavnfreq, /* Constant, always available. */
460  dfreqvrad, dvradfreq, /* wavetype && velotype. */
461  dfreqwave, dwavefreq, /* wavetype. */
462  dfreqawav, dawavfreq, /* wavetype. */
463  dfreqvelo, dvelofreq, /* wavetype && velotype. */
464  dwavevopt, dvoptwave, /* wavetype && velotype. */
465  dwavezopt, dzoptwave, /* wavetype && velotype. */
466  dwaveawav, dawavwave, /* wavetype. */
467  dwavevelo, dvelowave, /* wavetype && velotype. */
468  dawavvelo, dveloawav, /* wavetype && velotype. */
469  dvelobeta, dbetavelo; /* Constant, always available. */
470 
471  /* Error handling */
472  /*------------------------------------------------------------------------*/
473  struct wcserr *err;
474 
475  /* Private */
476  /*------------------------------------------------------------------------*/
477  void *padding; /* (Dummy inserted for alignment purposes.) */
478 };
479 
480 /* Size of the spxprm struct in int units, used by the Fortran wrappers. */
481 #define SPXLEN (sizeof(struct spxprm)/sizeof(int))
482 
483 
484 int specx(const char *type, double spec, double restfrq, double restwav,
485  struct spxprm *specs);
486 
487 
488 /* For use in declaring function prototypes, e.g. in spcprm. */
489 #define SPX_ARGS double param, int nspec, int instep, int outstep, \
490  const double inspec[], double outspec[], int stat[]
491 
492 int freqafrq(SPX_ARGS);
493 int afrqfreq(SPX_ARGS);
494 
495 int freqener(SPX_ARGS);
496 int enerfreq(SPX_ARGS);
497 
498 int freqwavn(SPX_ARGS);
499 int wavnfreq(SPX_ARGS);
500 
501 int freqwave(SPX_ARGS);
502 int wavefreq(SPX_ARGS);
503 
504 int freqawav(SPX_ARGS);
505 int awavfreq(SPX_ARGS);
506 
507 int waveawav(SPX_ARGS);
508 int awavwave(SPX_ARGS);
509 
510 int velobeta(SPX_ARGS);
511 int betavelo(SPX_ARGS);
512 
513 
514 int freqvelo(SPX_ARGS);
515 int velofreq(SPX_ARGS);
516 
517 int freqvrad(SPX_ARGS);
518 int vradfreq(SPX_ARGS);
519 
520 
521 int wavevelo(SPX_ARGS);
522 int velowave(SPX_ARGS);
523 
524 int awavvelo(SPX_ARGS);
525 int veloawav(SPX_ARGS);
526 
527 int wavevopt(SPX_ARGS);
528 int voptwave(SPX_ARGS);
529 
530 int wavezopt(SPX_ARGS);
531 int zoptwave(SPX_ARGS);
532 
533 
534 #ifdef __cplusplus
535 }
536 #endif
537 
538 #endif /* WCSLIB_SPEC */
Generated on Wed Dec 18 2013 16:43:14 for WCSLIB 4.20 by   doxygen 1.8.4