cds.astro
Class Unit

java.lang.Object
  cds.astro.Unit

public class Unit
extends java.lang.Object

Class able to deal with scientific units and make the appropriate conversions. This class is an application of the "Adopted Standards for Astronomical Catalogues" (http://vizier.u-strasbg.fr/doc/catstd.htx). It is tightly related to the class Converter which can define non-standard conversions.

Basically, a unit consists in a value associated to a unit symbol which is itself related to the SI (Système International). Most of the unit symbols in use in astronomy are included, but it is possible to add the definition of new units with their equivalence via the addSymbol(java.lang.String, java.lang.String, java.lang.String) method.

The class can also deal with units expressed in log scale like [km/s] equivalent to log(km/s), or in mag scale which is defined as -2.5log. Values may be transformed between the linear and log scales with the log, mag and dexp methods; conversions may also be performed via the convert methods.

The operations on units include the basic operations plus, minus, mult, div and power and the square root sqrt. Addition or multiplications on physical values would however better use the sum or prod methods, which take care of converting the log scales. To illustrate the differences, assuming that u1 and u2 have the same content of 5mag, the operation u1.add(u2) gives the result 10mag, while u1.sum(u2) gives a value around 4.25mag corresponding to the brightness of a source merging the two brightnesses.

For repetitive operations, like working on values from a table, it is suggested to use the setValue method which assigns the value but keeps the unit symbol and definition.

The numbers with their associated unit are edited as a single word (without embedded blanks); the SI equivalent may be edited with the toStringInSI method. The numbers in their edited form use an exponential notation mx10+n; the classical form mE+n is also correctly interpreted. Values in sexagesimal notation are also interpreted correctly in setValue provided their associated unit is "h:m:s" (time) or "d:m:s" (angle) --- note that the quotes " around the unit symbol are required!

An example of a program reading data all with the same km/s unit could be:

 Unit aUnit = new Unit("km/s") ; 
 while (true) {
     aUnit.setValue(stdin.readLine()) ;
     System.out.println("Complete Value: " + aUnit);
     System.out.println(" SI Equivalent: " + aUnit.toStringInSI());
     System.out.println("  Unit Meaning: " + aUnit.explainUnit());
 }
 

The recursive (BNF) definition of a Unit is as follows:

 Full_Unit = factor Complex_unit
 Complex_Unit = single_Unit
                | single_Unit OP single_Unit
                | "log[" single_Unit OP single_Unit "]"
                | "mag[" single_Unit OP single_Unit "]"
 single_Unit  = extended_UnitSymbol
                | extended_UnitSymbol power
 extended_UnitSymbol = UnitSymbol
                       | Magnitude_Prefix UnitSymbol
                       | "(" Full_Unit ")"
 power = Number
         | +Number
         | -Number
 OP      = . | /
 

Field Summary

java.lang.String	symbol The symbolic unit, like km/s
double	value The value, expressed in unit symbol

Constructor Summary

Unit()
Define the default unit: unitless undefined value

Unit(java.lang.String symbol)
Define a Value+Unit by interpreting a String

Unit(Unit u)
Define a Unit and Value from an existing one (clone)

Method Summary

static Unit	addSymbol(java.lang.String symbol, java.lang.String equiv) Introduce a new Symbol into the list of Symbols.
static Unit	addSymbol(java.lang.String symbol, java.lang.String equiv, java.lang.String explain) Introduce a new Symbol into the list of Symbols.
static boolean	checkSymbol(java.lang.String symbol) Check whether a symbol exists.
static void	convert(Unit source_unit, Unit target_unit) Convert a unit+value into another unit+value.
void	convertFrom(Unit source_unit) Convert the value in argument to the target Unit.
void	convertTo(Unit unit) Convert the value into another unit.
static void	convertUnit(Unit source_unit, Unit target_unit) Convert a unit+value into another unit+value.
void	dexp() Convert a value to its linear scale
java.lang.String	dimension() Physical dimension of a unit.
void	div(Unit unit) Division of 2 quantities.
void	dump(java.lang.String title) Dump the details.
java.lang.StringBuffer	edit(java.lang.StringBuffer buf) Edition of the quantity.
java.lang.StringBuffer	editDimension(java.lang.StringBuffer buf) Edit the physical dimension of a unit.
java.lang.String	editedValue() String represntation of the value.
java.lang.StringBuffer	editValue(java.lang.StringBuffer buf) Edit the value in a StringBuffer
boolean	equals(java.lang.Object o) Check whether 2 quantities are equal.
java.lang.String	explainUnit() Give a full explanation of the unit.
static java.lang.String	explainUnit(java.lang.String text) Explain the unit given in argument.
static Converter	getConverter(java.lang.String source_unit, java.lang.String target_unit) Retrieve a special converter.
long	getSIdim() Get a representation of the unit dimension.
java.lang.String	getSIunit() Get the unit expressed in terms of SI units.
double	getSIvalue() Get the value converted to SI system
java.lang.String	getUnit() Get the unit symbol (identical to unit.symbol)
double	getValue() Get the value of a unit (identical to unit.value)
boolean	isCompatibleWith(Unit unit) Checks whether 2 units are compatible.
boolean	isUnitless() Checks whether a number has no unit (is unitless)
void	log() Convert a value to a decimal log scale
void	mag() Convert a value to a mag scale
void	minus(Unit unit) Subtraction of 2 quantities.
void	mult(double s) Multiplication by a Scalar.
void	mult(Unit unit) Multiplication of 2 quantities.
int	parse(java.lang.String text, int offset) Examine a String for a Unit + Value
int	parseUnit(java.lang.String text, int offset) Look in the input string for a Unit
int	parseValue(java.lang.String text, int offset) Look in the input string for a value
boolean	parsing(Parsing t) Interpret a string for a value + Unit.
void	plus(Unit unit) Addition of 2 quantities.
void	power(int expo) Compute the Power of a number/unit
void	prod(Unit unit) Product of 2 quantities.
static void	registerConverter(java.lang.String source_unit, java.lang.String target_unit, Converter special_converter) Introduce a special converter.
void	set() Reset a unit to unitless.
void	set(java.lang.String text) Interpret a String to a Unit + Value
void	set(Unit u) Copy a quantity.
void	setUnit() Convert the current number+Unit into a Unit.
void	setUnit(java.lang.String text) Assigns the Unit.
void	setValue(double value) Assign the value.
void	setValue(java.lang.String text) Assign the value.
void	sqrt() Take Square Root of a Value/Unit
void	sum(Unit unit) Sum of 2 quantities.
static java.util.Enumeration	symbols() List all symbols.
java.lang.String	toString() Standard Edition of the Unit.
java.lang.String	toStringInSI() Explain the Unit+Value in terms of SI units (Convert to non-log)
static long	unitless() Get a representation of the unitless dimension

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

value

public double value

The value, expressed in unit symbol

symbol

public java.lang.String symbol

The symbolic unit, like km/s

Constructor Detail

Unit

public Unit()

Define the default unit: unitless undefined value

Unit

public Unit(Unit u)

Define a Unit and Value from an existing one (clone)

Parameters:

u - the Unit to clone

Unit

public Unit(java.lang.String symbol)
     throws java.text.ParseException

Define a Value+Unit by interpreting a String

Parameters:

symbol - a text to interpret, e.g. 20km/s, or 2(75km/s/Mpc)

Throws:

java.text.ParseException - when the argument contains non-interpretable text

Method Detail

symbols

public static final java.util.Enumeration symbols()

List all symbols. Basic symbols only (without the multiplicity indexes) are listed. Use checkSymbol(java.lang.String) to verify one symbol.

Returns:

an Enumeration of the symbols. The symbols can be used as argument in the explain method to get details.

addSymbol

public static Unit addSymbol(java.lang.String symbol,
                             java.lang.String equiv,
                             java.lang.String explain)
                      throws java.text.ParseException

Introduce a new Symbol into the list of Symbols. An example could be Unit.addSymbol("Rayleigh", "10+6/(4*pi).ph.cm-2.s-1.sr-1", "apparent emission rate")

Parameters:

symbol - the text of the symbol -- made of letters only, or letters preceded by a backslash, or surrounded by quotes

equiv - the definition of the symbol in terms of existing symbols

explain - the text to be used for explanation (should be terminated by a blank)

Returns:

The unit having the same symbol which was removed, or null

Throws:

java.text.ParseException - when equiv can't be interpreted.

addSymbol

public static Unit addSymbol(java.lang.String symbol,
                             java.lang.String equiv)
                      throws java.text.ParseException

Introduce a new Symbol into the list of Symbols.

Parameters:

symbol - the text of the symbol -- made of letters only, or letters preceded by a backslash, or surrounded by quotes

equiv - the definition of the symbol in terms of existing symbols

Returns:

The text of the explanation of the unit previously defined having the same symbol

Throws:

java.text.ParseException - when equiv can't be interpreted.

registerConverter

public static void registerConverter(java.lang.String source_unit,
                                     java.lang.String target_unit,
                                     Converter special_converter)

Introduce a special converter. Converters created by the Converter class are automatically registered (no need to register them). Once registered, the converter is used by convert(cds.astro.Unit, cds.astro.Unit), convertFrom(cds.astro.Unit) and convertTo(cds.astro.Unit) preferably to the standard conversion rules.

Parameters:

source_unit - symbol of source unit, e.g. mag

target_unit - symbol of target unit, e.g. Jy

special_converter - a Converter object

getConverter

public static Converter getConverter(java.lang.String source_unit,
                                     java.lang.String target_unit)

Retrieve a special converter. (previously registered by registerConverter(java.lang.String, java.lang.String, cds.astro.Converter))

Parameters:

source_unit - symbol of source unit, e.g. "d:m:s"

target_unit - symbol of target unit, e.g. "h:m:s"

Returns:

The known Converter object. Object which know how to convert source_unit into target_unit

checkSymbol

public static boolean checkSymbol(java.lang.String symbol)

Check whether a symbol exists. Use symbols() to get all symbols.

Parameters:

symbol - the text of the symbol -- made of letters only, or letters preceded by a backslash, or surrounded by quotes

Returns:

true if the symbol exists, false if the symbol was not registered.

getValue

public double getValue()

Get the value of a unit (identical to unit.value)

Returns:

the value, expressed in units getUnit()

getSIvalue

public double getSIvalue()

Get the value converted to SI system

Returns:

the value, expressed in units getSIunit()

getSIdim

public long getSIdim()

Get a representation of the unit dimension. The result is unique for a combination of basic dimensions.

Returns:

the value

unitless

public static long unitless()

Get a representation of the unitless dimension

Returns:

the representation of a unitless dimension.

getUnit

public java.lang.String getUnit()

Get the unit symbol (identical to unit.symbol)

Returns:

the symbol representing the unit

getSIunit

public java.lang.String getSIunit()

Get the unit expressed in terms of SI units.

Returns:

the symbol representing the unit

log

public final void log()
               throws java.lang.ArithmeticException

Convert a value to a decimal log scale

Throws:

java.lang.ArithmeticException - when the unit contains already logs

mag

public final void mag()
               throws java.lang.ArithmeticException

Convert a value to a mag scale

Throws:

java.lang.ArithmeticException - when the unit contains already logs

dexp

public final void dexp()
                throws java.lang.ArithmeticException

Convert a value to its linear scale

Throws:

java.lang.ArithmeticException - when the unit is not a log

power

public final void power(int expo)
                 throws java.lang.ArithmeticException

Compute the Power of a number/unit

Parameters:

expo - Power value

Throws:

java.lang.ArithmeticException - when the power is too large

sqrt

public final void sqrt()
                throws java.lang.ArithmeticException

Take Square Root of a Value/Unit

Throws:

java.lang.ArithmeticException - when the unit is not a log, or not-even

isUnitless

public final boolean isUnitless()

Checks whether a number has no unit (is unitless)

Returns:

true if unit has no associated dimension

isCompatibleWith

public final boolean isCompatibleWith(Unit unit)

Checks whether 2 units are compatible. Compatible units can be summed via the sum method, as e.g. m/s and [km/h]

Parameters:

unit - another Unit, to be verified.

equals

public final boolean equals(java.lang.Object o)

Check whether 2 quantities are equal. Two units are equal when these have the same physical dimension, and have the same numeric value (e.g. 100cm and 1m should be equal).

Overrides:

equals in class java.lang.Object

Parameters:

o - any object

Returns:

true if identical values.

convert

public static void convert(Unit source_unit,
                           Unit target_unit)
                    throws java.lang.ArithmeticException

Convert a unit+value into another unit+value. The conversion uses first the registered conversions (via registerConverter(java.lang.String, java.lang.String, cds.astro.Converter))

Parameters:

source_unit - the value+unit to convert. This value is unchanged.

target_unit - the resulting value+unit. On return, its value part is modified.

Throws:

java.lang.ArithmeticException - when source_unit is not compatible with target_unit

convertUnit

public static void convertUnit(Unit source_unit,
                               Unit target_unit)
                        throws java.lang.ArithmeticException

Convert a unit+value into another unit+value. The conversions registered via registerConverter(java.lang.String, java.lang.String, cds.astro.Converter) are not used.

Parameters:

source_unit - the value+unit to convert. This value is unchanged.

target_unit - the resulting value+unit. On return, the value part is modified.

Throws:

java.lang.ArithmeticException - when source_unit is not compatible with target_unit

convertFrom

public void convertFrom(Unit source_unit)
                 throws java.lang.ArithmeticException

Convert the value in argument to the target Unit.

Parameters:

source_unit - the value+unit to convert. This value is unchanged.

Throws:

java.lang.ArithmeticException - when source_unit is not compatible with the unit of this.

convertTo

public void convertTo(Unit unit)
               throws java.lang.ArithmeticException

Convert the value into another unit.

Parameters:

unit - the target unit (unchanged) On return, this contains the value in another unit.

Throws:

java.lang.ArithmeticException - when the units are not compatible

plus

public final void plus(Unit unit)
                throws java.lang.ArithmeticException

Addition of 2 quantities. Compute the Addition of 2 numbers with their associated units.

Parameters:

unit - 2nd Unit, to add.

Throws:

java.lang.ArithmeticException - when the units are not compatible

minus

public final void minus(Unit unit)
                 throws java.lang.ArithmeticException

Subtraction of 2 quantities. Compute the Subtraction of 2 numbers with their associated units.

Parameters:

unit - 2nd Unit to be subtracted

Throws:

java.lang.ArithmeticException - when the units are not compatible

sum

public final void sum(Unit unit)
               throws java.lang.ArithmeticException

Sum of 2 quantities. Compute the Sum of 2 numbers with their associated units; The difference with "plus" exists only for log scales or magnitudes: the resulting value corresponds to a physical sum (e.g. of fluxes), whereas the "plus" corresponds to an arithmetic sum.

Parameters:

unit - 2nd Unit

Throws:

java.lang.ArithmeticException - when the units are not compatible

mult

public final void mult(double s)
                throws java.lang.ArithmeticException

Multiplication by a Scalar.

Parameters:

s - Scalar value for the multiplication

Throws:

java.lang.ArithmeticException - when the units can't be combined

mult

public final void mult(Unit unit)
                throws java.lang.ArithmeticException

Multiplication of 2 quantities. Compute the arithmetic Multiplication of 2 numbers with their associated units. The difference with prod exists only for log scales or magnitudes.

Parameters:

unit - 2nd Unit

Throws:

java.lang.ArithmeticException - when the units can't be combined

div

public final void div(Unit unit)
               throws java.lang.ArithmeticException

Division of 2 quantities. Compute the Division of 2 numbers with their associated units.

Parameters:

unit - 2nd Unit

Throws:

java.lang.ArithmeticException - when the units can't be combined

prod

public final void prod(Unit unit)
                throws java.lang.ArithmeticException

Product of 2 quantities. Compute the Product of 2 numbers with their associated units. The difference with "mult" exists only for log scales or magnitudes: the resulting value corresponds to a physical product whereas the "mult" corresponds to an arithmetic multiplication.

Parameters:

unit - 2nd Unit

Throws:

java.lang.ArithmeticException - when the units are not compatible

set

public final void set()

Reset a unit to unitless.

set

public final void set(Unit u)

Copy a quantity. Define a Unit and Value from an existing one (clone)

Parameters:

u - the Unit to clone

parsing

public boolean parsing(Parsing t)

Interpret a string for a value + Unit.

Parameters:

t - text to interpret. For instance
100km/s is interpreted as Unit=km/s; Value=100
To add a numeric factor in Unit, use parentheses, e.g.
123(100km/s) is: Unit: 100km/s; Value=123. The unit symbol may precede the value -- this way is required for sexagesimal and dates.

Returns:

true if something found, false if nothing found.

set

public void set(java.lang.String text)
         throws java.text.ParseException

Interpret a String to a Unit + Value

Parameters:

text - text to interpret. For instance
100km/s is interpreted as Unit=km/s; Value=100
To add a numeric factor in Unit, use parentheses, e.g.
123(100km/s) is: Unit: 100km/s; Value=123. The unit symbol may precede the value -- this way is required for sexagesimal and dates.

Throws:

java.text.ParseException - when the argument contains non-interpretable text

parse

public int parse(java.lang.String text,
                 int offset)

Examine a String for a Unit + Value

Parameters:

text - text to interpret; for instance
100km/s is interpreted as Unit=km/s; Value=100
To add a numeric factor in Unit, use parentheses, e.g.
123(100km/s) is: Unit: 100km/s; Value=123

offset - where to start in the text string.

Returns:

the new position in text following what's interpretated text

parseUnit

public int parseUnit(java.lang.String text,
                     int offset)

Look in the input string for a Unit

Parameters:

text - to be interpreted as a Unit. The value part is always set to NaN.

offset - where to start in the text string.

Returns:

the new position in text following what's interpretated

parseValue

public int parseValue(java.lang.String text,
                      int offset)

Look in the input string for a value

Parameters:

text - value (set to NaN when not correct), which can use the exponential notation like 10+8 to express 10⁸

offset - where to start in the text string.

Returns:

the new position in text following what's interpretated

setUnit

public void setUnit()

Convert the current number+Unit into a Unit. For instance, if value is 100 and unit is km/s, the value becomes 1 and the unit becomes (100km/s). Similar to setUnit(toString())

setUnit

public void setUnit(java.lang.String text)
             throws java.text.ParseException

Assigns the Unit. The value of the quantity is unchanged.

Parameters:

text - to be interpreted as a Unit. The value part is always set to NaN.

Throws:

java.text.ParseException - when the argument text which does not represent a number

setValue

public void setValue(java.lang.String text)
              throws java.text.ParseException

Assign the value. The unit of the quantity is unchanged.

Parameters:

text - value (set to NaN when not correct), which can use the exponential notation like 10+8 to express 10⁸

Throws:

java.text.ParseException - when the argument text which does not represent a number

setValue

public void setValue(double value)

Assign the value. The unit of the quantity is unchanged.

Parameters:

value - value to set

dump

public void dump(java.lang.String title)

Dump the details. Essentially for debugging purposes.

Parameters:

title - title of dump

editDimension

public final java.lang.StringBuffer editDimension(java.lang.StringBuffer buf)

Edit the physical dimension of a unit.

Parameters:

buf - Buffer where the result is appended. A question mark (?) indicates problems.

Returns:

the StringBuffer

dimension

public final java.lang.String dimension()

Physical dimension of a unit.

Returns:

the dimension with MLTAK and exponent. The symbols mean Mass, Length, Time, Ampere and Kelvin respectively.

editValue

public final java.lang.StringBuffer editValue(java.lang.StringBuffer buf)

Edit the value in a StringBuffer

Parameters:

buf - Buffer where the result is appended

Returns:

the StringBuffer

edit

public final java.lang.StringBuffer edit(java.lang.StringBuffer buf)

Edition of the quantity. This edition expresses the value and its associated unit; the unit is attached to the value as e.g. 10km/s, but precedes the value for complex values or dates as e.g. MJD51234 or "h:m:s"23:59:58

Parameters:

buf - Buffer where the result is appended

Returns:

the edited value and unit

explainUnit

public static final java.lang.String explainUnit(java.lang.String text)

Explain the unit given in argument. Interpret a String representing a Unit, and return a complete explanation.

Parameters:

text - the text containing the units to explain

Returns:

the full explanation of the Unit -- or a text ?***bad Unit when text is not interpretable

explainUnit

public final java.lang.String explainUnit()

Give a full explanation of the unit.

Returns:

the explanation in terms of SI units

toStringInSI

public final java.lang.String toStringInSI()

Explain the Unit+Value in terms of SI units (Convert to non-log)

Returns:

the explanation with basic SI units

toString

public java.lang.String toString()

Standard Edition of the Unit. Both value and associated unit are given; the conventions are detailed in edit(java.lang.StringBuffer)

Overrides:

toString in class java.lang.Object

Returns:

the edited value and unit. To edit the value only, see editedValue()

editedValue

public java.lang.String editedValue()

String represntation of the value. The unit is not edited.

Returns:

the edited value To edit the value and the number, see toString()