UnitConverter

class pywcs.UnitConverter

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.

  • If the string contains "s", translate "S" to "s".
  • If the string contains "h", translate "H" to "h".
  • If the string contains "d", translate "D" to "d".

  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:

• ValueError: Invalid numeric multiplier.
• SyntaxError: Dangling binary operator.
• SyntaxError: Invalid symbol in INITIAL context.
• SyntaxError: Function in invalid context.
• SyntaxError: Invalid symbol in EXPON context.
• SyntaxError: Unbalanced bracket.
• SyntaxError: Unbalanced parenthesis.
• SyntaxError: Consecutive binary operators.
• SyntaxError: Internal parser error.
• SyntaxError: Non-conformant unit specifications.
• SyntaxError: Non-conformant functions.
• ValueError: Potentially unsafe translation.

convert(array)

Perform the unit conversion on the elements of the given array, returning an array of the same shape.

have

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.

offset

double

The offset of the unit conversion.

power

double

The exponent of the unit conversion.

scale

double

The scaling factor for the unit conversion.

want

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.

FITS unit specification

Supported units

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.

Unit aliases

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.

Prefixes

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.

Operators

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 /).

Multiplication

Multiplicative units can be specified either:

• by simply using one or more preceding spaces, e.g. str1 str2 (The recommended method).
• by the use of a single asterisk (*) with optional whitespace, e.g. str1 * str2.

Division

Units which form the denominator of a compound expression can be specified either:

• by using a slash (/) with optional whitespace, e.g. str1 / str2. If such a syntax is used, it is recommended that no space is included between the slash and the unit string.
• by raising a multiplicative unit to a negative power (see below).

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

Raising to Powers

A unit string raised to the power y is specified:

• by using two asterisks (**) followed by the index enclosed within round brackets and with no preceding or intervening spaces, e.g. str1**(y) or str1**(-y).

However, if y is positive, then the brackets need not be included, but a following space is recommended if additional sub-strings follow.

Use of brackets

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

Avoidance of underflows & overflows

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:

• the numerical factor should precede any unit strings
• only powers of 10 are used as numerical factors

Mathematical Operations & Functions

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.