casacore
VelocityMachine.h
Go to the documentation of this file.
1//# VelocityMachine.h: Converts between velocities and frequencies
2//# Copyright (C) 1998,1999,2000
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef MEASURES_VELOCITYMACHINE_H
29#define MEASURES_VELOCITYMACHINE_H
30
31//# Includes
32#include <casacore/casa/aips.h>
33#include <casacore/casa/Quanta/Unit.h>
34#include <casacore/casa/Quanta/Quantum.h>
35#include <casacore/measures/Measures/MCFrequency.h>
36#include <casacore/measures/Measures/MCDoppler.h>
37#include <casacore/measures/Measures/MeasConvert.h>
38#include <casacore/casa/Arrays/ArrayFwd.h>
39
40namespace casacore { //# NAMESPACE CASACORE - BEGIN
41
42//# Forward Declarations
43class MeasFrame;
44
45// <summary> Converts between velocities and frequencies </summary>
46
47// <use visibility=export>
48
49// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tVelocityMachine.cc" demos="">
50// </reviewed>
51
52// <prerequisite>
53// <li> <linkto module=Measures>Measures</linkto> module
54// <li> <linkto class=MFrequency>MFrequency</linkto> class
55// <li> <linkto class=MDoppler>MDoppler</linkto> class
56// </prerequisite>
57//
58// <etymology>
59// From Velocity and machinery
60// </etymology>
61//
62// <synopsis>
63// The construction of a VelocityMachine class object creates a machine that
64// can calculate the velocity from a frequency, or vice versa, a frequency
65// from a velocity.
66//
67// To be able to do the conversions, the machine (or rather its constructors)
68// needs to know the following information:
69// <ul>
70// <li> Reference for frequencies. It should contain at least the reference
71// code, to specify what type of frequency we are talking about
72// (e.g. MFrequency::LSRK). The reference could also contain an offset.
73// In that case all
74// input frequencies are considered to be relative to this offset; all
75// output frequencies will have this offset removed.<br>
76// The reference can optionally contain a MeasFrame (which
77// specifies where, when and in which direction you are
78// observing). This frame is necessary if, in addition to
79// converting between velocity and frequency, you also want to
80// convert between different types (e.g. given an 'LSRK' velocity,
81// you want to know the 'TOPO' frequency), and if the offset is
82// in a different reference type. However, the MeasFrame
83// can also be given explicitly in the machine constructor as an
84// optional argument.
85// <li> Preferred 'frequency' units (e.g. GHz, or cm). These units are used
86// to output a frequency, or if an input frequency is given as a
87// simple double, these units will be implicitly assumed.
88// <li> Reference for velocity. It should contain at least the reference
89// code, to specify what type of velocity we are talking about
90// (e.g. MDoppler::OPTICAL, note
91// that MDoppler::BETA is the 'true' velocity).
92// The reference could also contain an offset. In that case all
93// input velocities are considered to be relative to this offset; all
94// output velocities will have this offset removed.
95// <li> Preferred velocity units (e.g. AU/a). These units are used
96// to output a velocity, or if an input velocity is given as a
97// simple double, these units will be implicitly assumed.
98// <li> The rest frequency to be used for converting between frequency and
99// velocity. It is given as an MVFrequency.
100// </ul>
101// To be able to convert between different types (say a velocity
102// referenced with respect to the 'LSRK', and a frequency referenced
103// with respect to 'TOPO', the following additional, optional
104// information can be included explicitly in the constructors:
105// <ul>
106// <li> A reference code for the velocity (given as a frequency reference
107// code (e.g. MFrequency::TOPO)). If given, all input frequencies
108// will be converted to the frequency belonging to this reference
109// code; all output frequencies will be converted from this
110// assumed reference to the specified Frequency reference. The
111// net effect is that all velocities will be assumed to refer to
112// this reference code. Note that in most cases the conversion
113// will have to know the 'when, where, which direction'
114// environment (the 'frame' -- a MeasFrame). This can be given
115// either implicitly in the 'reference for the frequency', or
116// explicitly (see next dot point).
117// <li> A frame (MeasFrame). This frame will be used in any conversion
118// between reference frames. If not given explicitly here, it will
119// tacitly be assumed that if a frame is necessary, it has been specified
120// in the frequency reference.
121// </ul>
122// Once the machine has been set up, operator() can be used to convert
123// between velocities and frequencies if the input argument type (e.g. an
124// MVFrequency) can be deduced. In other cases makeFrequency() or
125// makeVelocity() should be used (e.g. if the argument type is a
126// simple Double).
127// </synopsis>
128//
129// <example>
130// <srcblock>
131// // Define a time/position frame
132// MEpoch epo(MVEpoch(MVTime(98,5,16,0.5).day()));
133// MPosition pos;
134// MeasTable::Observatory(pos, "ATCA");
135// MeasFrame frame(epo, pos);
136// //
137// // Note that e.g. the time in the frame can be changed later
138// // Specify the frequency reference
139// MFrequency::Ref fr(MFrequency::LSRK);
140// //
141// // Specify the velocity reference
142// MDoppler::Ref vr(MDoppler::OPT);
143// //
144// // Specify the default units
145// Unit fu("eV");
146// Unit vu("AU/a");
147// //
148// // Get the rest frequency
149// MVFrequency rfrq(QC::HI);
150// //
151// // Set up a machine (no conversion of reference frame)
152// VelocityMachine exec(fr, fu, rfrq, vr, vu, frame);
153// //
154// // or as (with conversion of reference frame it could have been)
155// // VelocityMachine exec(fr, fu, rfrq, vr, vu, MFrequency::TOPO, frame);
156// // Given a current observational frequency of 5.87432837e-06 eV
157// // its velocity will be (in AU/yr)
158// cout << "Velocity: " << exec.makeVelocity(5.87432837e-06) << endl;
159// //
160// // Introducing an offset
161// MFrequency foff(MVFrequency(Quantity(5.87432837e-06, "eV")),
162// MFrequency::LSRK);
163// //
164// // and setting it in the reference, and regenerating machine:
165// fr.set(foff);
166// exec.set(fr);
167// //
168// // the following will give the same result:
169// cout << "Velocity: " << exec.makeVelocity(0.0) << endl;
170//
171// </srcblock>
172// See the test program for more examples
173// </example>
174//
175// <motivation>
176// To aid in converting series of frequencies and velocities
177// </motivation>
178//
179// <todo asof="1998/06/02">
180// <li> Nothing I know of
181// </todo>
182
184public:
185 //# Constructors
186 // Construct a machine from the input values (no frame conversion, implicit
187 // frame if necessary)
188 VelocityMachine(const MFrequency::Ref &freqRef, const Unit &freqUnits,
189 const MVFrequency &restFreq,
190 const MDoppler::Ref &velRef, const Unit &velUnits);
191
192 // Construct a machine from the input values (no frame conversion, explicit
193 // frame will be added to freqRef)
194 VelocityMachine(const MFrequency::Ref &freqRef, const Unit &freqUnits,
195 const MVFrequency &restFreq,
196 const MDoppler::Ref &velRef, const Unit &velUnits,
197 const MeasFrame &frame);
198
199 // Construct a machine from the input values (frame conversion, implicit
200 // frame assumed if necessary) with explicit velocity reference frame
201 // specified.
202 VelocityMachine(const MFrequency::Ref &freqRef, const Unit &freqUnits,
203 const MVFrequency &restFreq,
204 const MFrequency::Types &convertRef,
205 const MDoppler::Ref &velRef, const Unit &velUnits);
206
207 // Construct a machine from the input values (frame conversion, explicit
208 // frame) with explicit velocity reference frame
209 // specified, and added to freqref.
210 VelocityMachine(const MFrequency::Ref &freqref, const Unit &freqUnits,
211 const MVFrequency &restFreq,
212 const MFrequency::Types &convertRef,
213 const MDoppler::Ref &velRef, const Unit &velUnits,
214 const MeasFrame &frame);
215
216 // Copy constructor (copy semantics)
218
219 // Copy assignment (copy semantics)
221
222 //# Destructor
224
225 //# Operators
226 // Return velocity if frequency given, or a frequency if a velocity is given
227 // <group>
235 // </group>
236
237 //# Member functions
238 // Set or reset the specified part of the machine. The machinery will be
239 // reset to reflect the changes made.
240 // <group>
241 // Sets a new frequency reference. Note that if an explicit frame has been
242 // used in earlier constructors, the frame should again be set explicitly
243 // with set(MeasFrame).
244 void set(const MFrequency::Ref &in);
245 void set(const Unit &in);
246 // Sets the rest frequency
247 void set(const MVFrequency &in);
248 void set(const MFrequency::Types &in);
249 void set(const MDoppler::Ref &in);
250 // Sets the MeasFrame to be used in conversions.
251 void set(const MeasFrame &in);
252 // </group>
253
254 // Get the general information used in the machine (shadows the sets above
255 // and the constructor arguments. The MeasFrame should be explicitly
256 // asked for from the frequency reference by the user
257 // <group>
259 const Unit &getFrequencyUnits() const;
261 const Unit &getDopplerUnits() const;
264 // </group>
265 // Recalculate the machinery from the original inputs. Note that in all
266 // normal circumstances this function does not have to be used (the set()
267 // methods will do it automatically). At the moment I cannot think of
268 // any circumstance it should be used explicitly.
270
271private:
272
273 //# Constructors
274 // Construct an empty machine (not implemented)
276
277 //# Data
278 // Frequency reference
280 // Frequency units
281 // <group>
283 // </group>
284 // Rest frequency
286 // Velocity frame
288 // Velocity reference
290 // Velocity units
291 // <group>
294 // </group>
295 // Frequency conversion forward
297 // Frequency conversion backward
299 // Velocity conversion forward
301 // Velocity conversion backward
303 // Result
304 // <group>
309 // </group>
310
311 //# Private Member Functions
312 // Initialise machinery
313 void init();
314 // Copy data members
315 void copy(const VelocityMachine &other);
316};
317
318
319} //# NAMESPACE CASACORE - END
320
321#endif
Types
Types of known MFrequencies Warning: The order defines the order in the translation matrix FromTo in...
Definition: MFrequency.h:176
VelocityMachine(const MFrequency::Ref &freqref, const Unit &freqUnits, const MVFrequency &restFreq, const MFrequency::Types &convertRef, const MDoppler::Ref &velRef, const Unit &velUnits, const MeasFrame &frame)
Construct a machine from the input values (frame conversion, explicit frame) with explicit velocity r...
const MFrequency::Types & getConversionReference() const
MDoppler::Convert cvvo_p
Velocity conversion forward.
const Quantum< Double > & operator()(const Quantum< Double > &in)
MVFrequency rest_p
Rest frequency.
void set(const MFrequency::Ref &in)
Set or reset the specified part of the machine.
VelocityMachine()
Construct an empty machine (not implemented)
VelocityMachine(const MFrequency::Ref &freqRef, const Unit &freqUnits, const MVFrequency &restFreq, const MFrequency::Types &convertRef, const MDoppler::Ref &velRef, const Unit &velUnits)
Construct a machine from the input values (frame conversion, implicit frame assumed if necessary) wit...
const MVFrequency & getRestFrequency() const
const Quantum< Double > & operator()(const MVDoppler &in)
Unit fun_p
Frequency units.
const Unit & getFrequencyUnits() const
MFrequency::Types vfm_p
Velocity frame.
const Quantum< Double > & operator()(const MVFrequency &in)
Return velocity if frequency given, or a frequency if a velocity is given.
void set(const MDoppler::Ref &in)
void set(const Unit &in)
VelocityMachine(const MFrequency::Ref &freqRef, const Unit &freqUnits, const MVFrequency &restFreq, const MDoppler::Ref &velRef, const Unit &velUnits, const MeasFrame &frame)
Construct a machine from the input values (no frame conversion, explicit frame will be added to freqR...
MFrequency::Convert cvvf_p
Frequency conversion backward.
void init()
Initialise machinery.
Quantum< Double > resf_p
const Quantum< Double > & makeFrequency(Double in)
void set(const MFrequency::Types &in)
const Quantum< Double > & makeVelocity(Double in)
Quantum< Vector< Double > > vresf_p
const Unit & getDopplerUnits() const
const MDoppler::Ref & getDopplerReference() const
Unit vun_p
Velocity units.
VelocityMachine(const VelocityMachine &other)
Copy constructor (copy semantics)
const Quantum< Vector< Double > > & makeVelocity(const Vector< Double > &in)
VelocityMachine(const MFrequency::Ref &freqRef, const Unit &freqUnits, const MVFrequency &restFreq, const MDoppler::Ref &velRef, const Unit &velUnits)
Construct a machine from the input values (no frame conversion, implicit frame if necessary)
const MFrequency::Ref & getFrequencyReference() const
Get the general information used in the machine (shadows the sets above and the constructor arguments...
void set(const MVFrequency &in)
Sets the rest frequency.
void copy(const VelocityMachine &other)
Copy data members.
MFrequency::Convert cvfv_p
Frequency conversion forward.
Quantum< Vector< Double > > vresv_p
MDoppler::Convert cvov_p
Velocity conversion backward.
MDoppler::Ref vref_p
Velocity reference.
const Quantum< Vector< Double > > & makeFrequency(const Vector< Double > &in)
void set(const MeasFrame &in)
Sets the MeasFrame to be used in conversions.
void reCalculate()
Recalculate the machinery from the original inputs.
VelocityMachine & operator=(const VelocityMachine &other)
Copy assignment (copy semantics)
Quantum< Double > resv_p
Result.
MFrequency::Ref fref_p
Frequency reference.
this file contains all the compiler specific defines
Definition: mainpage.dox:28
double Double
Definition: aipstype.h:55