natu¶

Natural units in Python

natu is a free, open-source package to represent physical quantities. There are many Python packages that deal with units and quantities, but natu is uniquely system-independent. The units are derived from physical constants with adjustable values and dimensions. The value of a unit is factored into a quantity so that the quantity is not “in” any particular unit. This has the following advantages:

• Flexible: Different unit systems, including natural units (hence the name “natu”), can be represented by simply adjusting the base physical constants.
• Simple: Unit conversion is inherent. This results in quick computations and a small code base (about 1500 lines). By default, dimensions and display units are tracked to catch errors and for string formatting. This can be disabled to nearly eliminate the computational overhead while still providing the core features.
• Intuitive: Each unit is a fixed quantity that is treated as a mathematical entity. A variable quantity is expressed as the product of a number and a unit, as stated in [BIPM2006].
• Representative: The design reflects the way modern units are defined. Standards organizations such as NIST assign values to universal physical constants so that the values of units can be determined by physical experiments instead of prototypes.
• Scalable: The values of the base physical constants can scaled to prevent exponent overflow, regardless of the units used [Davies2012], [1].

natu incorporates some of the best features of the existing packages:

• Units with offsets and even nonlinear functions are supported. For example:

  >>> from natu.units import degC, K
  >>> 0*degC + 100*K
  100.0 degC
  

  >>> from natu.units import dB
  >>> (10/dB + 10/dB)*dB  # Multiply by adding logarithms.
  100.0
  

• Prefixes are automatically applied. For example:

  >>> from natu.units import km, m
  >>> km/m
  1000
  

• Display units are simplified using coherent relations automatically gathered from the unit definitions:

  >>> from natu.units import kg, m, s
  >>> 1*kg*m**2/s**2
  1.0 J
  

• Units are automatically sorted into convenient submodules such as natu.groups.length.

• Nearly 40 physical constants are included. For example:

  >>> from natu.groups.constants import c
  >>> c
  299792458.0 m/s
  

• Additional constants and units can be easily added to the definition files or defined in code.

• There are drop-in, quantity-aware replacements for math and numpy. Quantities can be used in NumPy arrays or vice versa (see here).

• There are no dependencies except for the numpy replacements (previous feature).

• Units can have fractional powers. For example:

  >>> from fractions import Fraction
  >>> m**Fraction(1, 2)
  ScalarUnit m(1/2) with dimension L(1/2) (not prefixable)
  

• Units and quantities can be formatted for HTML, LaTeX, Unicode, and Modelica. For example:

  >>> '{:H}'.format(10*m**2)
  '10.0&nbsp;m<sup>2</sup>'
  

  This renders in HTML as 10.0 m².

• Rationalized and unrationalized unit systems are supported.

Please see the tutorial for more examples. The links in the sidebar give the installation instructions and more information.

License terms and development

natu is published under a BSD-compatible license. Please share any improvements you make, preferably as a pull request to the master branch of the GitHub repository. There are useful development scripts in the hooks folder. If you find a bug, have a suggestion, or just want to leave a comment, please open an issue.

References

Footnotes