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 
40 namespace casacore { //# NAMESPACE CASACORE - BEGIN
41 
42 //# Forward Declarations
43 class 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 
184 public:
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.
269  void reCalculate();
270 
271 private:
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...
MDoppler::Convert cvvo_p
Velocity conversion forward.
MVFrequency rest_p
Rest frequency.
const Unit & getFrequencyUnits() const
const Quantum< Double > & makeFrequency(Double in)
void set(const MFrequency::Ref &in)
Set or reset the specified part of the machine.
const Quantum< Double > & operator()(const Quantum< Double > &in)
const Quantum< Double > & operator()(const MVFrequency &in)
Return velocity if frequency given, or a frequency if a velocity is given.
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...
Unit fun_p
Frequency units.
const Quantum< Vector< Double > > & makeVelocity(const Vector< Double > &in)
MFrequency::Types vfm_p
Velocity frame.
const MFrequency::Types & getConversionReference() const
void set(const MDoppler::Ref &in)
void set(const Unit &in)
VelocityMachine & operator=(const VelocityMachine &other)
Copy assignment (copy semantics)
const Unit & getDopplerUnits() const
const MFrequency::Ref & getFrequencyReference() const
Get the general information used in the machine (shadows the sets above and the constructor arguments...
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...
const Quantum< Double > & operator()(const MVDoppler &in)
MFrequency::Convert cvvf_p
Frequency conversion backward.
void init()
Initialise machinery.
Quantum< Double > resf_p
void set(const MFrequency::Types &in)
Quantum< Vector< Double > > vresf_p
const Quantum< Double > & makeVelocity(Double in)
const Quantum< Vector< Double > > & makeFrequency(const Vector< Double > &in)
const MVFrequency & getRestFrequency() const
Unit vun_p
Velocity units.
VelocityMachine(const VelocityMachine &other)
Copy constructor (copy semantics)
const MDoppler::Ref & getDopplerReference() const
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)
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.
void set(const MeasFrame &in)
Sets the MeasFrame to be used in conversions.
void reCalculate()
Recalculate the machinery from the original inputs.
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