Quantum.h
Classes
- Quantum -- Quantities (i.e. dimensioned values) (full description)
- Global Functions -- Global input function (full description)
template <class Qtype> class Quantum : public QBase
Interface
- friend istream& operator>> (istream &is, Quantity &ku)
- Public Members
- Quantum()
- Quantum(const Quantum<Qtype> &other)
- Quantum(const Qtype &factor)
- Quantum(const Qtype &factor, const Unit &s)
- Quantum(const Qtype &factor, const QBase &other)
- ~Quantum()
- Quantum<Qtype> &operator=(const Quantum<Qtype> &other)
- const Quantum<Qtype> &operator+() const
- Quantum<Qtype> operator-() const
- Quantum<Qtype> &operator+=(const Quantum<Qtype> &other)
- Quantum<Qtype> &operator+=(const Qtype &other)
- Quantum<Qtype> &operator-=(const Quantum<Qtype> &other)
- Quantum<Qtype> &operator-=(const Qtype &other)
- Quantum<Qtype> &operator*=(const Quantum<Qtype> &other)
- Quantum<Qtype> &operator*=(const Qtype &other)
- Quantum<Qtype> &operator/=(const Quantum<Qtype> &other)
- Quantum<Qtype> &operator/=(const Qtype &other)
- Quantum<Qtype> operator+(const Quantum<Qtype> &other) const
- Quantum<Qtype> operator-(const Quantum<Qtype> &other) const
- Quantum<Qtype> operator*(const Quantum<Qtype> &other) const
- Quantum<Qtype> operator/(const Quantum<Qtype> &other) const
- const Qtype &getValue() const
- Qtype &getValue()
- Qtype getBaseValue() const
- Qtype getValue(const Unit &other) const
- virtual const Unit &getFullUnit() const
- void scale(const Qtype &factor)
- void setValue(const Qtype &val)
- static Bool read(Quantity &res, const String &in)
- static Bool read(Quantity &res, MUString &in)
- Bool check(const UnitVal &uv) const
- void assure(const UnitVal &uv) const
- Quantum<Qtype> get() const
- Quantum<Qtype> get(const Unit &s) const
- Quantum<Qtype> get(const Quantum<Qtype> &other) const
- void convert()
- void convert(const Unit &s)
- void convert(const Quantum<Qtype> &other)
- virtual QBase *clone() const
- virtual void print(ostream &os) const
- virtual uInt type() const
- static uInt myType()
- See Also
- Quantum logical operations -- Logical operations for the Quantum class.
- Quantum mathematical operations -- Mathematical operations for the Quantum class.
Review Status
- Reviewed By:
- UNKNOWN
- Date Reviewed:
- before2004/08/25
- Programs:
- Tests:
Prerequisite
Etymology
A Quantity is defined as a single Double value with attached units.
From this definition the templated Quantum class arose, to have non-Double,
non-scalar quantities.
Synopsis
Quantities are values with a unit. Their basic specification can be one of
two forms:
Quantity( Double value, String unit); // or: Unit unit
Quantum<Type> ( Type value, String unit) // or: Unit unit
A unit is a string of known unit fields separated
by 'space' or '.' (to indicate multiply) or '/' (to indicate divide).
See the Unit class for details.
Example: km/s/(Mpc.s)2 is identical to km.s-1.Mpc-2.s-2
Defining a Quantum
The following list of constructors is available.
In the following 'String' can be replaced by 'Unit' everywhere. The
only difference being a check for a legitimate unit string being executed
if Unit specified (with exception if error)
'Quantum<Type>' can, if Type equals Double, be replaced
with 'Quantity'
'Type' can be any simple or non-simple arithmetic type.
E.g. <Double>, <Complex>, <Vector<Double> >
- Quantum<Type>() value 0 generated
- Quantum<Type>( Quantum<Type>) copy constructor
- Quantum<Type>( Type factor) value factor generated
- Quantum<Type>( Type factor, Unit unit) specified quantity
- Quantum<Type>( Type factor, Quantum<any> quant) specified factor,
the unit from the quant
Manipulating quantities
Mathematical
operators and functions and
logical
operations (comparisons) are defined on Quantums. They are,
of course, only available if the template Type supports them.
- = assignment of identical <type>
- * *= multiple two Quantums of same <type>, or Quantum and type
- / /= divide two Quantums of same <type>, or Quantum and type
In multiplication and division, and if <type> is scalar, the left or
right-hand side can be of type <type> (e.g 2.*Quantity is allowed)
- + += add two Quantums of same <type> or Quantum and type
and same unit dimensions (else exception)
- - -= subtract (same as +)
- - negate Quantum
- + unary + on Quantum
- == != compare unit dimensions and value of same <type>. They will
be unequal if the units do not match or the values (possibly
converted to common base units). All comparisons work also
on a Quantum<type> and <type>
- < > compare unit dimensions. Exception if no match,
else compare the values
- <= >= ibid
- pow(Int) raise to an (integer) power
Manipulating the value and/or units of quanta
Quantities can be converted to other units by the following set of member
functions:
- convert() will convert the quantum to canonical units.
E.g. given myval=Quantity(5.,"Jy"),
myval.convert() will convert the qunatum to
Quantity(5.e-26,"kg.s-2")
- convert(Unit unit) will convert the quantum to the
specified unit with any remaining dimensions
expressed in canonical units. E.g given
myval as above, myval.convert("W/cm") will
make it Quantity(5.e-28,"W/cm.m-1.s")
- convert(Quantum<Type> quant) will convert the quantum
to the units of the specified quant with the
same conversion rules as the previous one
All converting type methods (i.e. convert(), get() and
getValue() with specified units), will automatically convert also from
time to angle units (or v.v) if necessary, as long as they are simple. I.e.
deg will be converted to h, but asking to convert m/s to m/deg will
produce the standard conversion to m/deg.rad/s.
Quanta can be checked for having the correct unit dimensions (e.g. before
addition or comparing) by the following two member functions, which will
return a Bool value:
- isConform(Unit unit)
- isConform(Quantum<Type> quant)
- check(UnitVal kind)
or by an assertion, which will throw an exception:
The quantum can be retrieved with a change in units by:
- get() will return the quantum converted to canonical units.
E.g. given myval=Quantity(5.,"Jy"),
myval.get() will return
Quantity(5.e-26,"kg.s-2")
- get(Unit unit) will return the quantum converted to the
specified unit with any remaining dimensions
expressed in canonical units. E.g given
myval as above, myval.get("W/cm") will
return it as Quantity(5.e-28,"W/cm.m-1.s")
- get(Quantum<Type> quant) will return the quantum converted
to the units of the specified quant with the
same conversion rules as the previous one
The value and units of a quantum can be set or retrieved separately by the
following member functions:
- getValue() return the value (as Type) of the quantum.
myval.get().getValue() will return the
value of myval expressed in canonical units
- getValue(Unit unit) return the value (as converted to unit)
- getUnit() return the String part of the unit of the
quantum (use getFullUnit if interested in
the complete Unit, e.g. for re-use)
- getFullUnit() return the complete unit of the Quantum (use
getUnit() if interested in String part only)
- setValue(Type val) replace the value of the quantum with val,
leaving the units the same
- scale(Type val) multiply the value (leaving units same) by the
specified value
- setUnit(Unit unit) replace the units of the quantum, leaving
the value the same.
- setUnit(Quantum<Type> quant) ibid
- set(String quantity) replace the value and unit as deduced from quantity
The output operator (<<) will produce the value of the quantum and its
units. Given Quantity myval(5.,"mJy"), << myval will produce:
5.0 mJy; while << myval.get("yW/m2")
will produce: .00005 yW/m2.s.
The input operator (>>, or the static read functions) will
convert a String to a Quantum (quantity only for now). The analysis
will do the following:
- Check if it can be converted as a time/angle, if so use
(MVAngle)
- Check if it can be used as a date/time. if so use
(MVTime)
- Interpret as a value with units
Since e.g. 12d could be interpreted as
being both an angle (12 degrees) or a quantity (12 days), the only way
is to differentiate them with a decimal point (12.d will be days)
Example
An experiment has measured the energy of a photon in keV. The following will
output the wavelength and frequency of this photon (see the
QC class for quantity constants):
#include <casa/Quanta.h>
Double myval; // keV photon energy
Quantity quant(myval,"keV"); // make quantity
cout << "A photon with energy " << quant << endl
<< " has a frequency of "
<< (quant/QC::h)->get("GHz") << endl // h=Planck
<< " and a wavelength of "
<< (QC::c/quant/QC::h)->get("nm") // c=light velocity
<< " or " << QC::c/quant/QC::h << endl;
Motivation
Major use is foreseen in all calculations with observed data.
Template Type Argument Requirements (Qtype)
It is assumed that all the following functions return either Bool or
the same data type as inputted (i.e. QType). Special functions are
provided in this module to convert Int and LogicalArray to Bool;
and to convert were necessary to Complex (e.g. abs(Complex)).
- prefix +,-
- + - * / and += -= *= /=
- < <= == != >= >
- sin
- cos
- tan
- asin
- acos
- atan
- atan2
- abs
- ceil
- floor
To Do
- Some inlining (did not work first go)
Member Description
friend istream& operator>> (istream &is, Quantity &ku)
Input, only quantity is supported now
Default constructor, generates '0'
Quantum(const Quantum<Qtype> &other)
Copy constructor (deep copy)
Quantum(const Qtype &factor)
Construct undimensioned quantum (i.e. unit="")
Quantum(const Qtype &factor, const Unit &s)
Construct dimensioned quantum (e.g. '1.23 km/Mpc')
Thrown Exceptions
- AipsError if non-matching unit dimensions
Quantum(const Qtype &factor, const QBase &other)
Construct quantum with unit copied from existing quantum
Destructor
Quantum<Qtype> &operator=(const Quantum<Qtype> &other)
Assignment (deep copy)
const Quantum<Qtype> &operator+() const
Quantum<Qtype> operator-() const
Unary operations
Quantum<Qtype> &operator+=(const Quantum<Qtype> &other)
Quantum<Qtype> &operator+=(const Qtype &other)
Quantum<Qtype> &operator-=(const Quantum<Qtype> &other)
Quantum<Qtype> &operator-=(const Qtype &other)
Quantum<Qtype> &operator*=(const Quantum<Qtype> &other)
Quantum<Qtype> &operator*=(const Qtype &other)
Quantum<Qtype> &operator/=(const Quantum<Qtype> &other)
Quantum<Qtype> &operator/=(const Qtype &other)
In place arithmetic functions: left hand side changed in place
Thrown Exceptions
- AipsError if non-conforming units (+ and -)
- AipsError if illegal result unit (* and /; programming error)
Quantum<Qtype> operator+(const Quantum<Qtype> &other) const
Quantum<Qtype> operator-(const Quantum<Qtype> &other) const
Quantum<Qtype> operator*(const Quantum<Qtype> &other) const
Quantum<Qtype> operator/(const Quantum<Qtype> &other) const
Arithmetic operators: return Quantum
Thrown Exceptions
- AipsError if non-conforming units (+ and -)
See QMath class for unequal argument types
Get value of quantum in current units (i.e. in units specified in quantum)
Get value in canonical base units
Qtype getValue(const Unit &other) const
Get value in specified units
Get the unit (as Unit) that is attached to the Quantum. (use getUnit() if
interested in the String part only, e.g. for output)
void scale(const Qtype &factor)
Re-specify parts of a quantum
Scale ( i.e. multiply) the value of the Quantum without changing units
void setValue(const Qtype &val)
Re-specify parts of a quantum
Set the value without changing units
static Bool read(Quantity &res, const String &in)
static Bool read(Quantity &res, MUString &in)
Re-specify parts of a quantum
Check if of specified type
Assert correct kind
Thrown Exceptions
- AipsError if non-conforming unit dimensions
Quantum<Qtype> get() const
Return a Quantum converted to specified units
Convert to canonical units
Quantum<Qtype> get(const Unit &s) const
Return a Quantum converted to specified units
Convert to specified units; any remainder will be expressed in canonical
units. E.g. conversion of Jy/pc into W/ly2 will result in W/ly2.m-1.s .
Thrown Exceptions
- AipsError if illegal unit
Quantum<Qtype> get(const Quantum<Qtype> &other) const
Return a Quantum converted to specified units
Convert a Quantum to units from specified quantum (ibid example)
Convert a Quantum to specified units
Convert to specified units; any remainder will be expressed in canonical
units. E.g. conversion of Jy/pc into W/ly2 will result in W/ly2.m-1.s .
Thrown Exceptions
- AipsError if illegal unit
void convert(const Quantum<Qtype> &other)
Convert a Quantum to specified units
Convert a Quantum to units from specified quantum (ibid example)
Convert a Quantum to specified units
Get a copy of Quantum
virtual void print(ostream &os) const
Print a Quantum
virtual uInt type() const
static uInt myType()
Get the type (== Register()) of derived Quantum (faster than Strings)
Interface
Private Members
- istream& operator>> (istream &is, Quantity &ku)
Global functions
Output/Input
Member Description
istream& operator>> (istream &is, Quantity &ku)
only Quantity is supported on input