search

connorferster / forallpeople

Python SI units library: your 'daily driver' for calculations.
Apache License 2.0
272 stars 38 forks source link

readme

forallpeople:
The world's units
at your fingertips

"For all people. For all time."
Nicolas de Caritat (Marquis de Condorcet),
in regards to the creation of the metric (SI) system.

Github Stars Github Pages Documentation Link GitHub Issues or Pull Requests

forallpeople is a Python library for providing access to units-aware calculations through the SI units system, and other units defined by the SI sytem (e.g. US customary units, Imperial).

While there are many other units libraries available for Python, forallpeople is unique in the following ways:

  1. Physical quantities are automatically reduced during multiplication and division.
  2. Physical quantities that are completely cancelled out return just a number (instead of a dimensionless unit).
  3. Physical quantities carry their own dimension vectors and, as such, their definitions exist independently of the units environment they are in.
  4. When loaded, the units variables can either be dynamically pushed to the module namespace or to the top-level namespace. This allows for faster code writing that looks like this a = 5 * kg instead of a = 5 * si.kg
  5. Released on PyPI on the day the new definition of the kilogram was adopted by the world on World Metrology Day, 20 May 2019.

Installing

You can install using pip:

pip install forallpeople

Basic usage 1: Module-level namespace

The most basic use is just to import the library:

import forallpeople as si

This will import the Physical class. It is the primary class in the module and is used to describe all physical quantities. Physical instances are immutable.

Upon import, the SI base units are instantiated and are available in the namespace as the following variables:

Basic Usage 1

Loading an environment

si.environment('default', [top_level=False])

This will load the 'default.json' file within the forallpeople module that describes the SI derived units, the units created by compounding the base units (e.g. Newton, Pascal, Celsius, Watt, Joule, etc.).

When you load an environment, whether it is the default environment or one you define, the representation of the units will change to fit the definitions in the environment. Environment definitions are dimensional, meaning, if you end up with a Physical of a dimension that matches a dimension in the environment, then the repr() of that instance will change to match the dimensioned unit in the environment.

It is important to note that, no matter what environment is loaded or not loaded, your Physical instances will always carry their value in the SI base units, e.g.:

>>> pressure = force / area
>>> pressure = 208.333 Pa
>>> pressure.repr
>>> 'Physical(value=208.33333333333334, dimensions=Dimensions(kg=1, m=-1, s=-2, A=0, cd=0, K=0, mol=0), factor=1, _precision=3)'

Additionally, when you load an environment, the units defined in the environment will be instantiated as Physical and you can utilize them as variables in calculations.

The 'default' environment defines and loads the following units as variables into the module namespace:

Because the units of si.N are one of the Physical instances that have now been instantiated and loaded into the si namespace, you can perform calculations with them directly: 

>>> area = 3*si.m * 4*si.m
>>> force = 2500 * si.N
>>> force / area
>>> 208.333 Pa

Basic usage 2: Top-level namespace

Everything from Basic usage 1 applies, except that, when loading an environment by setting top_level=True, all of the units described in the environment json file will instead be "pushed" into the top-level namespace, i.e. you would not type 5 * si.N but 5 * N.

Basic Usage 2

API

Each Physical instance offers the following methods and properties:

Properties

Methods

Almost all methods return a new Physical because all instances are immutable.

Dimensionally inconsistent calculations

It is not uncommon for some calculations to use formulas whose dimensions seem to magically appear on their own. The forallpeople library can handle these calculations if the "hidden dimensions" are recognized and accounted for by the user.

Example: in the Canadian concrete design code it is recognized that sqrt(1*MPa) results in units of MPa instead of MPa0.5. Here is one way this can be managed in forallpeople:

>>> import forallpeople as si
>>> from math import sqrt
>>> si.environment('default')
>>> MPa = 1e6 * si.Pa
>>> f_c = 35 * MPa
>>> sqrt(f_c) * MPa
5.916 MPa

This behaviour occurs because of the way __float__ is defined in the Physical class: if float() is called on a Physical, the returned value will be the numerical portion of the auto-reduced, auto-prefixed unit representation.

Example:

>>> import forallpeople as si
>>> from math import sqrt
>>> si.environment('default')
>>> MPa = 1e6 * si.Pa
>>> f_c = 35 * MPa
>>> f_c # As expected
35.000 MPa
>>> float(f_c) # The numerical portion of the prefixed unit
35.0
>>> f_c.value # However, the actual value is 35e6 Pa
35000000.0
>>> sqrt(f_c) # Sqrt of "35"
5.916079783099616
>>> sqrt(f_c.value) # Sqrt of "35000000.0"
5916.079783099616

Many of Python's math functions will first attempt to call float() on an argument that is not already a float. forallpeople takes advantage of this by ensuring the float value returned is the same number you would see in the unit representation. If you prefer the operation be performed on the base unit value, then simply substitute the .value value as the function argument.

How Physical instances work

forallpeople is for describing physical quantities and defines a single class, Physical, to represent them. Physical instances are composed of four components (as attributes):

