Units of measurement¶

This is the units package. It contains information about many units and conversions between them.

TUTORIAL:

To return a unit:

Sage

sage: units.length.meter
meter

Python

>>> from sage.all import *
>>> units.length.meter
meter

Sage Live

units.length.meter

This unit acts exactly like a symbolic variable:

Sage

sage: s = units.length.meter
sage: s^2
meter^2
sage: s + var('x')
meter + x

Python

>>> from sage.all import *
>>> s = units.length.meter
>>> s**Integer(2)
meter^2
>>> s + var('x')
meter + x

Sage Live

s = units.length.meter
s^2
s + var('x')

Units have additional information in their docstring:

Sage

sage: # You would type: units.force.dyne?
sage: print(units.force.dyne.__doc__)
CGS unit for force defined to be gram*centimeter/second^2.
Equal to 10^-5 newtons.

Python

>>> from sage.all import *
>>> # You would type: units.force.dyne?
>>> print(units.force.dyne.__doc__)
CGS unit for force defined to be gram*centimeter/second^2.
Equal to 10^-5 newtons.

Sage Live

# You would type: units.force.dyne?
print(units.force.dyne.__doc__)

You may call the convert function with units:

Sage

sage: t = units.mass.gram*units.length.centimeter/units.time.second^2
sage: t.convert(units.mass.pound*units.length.foot/units.time.hour^2)
5400000000000/5760623099*(foot*pound/hour^2)
sage: t.convert(units.force.newton)
1/100000*newton

Python

>>> from sage.all import *
>>> t = units.mass.gram*units.length.centimeter/units.time.second**Integer(2)
>>> t.convert(units.mass.pound*units.length.foot/units.time.hour**Integer(2))
5400000000000/5760623099*(foot*pound/hour^2)
>>> t.convert(units.force.newton)
1/100000*newton

Sage Live

t = units.mass.gram*units.length.centimeter/units.time.second^2
t.convert(units.mass.pound*units.length.foot/units.time.hour^2)
t.convert(units.force.newton)

Calling the convert function with no target returns base SI units:

Sage

sage: t.convert()
1/100000*kilogram*meter/second^2

Python

>>> from sage.all import *
>>> t.convert()
1/100000*kilogram*meter/second^2

Sage Live

t.convert()

Giving improper units to convert to raises a ValueError:

Sage

sage: t.convert(units.charge.coulomb)
Traceback (most recent call last):
...
ValueError: Incompatible units

Python

>>> from sage.all import *
>>> t.convert(units.charge.coulomb)
Traceback (most recent call last):
...
ValueError: Incompatible units

Sage Live

t.convert(units.charge.coulomb)

Converting temperatures works as well:

Sage

sage: s = 68*units.temperature.fahrenheit
sage: s.convert(units.temperature.celsius)
20*celsius
sage: s.convert()
293.150000000000*kelvin

Python

>>> from sage.all import *
>>> s = Integer(68)*units.temperature.fahrenheit
>>> s.convert(units.temperature.celsius)
20*celsius
>>> s.convert()
293.150000000000*kelvin

Sage Live

s = 68*units.temperature.fahrenheit
s.convert(units.temperature.celsius)
s.convert()

Trying to multiply temperatures by another unit then converting raises a ValueError:

Sage

sage: wrong = 50*units.temperature.celsius*units.length.foot
sage: wrong.convert()
Traceback (most recent call last):
...
ValueError: cannot convert

Python

>>> from sage.all import *
>>> wrong = Integer(50)*units.temperature.celsius*units.length.foot
>>> wrong.convert()
Traceback (most recent call last):
...
ValueError: cannot convert

Sage Live

wrong = 50*units.temperature.celsius*units.length.foot
wrong.convert()

AUTHORS:

David Ackerman
William Stein

class sage.symbolic.units.UnitExpression[source]¶

Bases: Expression

A symbolic unit.

EXAMPLES:

Sage

sage: acre = units.area.acre
sage: type(acre)
<class 'sage.symbolic.units.UnitExpression'>

Python

>>> from sage.all import *
>>> acre = units.area.acre
>>> type(acre)
<class 'sage.symbolic.units.UnitExpression'>

Sage Live

