wcslib (8.2.2)
1 /*============================================================================
2 WCSLIB 8.2 - an implementation of the FITS WCS standard.
3 Copyright (C) 1995-2023, Mark Calabretta
4
5 This file is part of WCSLIB.
6
7 WCSLIB is free software: you can redistribute it and/or modify it under the
8 terms of the GNU Lesser General Public License as published by the Free
9 Software Foundation, either version 3 of the License, or (at your option)
10 any later version.
11
12 WCSLIB is distributed in the hope that it will be useful, but WITHOUT ANY
13 WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
14 FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for
15 more details.
16
17 You should have received a copy of the GNU Lesser General Public License
18 along with WCSLIB. If not, see http://www.gnu.org/licenses.
19
20 Author: Mark Calabretta, Australia Telescope National Facility, CSIRO.
21 http://www.atnf.csiro.au/people/Mark.Calabretta
22 $Id: spx.h,v 8.2.1.1 2023/11/16 10:05:57 mcalabre Exp mcalabre $
23 *=============================================================================
24 *
25 * WCSLIB 8.2 - C routines that implement the FITS World Coordinate System
26 * (WCS) standard. Refer to the README file provided with WCSLIB for an
27 * overview of the library.
28 *
29 *
30 * Summary of the spx routines
31 * ---------------------------
32 * Routines in this suite implement the spectral coordinate systems recognized
33 * by the FITS World Coordinate System (WCS) standard, as described in
34 *
35 = "Representations of world coordinates in FITS",
36 = Greisen, E.W., & Calabretta, M.R. 2002, A&A, 395, 1061 (WCS Paper I)
37 =
38 = "Representations of spectral coordinates in FITS",
39 = Greisen, E.W., Calabretta, M.R., Valdes, F.G., & Allen, S.L.
40 = 2006, A&A, 446, 747 (WCS Paper III)
41 *
42 * specx() is a scalar routine that, given one spectral variable (e.g.
43 * frequency), computes all the others (e.g. wavelength, velocity, etc.) plus
44 * the required derivatives of each with respect to the others. The results
45 * are returned in the spxprm struct.
46 *
47 * spxperr() prints the error message(s) (if any) stored in a 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 * Air-to-vacuum wavelength conversion:
99 * ------------------------------------
100 * The air-to-vacuum wavelength conversion in early drafts of WCS Paper III
101 * cites Cox (ed., 2000, Allen’s Astrophysical Quantities, AIP Press,
102 * Springer-Verlag, New York), which itself derives from Edlén (1953, Journal
103 * of the Optical Society of America, 43, 339). This is the IAU standard,
104 * adopted in 1957 and again in 1991. No more recent IAU resolution replaces
105 * this relation, and it is the one used by WCSLIB.
106 *
107 * However, the Cox relation was replaced in later drafts of Paper III, and as
108 * eventually published, by the IUGG relation (1999, International Union of
109 * Geodesy and Geophysics, comptes rendus of the 22nd General Assembly,
110 * Birmingham UK, p111). There is a nearly constant ratio between the two,
111 * with IUGG/Cox = 1.000015 over most of the range between 200nm and 10,000nm.
112 *
113 * The IUGG relation itself is derived from the work of Ciddor (1996, Applied
114 * Optics, 35, 1566), which is used directly by the Sloan Digital Sky Survey.
115 * It agrees closely with Cox; longwards of 2500nm, the ratio Ciddor/Cox is
116 * fixed at 1.000000021, decreasing only slightly, to 1.000000018, at 1000nm.
117 *
118 * The Cox, IUGG, and Ciddor relations all accurately provide the wavelength
119 * dependence of the air-to-vacuum wavelength conversion. However, for full
120 * accuracy, the atmospheric temperature, pressure, and partial pressure of
121 * water vapour must be taken into account. These will determine a small,
122 * wavelength-independent scale factor and offset, which is not considered by
123 * WCS Paper III.
124 *
125 * WCS Paper III is also silent on the question of the range of validity of the
126 * air-to-vacuum wavelength conversion. Cox's relation would appear to be
127 * valid in the range 200nm to 10,000nm. Both the Cox and the Ciddor relations
128 * have singularities below 200nm, with Cox's at 156nm and 83nm. WCSLIB checks
129 * neither the range of validity, nor for these singularities.
130 *
131 * Argument checking:
132 * ------------------
133 * The input spectral values are only checked for values that would result
134 * in floating point exceptions. In particular, negative frequencies and
135 * wavelengths are allowed, as are velocities greater than the speed of
136 * light. The same is true for the spectral parameters - rest frequency and
137 * wavelength.
138 *
139 * Accuracy:
140 * ---------
141 * No warranty is given for the accuracy of these routines (refer to the
142 * copyright notice); intending users must satisfy for themselves their
143 * adequacy for the intended purpose. However, closure effectively to within
144 * double precision rounding error was demonstrated by test routine tspec.c
145 * which accompanies this software.
146 *
147 *
148 * specx() - Spectral cross conversions (scalar)
149 * ---------------------------------------------
150 * Given one spectral variable specx() computes all the others, plus the
151 * required derivatives of each with respect to the others.
152 *
153 * Given:
154 * type const char*
155 * The type of spectral variable given by spec, FREQ,
156 * AFRQ, ENER, WAVN, VRAD, WAVE, VOPT, ZOPT, AWAV, VELO,
157 * or BETA (case sensitive).
158 *
159 * spec double The spectral variable given, in SI units.
160 *
161 * restfrq,
162 * restwav double Rest frequency [Hz] or rest wavelength in vacuo [m],
163 * only one of which need be given. The other should be
164 * set to zero. If both are zero, only a subset of the
165 * spectral variables can be computed, the remainder are
166 * set to zero. Specifically, given one of FREQ, AFRQ,
167 * ENER, WAVN, WAVE, or AWAV the others can be computed
168 * without knowledge of the rest frequency. Likewise,
169 * VRAD, VOPT, ZOPT, VELO, and BETA.
170 *
171 * Given and returned:
172 * specs struct spxprm*
173 * Data structure containing all spectral variables and
174 * their derivatives, in SI units.
175 *
176 * Function return value:
177 * int Status return value:
178 * 0: Success.
179 * 1: Null spxprm pointer passed.
180 * 2: Invalid spectral parameters.
181 * 3: Invalid spectral variable.
182 *
183 * For returns > 1, a detailed error message is set in
184 * spxprm::err if enabled, see wcserr_enable().
185 *
186 * freqafrq(), afrqfreq(), freqener(), enerfreq(), freqwavn(), wavnfreq(),
187 * freqwave(), wavefreq(), freqawav(), awavfreq(), waveawav(), awavwave(),
188 * velobeta(), and betavelo() implement vector conversions between wave-like
189 * or velocity-like spectral types (i.e. conversions that do not need the rest
190 * frequency or wavelength). They all have the same API.
191 *
192 *
193 * spxperr() - Print error messages from a spxprm struct
194 * -----------------------------------------------------
195 * spxperr() prints the error message(s) (if any) stored in a spxprm struct.
196 * If there are no errors then nothing is printed. It uses wcserr_prt(), q.v.
197 *
198 * Given:
199 * spx const struct spxprm*
200 * Spectral variables and their derivatives.
201 *
202 * prefix const char *
203 * If non-NULL, each output line will be prefixed with
204 * this string.
205 *
206 * Function return value:
207 * int Status return value:
208 * 0: Success.
209 * 1: Null spxprm pointer passed.
210 *
211 *
212 * freqafrq() - Convert frequency to angular frequency (vector)
213 * ------------------------------------------------------------
214 * freqafrq() converts frequency to angular frequency.
215 *
216 * Given:
217 * param double Ignored.
218 *
219 * nspec int Vector length.
220 *
221 * instep,
222 * outstep int Vector strides.
223 *
224 * inspec const double[]
225 * Input spectral variables, in SI units.
226 *
227 * Returned:
228 * outspec double[] Output spectral variables, in SI units.
229 *
230 * stat int[] Status return value for each vector element:
231 * 0: Success.
232 * 1: Invalid value of inspec.
233 *
234 * Function return value:
235 * int Status return value:
236 * 0: Success.
237 * 2: Invalid spectral parameters.
238 * 4: One or more of the inspec coordinates were
239 * invalid, as indicated by the stat vector.
240 *
241 *
242 * freqvelo(), velofreq(), freqvrad(), and vradfreq() implement vector
243 * conversions between frequency and velocity spectral types. They all have
244 * the same API.
245 *
246 *
247 * freqvelo() - Convert frequency to relativistic velocity (vector)
248 * ----------------------------------------------------------------
249 * freqvelo() converts frequency to relativistic velocity.
250 *
251 * Given:
252 * param double Rest frequency [Hz].
253 *
254 * nspec int Vector length.
255 *
256 * instep,
257 * outstep int Vector strides.
258 *
259 * inspec const double[]
260 * Input spectral variables, in SI units.
261 *
262 * Returned:
263 * outspec double[] Output spectral variables, in SI units.
264 *
265 * stat int[] Status return value for each vector element:
266 * 0: Success.
267 * 1: Invalid value of inspec.
268 *
269 * Function return value:
270 * int Status return value:
271 * 0: Success.
272 * 2: Invalid spectral parameters.
273 * 4: One or more of the inspec coordinates were
274 * invalid, as indicated by the stat vector.
275 *
276 *
277 * wavevelo(), velowave(), awavvelo(), veloawav(), wavevopt(), voptwave(),
278 * wavezopt(), and zoptwave() implement vector conversions between wavelength
279 * and velocity spectral types. They all have the same API.
280 *
281 *
282 * wavevelo() - Conversions between wavelength and velocity types (vector)
283 * -----------------------------------------------------------------------
284 * wavevelo() converts vacuum wavelength to relativistic velocity.
285 *
286 * Given:
287 * param double Rest wavelength in vacuo [m].
288 *
289 * nspec int Vector length.
290 *
291 * instep,
292 * outstep int Vector strides.
293 *
294 * inspec const double[]
295 * Input spectral variables, in SI units.
296 *
297 * Returned:
298 * outspec double[] Output spectral variables, in SI units.
299 *
300 * stat int[] Status return value for each vector element:
301 * 0: Success.
302 * 1: Invalid value of inspec.
303 *
304 * Function return value:
305 * int Status return value:
306 * 0: Success.
307 * 2: Invalid spectral parameters.
308 * 4: One or more of the inspec coordinates were
309 * invalid, as indicated by the stat vector.
310 *
311 *
312 * spxprm struct - Spectral variables and their derivatives
313 * --------------------------------------------------------
314 * The spxprm struct contains the value of all spectral variables and their
315 * derivatives. It is used solely by specx() which constructs it from
316 * information provided via its function arguments.
317 *
318 * This struct should be considered read-only, no members need ever be set nor
319 * should ever be modified by the user.
320 *
321 * double restfrq
322 * (Returned) Rest frequency [Hz].
323 *
324 * double restwav
325 * (Returned) Rest wavelength [m].
326 *
327 * int wavetype
328 * (Returned) True if wave types have been computed, and ...
329 *
330 * int velotype
331 * (Returned) ... true if velocity types have been computed; types are
332 * defined below.
333 *
334 * If one or other of spxprm::restfrq and spxprm::restwav is given
335 * (non-zero) then all spectral variables may be computed. If both are
336 * given, restfrq is used. If restfrq and restwav are both zero, only wave
337 * characteristic xor velocity type spectral variables may be computed
338 * depending on the variable given. These flags indicate what is
339 * available.
340 *
341 * double freq
342 * (Returned) Frequency [Hz] (wavetype).
343 *
344 * double afrq
345 * (Returned) Angular frequency [rad/s] (wavetype).
346 *
347 * double ener
348 * (Returned) Photon energy [J] (wavetype).
349 *
350 * double wavn
351 * (Returned) Wave number [/m] (wavetype).
352 *
353 * double vrad
354 * (Returned) Radio velocity [m/s] (velotype).
355 *
356 * double wave
357 * (Returned) Vacuum wavelength [m] (wavetype).
358 *
359 * double vopt
360 * (Returned) Optical velocity [m/s] (velotype).
361 *
362 * double zopt
363 * (Returned) Redshift [dimensionless] (velotype).
364 *
365 * double awav
366 * (Returned) Air wavelength [m] (wavetype).
367 *
368 * double velo
369 * (Returned) Relativistic velocity [m/s] (velotype).
370 *
371 * double beta
372 * (Returned) Relativistic beta [dimensionless] (velotype).
373 *
374 * double dfreqafrq
375 * (Returned) Derivative of frequency with respect to angular frequency
376 * [/rad] (constant, = 1 / 2*pi), and ...
377 * double dafrqfreq
378 * (Returned) ... vice versa [rad] (constant, = 2*pi, always available).
379 *
380 * double dfreqener
381 * (Returned) Derivative of frequency with respect to photon energy
382 * [/J/s] (constant, = 1/h), and ...
383 * double denerfreq
384 * (Returned) ... vice versa [Js] (constant, = h, Planck's constant,
385 * always available).
386 *
387 * double dfreqwavn
388 * (Returned) Derivative of frequency with respect to wave number [m/s]
389 * (constant, = c, the speed of light in vacuo), and ...
390 * double dwavnfreq
391 * (Returned) ... vice versa [s/m] (constant, = 1/c, always available).
392 *
393 * double dfreqvrad
394 * (Returned) Derivative of frequency with respect to radio velocity [/m],
395 * and ...
396 * double dvradfreq
397 * (Returned) ... vice versa [m] (wavetype && velotype).
398 *
399 * double dfreqwave
400 * (Returned) Derivative of frequency with respect to vacuum wavelength
401 * [/m/s], and ...
402 * double dwavefreq
403 * (Returned) ... vice versa [m s] (wavetype).
404 *
405 * double dfreqawav
406 * (Returned) Derivative of frequency with respect to air wavelength,
407 * [/m/s], and ...
408 * double dawavfreq
409 * (Returned) ... vice versa [m s] (wavetype).
410 *
411 * double dfreqvelo
412 * (Returned) Derivative of frequency with respect to relativistic
413 * velocity [/m], and ...
414 * double dvelofreq
415 * (Returned) ... vice versa [m] (wavetype && velotype).
416 *
417 * double dwavevopt
418 * (Returned) Derivative of vacuum wavelength with respect to optical
419 * velocity [s], and ...
420 * double dvoptwave
421 * (Returned) ... vice versa [/s] (wavetype && velotype).
422 *
423 * double dwavezopt
424 * (Returned) Derivative of vacuum wavelength with respect to redshift [m],
425 * and ...
426 * double dzoptwave
427 * (Returned) ... vice versa [/m] (wavetype && velotype).
428 *
429 * double dwaveawav
430 * (Returned) Derivative of vacuum wavelength with respect to air
431 * wavelength [dimensionless], and ...
432 * double dawavwave
433 * (Returned) ... vice versa [dimensionless] (wavetype).
434 *
435 * double dwavevelo
436 * (Returned) Derivative of vacuum wavelength with respect to relativistic
437 * velocity [s], and ...
438 * double dvelowave
439 * (Returned) ... vice versa [/s] (wavetype && velotype).
440 *
441 * double dawavvelo
442 * (Returned) Derivative of air wavelength with respect to relativistic
443 * velocity [s], and ...
444 * double dveloawav
445 * (Returned) ... vice versa [/s] (wavetype && velotype).
446 *
447 * double dvelobeta
448 * (Returned) Derivative of relativistic velocity with respect to
449 * relativistic beta [m/s] (constant, = c, the speed of light in vacuo),
450 * and ...
451 * double dbetavelo
452 * (Returned) ... vice versa [s/m] (constant, = 1/c, always available).
453 *
454 * struct wcserr *err
455 * (Returned) If enabled, when an error status is returned, this struct
456 * contains detailed information about the error, see wcserr_enable().
457 *
458 * void *padding
459 * (An unused variable inserted for alignment purposes only.)
460 *
461 * Global variable: const char *spx_errmsg[] - Status return messages
462 * ------------------------------------------------------------------
463 * Error messages to match the status value returned from each function.
464 *
465 *===========================================================================*/
466
467 #ifndef WCSLIB_SPEC
468 #define WCSLIB_SPEC
469
470 #ifdef __cplusplus
471 extern "C" {
472 #endif
473
474 extern const char *spx_errmsg[];
475
476 enum spx_errmsg {
477 SPXERR_SUCCESS = 0, // Success.
478 SPXERR_NULL_POINTER = 1, // Null spxprm pointer passed.
479 SPXERR_BAD_SPEC_PARAMS = 2, // Invalid spectral parameters.
480 SPXERR_BAD_SPEC_VAR = 3, // Invalid spectral variable.
481 SPXERR_BAD_INSPEC_COORD = 4 // One or more of the inspec coordinates were
482 // invalid.
483 };
484
485 struct spxprm {
486 double restfrq, restwav; // Rest frequency [Hz] and wavelength [m].
487
488 int wavetype, velotype; // True if wave/velocity types have been
489 // computed; types are defined below.
490
491 // Spectral variables computed by specx().
492 //--------------------------------------------------------------------------
493 double freq, // wavetype: Frequency [Hz].
494 afrq, // wavetype: Angular frequency [rad/s].
495 ener, // wavetype: Photon energy [J].
496 wavn, // wavetype: Wave number [/m].
497 vrad, // velotype: Radio velocity [m/s].
498 wave, // wavetype: Vacuum wavelength [m].
499 vopt, // velotype: Optical velocity [m/s].
500 zopt, // velotype: Redshift.
501 awav, // wavetype: Air wavelength [m].
502 velo, // velotype: Relativistic velocity [m/s].
503 beta; // velotype: Relativistic beta.
504
505 // Derivatives of spectral variables computed by specx().
506 //--------------------------------------------------------------------------
507 double dfreqafrq, dafrqfreq, // Constant, always available.
508 dfreqener, denerfreq, // Constant, always available.
509 dfreqwavn, dwavnfreq, // Constant, always available.
510 dfreqvrad, dvradfreq, // wavetype && velotype.
511 dfreqwave, dwavefreq, // wavetype.
512 dfreqawav, dawavfreq, // wavetype.
513 dfreqvelo, dvelofreq, // wavetype && velotype.
514 dwavevopt, dvoptwave, // wavetype && velotype.
515 dwavezopt, dzoptwave, // wavetype && velotype.
516 dwaveawav, dawavwave, // wavetype.
517 dwavevelo, dvelowave, // wavetype && velotype.
518 dawavvelo, dveloawav, // wavetype && velotype.
519 dvelobeta, dbetavelo; // Constant, always available.
520
521 // Error handling
522 //--------------------------------------------------------------------------
523 struct wcserr *err;
524
525 // Private
526 //--------------------------------------------------------------------------
527 void *padding; // (Dummy inserted for alignment purposes.)
528 };
529
530 // Size of the spxprm struct in int units, used by the Fortran wrappers.
531 #define SPXLEN (sizeof(struct spxprm)/sizeof(int))
532
533
534 int specx(const char *type, double spec, double restfrq, double restwav,
535 struct spxprm *specs);
536
537 int spxperr(const struct spxprm *spx, const char *prefix);
538
539 // For use in declaring function prototypes, e.g. in spcprm.
540 #define SPX_ARGS double param, int nspec, int instep, int outstep, \
541 const double inspec[], double outspec[], int stat[]
542
543 int freqafrq(SPX_ARGS);
544 int afrqfreq(SPX_ARGS);
545
546 int freqener(SPX_ARGS);
547 int enerfreq(SPX_ARGS);
548
549 int freqwavn(SPX_ARGS);
550 int wavnfreq(SPX_ARGS);
551
552 int freqwave(SPX_ARGS);
553 int wavefreq(SPX_ARGS);
554
555 int freqawav(SPX_ARGS);
556 int awavfreq(SPX_ARGS);
557
558 int waveawav(SPX_ARGS);
559 int awavwave(SPX_ARGS);
560
561 int velobeta(SPX_ARGS);
562 int betavelo(SPX_ARGS);
563
564
565 int freqvelo(SPX_ARGS);
566 int velofreq(SPX_ARGS);
567
568 int freqvrad(SPX_ARGS);
569 int vradfreq(SPX_ARGS);
570
571
572 int wavevelo(SPX_ARGS);
573 int velowave(SPX_ARGS);
574
575 int awavvelo(SPX_ARGS);
576 int veloawav(SPX_ARGS);
577
578 int wavevopt(SPX_ARGS);
579 int voptwave(SPX_ARGS);
580
581 int wavezopt(SPX_ARGS);
582 int zoptwave(SPX_ARGS);
583
584
585 #ifdef __cplusplus
586 }
587 #endif
588
589 #endif // WCSLIB_SPEC
Browse
Usage
Versions