Units of measurement¶
This is the units package. It contains information about many units and conversions between them.
TUTORIAL:
To return a unit:
sage: units.length.meter
meter
>>> from sage.all import *
>>> units.length.meter
meter
This unit acts exactly like a symbolic variable:
sage: s = units.length.meter
sage: s^2
meter^2
sage: s + var('x')
meter + x
>>> from sage.all import *
>>> s = units.length.meter
>>> s**Integer(2)
meter^2
>>> s + var('x')
meter + x
Units have additional information in their docstring:
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.
>>> 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.
You may call the convert function with units:
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
>>> 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
Calling the convert function with no target returns base SI units:
sage: t.convert()
1/100000*kilogram*meter/second^2
>>> from sage.all import *
>>> t.convert()
1/100000*kilogram*meter/second^2
Giving improper units to convert to raises a ValueError:
sage: t.convert(units.charge.coulomb)
Traceback (most recent call last):
...
ValueError: Incompatible units
>>> from sage.all import *
>>> t.convert(units.charge.coulomb)
Traceback (most recent call last):
...
ValueError: Incompatible units
Converting temperatures works as well:
sage: s = 68*units.temperature.fahrenheit
sage: s.convert(units.temperature.celsius)
20*celsius
sage: s.convert()
293.150000000000*kelvin
>>> from sage.all import *
>>> s = Integer(68)*units.temperature.fahrenheit
>>> s.convert(units.temperature.celsius)
20*celsius
>>> s.convert()
293.150000000000*kelvin
Trying to multiply temperatures by another unit then converting raises a ValueError:
sage: wrong = 50*units.temperature.celsius*units.length.foot
sage: wrong.convert()
Traceback (most recent call last):
...
ValueError: cannot convert
>>> from sage.all import *
>>> wrong = Integer(50)*units.temperature.celsius*units.length.foot
>>> wrong.convert()
Traceback (most recent call last):
...
ValueError: cannot convert
AUTHORS:
- David Ackerman 
- William Stein 
- class sage.symbolic.units.UnitExpression[source]¶
- Bases: - Expression- A symbolic unit. - EXAMPLES: - sage: acre = units.area.acre sage: type(acre) <class 'sage.symbolic.units.UnitExpression'> - >>> from sage.all import * >>> acre = units.area.acre >>> type(acre) <class 'sage.symbolic.units.UnitExpression'> 
- class sage.symbolic.units.Units(data, name='')[source]¶
- Bases: - ExtraTabCompletion- A collection of units of some type. - EXAMPLES: - sage: units.power Collection of units of power: cheval_vapeur horsepower watt - >>> from sage.all import * >>> units.power Collection of units of power: cheval_vapeur horsepower watt 
- sage.symbolic.units.base_units(unit)[source]¶
- Convert unit to base SI units. - INPUT: - unit– a unit
 - OUTPUT: a symbolic expression - EXAMPLES: - sage: sage.symbolic.units.base_units(units.length.foot) 381/1250*meter - >>> from sage.all import * >>> sage.symbolic.units.base_units(units.length.foot) 381/1250*meter - If unit is already a base unit, it just returns that unit: - sage: sage.symbolic.units.base_units(units.length.meter) meter - >>> from sage.all import * >>> sage.symbolic.units.base_units(units.length.meter) meter - Derived units get broken down into their base parts: - 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 - >>> 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 - Returns variable if - unitis not a unit:- sage: sage.symbolic.units.base_units(var('x')) x - >>> from sage.all import * >>> sage.symbolic.units.base_units(var('x')) x 
