Framework for physical units.

The unit class provides a basic framework for specifying values with physical units using readable notation such as 2.5km/h. The system ensures that values are consistent with a measurement system derived from base units, but it does impose or even preload one such system. Instead, a derived class, created using either create(), should specify the units and scales relevant for the situation to which it is applied.

Once units are defined, the formal syntax for instantiating a quantity is:

<quantity> ::= <number> <units> | <number> <operator> <units>
<number>   ::= "" | <integer> | <integer> "." <integer>
            ; Numerical value, allowing for decimal fractions but not
            ; scientific notation. An empty number is equivalent to 1.
<units>    ::= <unit> | <unit> <operator> <units>
<unit>     ::= <prefix> <name> <power>
<prefix>   ::= "" | "h" | "k" | "M" | "G" | "T" | "P" | "E" | "Z" | "Y"
            | "d" | "c" | "m" | "μ" | "n" | "p" | "f" | "a" | "z" | "y"
            ; Single character prefix to indicate a multiple or fraction
            ; of the unit. All SI prefixes are supported except for deca.
            ; An empty prefix signifies no scaling.
<name>     ::= <string>
            ; One of the defined units, case sensitive, containing Latin
            ; or Greek symbols.
<power>    ::= "" | <integer>
            ; Integer power to which to raise the unit. An empty power is
            ; equivalent to 1.
<operator> ::= "*" | "/"
            ; Multiplication or division.

With the prefix and unit name sharing an alphabet there is potential for ambiguities (is it mol or micro-ol?). These are resolved using the simple logic that the first character is considered part of the unit if this unit exists; otherwise it is considered a prefix.

nutils.unit.create(_typename='unit', **units)

Create new unit type.

The unit system is defined via variable keyword arguments, with every unit specified either as a direct numerical value or as a string referencing other units using the standard expression syntax. Ultimately every unit should be resolvable to a numerical value by tracing its dependencies.

The following example defines a subset of the SI system. Note that we cannot use prefixes on the receiving end of a definition for reasons of ambiguity, hence the definition of a gram as 1/1000:

>>> SI = create(m=1, s=1, g=1e-3, N='kg*m/s2', Pa='N/m2')
>>> SI('2km')
>>> SI('2g')
  • name (str (optional, positional only)) – Name of the new class object.

  • **units – Unit definitions.


The newly created (uninitiated) unit class.