Skip to main content

Fast quantities

Project description

https://travis-ci.org/cjrh/misu.svg?branch=master https://coveralls.io/repos/github/cjrh/misu/badge.svg?branch=master https://img.shields.io/pypi/pyversions/misu.svg https://img.shields.io/github/tag/cjrh/misu.svg https://img.shields.io/badge/install-pip%20install%20misu-ff69b4.svg https://img.shields.io/pypi/v/misu.svg https://img.shields.io/badge/calver-YYYY.MM.MINOR-22bfda.svg

misu

misu is short for “misura”, which means measurement (in Italian).

Demo

Most of the time you will probably work with misu interactively, and it will be most convenient to import the entire namespace:

from misu import *

mass = 100*kg
print(mass >> lb)

The symbol kg got imported from the misu package. We redefine the shift operator to perform inline conversions. The code above produces:

220.46226218487757

There are many units already defined, and it is easy to add more. Here we convert the same quantity into ounces:

print(mass >> oz)

output:

3571.4285714285716

What you see above would be useless on its own. What you really need is to be able to perform consistent calculations with quantities expressed in different, but compatible units:

mass = 10*kg + 20*lb
print(mass)

output:

19.07 kg

For addition and subtraction, misu will ensure that only consistent units can be used. Multiplication and division will produce new units:

distance = 100*metres
time = 9.2*seconds

speed = distance / time
print(speed)

output:

10.87 m/s

As before, it is trivially easy to express that quantity in different units of compatible dimensions:

print(speed >> km/hr)

output:

39.130434782608695

Introduction

misu is a package of handling physical quantities with dimensions. This means performing calculations with all the units being tracked correctly. It is possible to add kilograms per hour to ounces per minute, obtain the correct answer, and have that answer be reported in, say, pounds per week.

misu grew out of a personal need. I have used this code personally in a (chemical) engineering context for well over a year now (at time of writing, Feb 2015). Every feature has been added in response to a personal need.

Features

  • Speed optimized. misu is very fast! Heavy math code in Python will be around only 5X slower when used with misu. This is much faster than other quantities packages for Python.

  • Written as a Cython extension module. Speed benefits carry over when using misu from your own Cython module (a .pxd is provided for linking).

  • When an operation involving incompatible units is attempted, an EIncompatibleUnits exception is raised, with a clear explanation message about which units were inconsistent.

  • Decorators for functions to enforce dimensions

@dimensions(x='Length', y='Mass')
def f(x, y):
    return x/y

f(2*m, 3*kg)         # Works
f(200*feet, 3*tons)  # Works

f(2*joules, 3*kelvin)  # raises AssertionError
f(2*m, 3)              # raises AssertionError
  • An operator for easily stripping the units component to obtain a plain numerical value

mass = 100 * kg
mass_lb = mass >> lb

duty = 50 * MW
duty_BTU_hr = duty >> BTU / hr
  • An enormous amount of redundancy in the naming of various units. This means that m, metre, metres, METRE, METRES will all work. The reason for this is that from my own experience, when working interactively (e.g. in the IPython Notebook) it can be very distracting to incorrectly guess the name for a particular unit, and have to look it up. ft, foot and feet all work, m3 means m**3 and so on.

  • You can specify a reporting unit for a dimension, meaning that you could have all lengths be reported in “feet” by default for example.

  • You can specify a reporting format for a particular unit.

There are other projects, why misu?

There are several units systems for Python, but the primary motivating use-case is that misu is written as a Cython module and is by far the fastest* for managing units available in Python.

*Except for ``NumericalUnits``, which is a special case

**I haven’t actually checked that this statement is true for all of them yet.

General usage

For speed-critical code, the application of unit operations can still be too slow. In these situations it is typical to first cast quantities into numerical values (doubles, say), perform the speed-critical calculations (perhaps call into a C-library), and then re-cast the result back into a quantity and return that from a function.

@dimensions(x='Length', y='Mass')
def f(x, y):
    x = x >> metre
    y = y >> ounces
    <code that assumes meters and ounces, returns value in BTU>
    return answer * BTU

This way you can still easily wrap performance-critical calculations with robust unit-handling.

