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

Programs:

Tests:

• tQuantum

Prerequisite

• Unit

Etymology

Synopsis

    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

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'

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

• = 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

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

• assure(UnitVal kind)

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

	#include <aips/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

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)

Quantum()

Quantum(const Quantum<Qtype> &other)

Quantum(const Qtype &factor)

Quantum(const Qtype &factor, const Unit &s)

Thrown Exceptions

• AipsError if non-matching unit dimensions

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

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

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

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

Qtype getBaseValue() const

Qtype getValue(const Unit &other) const

virtual const Unit &getFullUnit() const

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

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

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

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

void convert()

Convert a Quantum to specified units

virtual QBase *clone() const

virtual void print(ostream &os) const

virtual uInt type() const
static uInt myType()

Global input function (source)

Interface