pyxx.units.Unit#

class pyxx.units.Unit(unit_system: UnitSystem, base_unit_exps: List[float] | Tuple[float, ...] | ndarray, to_base_function: Callable[[ndarray, float], ndarray], from_base_function: Callable[[ndarray, float], ndarray], identifier: str | None = None, name: str | None = None)#

Bases: object

Base class for representing a unit

This class can be used to represent an arbitrary unit that is part of a given system of units. The attributes of this class specify how the unit relates to the base units of the system of units.

Examples

For examples, refer to the Units 1: Basics page.

Methods

__init__(unit_system, base_unit_exps, ...[, ...])

Creates an instance of the Unit class

convert(value, convert_type, unit)

Converts a quantity from one unit to another

from_base(value[, exponent])

Converts a value or array from base units of the unit system to the given unit

is_convertible(unit)

Checks whether a unit can be converted to another unit

to_base(value[, exponent])

Converts a value or array from the given unit to the base units of the unit system

Attributes

CONSTANT_MATH_CONVENTION

Defines the mathematical conventions for multiplying or dividing a Unit object by a constant

base_unit_exps

A list of exponents relating the given object's units to the base units of unit_system

from_base_function

A function that transforms a value in the base units of the system of units unit_system to the given object's units

identifier

A user-defined string that represents the unit (examples: kg, m, rad)

name

A user-defined string that describes the unit (examples: kilogram, meter, radian)

to_base_function

A function that transforms a value from the given object's units to the base units of unit_system

unit_system

The system of units to which the unit belongs
CONSTANT_MATH_CONVENTION = 1#

Defines the mathematical conventions for multiplying or dividing a Unit object by a constant

Configures whether Unit objects can be generated by multiplying or dividing another Unit object by a constant, and if so what mathematical conventions are adopted. For more detail, refer to the ConstantUnitMathConventions documentation.

The default is ConstantUnitMathConventions.DISABLE, which prohibits multiplying or dividing Unit objects by constants.

Warning

This is a class attribute, so changing its value for one class (such as UnitLinear) will change it for ALL classes that are an instance of or inherit from Unit.

Notes

To select a math convention for multiplying Unit objects by constants, include code similar to:

>>> from pyxx.units import Unit, ConstantUnitMathConventions
>>> Unit.CONSTANT_MATH_CONVENTION = ConstantUnitMathConventions.DISABLE

In general, it is best to set this option at the beginning of your code, as it can get confusing if you set it later in your code and as a result different parts of your code follow different conventions.

__init__(unit_system: UnitSystem, base_unit_exps: List[float] | Tuple[float, ...] | ndarray, to_base_function: Callable[[ndarray, float], ndarray], from_base_function: Callable[[ndarray, float], ndarray], identifier: str | None = None, name: str | None = None)#

Creates an instance of the Unit class

Defines an object representing a base or derived unit that is part of a given system of units.

Parameters:

  • unit_system (UnitSystem) – The system of units to which the unit belongs

  • base_unit_exps (list or tuple or np.ndarray) – A 1D list of exponents relating the given object’s unit to the base units of unit system

  • to_base_function (Callable) – A function that transforms a value in the given object’s unit to the base units of unit_system

  • from_base_function (Callable) – A function that transforms a value in the base units of unit_system to the given object’s unit

  • identifier (str, optional) – A short identifier describing the unit (example: 'kg') (default is None)

  • name (str, optional) – A name describing the unit (example: 'kilogram') (default is None)

property base_unit_exps: ndarray#

A list of exponents relating the given object’s units to the base units of unit_system

property identifier: str | None#

A user-defined string that represents the unit (examples: kg, m, rad)

property from_base_function#

A function that transforms a value in the base units of the system of units unit_system to the given object’s units

property name: str | None#

A user-defined string that describes the unit (examples: kilogram, meter, radian)

property to_base_function#

A function that transforms a value from the given object’s units to the base units of unit_system

property unit_system: UnitSystem#

The system of units to which the unit belongs

convert(value: ndarray | list | tuple | float, convert_type: str, unit: Unit) → ndarray#

Converts a quantity from one unit to another

This method performs a unit conversion, converting one or more values from this object’s units to another unit. This conversion can be performed in “either direction” – either from this object’s units to another unit, or from another unit to this object’s units.

Parameters:

  • value (np.ndarray or list or tuple or float) – Quantities to convert to a different unit

  • convert_type (str) – Must be either 'to' or 'from'. Describes whether to convert value from this object’s units to the units specified by unit, or vice versa

  • unit (Unit) – The unit to convert value to or from

Returns:

NumPy array of the same shape as value containing the quantities after performing the specified unit conversion

Return type:

np.ndarray

is_convertible(unit: Unit) → bool#

Checks whether a unit can be converted to another unit

Checks two units can be converted between each other (i.e., whether they belong to the same system of units and have the same base_unit_exps relating them to the base units).

Parameters:

unit (Unit) – Another Unit instance

Returns:

Returns True if this unit instance and unit belong to the same system of units and have the same base_unit_exps attribute, and False otherwise

Return type:

bool

from_base(value: ndarray | list | tuple | float, exponent: float = 1.0) → ndarray#

Converts a value or array from base units of the unit system to the given unit

Parameters:

  • value (np.ndarray or list or tuple or float) – Value(s) to convert to base units

  • exponent (float, optional) – Exponent to which the unit is raised (default is 1.0)

Returns:

NumPy array with the same shape as value containing the value(s) in value expressed in base units

Return type:

np.ndarray

Notes

Use the exponent argument to handle units which are raised to a power. For instance, to convert square kilometers to base units (square meters), set exponent to 2.

to_base(value: ndarray | list | tuple | float, exponent: float = 1.0) → ndarray#

Converts a value or array from the given unit to the base units of the unit system

Parameters:

  • value (np.ndarray or list or tuple or float) – Value(s) to convert from base units to the given unit

  • exponent (float, optional) – Exponent to which the unit is raised (default is 1.0)

Returns:

NumPy array with the same shape as value containing the value(s) in value converted from base units to the given unit

Return type:

np.ndarray

Notes

Use the exponent argument to handle units which are raised to a power. For instance, to convert to cubic kilometers from cubic meters (the base unit), set exponent to 3.