cds.astro
Class Unit

java.lang.Object
  extended by 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
clone, finalize, 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 108
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 108
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()