Inspiration

The inspiration for misu was Frink by Alan Eliasen. It is wonderful, but I need to work with units in the IPython Notebook, and with all my other Python code.

There are a bunch of other similar projects. I have not used any of them enough yet to provide a fair comparison:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

misu-1.0.4.tar.gz (181.9 kB view details)

Uploaded Source

Built Distributions

misu-1.0.4-cp37-cp37m-win_amd64.whl (131.8 kB view details)

Uploaded CPython 3.7mWindows x86-64

misu-1.0.4-cp36-cp36m-win_amd64.whl (131.8 kB view details)

Uploaded CPython 3.6mWindows x86-64

misu-1.0.4-cp27-cp27m-win_amd64.whl (127.9 kB view details)

Uploaded CPython 2.7mWindows x86-64

File details

Details for the file misu-1.0.4.tar.gz.

File metadata

  • Download URL: misu-1.0.4.tar.gz
  • Upload date:
  • Size: 181.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/39.0.1 requests-toolbelt/0.8.0 tqdm/4.24.0 CPython/3.7.0

File hashes

Hashes for misu-1.0.4.tar.gz
Algorithm Hash digest
SHA256 7bb54e251137663574a659a958277c51cd5b98cb0af220302f834a2300f4cc03
MD5 6416e0b64a45373352faf0620ef48e0a
BLAKE2b-256 2ab483879074fc5e6c2129c9bfe8770f735581777a2906935c20202c80f3a330

See more details on using hashes here.

File details

Details for the file misu-1.0.4-cp37-cp37m-win_amd64.whl.

File metadata

  • Download URL: misu-1.0.4-cp37-cp37m-win_amd64.whl
  • Upload date:
  • Size: 131.8 kB
  • Tags: CPython 3.7m, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/39.0.1 requests-toolbelt/0.8.0 tqdm/4.24.0 CPython/3.7.0

File hashes

Hashes for misu-1.0.4-cp37-cp37m-win_amd64.whl
Algorithm Hash digest
SHA256 c18c63585b4dd9cfafbebfb5d78ea9a07e516beb827c7093684e3b23c8ad548d
MD5 f81addc66b2f673b36f47a3126e1825a
BLAKE2b-256 6723e7443fc309844e70c2ce6928b13c3d0f9da16dc789d79ee5e8dba7e278a1

See more details on using hashes here.

File details

Details for the file misu-1.0.4-cp36-cp36m-win_amd64.whl.

File metadata

  • Download URL: misu-1.0.4-cp36-cp36m-win_amd64.whl
  • Upload date:
  • Size: 131.8 kB
  • Tags: CPython 3.6m, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/39.0.1 requests-toolbelt/0.8.0 tqdm/4.24.0 CPython/3.7.0

File hashes

Hashes for misu-1.0.4-cp36-cp36m-win_amd64.whl
Algorithm Hash digest
SHA256 ef1883270ade358c22cdd8fa215101a2dac77a62ddf43fb1b47f517e86359767
MD5 dd8415cec167e2a3c6ccb9d4bd726010
BLAKE2b-256 eefa575e4fd00e85e4f7b50f8452e089528772db6bf49662ca8c93cf30f64eeb

See more details on using hashes here.

File details

Details for the file misu-1.0.4-cp27-cp27m-win_amd64.whl.

File metadata

  • Download URL: misu-1.0.4-cp27-cp27m-win_amd64.whl
  • Upload date:
  • Size: 127.9 kB
  • Tags: CPython 2.7m, Windows x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.11.0 pkginfo/1.4.2 requests/2.19.1 setuptools/39.0.1 requests-toolbelt/0.8.0 tqdm/4.24.0 CPython/3.7.0

File hashes

Hashes for misu-1.0.4-cp27-cp27m-win_amd64.whl
Algorithm Hash digest
SHA256 25bf6cabbf6b2d11cb3475ca8d61f307ccc34e426c91abaca06f8524af540d86
MD5 fbc239f29e463ca1a9fcd2139ffa0754
BLAKE2b-256 fcf04f5f1e82f1cb38e1746cbbbe1eccc415490d1e4cee6ad7e246e3ad967ba2

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page