acre = units.area.acre
type(acre)

class sage.symbolic.units.Units(data, name='')[source]¶

Bases: ExtraTabCompletion

A collection of units of some type.

EXAMPLES:

Sage

sage: units.power
Collection of units of power: cheval_vapeur horsepower watt

Python

>>> from sage.all import *
>>> units.power
Collection of units of power: cheval_vapeur horsepower watt

Sage Live

units.power

sage.symbolic.units.base_units(unit)[source]¶

Convert unit to base SI units.

INPUT:

unit – a unit

OUTPUT: a symbolic expression

EXAMPLES:

Sage

sage: sage.symbolic.units.base_units(units.length.foot)
381/1250*meter

Python

>>> from sage.all import *
>>> sage.symbolic.units.base_units(units.length.foot)
381/1250*meter

Sage Live

sage.symbolic.units.base_units(units.length.foot)

If unit is already a base unit, it just returns that unit:

Sage

sage: sage.symbolic.units.base_units(units.length.meter)
meter

Python

>>> from sage.all import *
>>> sage.symbolic.units.base_units(units.length.meter)
meter

Sage Live

sage.symbolic.units.base_units(units.length.meter)

Derived units get broken down into their base parts:

Sage

sage: sage.symbolic.units.base_units(units.force.newton)
kilogram*meter/second^2
sage: sage.symbolic.units.base_units(units.volume.liter)
1/1000*meter^3

Python

>>> from sage.all import *
>>> sage.symbolic.units.base_units(units.force.newton)
kilogram*meter/second^2
>>> sage.symbolic.units.base_units(units.volume.liter)
1/1000*meter^3

Sage Live

sage.symbolic.units.base_units(units.force.newton)
sage.symbolic.units.base_units(units.volume.liter)

Returns variable if unit is not a unit:

Sage

sage: sage.symbolic.units.base_units(var('x'))
x

Python

>>> from sage.all import *
>>> sage.symbolic.units.base_units(var('x'))
x

Sage Live

sage.symbolic.units.base_units(var('x'))

sage.symbolic.units.convert(expr, target)[source]¶

Convert units between expr and target. If target is None then converts to SI base units.

INPUT:

expr – the symbolic expression converting from
target – (default: None) the symbolic expression converting to

OUTPUT: a symbolic expression

EXAMPLES:

Sage

sage: sage.symbolic.units.convert(units.length.foot, None)
381/1250*meter
sage: sage.symbolic.units.convert(units.mass.kilogram, units.mass.pound)
100000000/45359237*pound

Python

>>> from sage.all import *
>>> sage.symbolic.units.convert(units.length.foot, None)
381/1250*meter
>>> sage.symbolic.units.convert(units.mass.kilogram, units.mass.pound)
100000000/45359237*pound

Sage Live

sage.symbolic.units.convert(units.length.foot, None)
sage.symbolic.units.convert(units.mass.kilogram, units.mass.pound)

This raises ValueError if expr and target are not convertible:

Sage

sage: sage.symbolic.units.convert(units.mass.kilogram, units.length.foot)
Traceback (most recent call last):
...
ValueError: Incompatible units
sage: sage.symbolic.units.convert(units.length.meter^2, units.length.foot)
Traceback (most recent call last):
...
ValueError: Incompatible units

Python

>>> from sage.all import *
>>> sage.symbolic.units.convert(units.mass.kilogram, units.length.foot)
Traceback (most recent call last):
...
ValueError: Incompatible units
>>> sage.symbolic.units.convert(units.length.meter**Integer(2), units.length.foot)
Traceback (most recent call last):
...
ValueError: Incompatible units

Sage Live

sage.symbolic.units.convert(units.mass.kilogram, units.length.foot)
sage.symbolic.units.convert(units.length.meter^2, units.length.foot)

Recognizes derived unit relationships to base units and other derived units:

Sage

