Core API

Creating dimensions and units

pyunitx._api.make_dimension(name: str) → DimensionBase

Dimensions are the basic measurable quantities about the world, like length and time.

For complex dimensions, see make_compound_dimension().

Parameters:

name – The name of this dimension.

Returns:

An object that captures information about the dimension and the units that implement it.

pyunitx._api.make_unit(*, name: str, dimension: DimensionBase, scale: Decimal | float | str, abbrev: str, doc='') → Type[UnitBase]

A unit is a particular convention for measuring a dimension.

The resulting class represents the abstract concept of the unit, say meters. Instances of the class associate that unit with a number, defining in this example a particular length like 8 meters. Instances of a unit class are called “measurements” within this documentation. Instances are immutable; any interactions with the public API will not change the object, anything that appears like it (for instance rounding with sig_figs) instead constructs and returns a copy.

Parameters:

  • name – The name of the new unit, like “meters”. Should be in its plural form.

  • dimension – The dimension this unit measures.

  • scale – How many of the base unit it would take to get one of the current unit. For instance, one kilometer has a scale of 1000 when the base unit is meters.

  • abbrev – The canonical abbreviation for this unit, like “lb” for pounds or “g” for grams. Officially called the unit’s symbol. Used for output.

  • doc – Documentation for this unit, optional.

Returns:

A class representing the unit. Instances of this class are measurements using the unit.

pyunitx._api.make_compound_dimension(exponents: Tuple[Tuple[Type[UnitBase] | DimensionBase, int | float | Decimal], ...] | Dict[Type[UnitBase] | DimensionBase, int | float | Decimal] | Multiset, name: str | None = None) → DimensionBase

Create a dimension that’s composed of basic dimensions.

Parameters:

  • exponents – A sequence of tuples or dict that pair existing dimensions with the exponent they should be raised to.

  • name – A name to give this dimension, like velocity for length/time. If there isn’t a physically useful name for it, leave it unfilled and a name will automatically be created by using the names of its constituents.

Returns:

An object that captures information about the dimension and the units that implement it.

pyunitx._api.make_compound_unit(*, scale: Decimal | float | str, exponents: Tuple[Tuple[Type[UnitBase] | DimensionBase, int | float | Decimal], ...] | Dict[Type[UnitBase] | DimensionBase, int | float | Decimal] | Multiset, name: str | None = None, abbrev=None, doc='') → Type[UnitBase]

Create or retrieve a unit composed of other units.

If an identical unit has already been created (defined by same exponents and scale) then return that pre-constructed unit. This makes sure that calculations that result in a named unit (such as ohms) will be correctly reported as such rather than breaking down into their base components.

Parameters:

  • scale – How many of the base unit one of this unit is equivalent to. Note that the scale factors of the constituent units are not taken into account. For instance, even though the conversion factor from meters per second to miles per hour could be determined strictly from the scale factors already defined for miles -> meters and hours -> seconds, doing that calculation is up to the constructor of the unit. I think this obeys the principle of least surprise, but I might be wrong. When new units are constructed by multiplication and division, the results do have the scale automatically computed as there is no other way that makes sense.

  • exponents – A sequence of tuples or dict that pair existing units with the exponent they should be raised to.

  • name – A name to give this unit, like joules. If no particular physical name exists, leave it unfilled and a name will be automatically constructed using the names of its component units and their exponents.

  • abbrev – A canonical abbreviation for this unit, like J for joules. Officially called the unit’s symbol. If no particular one exists, leave it unfilled and it will be automatically be constructed using the symbols of its base units.

  • doc – Documentation for this unit, to show in tools like Sphinx.

Returns:

A class representing this unit. Instances of the class are measurements with a magnitude.

pyunitx._api.si_unit(*, base_unit: Type[UnitBase], skip=()) → Dict[str, Type[UnitBase]]

Create the full range of SI prefixes on a unit.

Parameters:

  • base_unit – The unit to which prefixes can be applied.

  • skip – If you’ve already created one of the units (I did this with kilograms since prefixes apply to grams), list the prefix here so it doesn’t get overwritten.

Returns:

A dictionary between the name of the unit and the unit class.

See the definition of meters for an example of what an actual unit class looks like.