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
This unit acts exactly like a symbolic variable:
sage: s = units.length.meter
sage: s^2
meter^2
sage: s + var('x')
meter + x
Units have additional information in their docstring:
sage: # You would type: units.force.dyne?
sage: print units.force.dyne._sage_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
Calling the convert function with no target returns base SI units:
sage: t.convert()
1/100000*kilogram*meter/second^2
Giving improper units to convert to raises a ValueError:
sage: t.convert(units.charge.coulomb)
...
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
Trying to multiply temperatures by another unit then converting raises a ValueError:
sage: wrong = 50*units.temperature.celsius*units.length.foot
sage: wrong.convert()
...
ValueError: Cannot convert
AUTHORS:
- David Ackerman
- William Stein
Bases: sage.symbolic.expression.Expression
A symbolic unit.
EXAMPLES:
sage: acre = units.area.acre
sage: type(acre)
<class 'sage.symbolic.units.UnitExpression'>
TESTS:
sage: bool(loads(dumps(acre)) == acre)
True
sage: type(loads(dumps(acre)))
<class 'sage.symbolic.units.UnitExpression'>
A collection of units of a some type.
EXAMPLES:
sage: units.power Collection of units of power: cheval_vapeur horsepower watt
Return completions of this unit objects. This is used by the Sage command line and notebook to create the list of method names.
EXAMPLES:
sage: units.area.trait_names()
['acre', 'are', 'barn', 'hectare', 'rood', 'section', 'square_chain', 'square_meter', 'township']
Converts unit to base SI units.
INPUT:
- unit
OUTPUT:
EXAMPLES:
sage: 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
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
Returns variable if ‘unit’ is not a unit:
sage: sage.symbolic.units.base_units(var('x'))
x
Converts units between expr and target. If target is None then converts to SI base units.
INPUT:
- – the symbolic expression converting from
- – (default None) the symbolic expression converting to
OUTPUT:
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
Raises ValueError if expr and target are not convertible:
sage: sage.symbolic.units.convert(units.mass.kilogram, units.length.foot)
...
ValueError: Incompatible units
sage: sage.symbolic.units.convert(units.length.meter^2, units.length.foot)
...
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
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
Function for converting between temperatures.
INPUT:
- – a unit of temperature
- – a units of temperature
OUTPUT:
EXAMPLES:
sage: t = 32*units.temperature.fahrenheit
sage: t.convert(units.temperature.celsius)
0
sage: t.convert(units.temperature.kelvin)
273.150000000000*kelvin
If target is None then it defaults to kelvin:
sage: t.convert()
273.150000000000*kelvin
Raises ValueError when either input is not a unit of temperature:
sage: t.convert(units.length.foot)
...
ValueError: Cannot convert
sage: wrong = units.length.meter*units.temperature.fahrenheit
sage: wrong.convert()
...
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
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()
Returns a boolean when asked whether the input is in the list of units.
INPUT:
- – an object
OUTPUT:
- bool
EXAMPLES:
sage: sage.symbolic.units.is_unit(1)
False
sage: 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
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
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:
- 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'>
Given derived units name, returns the corresponding units expression. For example, given ‘acceleration’ output the symbolic expression length/time^2.
INPUT:
- – string, name of a unit type such as ‘area’, ‘volume’, etc.
OUTPUT:
- 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)
If the unit name is unknown, a KeyError is raised:
sage: sage.symbolic.units.unit_derivations_expr('invalid')
...
KeyError: 'invalid'
Returns docstring for the given unit.
INPUT:
- 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.'
Units not in the list unit_docs will raise a ValueError:
sage: sage.symbolic.units.unitdocs('earth')
...
ValueError: No documentation exists for the unit earth.
Given a string like ‘mass/(length*time)’, return the list [‘mass’, ‘length’, ‘time’].
INPUT:
- – string
OUTPUT:
- list of strings (unit names)
EXAMPLES:
sage: sage.symbolic.units.vars_in_str('mass/(length*time)')
['mass', 'length', 'time']