2. Units#

class Units(dimensions: Dimensions = None, scales: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | list = None)#

Bases: object

Defines Scarabaeus’ implementation of measurements as defined by the International System of Units [1]. From this system, the following four base units are adopted:

Gram, as a measurement of mass
Meter, as a measurement of length
Second, as a measurement of time
Radian, as a measurement of angle

These units form the base of all measurement operations in Scarabaeus.

Parameters:

dimensions (Dimensions) – The physical dimensions of the unit.
scales (numpy.ndarray | list) – A 1x4 vector describing the scale relationships for each dimension. For example, a kilogram would contain the scales [1e3, 0, 0, 0].

See also

scarabaeus.Dimensions: the building blocks of Units.
scarabaeus.ArrayWUnits: interface between numbers and units in Scarabaeus.

Notes

Lunar distance defined by JPL [2]. Astronomical unit defined by the IAU [3].

References

[1]

https://www.nist.gov/pml/owm/metric-si/si-units

[2]

https://cneos.jpl.nasa.gov/glossary/LD.html

[3]

XXVIII General Assembly of IAU, Beijing, 31 Aug 2012

Attributes

`dimensions`	Dimensions object containing information about the dimensionality of the unit.
`name`	The name of the unit.
`scales`	1x4 array defining the unit's scaled relation to each base dimension.
`unitless`	Boolean flag indicating if the Unit object is unitless or not.

Methods

`disp_named_units`()	Displays all named units, their scalings with respect to each dimensional power, dimension, and whether or not they may be mutated with metric prefixes.
`get_units`(unit_str)	Returns a Unit object or objects described by the given string formatted as a metric prefix (if necessary) and metric base unit.

classmethod disp_named_units() → None#

Displays all named units, their scalings with respect to each dimensional power, dimension, and whether or not they may be mutated with metric prefixes.

Includes base units.

classmethod get_units(unit_str: str | list[str]) → Self | tuple[Self]#

Returns a Unit object or objects described by the given string formatted as a metric prefix (if necessary) and metric base unit.

If a list[str] is given, a Unit object for each element in the list will be returned as a tuple of length n where n equals the length of the given list.

Additionally, there are a few single str inputs that return different sets of Unit objects. For example, 'base' returns a tuple containing each of the four base units. See the Notes section for more information on unique single str inputs.

See the following tables for metric base units and prefixes respectively.

Base Units +——–+———–+———–+ | Name | Dimension | Symbol | +========+===========+===========+ | Gram | Mass | 'g' | +——–+———–+———–+ | Meter | Length | 'm' | +——–+———–+———–+ | Second | Time | 'sec' | +——–+———–+———–+ | Radian | Angle | 'rad' | +——–+———–+———–+

Metric Prefixes +——-+———-+——-+–+——-+————-+——–+ | Name | Prefix | Power | | Name | Prefix | Power | +=======+==========+=======+==+=======+=============+========+ | Tera | 'T' | 10e12 | | Deci | 'd' | 10e-1 | +——-+———-+——-+–+——-+————-+——–+ | Giga | 'G' | 10e9 | | Centi | 'c' | 10e-2 | +——-+———-+——-+–+——-+————-+——–+ | Mega | 'M' | 10e6 | | Milli | 'm' | 10e-3 | +——-+———-+——-+–+——-+————-+——–+ | Kilo | 'k' | 10e3 | | Micro | 'micro' | 10e-6 | +——-+———-+——-+–+——-+————-+——–+ | Hecto | 'h' | 10e2 | | Nano | 'n' | 10e-9 | +——-+———-+——-+–+——-+————-+——–+ | Deka | 'da' | 10e1 | | Pico | 'pico' | 10e-12 | +——-+———-+——-+–+——-+————-+——–+

Parameters:: unit_str (str) – The name of the requested unit.
Returns:: req_units – A single Units or n-length tuple of Units objects where n equals the number of requested units. If only one unit is requested, a single Units object is returned.
Return type:: Units

See also

units-in-scb: For an in-depth explanation of how Units are used throughout Scarabaeus.

Notes

In addition to direct requests, get_units() also includes a few “set strings” that return mutiple relevant units with a single call. The sets and their commands are below:

Single `str` Input	Return Tuple Length	Return Tuple Contents
`'base'`	`4`	(gram, meter, second, radian)
`'common'`	`7`	(kilogram, kilometer, second, radian degree, Newton, \({\mu}\))

Examples

Create a single unit using get_units():

# initial setup
import scarabaeus as scb

# request a single unit
kg = scb.Units.get_units('kg')

Create multiple singular units using get_units():

# request multiple units in one line
km, sec, mN, rad = scb.Units.get_units(['km', 'sec', 'mN', 'rad'])

Create multiple units with a using get_units() set command:

# request multiple units from a set using a set command string
g, m, sec, rad = scb.Units.get_units('base')

property dimensions: Dimensions#: Dimensions object containing information about the dimensionality of the unit.

property name: str#: The name of the unit.

property scales: ndarray#: 1x4 array defining the unit’s scaled relation to each base dimension.

property unitless: bool#

Boolean flag indicating if the Unit object is unitless or not.

True if the Unit object is unitless., otherwise False.

2. Units#

This Page