Creates an object for performing conversion from one system of units to another.
have string: FITS unit specification to convert from, with or without surrounding square brackets (for inline specifications); text following the closing bracket is ignored.
want string: FITS unit specification to convert to, with or without surrounding square brackets (for inline specifications); text following the closing bracket is ignored.
ctrl string (optional): Do potentially unsafe translations of non-standard unit strings.
Although "S" is commonly used to represent seconds, its recognizes "S" formally as Siemens, however rarely that may be translation to "s" is potentially unsafe since the standard used. The same applies to "H" for hours (Henry), and "D" for days (Debye).
This string controls what to do in such cases, and is case-insensitive.
Thus '' doesn’t do any unsafe translations, whereas 'shd' does all of them.
See FITS unit specification for more information.
Use the returned object’s convert method to convert values from have to want.
This function is permissive in accepting whitespace in all contexts in a units specification where it does not create ambiguity (e.g. not between a metric prefix and a basic unit string), including in strings like "log (m ** 2)" which is formally disallowed.
Exceptions:
Perform the unit conversion on the elements of the given array, returning an array of the same shape.
The name of the unit being converted from.
This value always uses standard unit names, even if the UnitConverter was initialized with a non-standard unit name.
double
The offset of the unit conversion.
double
The exponent of the unit conversion.
double
The scaling factor for the unit conversion.
The name of the unit being converted to.
This value always uses standard unit names, even if the UnitConverter was initialized with a non-standard unit name.
The following units are supported by the FITS standard:
SI base & supplementary units
Quantity | Unit String | Meaning |
---|---|---|
length | m | metre |
mass | kg | kilogram |
time | s | second of time |
plane angle | rad | radian |
solid angle | sr | steradian |
temperature | K | kelvin |
electric current | A | ampere |
amount of substance | mol | mole |
luminous intensity | cd | candela |
IAU-recognized derived units
Quantity | Unit String | Meaning | Equivalence |
---|---|---|---|
frequency | Hz | hertz | s-1 |
energy | J | joule | N m |
power | W | watt | J s-1 |
electric potential | V | volts | J C-1 |
force | N | newton | kg m s-2 |
pressure, stress | Pa | pascal | N m-2 |
electric charge | C | coulomb | A s |
electric resistance | ohm | ohm (Ω) | V A-1 |
electric conductance | S | siemens | A V-1 |
electric capacitance | F | farad | C V-1 |
magnetic flux | Wb | weber | V s |
magnetic flux density | T | tesla | Wb m-2 |
inductance | H | henry | Wb A-1 |
luminous flux | lm | lumen | cd sr |
illuminance | lx | lux | lm m-2 |
Additional units
Quantity | Unit String | Meaning | Equivalence |
---|---|---|---|
mass | u | unified atomic mass unit | 1.6605387 x 10-27 kg |
mass | solMass | solar mass | 1.9891 x 1030 kg |
plane angle | deg | degree of arc | 1.745533 x 10-2 rad |
plane angle | arcsec | second of arc | 4.848137 x 10-6 rad |
plane angle | arcmin | minute of arc | 2.90888 x 10-4 rad |
time | min | minute | |
time | h | hour | |
time | d | day | 8.64 x 104 s |
time | yr | year (Julian) | 3.15576 x10-7 s (365.25 d) |
energy | eV | electron volt | 1.602177 x 10-19 J |
energy | erg | erg | 10-7 J |
energy | Ry | Rydberg | 13.605692 eV |
length | angstrom | angstrom | 10-10 m |
length | AU | astronomical unit | 1.49598 x 1011 m |
length | lyr | light year | 9.460530 x 10-15 m |
length | pc | parsec | 3.0857 x 10-16 m |
length | solRad | solar radius | 6.9599 x 108 m |
events | count | counts | |
events | photon | photons | |
flux density | Jy | jansky | 10-16 W m-2 Hz-1 |
flux density | mag | (stellar) magnitude | |
flux density | Crab | ‘crab’ | |
flux density | beam | beam | Jy/beam |
flux density | solLum | solar luminosity | |
magnetic field | G | gauss | 10-4 T |
area | pixel | (image/detector) pixel | |
area | voxel | 3-d analog of pixel | |
area | barn | barn | 10-28 m2 |
device | chan | (detector) channel | |
device | byte | (computer) byte | |
device | bit | (computer) bits | |
device | adu | A/D converter units | |
misc | bin | numerous applications | |
misc | Sun | wrt. sun |
Potentially unsafe translations of "D", "H", and "S", are optional, using the translate_units parameter.
When converting non-standard units to standard ones, a case-sensitive match is required for the aliases listed below, in particular the only recognized aliases with metric prefixes are "KM", "KHZ", "MHZ", and "GHZ".
Unit | Recognized aliases |
---|---|
Angstrom | angstrom |
arcmin | arcmins, ARCMIN, ARCMINS |
arcsec | arcsecs, ARCSEC, ARCSECS |
beam | BEAM |
byte | Byte |
count | ct |
d | day, days, (D), DAY, DAYS |
deg | degree, degrees, DEG, DEGREE, DEGREES |
GHz | GHZ |
h | hr, (H), HR |
Hz | hz, HZ |
kHz | KHZ |
Jy | JY |
K | kelvin, kelvins, Kelvin, Kelvins, KELVIN, KELVINS |
km | KM |
m | metre, meter, metres, meters, M, METRE, METER, METRES, METERS |
min | MIN |
MHz | MHZ |
Ohm | ohm |
Pa | pascal, pascals, Pascal, Pascals, PASCAL, PASCALS |
photon | ph |
pixel | pixels, PIXEL, PIXELS, pix |
rad | radian, radians, RAD, RADIAN, RADIANS |
s | sec, second, seconds, (S), SEC, SECOND, SECONDS |
V | volt, volts, Volt, Volts, VOLT, VOLTS |
yr | year, years, YR, YEAR, YEARS |
The aliases "angstrom", "ohm", and "Byte" for (Angstrom, Ohm, and byte) are recognized by pywcs/wcslib itself as an unofficial extension of the standard, but they are converted to the standard form here.
The following metric prefixes are supported:
Prefix | String | Magnitude |
---|---|---|
yocto | y | 10-24 |
zepto | z | 10-21 |
atto | a | 10-18 |
femto | f | 10-15 |
pico | p | 10-12 |
nano | n | 10-9 |
micro | u | 10-6 |
milli | m | 10-3 |
centi | c | 10-2 |
deci | d | 10-1 |
deka | da | 101 |
hecto | h | 102 |
kilo | k | 103 |
Mega | M | 106 |
Giga | G | 109 |
Tera | T | 1012 |
Peta | P | 1015 |
Exa | E | 1018 |
Zetta | Z | 1021 |
Yotta | Y | 1024 |
Table 6 of WCS Paper I lists eleven units for which metric prefixes are allowed. However, in this implementation only prefixes greater than unity are allowed for "a" (annum), "yr" (year), "pc" (parsec), "bit", and "byte", and only prefixes less than unity are allowed for "mag" (stellar magnitude).
Metric prefix "P" (peta) is specifically forbidden for "a" (annum) to avoid confusion with "Pa" (Pascal, not peta-annum). Note that metric prefixes are specifically disallowed for "h" (hour) and "d" (day) so that "ph" (photons) cannot be interpreted as pico-hours, nor "cd" (candela) as centi-days.
A compound unit is considered to be formed by a series of sub-strings of component units & mathematical operations. Each of these sub-strings must be separated by at least one space or a mathematical operator (* or /).
Multiplicative units can be specified either:
Units which form the denominator of a compound expression can be specified either:
It should be stressed that the slash character only effects the sub-string it immediately precedes. Thus, unless brackets are used, subsequent sub-strings which also form part of the denominator of the compound expression must also be preceded by a slash. For example, str1 /str2 str3 is equivalent to str1 str3 /str2 whilst str1 /str2 /str3 is equivalent to str1 /(str2 * str3).
A unit string raised to the power y is specified:
However, if y is positive, then the brackets need not be included, but a following space is recommended if additional sub-strings follow.
Any number of pairs of round brackets (()) may be used within the string for a compound unit in order to prevent ambiguities. As described within this section, a number of rules always/often require their use. However, it is suggested that conservative use is made of such pairs of brackets in order to minimize the total length of compound strings. (It should be remembered that a maximum of 68 characters are allowed in the card image of keywords.)
The inclusion of numerical factors within the unit string should generally be avoided (by the use of multiples and/or submultiples of component basic units).
However, occasionally it may be preferable to include such factors on the grounds of user-friendliness and/or to minimize the risk of computer under- or overflows. In such cases, the numerical factor can simply be considered a basic unit string.
The following additional guidelines are suggested:
A number of mathematical operations are supported. It should be noted that the (round) brackets are mandatory in all cases in which they are included in the table.
String | Meaning |
---|---|
str1*str2 | Multiplication |
str1 /str2 | Division |
str1**(y) | Raised to the power y |
log(str1) | Common Logarithm (to base 10) |
ln(str1) | Natural Logarithm |
exp(str1) | Exponential (expstr1) |
sqrt(str1) | Square root |
sin(str1) | Sine |
cos(str1) | Cosine |
tan(str1) | Tangent |
asin(str1) | Arc Sine |
acos(str1) | Arc Cosine |
atan(str1) | Arc Tangent |
sinh(str1) | Hyperbolic Sine |
cosh(str1) | Hyperbolic Cosine |
tanh(str1) | Hyperbolic Tangent |
Function types log(), ln() and exp() may only occur at the start of the units specification.