A Python library for computing with numbers with units.

A magnitude is a number with a unit, like 10 km/h. Units can be any of the SI units, plus a bunch of non-SI, bits, dollars, and any combination of them. They can include the standard SI prefixes. Magnitude can operate with physical quantities, parse their units, and print them. You don't have to worry about unit consistency or conversions; everything is handled transparently. By default output is done in basic SI units, but you can specify any output unit, as long as it can be reduced to the basic units of the physical quantity.

uv add magnitude # recommended

# or with pip

pip install magnitude

from magnitude import mg

# Basic usage
print("10 m/s ** 2 ->", mg(10, 'm/s') ** 2)
# 10 m/s ** 2 -> 100.0000 m2 / s2

# Unit conversions
speed = mg(10, 'm/s', 'km/h')
speed
# 36.0000 km/h

# Dimensional analysis
time_squared = mg(10, 'm') * 2 / (10, 'm/s2')
time_squared
# 2.0000 s2
back_to_time = time_squared ** 0.5
back_to_time
# 1.4142 s

# Natural constants
year = mg(1, "lightyear") / (1, "c")
year.ounit("year")
# 1.0000 year
year.ounit('day')
# 365.2500 day

• Full support for SI units and prefixes
• Automatic unit conversion and dimensional analysis
• Support for derived units (joules, watts, etc.)
• Binary prefixes (Ki, Mi, Gi, etc.)
• Currency units
• Unicode superscript support for unit notation (m², s⁻¹, etc.)
• Extensible - add your own units
• Pure Python, no dependencies

The basic units understood by magnitude are:

• $ - dollar
• A - ampere
• b - bit
• cd - candela
• K - degrees Kelvin
• kg - kilograms
• m - meters
• mol - amount of substance
• s - seconds

From the basic units, magnitude supports many derived units:

• Bq - becquerel
• C - coulomb
• c - speed of light (m/s)
• day - day
• degC - degree Celsius
• dpi - dots per inch
• F - farad
• ft - feet ("'" is also acceptable)
• g - gram
• gravity - acceleration due to gravity (m/s²)
• Gy - gray
• H - henry
• h - hour
• Hz - Hertz
• inch - inch ('"' is also acceptable)
• ips - inches per second
• J - joule
• kat - katal
• l - liter
• lightyear - light year
• lm - lumen
• lpi - lines per inch
• lux - lux
• min - minute
• N - newton
• ohm - ohm
• Pa - pascal
• S - siemens
• Sv - sievert
• T - tesla
• V - volt
• W - watt
• Wb - weber
• year - year
• B - byte

Two magnitudes have no units: rad (radian - unit of plane angle) and sr (steradian - unit of solid angle).

Any unit can be augmented with these scale prefixes:

• y - yocto (10⁻²⁴)
• z - zepto (10⁻²¹)
• a - atto (10⁻¹⁸)
• f - femto (10⁻¹⁵)
• p - pico (10⁻¹²)
• n - nano (10⁻⁹)
• u - micro (10⁻⁶)
• m - milli (10⁻³)
• c - centi (10⁻²)
• d - deci (10⁻¹)
• k - kilo (10³)
• M - mega (10⁶)
• G - giga (10⁹)
• T - tera (10¹²)
• P - peta (10¹⁵)
• E - exa (10¹⁸)
• Z - zetta (10²¹)
• Y - yotta (10²⁴)

• Ki - Kibi (2¹⁰)
• Mi - Mebi (2²⁰)
• Gi - Gibi (2³⁰)
• Ti - Tebi (2⁴⁰)
• Pi - Pebi (2⁵⁰)
• Ei - Exbi (2⁶⁰)

Magnitude supports Unicode superscripts for both input and output of units:

You can use Unicode superscripts when creating magnitudes:

from magnitude import mg

# These are equivalent
area1 = mg(10, 'm²')
area2 = mg(10, 'm2')

# Works with negative exponents too
frequency = mg(440, 's⁻¹')  # Same as mg(440, 's-1') or mg(440, 'Hz')

# And multi-digit exponents
special = mg(1, 'kg¹²')  # Same as mg(1, 'kg12')

By default, output uses regular ASCII notation. You can enable Unicode superscripts:

from magnitude import mg, unicode_superscript

m = mg(10, 'm2/s2')
print(m)  # 10.0000 m2/s2

# Enable Unicode superscripts
unicode_superscript(True)
print(m)  # 10.0000 m²/s²

# Works with all units
print(mg(1, 'kg') / mg(1, 'm3'))  # 1.0000 kg / m³

You can set the default behavior using the MAGNITUDE_UNICODE_SUPERSCRIPTS environment variable:

# Enable Unicode superscripts by default
export MAGNITUDE_UNICODE_SUPERSCRIPTS=1  # or 'true', 'yes', 'on'

# In Python
from magnitude import mg
print(mg(10, 'm2'))  # Will print: 10.0000 m²

You can define new magnitudes by instantiating the Magnitude class. For example, to define pounds:

from magnitude import Magnitude, mg, new_mag

# A pound is 0.45359237 kilograms
lb = Magnitude(0.45359237, kg=1)

# Register it in the system
new_mag('lb', lb)

# Now you can use it
me = mg(180, 'lb')
print(me.ounit('kg'))  # 81.6466 kg

• Magnitude - The main class for numbers with units
• mg(value, unit, ounit='') - Construct a Magnitude
• ensmg(m, unit='') - Convert something to a Magnitude
• new_mag(indicator, mag) - Register a new magnitude unit
• MagnitudeError - Exception for magnitude errors

• output_precision(prec) - Set/get output precision (default: 4)
• output_units(enabled) - Enable/disable unit output
• default_format(fmt) - Set/get default output format

Full documentation is available at: https://juanreyero.com/open/magnitude/

• NIST Units
• SI Units on Wikipedia
• GNU Units

This code was inspired by Novak's units code and its associated paper.

Copyright (c) 2006-2024 Juan Reyero (https://juanreyero.com).

Licensed under the MIT License. See LICENSE for details.