- sage.symbolic.units.convert(expr, target)[source]¶
- Convert units between - exprand- target. If- targetis- Nonethen 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.symbolic.units.convert(units.length.foot, None) 381/1250*meter sage: sage.symbolic.units.convert(units.mass.kilogram, units.mass.pound) 100000000/45359237*pound - >>> 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 - This raises - ValueErrorif expr and target are not convertible:- 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 - >>> 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 - Recognizes derived unit relationships to base units and other derived units: - 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 - >>> 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 - For decimal answers multiply 1.0: - 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 - >>> 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 - You can also convert quantities of units: - 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) - >>> 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) - Quantities may contain variables (not for temperature conversion, though): - sage: sage.symbolic.units.convert(50 * x * units.area.square_meter, units.area.acre) acre*(1953125/158080329*x) - >>> from sage.all import * >>> sage.symbolic.units.convert(Integer(50) * x * units.area.square_meter, units.area.acre) acre*(1953125/158080329*x) 
- 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: t = 32*units.temperature.fahrenheit sage: t.convert(units.temperature.celsius) 0 sage: t.convert(units.temperature.kelvin) 273.150000000000*kelvin - >>> from sage.all import * >>> t = Integer(32)*units.temperature.fahrenheit >>> t.convert(units.temperature.celsius) 0 >>> t.convert(units.temperature.kelvin) 273.150000000000*kelvin - If target is - Nonethen it defaults to kelvin:- sage: t.convert() 273.150000000000*kelvin - >>> from sage.all import * >>> t.convert() 273.150000000000*kelvin - This raises - ValueErrorwhen either input is not a unit of temperature:- 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 - >>> 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 - We directly call the convert_temperature function: - sage: sage.symbolic.units.convert_temperature(37*units.temperature.celsius, units.temperature.fahrenheit) 493/5*fahrenheit sage: 493/5.0 98.6000000000000 - >>> 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.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.symbolic.units.evalunitdict() - >>> from sage.all import * >>> 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.symbolic.units.is_unit(1) False sage: sage.symbolic.units.is_unit(units.length.meter) True - >>> from sage.all import * >>> sage.symbolic.units.is_unit(Integer(1)) False >>> sage.symbolic.units.is_unit(units.length.meter) True - The square of a unit is not a unit: - sage: sage.symbolic.units.is_unit(units.length.meter^2) False - >>> from sage.all import * >>> sage.symbolic.units.is_unit(units.length.meter**Integer(2)) False - You can also directly create units using var, though they won’t have a nice docstring describing the unit: - sage: sage.symbolic.units.is_unit(var('meter')) True - >>> from sage.all import * >>> sage.symbolic.units.is_unit(var('meter')) True 
- 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.symbolic.units.str_to_unit('acre') acre sage: type(sage.symbolic.units.str_to_unit('acre')) <class 'sage.symbolic.units.UnitExpression'> - >>> 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.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.symbolic.units.unit_derivations_expr('volume') length^3 sage: sage.symbolic.units.unit_derivations_expr('electric_potential') length^2*mass/(current*time^3) - >>> 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) - If the unit name is unknown, a - KeyErroris raised:- sage: sage.symbolic.units.unit_derivations_expr('invalid') Traceback (most recent call last): ... KeyError: 'invalid' - >>> from sage.all import * >>> sage.symbolic.units.unit_derivations_expr('invalid') Traceback (most recent call last): ... KeyError: 'invalid' 
- sage.symbolic.units.unitdocs(unit)[source]¶
- Return docstring for the given unit. - INPUT: - unit– a unit
 - OUTPUT: string - EXAMPLES: - 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.' - >>> 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.' - Units not in the list unit_docs will raise a - ValueError:- sage: sage.symbolic.units.unitdocs('earth') Traceback (most recent call last): ... ValueError: no documentation exists for the unit earth - >>> from sage.all import * >>> sage.symbolic.units.unitdocs('earth') Traceback (most recent call last): ... ValueError: no documentation exists for the unit 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.symbolic.units.vars_in_str('mass/(length*time)') ['mass', 'length', 'time'] - >>> from sage.all import * >>> sage.symbolic.units.vars_in_str('mass/(length*time)') ['mass', 'length', 'time']