ketakopter/spq

Simple Physical Quantities for Python - Unit conversions made easy

SPQ

Simple Physical Quantities for Python - Unit conversions made easy

The name of the game

SPQ is a small python package for working easily with physical quantities and different units, with the goal of having a compact interface and an easy way of defining units.

>>> from spq import Dist
>>> a = Dist.fromft(3.3)
>>> a
1.00584
>>> a.km
0.00100584

A physical quantity has factory methods to initialize the quantity from any of the defined units, resulting in a functional interface. The units are accessible as attributes of the quantity, resulting in a compact interface. No "convert_to", no strings needed - just ask for the value in the wanted unit directly.

Internally the value of the quantity is expressed in the main unit (e.g. m for distance). You can use the variable to feed them into any function and perform calculations: this way the computations will be consistent. If you like, you can convert a variable to another unit for your output. Or you can use the package to perform quick unit conversions. It works with numpy arrays, too.

>>> Dist.fromkm(np.linspace(1,5,5)).m
array([1000., 2000., 3000., 4000., 5000.])

See more examples below.

Installation and loading

Currently there is no proper installation method. Clone the git repository to have the files in your system:

$ git clone git://github.com/ketakopter/spq.git

Add the directory to the Python path and you can import all the symbols for interactive work. This will load all the defined physical quantities.

from spq import *

Of course, you can also load the physical quantities explicitly:

from spq import Dist, Vel

Available physical quantities/units

The definition of physical quantities and units is fully specified in a json file. The best is to inspect the file. At runtime, you can also see the available units of a physical quantity with the _units attribute:

>>> Dist._units
['m', 'ft', 'km', 'nm', 'mi', 'inch']

If you want to know what is the "working" unit of a physical quantity, inspect the _mainUnit attribute:

>>> Dist._mainUnit
'm'

Loading custom physical quantities/units

You can specify physical quantities and units at runtime, but the easiest is to have the definitions in a json file. Currently the way of specifying a non-default file is to set the SPQFILE environment variable before loading the package:

# If not done prior to starting python.
import os
os.environ["SPQFILE"] = "/path/to/file"

from spc import *

To know more about defining physical quantities and units, see the example notebook. You can also try it live: -

Examples

The most basic stuff is converting scalars.

>>> a = Dist(34)
>>> a.ft
111.54855643044618

>>> b = Dist.fromft(15000)
>>> b
4572.0
>>> b.ft
14999.999999999998

It works with numpy arrays too, and the array is converted easily to the desired units:

>>> import numpy as np
>>> b = Dist.fromft(np.linspace(1,5,5))
>>> print(b)
[0.3048 0.6096 0.9144 1.2192 1.524 ]
>>> print(b.km)
[0.0003048 0.0006096 0.0009144 0.0012192 0.001524 ]

You can start variables from the units you want, and use the variables in functions that expect a consistent set of units, like SI:

>>> def earthGravForce(m, r):
...   mu = 3.986e14  # in m3/s2
...   return mu*m/r**2

>>> m = Mass.fromlb(23)
>>> r = Dist.frommi(5000)
>>> earthGravForce(m, r)
64.22337018599708

>>> earthGravForce(10.43262, 8046720.0) # if we had input the values in kg and m directly. Same result, disregarding inaccuracies in the inputs.
64.22334242237929

And many more functionalities to make working with units really easy. You can find more examples in the examples directory.

If you would like to try it live, try with the following Ipython notebook:

• Showcase - -

What SPQ is, and what is not

The goal of SPQ was to be able to quickly work with quantities and output results in different units, especially for interactive work. The variables derive from float and np.ndarray to be able to feed them to existing functions, and the value is internally stored in SI units (by default) in order to have consistent computations. The idea was to work with numerical values, no strings needed. Having the units as attributes makes it really easy to write the output in the wanted units or plot them, like plt.plot(x.mi, y.mph).

Also, the definition of physical quantities and units should be easy. The json file defining the defaults was easy to prepare and extending it is immediate.

SPQ is not intended to be a full-fledged physical quantities library, like when you multiply a length by a force you get a torque (or an energy...). Doing that would need to define relationships between physical quantities, define how operators work, and it would over-complicate the library for the intended use. Doing computations with SPQ objects just results in floats or arrays; it's up to the user to initialize whatever physical quantity with the results.

Requirements

SPQ works with Python 3 (tested with Python 3.6). The only needed dependency is Numpy (tested with Numpy 1.19).