PicoUnits logo

A Dynamic Runtime Type System for Dimensional Numerical Quantities.

Define the type. Define the variable. Execute.
Automate physical meaning throughout your pipeline.

Overview

License Python Version Coverage PyPI Downloads

PicoUnits is a dynamic runtime dimensional typing system for numerical quantities. It provides a consistent type system for expressing dimensional quantities throughout your pipeline.

[!important]

Features:

  • Configurable unit frames with custom symbols and dimension ordering
  • Parses UnitValues language formats: unit types (.ut) and unit-informed values (.uiv)
  • Numerical support for real, complex, and vector quantities

Why convert at all?

PicoUnits removes uncertainty by reducing the set of units to one canonical set defined by the user.

It does not attempt to answer:

How might one convert between systems at a boundary?

3 feet → ? metre (1/3.280839895...?) 
↺ Each iteration

Because for computation, this is quite flawed. It destroys certainty for implementation convenience.

Define unit frame → Define derived units → Work within it, not outside it.

What is a Unit Frame?

A unit frame defines the dimensional system used by an application.

For example:

[symbols]
time: s
length: m
mass: kg
current: A
temperature: K
amount: mol
luminosity: cd
dimensionless: ∅

The dimensional environment is independent of the notation used to represent it. Hence, any semantic representation can be used. However, PicoUnits operates on a fixed set of fundamental dimensions and prefixes.

See the .picounits file for implementation details.

What are .ut and .uiv?

Both are dimensionally aware formats: .ut defines custom units, while .uiv encodes quantities as value prefix(unit) groups.

.ut defines the custom units for your unit system:

[units]
p: kg*m^-1*s^-2                # Defines the unit for pressure (Pascal)

.uiv defines the quantities within your unit system:

[model]
inlet_pressure: 101 k(p)  # 101 kPa using the defined unit p

See the UnitValues repository for notation and language specification.

Quick Start

A standard introduction example is available in example/.

from picounits import expects, VOLTAGE, CURRENT, RESISTANCE
 
@expects(VOLTAGE)
def ohm_law(i, r):
    return i * r
 
# Correct Usage
ohm_law(10 * CURRENT, 5 * RESISTANCE) 
# > Output: 50.0 (kg·m²·s⁻³·A⁻¹)

# Incorrect Usage
ohm_law(10 * CURRENT, 5 * VOLTAGE)
# > DimensionError: 'ohm_law' returned kg·m²·s⁻³, expected kg·m²·s⁻³·A⁻¹

Installation

To install:

pip install PicoUnits

Documentation

Full documentation is available in the docs/ folder, including API reference, changelog, and contributors.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for wgbowley from gravatar.com wgbowley

Credits

Author/Maintainer: William Bowley

License

MIT License (MIT License)

Requires

Python >=3.10

Tags

error-checking minimal physics si units

Classifiers

Report project as malware

Download files

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

Source Distribution

picounits-1.0.9.tar.gz (184.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

picounits-1.0.9-py3-none-any.whl (60.7 kB view details)

Uploaded Python 3

File details

Details for the file picounits-1.0.9.tar.gz.

File metadata

  • Download URL: picounits-1.0.9.tar.gz
  • Upload date:
  • Size: 184.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for picounits-1.0.9.tar.gz
Algorithm Hash digest
SHA256 89dd9e0bb6061da571cd2c07d27dd108d239520f4727d596be4e22b4ce62a71b
MD5 e4e2e08ff312f8d18fb271e15da287a5
BLAKE2b-256 cb7c437893659f34705bec99e98ecc72ec7f946df3b6e6c852d0545212b8e689

See more details on using hashes here.

Provenance

The following attestation bundles were made for picounits-1.0.9.tar.gz:

Publisher: publish_picounits.yml on Bowley-Systems/PicoUnits

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file picounits-1.0.9-py3-none-any.whl.

File metadata

  • Download URL: picounits-1.0.9-py3-none-any.whl
  • Upload date:
  • Size: 60.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for picounits-1.0.9-py3-none-any.whl
Algorithm Hash digest
SHA256 74772472d06f0941b1271861b5ed72abc2532b0fff12f37b67c3c8f00b51abc3
MD5 6d48c3a5c3868c6b57fb37fc5922dabe
BLAKE2b-256 cc6c18b71e0af276539ed97a27a6d73f30a778a12eb55c013f136937812c7468

See more details on using hashes here.

Provenance

The following attestation bundles were made for picounits-1.0.9-py3-none-any.whl:

Publisher: publish_picounits.yml on Bowley-Systems/PicoUnits

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.0.9 This release

2 files

1.0.8

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

0.1.0

2 files

0.0.1

2 files

Supported by

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