casacore
Quantum.h
Go to the documentation of this file.
1 //# Quantum.h: class to manipulate physical, dimensioned quantities
2 //# Copyright (C) 1994,1995,1996,1997,1998,1999,2000,2001
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: Quantum.h 20993 2010-11-08 13:36:32Z gervandiepen $
27 
28 #ifndef CASA_QUANTUM_H
29 #define CASA_QUANTUM_H
30 
31 #include <casacore/casa/aips.h>
32 #include <casacore/casa/Quanta/QBase.h>
33 #include <casacore/casa/iosstrfwd.h>
34 
35 namespace casacore { //# NAMESPACE CASACORE - BEGIN
36 
37 //# Forward Declarations
38 template <class T> class Quantum;
39 
40 //# Typedefs
42 
43 // <summary>
44 // Quantities (i.e. dimensioned values)
45 // </summary>
46 
47 // <use visibility=export>
48 
49 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tQuantum">
50 // </reviewed>
51 //
52 // <prerequisite>
53 // <li> <linkto class=Unit>Unit</linkto>
54 // </prerequisite>
55 //
56 // <etymology>
57 // A Quantity is defined as a single Double value with attached units.
58 // From this definition the templated Quantum class arose, to have non-Double,
59 // non-scalar quantities.
60 // </etymology>
61 //
62 // <synopsis>
63 // Quantities are values with a unit. Their basic specification can be one of
64 // two forms:
65 // <srcblock>
66 // Quantity( Double value, String unit); // or: Unit unit
67 // Quantum<Type> ( Type value, String unit) // or: Unit unit
68 // </srcblock>
69 //
70 // A unit is a string of known unit fields separated
71 // by 'space' or '.' (to indicate multiply) or '/' (to indicate divide).
72 // See the <linkto class=Unit>Unit</linkto> class for details.
73 //
74 // Example: km/s/(Mpc.s)2 is identical to km.s-1.Mpc-2.s-2
75 //
76 // <h3> Defining a Quantum </h3>
77 // The following list of constructors is available.
78 // <note role=tip>
79 // In the following 'String' can be replaced by 'Unit' everywhere. The
80 // only difference being a check for a legitimate unit string being executed
81 // if Unit specified (with exception if error)
82 // </note>
83 // <note role=tip>
84 // <src>'Quantum<Type>'</src> can, if Type equals Double, be replaced
85 // with 'Quantity'
86 //
87 // 'Type' can be any simple or non-simple arithmetic type.
88 //
89 // E.g. <src><Double>, <Complex>, <Vector<Double> ></src>
90 // </note>
91 // <ul>
92 // <li> <src>Quantum<Type>() value 0 generated</src>
93 // <li> <src>Quantum<Type>( Quantum<Type>) copy constructor</src>
94 // <li> <src>Quantum<Type>( Type factor) value factor generated</src>
95 // <li> <src>Quantum<Type>( Type factor, Unit unit) specified quantity</src>
96 // <li> <src>Quantum<Type>( Type factor, Quantum<any> quant) specified factor,</src>
97 // the unit from the quant
98 // </ul>
99 //
100 //
101 // <h3> Manipulating quantities </h3>
102 // <linkto group="QMath.h#Quantum mathematical operations">Mathematical operators and functions</linkto> and
103 // <linkto group="QLogical.h#Quantum logical operations">logical operations</linkto> (comparisons)
104 // are defined on Quantums. They are,
105 // of course, only available if the template Type supports them.
106 // <ul>
107 // <li> <src>= assignment of identical <type></src>
108 // <li> <src>* *= multiple two Quantums of same <type>, or Quantum and type</src>
109 // <li> <src>/ /= divide two Quantums of same <type>, or Quantum and type</src>
110 // note:
111 // In multiplication and division, and if <src><type></src> is scalar, the left or
112 // right-hand side can be of type <src><type></src> (e.g 2.*Quantity is allowed)
113 // <li> <src>+ += add two Quantums of same <type> or Quantum and type</src>
114 // and same unit dimensions (else exception)
115 // <li> - -= subtract (same as +)
116 // <li> - negate Quantum
117 // <li> + unary + on Quantum
118 // <li> <src>== != compare unit dimensions and value of same <type>. They will</src>
119 // be unequal if the units do not match or the values (possibly
120 // converted to common base units). All comparisons work also
121 // on a <src>Quantum<type> and <type></src>
122 // <li> <src>< > compare unit dimensions. Exception if no match,</src>
123 // else compare the values
124 // <li> <src><= >= ibid</src>
125 // <li> pow(Int) raise to an (integer) power
126 // </ul>
127 //
128 //
129 // <h3> Manipulating the value and/or units of quanta </h3>
130 // Quantities can be converted to other units by the following set of member
131 // functions:
132 // <ul>
133 // <li> convert() will convert the quantum to canonical units.
134 // E.g. given myval=Quantity(5.,"Jy"),
135 // myval.convert() will convert the qunatum to
136 // Quantity(5.e-26,"kg.s-2")
137 // <li> convert(Unit unit) will convert the quantum to the
138 // specified unit with any remaining dimensions
139 // expressed in canonical units. E.g given
140 // myval as above, myval.convert("W/cm") will
141 // make it Quantity(5.e-28,"W/cm.m-1.s")
142 // <li> <src>convert(Quantum<Type> quant) will convert the quantum</src>
143 // to the units of the specified quant with the
144 // same conversion rules as the previous one
145 // </ul>
146 // <note role=tip> All converting type methods (i.e. convert(), get() and
147 // getValue() with specified units), will automatically convert also from
148 // time to angle units (or v.v) if necessary, as long as they are simple. I.e.
149 // deg will be converted to h, but asking to convert m/s to m/deg will
150 // produce the standard conversion to m/deg.rad/s. </note>
151 //
152 // Quanta can be checked for having the correct unit dimensions (e.g. before
153 // addition or comparing) by the following two member functions, which will
154 // return a Bool value:
155 // <ul>
156 // <li> isConform(Unit unit)
157 // <li> <src>isConform(Quantum<Type> quant)</src>
158 // <li> check(UnitVal kind)
159 // </ul>
160 // or by an assertion, which will throw an exception:<br>
161 // <ul>
162 // <li> assure(UnitVal kind)
163 // </ul>
164 //
165 // The quantum can be retrieved with a change in units by:
166 // <ul>
167 // <li> get() will return the quantum converted to canonical units.
168 // E.g. given myval=Quantity(5.,"Jy"),
169 // myval.get() will return
170 // Quantity(5.e-26,"kg.s-2")
171 // <li> get(Unit unit) will return the quantum converted to the
172 // specified unit with any remaining dimensions
173 // expressed in canonical units. E.g given
174 // myval as above, myval.get("W/cm") will
175 // return it as Quantity(5.e-28,"W/cm.m-1.s")
176 // <li> <src>get(Quantum<Type> quant) will return the quantum converted</src>
177 // to the units of the specified quant with the
178 // same conversion rules as the previous one
179 // </ul>
180 //
181 // The value and units of a quantum can be set or retrieved separately by the
182 // following member functions:
183 // <ul>
184 // <li> getValue() return the value (as Type) of the quantum.
185 // <note role=tip> myval.get().getValue() will return the
186 // value of myval expressed in canonical units
187 // </note>
188 // <li> getValue(Unit unit) return the value (as converted to unit)
189 // <li> getUnit() return the String part of the unit of the
190 // quantum (use getFullUnit if interested in
191 // the complete Unit, e.g. for re-use)
192 // <li> getFullUnit() return the complete unit of the Quantum (use
193 // getUnit() if interested in String part only)
194 // <li> setValue(Type val) replace the value of the quantum with val,
195 // leaving the units the same
196 // <li> scale(Type val) multiply the value (leaving units same) by the
197 // specified value
198 // <li> setUnit(Unit unit) replace the units of the quantum, leaving
199 // the value the same.
200 // <li> <src>setUnit(Quantum<Type> quant) ibid</src>
201 // <li> set(String quantity) replace the value and unit as deduced from quantity
202 // </ul>
203 //
204 // The output operator (<src><<</src>) will produce the value of the quantum and its
205 // units. Given <src>Quantity myval(5.,"mJy"), << myval</src> will produce:
206 // <src>5.0 mJy</src>; while <src><< myval.get("yW/m2")</src>
207 // will produce: <src>.00005 yW/m2.s</src>.<br>
208 // The input operator (<src>>></src>, or the static read functions) will
209 // convert a String to a Quantum (quantity only for now). The analysis
210 // will do the following:
211 // <ul>
212 // <li> Check if it can be converted as a time/angle, if so use
213 // (<linkto class=MVAngle>MVAngle</linkto>)
214 // <li> Check if it can be used as a date/time. if so use
215 // (<linkto class=MVTime>MVTime</linkto>)
216 // <li> Interpret as a value with units
217 // </ul>
218 // <note role=caution> Since e.g. <em>12d</em> could be interpreted as
219 // being both an angle (12 degrees) or a quantity (12 days), the only way
220 // is to differentiate them with a decimal point (12.d will be days)</note>
221 //
222 // </synopsis>
223 //
224 // <example>
225 // An experiment has measured the energy of a photon in keV. The following will
226 // output the wavelength and frequency of this photon (see the
227 // <linkto class=QC">QC</linkto> class for quantity constants):
228 // <srcblock>
229 // #include <casacore/casa/Quanta.h>
230 // Double myval; // keV photon energy
231 // Quantity quant(myval,"keV"); // make quantity
232 // cout << "A photon with energy " << quant << endl
233 // << " has a frequency of "
234 // << (quant/QC::h)->get("GHz") << endl // h=Planck
235 // << " and a wavelength of "
236 // << (QC::c/quant/QC::h)->get("nm") // c=light velocity
237 // << " or " << QC::c/quant/QC::h << endl;
238 // </srcblock>
239 // </example>
240 //
241 // <motivation>
242 // Major use is foreseen in all calculations with observed data.
243 // </motivation>
244 
245 // <templating arg=Qtype>
246 // <li> prefix +,-
247 // <li> + - * / and += -= *= /=
248 // <li> <src>< <= == != >= ></src>
249 // <li> sin
250 // <li> cos
251 // <li> tan
252 // <li> asin
253 // <li> acos
254 // <li> atan
255 // <li> atan2
256 // <li> abs
257 // <li> ceil
258 // <li> floor
259 // <li> <note role=caution>
260 // It is assumed that all these functions return either Bool or
261 // the same data type as inputted (i.e. QType). Special functions are
262 // provided in this module to convert Int and LogicalArray to Bool;
263 // and to convert were necessary to Complex (e.g. abs(Complex)).
264 // </note>
265 // </templating>
266 
267 // <todo asof="941123">
268 // <li> Some inlining (did not work first go)
269 // </todo>
270 
271 template <class Qtype> class Quantum : public QBase{
272  //# Friends
273  // Input, only quantity is supported now
274  friend istream& operator>> (istream &is, Quantity &ku);
275  public:
276  //# Constructors
277  // Default constructor, generates '0'
279  // Copy constructor (deep copy)
280  Quantum(const Quantum<Qtype> &other);
281  // Construct undimensioned quantum (i.e. unit="")
282  Quantum(const Qtype &factor);
283  // Construct dimensioned quantum (e.g. '1.23 km/Mpc')
284  // <thrown>
285  // <li> AipsError if non-matching unit dimensions
286  // </thrown>
287  // <group>
288  Quantum(const Qtype &factor, const Unit &s);
289  // </group>
290  // Construct quantum with unit copied from existing quantum
291  Quantum(const Qtype &factor, const QBase &other);
292 
293  //# Operators
294  // Assignment (deep copy)
296 
297  // Unary operations
298  // <group>
299  const Quantum<Qtype> &operator+() const;
301  // </group>
302 
303  // In place arithmetic functions: left hand side changed in place
304  // <thrown>
305  // <li> AipsError if non-conforming units (+ and -)
306  // <li> AipsError if illegal result unit (* and /; programming error)
307  // </thrown>
308  // <group>
310  Quantum<Qtype> &operator+=(const Qtype &other);
312  Quantum<Qtype> &operator-=(const Qtype &other);
314  Quantum<Qtype> &operator*=(const Qtype &other);
316  Quantum<Qtype> &operator/=(const Qtype &other);
317  // </group>
318 
319  // Arithmetic operators: return Quantum<T>
320  // <thrown>
321  // <li> AipsError if non-conforming units (+ and -)
322  // </thrown>
323  // See <linkto group="QMath#Quantum mathematical operations">QMath</linkto> class for unequal argument types
324  // <group>
329  // </group>
330 
331  //# General member functions
332  // Get value of quantum in current units (i.e. in units specified in quantum)
333  // <group>
334  const Qtype &getValue() const;
335  Qtype &getValue();
336  // </group>
337  // Get value in canonical base units
338  Qtype getBaseValue() const;
339 
340  // Get value in specified units.
341  // If the <src>other</src> units do not conform to the units of this
342  // object and requireConform is True, an exception is thrown,
343  // with the following exceptions:
344  // <br>- angle to/from time conversions are implicitly supported
345  // <br>- frequency to/from/ wavelength conversions are implicitly supported
346  //# <br>Note, I added requireConform and made the default value False for
347  //# backward compatibility. However, I think that ultimately requireConform
348  //# should be removed and an exception should be thrown if the units do
349  //# not conform. It's not clear to me why this was not in the original
350  //# implementation; it's much too easy for non-conformation bugs to
351  //# slip by unnoticed. - dmehring 09feb2015
352  //# It should be left in since conversion from time to angle makes sense.
353  //# Maybe the default could be changed to True. - gvandiepen09feb2016
354  Qtype getValue(const Unit &other, Bool requireConform=False) const;
355 
356  // Get the unit (as Unit) that is attached to the Quantum. (use getUnit() if
357  // interested in the String part only, e.g. for output)
358  virtual const Unit &getFullUnit() const;
359 
360  // Re-specify parts of a quantum
361  // <group name="set value">
362  // Scale ( i.e. multiply) the value of the Quantum without changing units
363  void scale(const Qtype &factor);
364  // Set the value without changing units
365  void setValue(const Qtype &val);
366  // Set the value and unit deduced from input string
367  // <note role=caution> At the moment the implementation can only convert
368  // scalars to the appropiate Quantum. If format for Array input defined,
369  // it could easily be changed. In addition recognition of date/time/angle
370  // still has to be added </note>
371  // <group>
372  static Bool read(Quantity &res, const String &in);
373  static Bool read(Quantity &res, MUString &in);
374  // </group>
375  // </group>
376 
377  // Check if of specified type
378  Bool check(const UnitVal &uv) const;
379 
380  // Assert correct kind
381  // <thrown>
382  // <li> AipsError if non-conforming unit dimensions
383  // </thrown>
384  void assure(const UnitVal &uv) const;
385 
386  // Return a Quantum converted to specified units
387  // <group name="get">
388  // Convert to canonical units
389  Quantum<Qtype> get() const;
390  // Convert to specified units; any remainder will be expressed in canonical
391  // units. E.g. conversion of Jy/pc into W/ly2 will result in W/ly2.m-1.s .
392  // <thrown>
393  // <li> AipsError if illegal unit
394  // </thrown>
395  Quantum<Qtype> get(const Unit &s) const;
396  // Convert a Quantum to units from specified quantum (ibid example)
397  Quantum<Qtype> get(const Quantum<Qtype> &other) const;
398  // </group>
399 
400  // Convert a Quantum to specified units
401  // <group>
402  // Convert to canonical units
403  void convert();
404  // Convert to specified units; any remainder will be expressed in canonical
405  // units. E.g. conversion of Jy/pc into W/ly2 will result in W/ly2.m-1.s .
406  // <thrown>
407  // <li> AipsError if illegal unit
408  // </thrown>
409  void convert(const Unit &s);
410  // Convert a Quantum to units from specified quantum (ibid example)
411  void convert(const Quantum<Qtype> &other) ;
412  // </group>
413  // Get a copy of Quantum
414  virtual QBase *clone() const;
415  // Print a Quantum
416  virtual void print(ostream &os) const;
417  // Get the type (using QuantumType) of derived Quantum (faster than Strings)
418  // <group>
419  virtual uInt type() const;
420  static uInt myType();
421  // </group>
422 
423 private:
424  //# Data members
425  // Actual quantum value
426  Qtype qVal;
427 
428 };
429 
430 // Global functions
431 // <summary> Global input function </summary>
432 // Output/Input
433 // <group name=output>
434 // only Quantity is supported on input
435 istream& operator>> (istream &is, Quantity &ku);
436 Bool readQuantity(Quantity &res, MUString &in);
437 Bool readQuantity(Quantity &res, const String &in);
438 // </group>
439 
440 //# Declare extern templates for often used types.
441  extern template class Quantum<Double>;
442 
443 
444 } //# NAMESPACE CASACORE - END
445 
446 #ifndef CASACORE_NO_AUTO_TEMPLATES
447 #include <casacore/casa/Quanta/Quantum.tcc>
448 #endif //# CASACORE_NO_AUTO_TEMPLATES
449 #endif
Quantum(const Quantum< Qtype > &other)
Copy constructor (deep copy)
Quantum< Qtype > get() const
Return a Quantum converted to specified units
Quantum< Qtype > get(const Quantum< Qtype > &other) const
Convert a Quantum to units from specified quantum (ibid example)
Quantum(const Qtype &factor, const Unit &s)
Construct dimensioned quantum (e.g.
friend istream & operator>>(istream &is, Quantity &ku)
Input, only quantity is supported now.
Quantum(const Qtype &factor, const QBase &other)
Construct quantum with unit copied from existing quantum.
void convert()
Convert a Quantum to specified units.
void convert(const Quantum< Qtype > &other)
Convert a Quantum to units from specified quantum (ibid example)
Qtype qVal
Actual quantum value.
Definition: Quantum.h:426
Quantum< Qtype > & operator+=(const Quantum< Qtype > &other)
In place arithmetic functions: left hand side changed in place.
virtual const Unit & getFullUnit() const
Get the unit (as Unit) that is attached to the Quantum.
Quantum< Qtype > operator+(const Quantum< Qtype > &other) const
Arithmetic operators: return Quantum<T>
Bool check(const UnitVal &uv) const
Check if of specified type.
Quantum< Qtype > operator-(const Quantum< Qtype > &other) const
Qtype & getValue()
virtual QBase * clone() const
Get a copy of Quantum.
Quantum< Qtype > operator-() const
void convert(const Unit &s)
Convert to specified units; any remainder will be expressed in canonical units.
Quantum< Qtype > & operator*=(const Quantum< Qtype > &other)
void scale(const Qtype &factor)
Re-specify parts of a quantum
Quantum< Qtype > operator*(const Quantum< Qtype > &other) const
Quantum< Qtype > & operator/=(const Quantum< Qtype > &other)
virtual void print(ostream &os) const
Print a Quantum.
Qtype getValue(const Unit &other, Bool requireConform=False) const
Get value in specified units.
Quantum< Qtype > & operator-=(const Qtype &other)
const Quantum< Qtype > & operator+() const
Unary operations.
Qtype getBaseValue() const
Get value in canonical base units.
Quantum< Qtype > & operator+=(const Qtype &other)
Quantum< Qtype > operator/(const Quantum< Qtype > &other) const
Quantum< Qtype > get(const Unit &s) const
Convert to specified units; any remainder will be expressed in canonical units.
Quantum< Qtype > & operator=(const Quantum< Qtype > &other)
Assignment (deep copy)
virtual uInt type() const
Get the type (using QuantumType) of derived Quantum (faster than Strings)
Quantum(const Qtype &factor)
Construct undimensioned quantum (i.e.
static Bool read(Quantity &res, const String &in)
Set the value and unit deduced from input string Caution: At the moment the implementation can only ...
static uInt myType()
void assure(const UnitVal &uv) const
Assert correct kind.
void setValue(const Qtype &val)
Set the value without changing units.
Quantum()
Default constructor, generates '0'.
const Qtype & getValue() const
Get value of quantum in current units (i.e.
static Bool read(Quantity &res, MUString &in)
Quantum< Qtype > & operator/=(const Qtype &other)
Quantum< Qtype > & operator-=(const Quantum< Qtype > &other)
Quantum< Qtype > & operator*=(const Qtype &other)
String: the storage and methods of handling collections of characters.
Definition: String.h:225
this file contains all the compiler specific defines
Definition: mainpage.dox:28
const Bool False
Definition: aipstype.h:44
unsigned int uInt
Definition: aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
Quantum< Double > Quantity
Definition: Quantum.h:38
AipsIO & operator>>(AipsIO &os, Record &rec)
Definition: Record.h:465