unit-system-py 0.8.0rc9

A simple unit system for python

unit-system Python

As of version 0.6.0 all the source code is generated by python scripts. This repository only contains the generated source files. If you want to report a bug or change something check the generator repository.

This is an implementation of the SI unit system for Python development. All units, combinations, literals and constants are generated from templates. If you feel something is missing open an issue or a pull request on the generator repository.

Usage examples

from unit_system_py import literals

# create some units
l1 = literals.km(10)
t1 = literals.s(5)

# combine the two units to the correct one
v1 = l1 / t1

# print the result, with correct unit names
# This should print
# 10000 meter in 5 second is 2000 meter / second
print(l1, "in", t1, "is", v1)

As you can see using the unit system is pretty easy. The literals class contains all implemented SI unit names. You can use them to create units with the correct multiplier and offset.

While it is generally better to create units using the literals, it is also possible to include the units directly. Just note that you have to manually set the multiplier, since the unit is not created using the literals.

from unit_system_py import time, length

# create some units
l1 = length(10, 1000)
t1 = time(5)

# combine the two units to the correct one
v1 = l1 / t1

# print the result, with correct unit names
# This should print
# 10000 meter in 5 second is 2000 meter / second
print(l1, "in", t1, "is", v1)

This allows to specify multipliers that are not created by the literals. Another use of this, is to specify type hints for the units. This is highly encouraged, when defining functions that take units as arguments.

from unit_system_py import length, speed, literals
from math import sin, radians

# create an example function which calculates a throw distance from a speed and angle
def throw_distance(throw_speed: speed, angle_degrees: float) -> length:
    # verify that the correct unit is passed
    if not isinstance(throw_speed, speed):
        raise TypeError("throw_speed must be of type speed")
    
    # convert the angle to radians
    angle = radians(angle_degrees)
    # get the speed in m/s and the local gravity acceleration
    speed_mps = float(throw_speed)
    g = float(literals.G(1))
    # calculate the distance
    return speed_mps**2 * sin(2 * angle)  / g

# get the distance for a throw with 10 m/s and 45 degrees
print(throw_distance(literals.mps(10), 45))

Because not all combinations of units are implemented, you can also cast units to a float. Calling float on a unit will return the value of the unit in the base unit. Alternatively you can also use the convert_to method to convert a unit to another multiplier and offset. If you want to use the value property directly, make sure to check the multiplier and offset first. If you don't do this, you might get wrong results since the value of literals.km(1) is the same as the value of literals.m(1). They have to be converted to the same multiplier and offset before you can use them directly. All functions of the unit_system either do this, or they also combine the multipliers and offsets correctly.

Units that are currently supported

• time -> time with seconds as base unit
• length -> length with meter as base unit
• mass -> mass with kg as base unit
• temperature -> temperature with K as base unit
• amount -> amount of substance with mole as base unit
• electric_current -> electric current with Ampere as base unit
• luminous_intensity -> luminous intensity with candela as base unit
• area -> area with m^2 as base unit
• speed -> speed with m / s as base unit
• acceleration -> acceleration with m / s^2 as base unit
• momentum -> momentum with kg * m / s as base unit
• force -> force with kg * m / s^2 (Newton) as base unit
• energy -> energy with kg * m^2 / s^2 (Joules) as base unit
• power -> power with kg * m^2 / s^3 (Watts) as base unit

Upgrade Instructions

Since 0.8.0 is the first release, there are no upgrade instructions yet.