midgard.math.unit

Midgard library module for handling of SI-unit conversions

Description:

This module provides unit conversion constants and functions. The heavy lifting is done by the pint package. The basic usage is as follows:

>>> from midgard.math.unit import Unit
>>> seconds_in_two_weeks = 2 * Unit.week2secs
>>> seconds_in_two_weeks
1209600.0

In general Unit.spam2ham will give the multiplicative conversion scale between the units spam and ham. Through the pint package we support a lot of units. See Unit.list() or https://github.com/hgrecco/pint/blob/master/pint/default_en.txt. Another notation is also available, and might be necessary for some more complicated conversions:

>>> seconds_in_two_weeks = 2 * Unit('week', 'seconds')
>>> miles_per_hour_in_meters_per_second = Unit('mph', 'meters / sec')

Do note that we support most normal aliases as well as singular and plural forms of the units. For instance can second be represented as s, sec, secs and seconds. Prefixes are also handled:

>>> nanoseconds_in_an_hour = Unit.hour2nanosecs
>>> inches_in_a_kilometer = Unit.km2inches

For more complicated conversions (for instance from Celsius to Fahrenheit) one can create custom conversion functions using convert:

>>> c2f = Unit.function('celsius', 'fahrenheit')
>>> absolute_zero_in_fahrenheit = c2f(-273.15)

For convenience, this can also be written using the attribute notation as Unit.spam_to_ham(spam_value). Then the previous example simply becomes:

>>> absolute_zero_in_fahrenheit = Unit.celsius_to_fahrenheit(-273.15)

(or even easier Unit.kelvin_to_fahrenheit(0)).

Finally, we can access the unit/quantity system of pint by using the name of a unit by itself, e.g. Unit.spam. For instance:

>>> distance = 42 * Unit.km
>>> time = 31 * Unit('minutes')
>>> speed = distance / time
>>> speed.to(Unit.mph)
<Quantity(50.511464659292955, 'mph')>

>>> speed.to_base_units()
<Quantity(22.580645161290324, 'meter / second')>

However, using the full unit system adds some overhead so we should be careful in using it in heavy calculations.

Unit

Unit(from_unit:str, to_unit:Union[str, NoneType]=None) -> Any

Unit converter

The implementation of the unit conversion is done in the _convert_units-metaclass.

Unit.dms_to_rad()

dms_to_rad(degrees:~np_float, minutes:~np_float, seconds:~np_float) -> ~np_float

Convert degrees, minutes and seconds to radians

The sign of degrees will be used. In this case, be careful that the sign of +0 or -0 is correctly passed on. That is, degrees must be specified as a float, not an int.

Args:

Returns:

Given degrees, minutes and seconds as radians.

Examples:

>>> Unit.dms_to_rad(59, 54, 52.32)
1.04570587646256
>>> Unit.dms_to_rad(-12.0, 34, 56.789)
-0.21960503017531938
>>> Unit.dms_to_rad(-0.0, 19, 59.974870)
-0.005817642339636369

Unit.hms_to_rad()

hms_to_rad(hours:~np_float, minutes:~np_float, seconds:~np_float) -> ~np_float

Convert hours, minutes and seconds to radians

Args:

Returns:

Given hours, minutes and seconds as radians.

Examples:

>>> Unit.hms_to_rad(17, 7, 17.753427)
4.482423920139868
>>> Unit.hms_to_rad(12, 0, 0.00)
3.1415926535897936
>>> Unit.hms_to_rad(-12, 34, 56.789)
Traceback (most recent call last):
ValueError: hours must be non-negative

Unit.rad_to_dms()

rad_to_dms(radians:~np_float) -> Tuple[~np_float, ~np_float, ~np_float]

Converts radians to degrees, minutes and seconds

Args:

Returns:

Tuple with degrees, minutes, and seconds.

Examples:

>>> Unit.rad_to_dms(1.04570587646256)
(59.0, 54.0, 52.3200000000179)
>>> Unit.rad_to_dms(-0.2196050301753194)
(-12.0, 34.0, 56.78900000000468)
>>> Unit.rad_to_dms(-0.005817642339636369)
(-0.0, 19.0, 59.974869999999925)