sage: sage.symbolic.units.convert(units.length.foot/units.time.second^2, units.acceleration.galileo)
762/25*galileo
sage: sage.symbolic.units.convert(units.mass.kilogram*units.length.meter/units.time.second^2, units.force.newton)
newton
sage: sage.symbolic.units.convert(units.length.foot^3, units.area.acre*units.length.inch)
1/3630*(acre*inch)
sage: sage.symbolic.units.convert(units.charge.coulomb, units.current.ampere*units.time.second)
(ampere*second)
sage: sage.symbolic.units.convert(units.pressure.pascal*units.si_prefixes.kilo, units.pressure.pounds_per_square_inch)
1290320000000/8896443230521*pounds_per_square_inch

Python

>>> from sage.all import *
>>> sage.symbolic.units.convert(units.length.foot/units.time.second**Integer(2), units.acceleration.galileo)
762/25*galileo
>>> sage.symbolic.units.convert(units.mass.kilogram*units.length.meter/units.time.second**Integer(2), units.force.newton)
newton
>>> sage.symbolic.units.convert(units.length.foot**Integer(3), units.area.acre*units.length.inch)
1/3630*(acre*inch)
>>> sage.symbolic.units.convert(units.charge.coulomb, units.current.ampere*units.time.second)
(ampere*second)
>>> sage.symbolic.units.convert(units.pressure.pascal*units.si_prefixes.kilo, units.pressure.pounds_per_square_inch)
1290320000000/8896443230521*pounds_per_square_inch

Sage Live

sage.symbolic.units.convert(units.length.foot/units.time.second^2, units.acceleration.galileo)
sage.symbolic.units.convert(units.mass.kilogram*units.length.meter/units.time.second^2, units.force.newton)
sage.symbolic.units.convert(units.length.foot^3, units.area.acre*units.length.inch)
sage.symbolic.units.convert(units.charge.coulomb, units.current.ampere*units.time.second)
sage.symbolic.units.convert(units.pressure.pascal*units.si_prefixes.kilo, units.pressure.pounds_per_square_inch)

For decimal answers multiply 1.0:

Sage

sage: sage.symbolic.units.convert(units.pressure.pascal*units.si_prefixes.kilo, units.pressure.pounds_per_square_inch)*1.0
0.145037737730209*pounds_per_square_inch

Python

>>> from sage.all import *
>>> sage.symbolic.units.convert(units.pressure.pascal*units.si_prefixes.kilo, units.pressure.pounds_per_square_inch)*RealNumber('1.0')
0.145037737730209*pounds_per_square_inch

Sage Live

sage.symbolic.units.convert(units.pressure.pascal*units.si_prefixes.kilo, units.pressure.pounds_per_square_inch)*1.0

You can also convert quantities of units:

Sage

sage: sage.symbolic.units.convert(cos(50) * units.angles.radian, units.angles.degree)
degree*(180*cos(50)/pi)
sage: sage.symbolic.units.convert(cos(30) * units.angles.radian, units.angles.degree).polynomial(RR)
8.83795706233228*degree
sage: sage.symbolic.units.convert(50 * units.length.light_year / units.time.year, units.length.foot / units.time.second)
6249954068750/127*(foot/second)

Python

>>> from sage.all import *
>>> sage.symbolic.units.convert(cos(Integer(50)) * units.angles.radian, units.angles.degree)
degree*(180*cos(50)/pi)
>>> sage.symbolic.units.convert(cos(Integer(30)) * units.angles.radian, units.angles.degree).polynomial(RR)
8.83795706233228*degree
>>> sage.symbolic.units.convert(Integer(50) * units.length.light_year / units.time.year, units.length.foot / units.time.second)
6249954068750/127*(foot/second)

Sage Live

sage.symbolic.units.convert(cos(50) * units.angles.radian, units.angles.degree)
sage.symbolic.units.convert(cos(30) * units.angles.radian, units.angles.degree).polynomial(RR)
sage.symbolic.units.convert(50 * units.length.light_year / units.time.year, units.length.foot / units.time.second)

Quantities may contain variables (not for temperature conversion, though):

Sage

sage: sage.symbolic.units.convert(50 * x * units.area.square_meter, units.area.acre)
acre*(1953125/158080329*x)

Python

>>> from sage.all import *
>>> sage.symbolic.units.convert(Integer(50) * x * units.area.square_meter, units.area.acre)
acre*(1953125/158080329*x)

Sage Live

sage.symbolic.units.convert(50 * x * units.area.square_meter, units.area.acre)

