casa::Quantum< Qtype > Class Template Reference
[Quanta]

#include <Quantum.h>

Inheritance diagram for casa::Quantum< Qtype >:

[legend]Collaboration diagram for casa::Quantum< Qtype >:

[legend]List of all members.

---

Detailed Description

template<class Qtype>
class casa::Quantum< Qtype >

Quantities (i.e.

dimensioned values)

Intended use:

Part of API

Review Status

Reviewed By:

UNKNOWN

Date Reviewed:

before2004/08/25

Test programs:

tQuantum

Prerequisite

• Unit

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

• 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 note: 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

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:

• isConform(Unit unit)
• isConform(Quantum<Type> quant)
• check(UnitVal kind)

or by an assertion, which will throw an exception:

• 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. Tip: 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

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)

• prefix +,-
• + - * / and += -= *= /=
• < <= == != >= >
• sin
• cos
• tan
• asin
• acos
• atan
• atan2
• abs
• ceil
• floor
• Caution: It is assumed that all these 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)).

To Do

• Some inlining (did not work first go)

Definition at line 273 of file Quantum.h.

void	scale (const Qtype &factor)
	Scale ( i.e.
void	setValue (const Qtype &val)
	Set the value without changing units.
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 convert scalars to the appropiate Quantum.
static Bool	read (Quantity &res, MUString &in)
virtual uInt	type () const
	Get the type (== Register()) of derived Quantum (faster than Strings).
static uInt	myType ()
Public Member Functions
	Quantum ()
	Default constructor, generates '0'.
	Quantum (const Quantum< Qtype > &other)
	Copy constructor (deep copy).
	Quantum (const Qtype &factor)
	Construct undimensioned quantum (i.e.
	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).
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.
Bool	check (const UnitVal &uv) const
	Check if of specified type.
void	assure (const UnitVal &uv) const
	Assert correct kind.
virtual QBase *	clone () const
	Get a copy of Quantum.
virtual void	print (ostream &os) const
	Print a Quantum.
	Quantum (const Qtype &factor, const Unit &s)
	Construct dimensioned quantum (e.g.
const Quantum< Qtype > &	operator+ () const
	Unary operations.
Quantum< Qtype >	operator- () const
Quantum< Qtype > &	operator+= (const Quantum< Qtype > &other)
	In place arithmetic functions: left hand side changed in place.
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
	Arithmetic operators: return Quantum<T>.
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
	Get value of quantum in current units (i.e.
Qtype &	getValue ()
Quantum< Qtype >	get () const
	Convert to canonical units.
Quantum< Qtype >	get (const Unit &s) const
	Convert to specified units; any remainder will be expressed in canonical units.
Quantum< Qtype >	get (const Quantum< Qtype > &other) const
	Convert a Quantum to units from specified quantum (ibid example).
void	convert ()
	Convert to canonical units.
void	convert (const Unit &s)
	Convert to specified units; any remainder will be expressed in canonical units.
void	convert (const Quantum< Qtype > &other)
	Convert a Quantum to units from specified quantum (ibid example).
Private Attributes
Qtype	qVal
	Actual quantum value.
Friends
istream &	operator>> (istream &is, Quantity &ku)
	Input, only quantity is supported now.

---

Constructor & Destructor Documentation

template<class Qtype>

casa::Quantum< Qtype >::Quantum

(

)

Default constructor, generates '0'.

template<class Qtype>

casa::Quantum< Qtype >::Quantum

(

const Quantum< Qtype > &

other

)

Copy constructor (deep copy).

template<class Qtype>

casa::Quantum< Qtype >::Quantum

(

const Qtype &

factor

)

Construct undimensioned quantum (i.e.

unit="")

template<class Qtype>

casa::Quantum< Qtype >::Quantum	(	const Qtype &	factor,
		const Unit &	s
	)

Construct dimensioned quantum (e.g.

'1.23 km/Mpc')

Thrown Exceptions

• AipsError if non-matching unit dimensions

template<class Qtype>

casa::Quantum< Qtype >::Quantum	(	const Qtype &	factor,
		const QBase &	other
	)

Construct quantum with unit copied from existing quantum.

template<class Qtype>

casa::Quantum< Qtype >::~Quantum

(

)

Destructor.

---

Member Function Documentation

template<class Qtype>

Quantum<Qtype>& casa::Quantum< Qtype >::operator=

(

const Quantum< Qtype > &

other

)

Assignment (deep copy).

template<class Qtype>

const Quantum<Qtype>& casa::Quantum< Qtype >::operator+

(

)

const

Unary operations.

template<class Qtype>

Quantum<Qtype> casa::Quantum< Qtype >::operator-

(

)

const

template<class Qtype>

Quantum<Qtype>& casa::Quantum< Qtype >::operator+=

(

const Quantum< 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)

template<class Qtype>

Quantum<Qtype>& casa::Quantum< Qtype >::operator+=

(

const Qtype &

other

)

template<class Qtype>

Quantum<Qtype>& casa::Quantum< Qtype >::operator-=

(

const Quantum< Qtype > &

other

)

template<class Qtype>

Quantum<Qtype>& casa::Quantum< Qtype >::operator-=

(

const Qtype &

other

)

template<class Qtype>

Quantum<Qtype>& casa::Quantum< Qtype >::operator *=

(

const Quantum< Qtype > &

other

)

template<class Qtype>

Quantum<Qtype>& casa::Quantum< Qtype >::operator *=

(

const Qtype &

other

)

template<class Qtype>

Quantum<Qtype>& casa::Quantum< Qtype >::operator/=

(

const Quantum< Qtype > &

other

)

template<class Qtype>

Quantum<Qtype>& casa::Quantum< Qtype >::operator/=

(

const Qtype &

other

)

template<class Qtype>

Quantum<Qtype> casa::Quantum< Qtype >::operator+

(

const Quantum< Qtype > &

other

)

const

Arithmetic operators: return Quantum<T>.

Thrown Exceptions

• AipsError if non-conforming units (+ and -)

See QMath class for unequal argument types

template<class Qtype>

Quantum<Qtype> casa::Quantum< Qtype >::operator-

(

const Quantum< Qtype > &

other

)

const

template<class Qtype>

Quantum<Qtype> casa::Quantum< Qtype >::operator *

(

const Quantum< Qtype > &

other

)

const

template<class Qtype>

Quantum<Qtype> casa::Quantum< Qtype >::operator/

(

const Quantum< Qtype > &

other

)

const

template<class Qtype>

const Qtype& casa::Quantum< Qtype >::getValue

(

)

const

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

in units specified in quantum)

Referenced by casa::SimObservations::addField(), casa::SimSpWin::chanFreq(), casa::SimSpWin::chanWidth(), casa::SimScan::gapTimeSec(), casa::SimScan::intTimeSec(), casa::SimSource::setDistance(), casa::SimSource::setInterval(), casa::SimScan::slewTimeSec(), casa::SimSource::timeSec(), and casa::SimSpWin::totalBandwidth().

template<class Qtype>

Qtype& casa::Quantum< Qtype >::getValue

(

)

template<class Qtype>

Qtype casa::Quantum< Qtype >::getBaseValue

(

)

const

Get value in canonical base units.

template<class Qtype>

Qtype casa::Quantum< Qtype >::getValue

(

const Unit &

other

)

const

Get value in specified units.

template<class Qtype>

virtual const Unit& casa::Quantum< Qtype >::getFullUnit

(

)

const [virtual]

Get the unit (as Unit) that is attached to the Quantum.

(use getUnit() if interested in the String part only, e.g. for output)

Implements casa::QBase.

template<class Qtype>

void casa::Quantum< Qtype >::scale

(

const Qtype &

factor

)

Scale ( i.e.

multiply) the value of the Quantum without changing units

template<class Qtype>

void casa::Quantum< Qtype >::setValue

(

const Qtype &

val

)

Set the value without changing units.

template<class Qtype>

static Bool casa::Quantum< Qtype >::read	(	Quantity &	res,
		const String &	in
	)			[static]

Set the value and unit deduced from input string Caution: At the moment the implementation can only convert scalars to the appropiate Quantum.

If format for Array input defined, it could easily be changed. In addition recognition of date/time/angle still has to be added

template<class Qtype>

static Bool casa::Quantum< Qtype >::read	(	Quantity &	res,
		MUString &	in
	)			[static]

template<class Qtype>

Bool casa::Quantum< Qtype >::check

(

const UnitVal &

uv

)

const

Check if of specified type.

template<class Qtype>

void casa::Quantum< Qtype >::assure

(

const UnitVal &

uv

)

const

Assert correct kind.

Thrown Exceptions

• AipsError if non-conforming unit dimensions

template<class Qtype>

Quantum<Qtype> casa::Quantum< Qtype >::get

(

)

const

Convert to canonical units.

template<class Qtype>

Quantum<Qtype> casa::Quantum< Qtype >::get

(

const Unit &

s

)

const

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

template<class Qtype>

Quantum<Qtype> casa::Quantum< Qtype >::get

(

const Quantum< Qtype > &

other

)

const

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

template<class Qtype>

void casa::Quantum< Qtype >::convert

(

)

Convert to canonical units.

template<class Qtype>

void casa::Quantum< Qtype >::convert

(

const Unit &

s

)

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

template<class Qtype>

void casa::Quantum< Qtype >::convert

(

const Quantum< Qtype > &

other

)

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

template<class Qtype>

virtual QBase* casa::Quantum< Qtype >::clone

(

)

const [virtual]

Get a copy of Quantum.

Implements casa::QBase.

template<class Qtype>

virtual void casa::Quantum< Qtype >::print

(

ostream &

os

)

const [virtual]

Print a Quantum.

Implements casa::QBase.

template<class Qtype>

virtual uInt casa::Quantum< Qtype >::type

(

)

const [virtual]

Get the type (== Register()) of derived Quantum (faster than Strings).

Implements casa::QBase.

template<class Qtype>

static uInt casa::Quantum< Qtype >::myType

(

)

[static]

---

Friends And Related Function Documentation

template<class Qtype>

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

Input, only quantity is supported now.

---

Member Data Documentation

template<class Qtype>

Qtype casa::Quantum< Qtype >::qVal [private]

Actual quantum value.

Definition at line 417 of file Quantum.h.

---

The documentation for this class was generated from the following file:

• casa/implement/Quanta/Quantum.h

---