quanta - Module

Description

Introduction

A quantity is a value with a unit. For example, '5km/s', or '20Jy/pc2'. This module (the quanta module) enables you to create and manipulate such quantities. The types of functionality provided are:

Conversion Conversion of quantities to different units
Calculation Calculations with quantities
GUI A GUI interface is also provided

To access the quanta module, include the the quanta.g Glish script. This will create a default Quanta tool called dq.

- include 'quanta.g'
- dq.type()             # Default tool created for you
quanta

The Quanta tool has no state (it doesn't remember anything), so there is generally no need to create your own tool. Just use the default one. However, if you do require one, perhaps in a script, then use the quanta constructor to make one.

- include 'quanta.g';
- myqt := quanta();
- myqt.type();  
quanta

The Quanta tool manipulates quantities. A quantity is stored as a Glish record with two fields. These fields are named `value' and `unit'. As well as simple scalar quantites, one can also create quantities as vectors or arrays. For example, you may have a vector of values, which all have the same unit - there is no need to store a copy of the unit for each value. Access to the individual fields of a quantum should always be by using the getvalue and getunit methods, especially since the internal names can change or be not accessable at some stage.

Example

- dq.quantity(5.4, 'km/s')
[value=5.4, unit=km/s]		
-
- q1 := dq.quantity([8.57132661e+09, 1.71426532e+10], 'km/s')
-
- dq.convert(q1, 'pc/h');
[value=[1 2] , unit=pc/h]

In the first example, we make a simple scalar quantity. You can see that the quantity (which is actually a Glish record) has fields `value' and `unit'.

In the second example, we make a vector quantity and then convert it from units of km/s to pc/h.

Example

- dq.quantity('5.4km/s')          
[value=5.4, unit=km/s] 
- dq.quantity(dq.unit('5.4km/s')) 
[value=5.4, unit=km/s]

In the first example, the value and unit were combined into one string (just saves a bit of typing). The second example shows that the function unit is an alias for quantity, and that you can create a quantity from another quantity.

Example

- q1 := dq.unit("5s 5.4km/s")	
- length(q1)
2
- q1[1]
[value=5, unit=s]
- q1[2]
[value=5.4, unit=km/s]

Here we make a vector quantity by using the Glish string vector (double quote) feature. You can see that the resultant quantity (Glish record) is of length 2 and that each field of that vector quantity is a scalar quantity. So you see that q1 itself does not have fields `value' and `unit', only the elements of q1 have that.

Example

- q1 := dq.unit('5km');
- q2 := dq.unit('200m');
- dq.canonical(dq.add(q1,q2))
[value=5200, unit=m]

Here we make two quantities with consistent but different units, add them together and then convert the result to canonical units.

Example

- q1 := dq.quantity('6rad');
- q2 := dq.quantity('3deg');
- dq.compare(q1,q2)
T
- dq.compare(q1,dq.unit('3km'))
F

Here we make compare the dimensionality of the units of two quantities.

Example

- q1 := dq.unit(array("5s 5.4km/s", 3, 2))
- length(q1)
6 
- q1[1]
[value=5, unit=s] 
- q1[2]
[value=5.4, unit=km/s] 
- q1[6]
[value=5.4, unit=km/s] 
- q1::
[id=quant, shape=[3 2] ]

Here we fill a quantity with a 2-dimensional array. In this case, the array is an array of strings. and its shape is [3,2]. We see that the resultant quantity is a vector of length 6 (it does not preserve the array shape here). However, we see that the shape attribute of the quantity does preserve the original array shape though (see below for more information about attributes).

Constants, time and angle formatting

If you would like to see all the possible constants known to the Quanta tool you can issue the command dq.map('const'). You can get the value of any constant in that list with a command such as

- boltzmann := dq.constants('k')
- print 'Boltzmann constant is ', boltzmann
Boltzmann constant is  [value=1.3806578e-23, unit=J/K]

There are some extra handy ways you can manipulate strings when you are dealing with times or angles. The following list shows special strings and string formats which you can input to the quantity function. Something in square brackets is optional. There are examples after the list.

time: [+-]hh:mm:ss.t... - This is the preferred time format (trailing fields can be omitted)
time: [+-]hhHmmMss.t..[S] - This is an alternative time format (HMS case insensitive, trailing second fields can be omitted)
angle: [+-]dd.mm.ss.t.. - This is the preferred angle format (trailing fields after second priod can be omitted; dd.. is valid)
angle: [+-]ddDmmMss.t...[S] - This is an alternative angle format (DMS case insensitive, trailing fields can be omitted after M)
today - The special string ``today'' gives the UTC time at the instant the command was issued.
today/time - The special string ``today'' plus the specified time string gives the UTC time at the specified instant
yyyy/mm/dd[/time] - gives the UTC time at the specified instant
dd[-]mmm[-][cc]yy[/time] - gives the UTC time at the specified instant in calendat style notation (23-jun-1999)

Note that the standard unit for degrees is 'deg', and for days 'd'. Formatting is done in such a way that it interprets a 'd' as degrees if preceded by a value without a period and if any value following it is terminated with an 'm'. In other cases 'days' are assumed. Here are some examples.

- dq.quantity('today')
[value=50611.2108, unit=d] 
- dq.quantity('5jul1998')
[value=50999, unit=d] 
- dq.quantity('5jul1998/12:')
[value=50999.5, unit=d] 
- dq.quantity('-30.12.2')
[value=-30.2005556, unit=deg] 
- dq.quantity('2:2:10')
[value=30.5416667, unit=deg] 
- dq.unit('23h3m2.2s')  
[value=345.759167, unit=deg]

Angles and times can often be used interchangeably. Special functions (dq.totime() and dq.toangle()) are available to make them in the right units for the purpose. E.g. dq.sin(time) gives an error, whereas dq.sin(dq.toangle(time)) works ok. See units for more information on units and quantities, and the map function for pre-defined units.

- print a := dq.quantity('today');        # 1
[value=51045.9972, unit=d];
- print b := dq.toangle(a);               # 2
[value=320731.459, unit=rad]
- dq.angle(dq.norm(dq.toangle(a)));       # 3
-001.00.56.308 
- dq.angle(dq.norm(dq.toangle(a), 0));    # 4
+358.59.03.692 
- dq.sub('today',a);                      # 5
[value=0.00192880747, unit=d]

1.: Get the time now
2.: Get the time as an angle
3.: Get the time as a normalised angle (-pi to +pi) and show as dms
4.: Get the time as a normalised angle (0 to 2pi) and show as dms
5.: Get time since creation of a

Attributes

Quantities (that is, the Glish record) have attributes attached to them. All quantities have the attribute called `id' which has the string value `quant'. This can be used to identify that a record is in fact a valid quantity. When you make quantities from arrays, you will generally find an attribute called ``shape'' attached to the quantity indicating what shape the array was. Attributes are accessed via the ``::'' operator.

Example

- q1 := dq.unit(array("5s 5.4km/s", 3, 2))
- length(q1)
6
- q1::
[id=quant, shape=[3 2] ]

Functions

is_quantity Check if quantity

r_array Create an array or vector of records

r_fill Fill only a slice of a record array

r_index Get index array for a record array

r_slice Get a slice of a record array

Tools

quanta	quanta tool
quantagui	GUI code for quanta.g

Next: is_quantity - Function Up: General Previous: igrf - Function Contents Index

is_quantity	Check if quantity
r_array	Create an array or vector of records
r_fill	Fill only a slice of a record array
r_index	Get index array for a record array
r_slice	Get a slice of a record array