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