Because Physical instances are immutable (just like int, float, str, and bool), the user cannot set these attributes directly. It also means that any arithmetic operation on a Physical instance returns a new instance. Arithmetic operations is the intended way of creating new Physical instances.

Dimension vectors

Physical instances track the dimensions of their physical quantities by using vectors. The vector is stored in the Dimensions class, which is a NamedTuple. Using the vector library, tuplevector (which is "baked in" to forallpeople), vector arithmetic is performed on Dimensions objects directly.

Arithmetic on Physical instancess

Arithmetic on Physical instances work mostly how you would expect, with few caveats:

Auto-prefixing

forallpeople employs "auto-prefixing" and by default selects the most conventional way of representing the unit, scaled to an appropriate prefix.

>>> current = 0.5 * A
>>> current
500.000 mA # 'current' is auto-prefixed to 500 milliamperes
>>> resistance = 1200 * Ohm
>>> resistance
1.200 kΩ # 'resistance' is auto-prefixed to kilo-ohms
>>> voltage = current * resistance
>>> voltage
600.000 V # 'voltage' does not have a prefix because its value is above 1 V but less than 1000 V

The prefixes of the entire SI units system (from 10**-24 to 10**24) are built-in to the Physical class and they step at every three powers of ten (i.e. 10**-3, 10**0, 10**3, 10**6, etc.).

However, auto-prefixing is only triggered in certain, intuitive circumstances:

  1. The unit is one of m, kg, s, A, cd, K, or mol (i.e. the SI base units).
  2. The unit is a derived unit in the SI unit system (i.e. it is defined in the environment and has a .factor == 1).

This means that auto-prefixing is not used in the following circumstances:

  1. The unit is defined in the environment with a factor (e.g. lb: it would not make sense to have a klb or a mlb).
  2. The unit is a compound unit but not defined in the environment (e.g. it would not make sense to have a kkg*m/s).

When the auto-prefixing is triggered for a unit and that unit is of a power other than 1, then auto-prefixing considers the prefix to also be part of the unit's power. For example:

>>> a = 5000 * si.m
>>> a
5.000 km
>>> a**2
25.000 km² # Remember that the 'kilo' prefix is also being squared
>>> b = 500000 * si.m 
>>> b
500.000 km
>>> b**2
250000.000 km² # Why isn't this being shown as 250 Mm²? Because it would take 1,000,000 km² to make a Mm². This is only 250,000 km².

How to define your own environments

NOTE: See the documentation for more information

An environment is simply a JSON document stored within the package folder in the following format:

"Name": {
    "Dimension": [0,0,0,0,0,0,0],
    "Value": 1,
    "Factor": 1,
    "Symbol": ""}

For example, if you wanted to create an environment that defined only kilopascals and pounds-force in US customary units, you would do it like this:

"kPa": {
    "Dimension": [1,-1,-2,0,0,0,0],
    "Value": 1000},
"lb-f": {
    "Dimension": [1, 1, -2, 0, 0, 0, 0],
    "Factor": "1/0.45359237/9.80665",
    "Symbol": "lb"}

Note also that arithmetical expressions in "Factor" are eval'd to allow for the most accurate input of factors; to prevent a security risk, "Factor" is regex'd to ensure that only numbers and arithmetic symbols are in "Factor" and not any alphabetic characters (see Environment._load_environment in source code to validate).

REPLs and Jupyter Notebook/Lab

forallpeople prioritizes usage conventions over Python conventions. Specifically, the library deliberately switches the intentions behind the __repr__() and __str__() methods: __repr__() will give the pretty printed version and __str__() will return the same. As such, it becomes intuitive to use within any Python REPL and it really shines when used in a Jupyter Notebook, where HTML representations are the default. This also makes it nicer to use with Python libraries such as pandas and numpy.

Using Physicals with Numpy

Physical instances can be used with many numpy operations. See below example:

>>> a = 5 * si.kN
>>> b = 3.5 * si.kN
>>> c = 7.7 * si.kN
>>> d = 6.6 * si.kN
>>> m1 = np.matrix([[a, b], [b, a]])
>>> m2 = np.matrix([[c, d], [d, c]])
>>> m1
matrix([
[5.000 kN, 3.500 kN],
[3.500 kN, 5.000 kN]], dtype=object)
>>> m2
matrix([
[7.700 kN, 6.600 kN],
[6.600 kN, 7.700 kN]], dtype=object)
>>> m1 + m2
matrix([
[12.700 kN, 10.100 kN],
[10.100 kN, 12.700 kN]], dtype=object)
>>> m1 @ m2
matrix([
[61.600 kN², 59.950 kN²],
[59.950 kN², 61.600 kN²]], dtype=object)
>>> m2 - m1
matrix([
[2.700 kN, 3.100 kN],
[3.100 kN, 2.700 kN]], dtype=object)
>>> m1 / m2
matrix([
[0.6493506493506493, 0.5303030303030303],
[0.5303030303030303, 0.6493506493506493]], dtype=object)

Documentation

For more detailed information, visit the documentation

PyPI

This package is available on PyPI