Units

Introduction

This module provides around 200 predefined units that are commonly used in the sciences. Additionally, it provides the Unit class which allows you to define your own units.

Examples

All examples in this tutorial are computable, so one can just copy and paste them into a Python shell and do something useful with them. All computations were done using the following setup:

>>> from sympy.physics.units import *

Dimensionless quantities

Provides variables for commonly written dimensionless (unit-less) quantities.

>>> 2*ten
20
>>> 20*percent
1/5
>>> 300*kilo*20*percent
60000
>>> nano*deg
pi/180000000000

Base units

The SI base units are defined variable name that are commonly used in written and verbal communication. The singular abbreviated versions are what is used for display purposes, but the plural non-abbreviated versions are defined in case it helps readability.

>>> 5*meters
5*m
>>> milli*kilogram
kg/1000
>>> gram
kg/1000

Note that British Imperial and U.S. customary units are not included. We strongly urge the use of SI units; only Myanmar (Burma), Liberia, and the United States have not officially accepted the SI system.

Derived units

Common SI derived units.

>>> joule
kg*m**2/s**2

Docstring

Physical units and dimensions.

The base class is Unit, where all here defined units (~200) inherit from.

The find_unit function can help you find units for a given quantity:

>>> import sympy.physics.units as u
>>> u.find_unit('coul')
['coulomb', 'coulombs']
>>> u.find_unit(u.charge)
['C', 'charge', 'coulomb', 'coulombs']
>>> u.coulomb
A*s

Units are always given in terms of base units that have a name and an abbreviation:

>>> u.A.name
'ampere'
>>> u.ampere.abbrev
'A'

The generic name for a unit (like ‘length’, ‘mass’, etc...) can help you find units:

>>> u.find_unit('magnet')
['magnetic_flux', 'magnetic_constant', 'magnetic_flux_density']
>>> u.find_unit(u.magnetic_flux)
['Wb', 'wb', 'weber', 'webers', 'magnetic_flux']

If, for a given session, you wish to add a unit you may do so:

>>> u.find_unit('gal')
[]
>>> u.gal = 4*u.quart
>>> u.gal/u.inch**3
231

To see a given quantity in terms of some other unit, divide by the desired unit:

>>> mph = u.miles/u.hours
>>> (u.m/u.s/mph).n(2)
2.2

The units are defined in terms of base units, so when you divide similar units you will obtain a pure number. This means, for example, that if you divide a real-world mass (like grams) by the atomic mass unit (amu) you will obtain Avogadro’s number. To obtain the answer in moles you should divide by the unit avogadro:

>>> u.grams/u.amu
602214179000000000000000
>>> _/u.avogadro
mol

For chemical calculations the unit mmu (molar mass unit) has been defined so this conversion is handled automatically. For example, the number of moles in 1 kg of water might be calculated as:

>>> u.kg/(18*u.mmu).n(3)
55.5*mol

If you need the number of atoms in a mol as a pure number you can use avogadro_number but if you need it as a dimensional quantity you should use avogadro_constant. (avogadro is a shorthand for the dimensional quantity.)

>>> u.avogadro_number
602214179000000000000000
>>> u.avogadro_constant
602214179000000000000000/mol

class sympy.physics.units.Unit

Base class for base unit of physical units.

>>> from sympy.physics.units import Unit
>>> Unit("meter", "m")
m

Other units are derived from base units:

>>> import sympy.physics.units as u
>>> cm = u.m/100
>>> 100*u.cm
m

sympy.physics.units.find_unit(quantity)

Return a list of matching units names. if quantity is a string – units containing the string \(quantity\) if quantity is a unit – units having matching base units

Examples

>>> from sympy.physics import units as u
>>> u.find_unit('charge')
['charge']
>>> u.find_unit(u.charge)
['C', 'charge', 'coulomb', 'coulombs']
>>> u.find_unit('volt')
['volt', 'volts', 'voltage']
>>> u.find_unit(u.inch**3)[:5]
['l', 'cl', 'dl', 'ml', 'liter']