sage.symbolic.units.convert_temperature(expr, target)[source]¶

Function for converting between temperatures.

INPUT:

expr – a unit of temperature
target – a units of temperature

OUTPUT: a symbolic expression

EXAMPLES:

Sage

sage: t = 32*units.temperature.fahrenheit
sage: t.convert(units.temperature.celsius)
0
sage: t.convert(units.temperature.kelvin)
273.150000000000*kelvin

Python

>>> from sage.all import *
>>> t = Integer(32)*units.temperature.fahrenheit
>>> t.convert(units.temperature.celsius)
0
>>> t.convert(units.temperature.kelvin)
273.150000000000*kelvin

Sage Live

t = 32*units.temperature.fahrenheit
t.convert(units.temperature.celsius)
t.convert(units.temperature.kelvin)

If target is None then it defaults to kelvin:

Sage

sage: t.convert()
273.150000000000*kelvin

Python

>>> from sage.all import *
>>> t.convert()
273.150000000000*kelvin

Sage Live

t.convert()

This raises ValueError when either input is not a unit of temperature:

Sage

sage: t.convert(units.length.foot)
Traceback (most recent call last):
...
ValueError: cannot convert
sage: wrong = units.length.meter*units.temperature.fahrenheit
sage: wrong.convert()
Traceback (most recent call last):
...
ValueError: cannot convert

Python

>>> from sage.all import *
>>> t.convert(units.length.foot)
Traceback (most recent call last):
...
ValueError: cannot convert
>>> wrong = units.length.meter*units.temperature.fahrenheit
>>> wrong.convert()
Traceback (most recent call last):
...
ValueError: cannot convert

Sage Live

t.convert(units.length.foot)
wrong = units.length.meter*units.temperature.fahrenheit
wrong.convert()

We directly call the convert_temperature function:

Sage

sage: sage.symbolic.units.convert_temperature(37*units.temperature.celsius, units.temperature.fahrenheit)
493/5*fahrenheit
sage: 493/5.0
98.6000000000000

Python

>>> from sage.all import *
>>> sage.symbolic.units.convert_temperature(Integer(37)*units.temperature.celsius, units.temperature.fahrenheit)
493/5*fahrenheit
>>> Integer(493)/RealNumber('5.0')
98.6000000000000

Sage Live

sage.symbolic.units.convert_temperature(37*units.temperature.celsius, units.temperature.fahrenheit)
493/5.0

sage.symbolic.units.evalunitdict()[source]¶

Replace all the string values of the unitdict variable by their evaluated forms, and builds some other tables for ease of use. This function is mainly used internally, for efficiency (and flexibility) purposes, making it easier to describe the units.

EXAMPLES:

Sage

sage: sage.symbolic.units.evalunitdict()

Python

>>> from sage.all import *
>>> sage.symbolic.units.evalunitdict()

Sage Live

sage.symbolic.units.evalunitdict()

sage.symbolic.units.is_unit(s)[source]¶

Return a boolean when asked whether the input is in the list of units.

INPUT:

s – an object

OUTPUT: boolean

EXAMPLES:

Sage

sage: sage.symbolic.units.is_unit(1)
False
sage: sage.symbolic.units.is_unit(units.length.meter)
True

Python

>>> from sage.all import *
>>> sage.symbolic.units.is_unit(Integer(1))
False
>>> sage.symbolic.units.is_unit(units.length.meter)
True

Sage Live

sage.symbolic.units.is_unit(1)
sage.symbolic.units.is_unit(units.length.meter)

The square of a unit is not a unit:

Sage

sage: sage.symbolic.units.is_unit(units.length.meter^2)
False

Python

>>> from sage.all import *
>>> sage.symbolic.units.is_unit(units.length.meter**Integer(2))
False

Sage Live

sage.symbolic.units.is_unit(units.length.meter^2)

You can also directly create units using var, though they won’t have a nice docstring describing the unit:

Sage

sage: sage.symbolic.units.is_unit(var('meter'))
True

Python

>>> from sage.all import *
>>> sage.symbolic.units.is_unit(var('meter'))
True

Sage Live

sage.symbolic.units.is_unit(var('meter'))

