Unit systems

This module integrates unit systems into SymPy, allowing a user choose which system to use when doing their computations and providing utilities to display and convert units.

Units (like meters, pounds, seconds) and constants (like light years, Boltzmann’s constant) are all considered quantities. A Quantity object defines both units and physical constants (though its subclass PhysicalConstant may be preferred for physical constants).

The relations between quantities are defined by their dimensions and the scale factor to at least another quantity of the same dimension. These two types of relations are usually defined inside UnitSystem objects, except for properties valid in every unit system. For example, 1 kilometer is equal to 1000 meters in all unit systems and its dimension is length in all dimension systems. On the other hand, the speed of light is equal to 299792458 meters per second in SI units, while it is equal to 1 (unitless) in natural units. In both SI and natural units the dimension of the speed of light in velocity, but in the dimension system of natural units velocity is dimensionless because length and time are equivalent. Similarly, there are discrepancies in the dimensions and scale factors of electromagnetic quantities between SI unit system and CGS and gaussian unit systems, as the last two ones do not consider the current to be a fundamental dimension.

The advantage of this implementation over the one found in other libraries is that it handles relations between units differently in different unit systems, without restrictions to the assumption of relations between units and physical constants provided by the SI unit system.


The most important function in the units module is convert_to, it allows the given quantity to be rewritten as the product of powers of some target quantities. For example, to represent the speed of light in terms of meters and seconds:

>>> from sympy.physics.units import speed_of_light, meter, second
>>> from sympy.physics.units import convert_to
>>> convert_to(speed_of_light, [meter, second])

If it is not possible to represent the given quantity in the target units, the given quantity will be returned unchanged:

>>> convert_to(speed_of_light, [meter])

The relations between quantities depend on the unit systems. So, convert_to accepts an optional third parameter representing the unit system, which is SI by default. The conversion may return different results depending on the chosen unit system, for example, in the cgs_gauss unit system the current is not a fundamental dimension, rather it can be represented as a combination of length, time and mass:

>>> from sympy.physics.units.systems.si import SI
>>> from sympy.physics.units.systems.cgs import cgs_gauss
>>> from sympy.physics.units import ampere, gram, second
>>> convert_to(ampere, [meter, gram, second], SI)
>>> convert_to(ampere, [meter, gram, second], cgs_gauss)

Quantities of the same dimension do not get simplified automatically, for example if you divide meters by kilometers, you will get an object representing the division between the two units. In order to simplify this kind of expressions, you can either call the .simplify() method or import the quantity_simplify( ) function, the last one also accepting a unit system as optional parameter.

>>> from sympy.physics.units.util import quantity_simplify
>>> from sympy.physics.units import kilometer
>>> meter/kilometer
>>> (meter/kilometer).simplify()
>>> quantity_simplify(meter/kilometer)


Ideas about future developments can be found on the Github wiki.