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.

Description

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.
Tip 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)
Tip '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> >

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.

Manipulating the value and/or units of quanta

Quantities can be converted to other units by the following set of member functions:
Tip 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:

or by an assertion, which will throw an exception:

The quantum can be retrieved with a change in units by:

The value and units of a quantum can be set or retrieved separately by the following member functions:

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:

Caution 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)

To Do

Member Description

friend istream& operator>> (istream &is, Quantity &ku)

Input, only quantity is supported now

Quantum()

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

Quantum(const Qtype &factor, const QBase &other)

Construct quantum with unit copied from existing quantum

~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

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

See QMath class for unequal argument types

const Qtype &getValue() const
Qtype &getValue()

Get value of quantum in current units (i.e. in units specified in quantum)

Qtype getBaseValue() const

Get value in canonical base units

Qtype getValue(const Unit &other) const

Get value in specified units

virtual const Unit &getFullUnit() const

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

Bool check(const UnitVal &uv) const

Check if of specified type

void assure(const UnitVal &uv) const

Assert correct kind

Thrown Exceptions

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

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)

void convert(const Unit &s)

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

void convert(const Quantum<Qtype> &other)

Convert a Quantum to specified units

Convert a Quantum to units from specified quantum (ibid example)

void convert()

Convert a Quantum to specified units

virtual QBase *clone() const

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)

Global input function (source)

Interface

Private Members
istream& operator>> (istream &is, Quantity &ku)

Description

Global functions Output/Input

Member Description

istream& operator>> (istream &is, Quantity &ku)

only Quantity is supported on input