sage.symbolic.units.str_to_unit(name)[source]¶

Create the symbolic unit with given name. A symbolic unit is a class that derives from symbolic expression, and has a specialized docstring.

INPUT:

name – string

OUTPUT: a UnitExpression

EXAMPLES:

Sage

sage: sage.symbolic.units.str_to_unit('acre')
acre
sage: type(sage.symbolic.units.str_to_unit('acre'))
<class 'sage.symbolic.units.UnitExpression'>

Python

>>> from sage.all import *
>>> sage.symbolic.units.str_to_unit('acre')
acre
>>> type(sage.symbolic.units.str_to_unit('acre'))
<class 'sage.symbolic.units.UnitExpression'>

Sage Live

sage.symbolic.units.str_to_unit('acre')
type(sage.symbolic.units.str_to_unit('acre'))

sage.symbolic.units.unit_derivations_expr(v)[source]¶

Given derived units name, returns the corresponding units expression.

For example, given 'acceleration' output the symbolic expression length/time^2.

INPUT:

v – string; name of a unit type such as 'area', 'volume', etc.

OUTPUT: a symbolic expression

EXAMPLES:

Sage

sage: sage.symbolic.units.unit_derivations_expr('volume')
length^3
sage: sage.symbolic.units.unit_derivations_expr('electric_potential')
length^2*mass/(current*time^3)

Python

>>> from sage.all import *
>>> sage.symbolic.units.unit_derivations_expr('volume')
length^3
>>> sage.symbolic.units.unit_derivations_expr('electric_potential')
length^2*mass/(current*time^3)

Sage Live

sage.symbolic.units.unit_derivations_expr('volume')
sage.symbolic.units.unit_derivations_expr('electric_potential')

If the unit name is unknown, a KeyError is raised:

Sage

sage: sage.symbolic.units.unit_derivations_expr('invalid')
Traceback (most recent call last):
...
KeyError: 'invalid'

Python

>>> from sage.all import *
>>> sage.symbolic.units.unit_derivations_expr('invalid')
Traceback (most recent call last):
...
KeyError: 'invalid'

Sage Live

sage.symbolic.units.unit_derivations_expr('invalid')

sage.symbolic.units.unitdocs(unit)[source]¶

Return docstring for the given unit.

INPUT:

unit – a unit

OUTPUT: string

EXAMPLES:

Sage

sage: sage.symbolic.units.unitdocs('meter')
'SI base unit of length.\nDefined to be the distance light travels in vacuum in 1/299792458 of a second.'
sage: sage.symbolic.units.unitdocs('amu')
'Abbreviation for atomic mass unit.\nApproximately equal to 1.660538782*10^-27 kilograms.'

Python

>>> from sage.all import *
>>> sage.symbolic.units.unitdocs('meter')
'SI base unit of length.\nDefined to be the distance light travels in vacuum in 1/299792458 of a second.'
>>> sage.symbolic.units.unitdocs('amu')
'Abbreviation for atomic mass unit.\nApproximately equal to 1.660538782*10^-27 kilograms.'

Sage Live

sage.symbolic.units.unitdocs('meter')
sage.symbolic.units.unitdocs('amu')

Units not in the list unit_docs will raise a ValueError:

Sage

sage: sage.symbolic.units.unitdocs('earth')
Traceback (most recent call last):
...
ValueError: no documentation exists for the unit earth

Python

>>> from sage.all import *
>>> sage.symbolic.units.unitdocs('earth')
Traceback (most recent call last):
...
ValueError: no documentation exists for the unit earth

Sage Live

sage.symbolic.units.unitdocs('earth')

sage.symbolic.units.vars_in_str(s)[source]¶

Given a string like 'mass/(length*time)', return the list ['mass', 'length', 'time'].

INPUT:

s – string

OUTPUT: list of strings (unit names)

EXAMPLES:

Sage

sage: sage.symbolic.units.vars_in_str('mass/(length*time)')
['mass', 'length', 'time']

Python

>>> from sage.all import *
>>> sage.symbolic.units.vars_in_str('mass/(length*time)')
['mass', 'length', 'time']

Sage Live

sage.symbolic.units.vars_in_str('mass/(length*time)')