Skip to main content

No project description provided

Project description

TUnits - Fast Python Units

GCB CI status:
GCB Build Status

Implements unit of measurement arithmetic, where a number is associated with a product of powers of base units and values with compatible units can be added.

The library is written in Cython for speed. The library provides the ability to statically check dimensionality type (see below) and a limited protobuffer serialization support for select units (see below). Contributions to extend support for more units are welcome.

A precompiled wheel can be installed using pip install typedunits [--pre].

Example

>> import tunits
>> from tunits.units import meter, km, N, MHz

>> print(3*MHz)
Frequency(3, 'MHz')

>> print(5*meter + km)
Length(1005.0, 'm')

>> print(N/meter)
N/m

>> print((N/meter).in_base_units())
kg/s^2

>> print(2*km / tunits.Value(3, 's'))
0.666666666667 km/s

Static Type Check

TypedUnits provides the ability to statically check the dimensionality of variables and parameters. For example mypy would complain about incompatible types for the following code.

from tunits import Frequency, LengthArray
from tunits.units import meter, km, MHz

def frequency_fn(f: Frequency) -> Frequency:
    return 3*f

x = 2 * meter
x_arr = LengthArray([1, 2], km)
y = 3 * km
f = 7 * MHz

# okay
print(frequency_fn(f))
print(x + y)
print(x_arr - y)

# not okay
print(frequency_fn(x))
print(f + x)
print(x - f)
frequency_fn(x_arr)
$ mypy my_code.py
my_code.py:18: error: Argument 1 to "frequency_fn" has incompatible type "Length"; expected "Frequency"  [arg-type]
my_code.py:19: error: No overload variant of "__add__" of "Value" matches argument type "Length"  [operator]
my_code.py:19: note: Possible overload variants:
my_code.py:19: note:     def __add__(self, int | float | complex | number[Any], /) -> Frequency
my_code.py:19: note:     def __add__(self, ValueArray | list[Any] | tuple[Any] | ndarray[Any, dtype[Any]], /) -> ValueArray
my_code.py:19: note:     def __add__(self, Frequency, /) -> Frequency
my_code.py:20: error: No overload variant of "__sub__" of "Value" matches argument type "Frequency"  [operator]
my_code.py:20: note: Possible overload variants:
my_code.py:20: note:     def __sub__(self, int | float | complex | number[Any], /) -> Length
my_code.py:20: note:     def __sub__(self, list[Any] | tuple[Any] | ndarray[Any, dtype[Any]], /) -> ValueArray
my_code.py:20: note:     def __sub__(self, Length, /) -> Length
my_code.py:21: error: Argument 1 to "frequency_fn" has incompatible type "LengthArray"; expected "Frequency"  [arg-type]
Found 4 errors in 1 file (checked 1 source file)

Serialization support

TypedUnits provides protobuffer serialization support for selected units. Contributions are welcome to increase serialization coverage.

>> from tunits import Frequency
>> from tunits.units import MHz
>>
>> v = 3*MHz
>> msg = v.to_proto()
>> print(msg)
units {
  unit: HERTZ
  scale: MEGA
}
real_value: 3

>> Frequency.from_proto(msg)
Frequency(3.0, 'MHz')

Installation

  1. To install a precompiled wheel (add --pre for prelease version)

    pip install typedunits # [--pre] 
    
  2. To locally build the latest version from the main branch

    pip install git+https://github.com/quantumlib/TypedUnits
    
  3. For a local editable copy

    git clone https://github.com/quantumlib/TypedUnits
    cd TypedUnits
    pip install .
    

Development and Testing

  1. Clone the repository.

    git clone https://github.com/quantumlib/TypedUnits
    
    cd TypedUnits
    

    All future steps assume you are in the repository's directory.

  2. Install dev environment dependencies.

    pip install -r dev_tools/dev.env.txt
    
  3. Install TUnits

    pip install .
    
  4. Test.

    pytest
    

Formatting

dev_tools/format.sh  # to format
dev_tools/format.sh --check  # to verify format

Note: This is not an officially supported Google product

Project details


Download files

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

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

typedunits-0.0.1.dev20240912133457-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.1 MB view details)

Uploaded CPython 3.12 manylinux: glibc 2.17+ x86-64

typedunits-0.0.1.dev20240912133457-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.6 MB view details)

Uploaded CPython 3.11 manylinux: glibc 2.17+ x86-64

typedunits-0.0.1.dev20240912133457-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.2 MB view details)

Uploaded CPython 3.10 manylinux: glibc 2.17+ x86-64

File details

Details for the file typedunits-0.0.1.dev20240912133457-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for typedunits-0.0.1.dev20240912133457-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 1ae851d81b5b1d04f5afdb65d5c233f97ddfd57b219c7f06dc91fce3d261d2bb
MD5 cc19e5c54def9d29377a89c87934db0c
BLAKE2b-256 26eb87cd4b0e9c0c2b1b8c66f83c32738fd1e5d5c2ae2ebfe9d96ee5d0d44a32

See more details on using hashes here.

File details

Details for the file typedunits-0.0.1.dev20240912133457-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for typedunits-0.0.1.dev20240912133457-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d59fe8e3a0445243add9cdc97699719e889163ba90e9fdf4f6a5dd90129561d9
MD5 7932e95880cd26ea59bc5227d24e8dae
BLAKE2b-256 8995d6e1b5797140ee03e5c1052cb648b594dfed16cfc2ee98fcd9a92860d310

See more details on using hashes here.

File details

Details for the file typedunits-0.0.1.dev20240912133457-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for typedunits-0.0.1.dev20240912133457-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8fb810de1055eaee21e5cc67fba9e80f69c2f6f6358778a79f775d86079c1196
MD5 3e0dbc1924ffd39e270b9550a3219883
BLAKE2b-256 1634deaa04e7ffa23c72efcbd6384745d5a718fac9fe31019c5be4c5399dc296

See more details on using hashes here.

Supported by

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