Basic Usage

The library can be used either as part of a typical Python module or as part of an interactive session.

The module-level import can be used in any context but may be less convenient in an interactive session. Using the interactive import can cause namespace conflicts when used across multiple Python modules and is primarily recommended for interactive use.

Units are imported as variables and then the variables are to be multiplied to numbers to create a physical quantities. This is the generally accepted interpretation of a physical quantity as described in the SI units brochure (section 2.1, 9th ed.).

Module-level import

import forallpeople as si

Upon import, the SI base units (si.kg, si.m, si.s, si.A, si.cd, si.K, and si.mol) are instantiated and are available in the module-level namespace as variables. These can be seen by calling si.environment() without any arguments.

si.environment()

{'kg': 1.000 kg, 'm': 1.000 m, 's': 1.000 s, 'A': 1.000 A, 'cd': 1.000 cd, 'K': 1.000 K, 'mol': 1.000 mol}

These units can be used as shown:

mass = 5.25 * si.kg
g = 9.81 * si.m/si.s**2
print(mass*g)

51.503 kg·m·s⁻²

By using the si.environment() function, you can create a units environment which serves two purposes:

1. The new environment pushes the additional unit definitions into the module namespace as variables.

2. It modifies the representation of the units that are to be displayed in accordance with the definitions contained within the environment.

si.environment('default') # Load the default.json environment
print(mass*g)

51.503 N

# See the names of the new variables accessible in the namespace
si.environment()

{'Hz': 1.000 Hz, 'N': 1.000 N, 'Pa': 1.000 Pa, 'J': 1.000 J, 'W': 1.000 W, 'C': 1.000 C, 'V': 1.000 V, 'F': 1.000 F, 'Ohm': 1.000 Ω, 'S': 1.000 S, 'Wb': 1.000 Wb, 'T': 1.000 T, 'H': 1.000 H, 'Celsius': 1.000 °C, 'lux': 1.000 lux, 'Gy': 1.000 Gy, 'katal': 1.000 kat, 'minute': 1.000 minutes, 'hour': 1.000 hours, 'day': 1.000 days}
 {'kg': 1.000 kg, 'm': 1.000 m, 's': 1.000 s, 'A': 1.000 A, 'cd': 1.000 cd, 'K': 1.000 °C, 'mol': 1.000 mol}

Interactive import

The interactive import pushes the module-level variables into the top-level namespace so they are available to you without having to type a module prefix such as si..

Be careful of variable name clashes especially if you commonly use single character variable names (e.g. m or s, etc.)

import forallpeople
forallpeople.environment('default', top_level=True)

Now the units are available as variables in the top-level namespace.

mass = 5.25*kg
g = 9.81 * m/s**2
mass*g

51.503 N

String formatting

Physical instances are represented as formatted strings and can accept the standard Python string formatting specifications.

In addition, Physical instances can accept the special format codes L and H for formatting strings in either LaTeX or HTML, respectively.

Some examples:

mass = 32.902392 * kg
g = 9.8065 * m/s**2
force = mass * g
force # Default format is {:.3f}

322.657 N

"{:.6f}".format(force)

'322.657307 N'

"{:.4e}".format(force)

'3.2266e+02 N'

"{:.4eH}".format(force) # Use 'H' to render HTML

'3.2266 &times; 10<sup>2</sup> N'

"{:.4eL}".format(force) # Use 'L' to render LaTeX

'$3.2266 \\times 10^ {2}\\ \\mathrm{N}$'