Basic classes and functions for dimensional computation

This module contains the class definitions of
and the functions
The following fundamental units are defined:
metre, meter, kilogram, second, amp, ampere, kelvin, mole, candela.
And these named derived units:
radian, steradian, hertz, newton, pascal, joule, watt, coulomb, volt, farad, ohm, siemens, weber, tesla, henry, celsius, lumen, lux, becquerel, gray, sievert, katal

Non-SI units, such as mile, foot etc. can be found in the module additional_units, along with some physical constants. For the names of all pre-defined units see Quantity.all_unit_names at runtime.

NOTES:

This module, along with additional_units and quantity_parser can be used outside Sage, but some functionality will not be available then. In particular, trigonometric and exponential functions won’t work and it will not be possible to set a BaseUnitSet.

Warning

Be aware that temperature conversions only work for temperature intervals.

AUTHORS:

  • Dan Goodman (2008): initial version, as module units in the piquant package; see http://sourceforge.net/projects/piquant/
  • David Bate (2008): modifications, added Flydims
  • Miriam Backens (2009): removed Unit class, added BaseUnitSet, LaTeX formatting, support for mathematical functions, various things to do with Sage, extended documentation

EXAMPLES:

To use the Quantity class, define new quantities in terms of existing ones:

sage: from sage.dimpy import *

sage: v = 5 * meter / second
sage: t = 7 * second
sage: v * t
35 m

sage: V = 3 * volt
sage: I = 2 * amp
sage: V/I
1.5 ohm

Use the in_unit() method or the operator % to display quantities in other units:

sage: R = 2 * ohm
sage: (I*R).in_unit('mV')
4000.0 mV
sage: 50 * kilometer % mile
31.0685596119 mi

Quantities can only be added or subtracted if they have the same dimensions; attempts to do dimensionally invalid operations will cause DimensionMismatchError:

sage: 3 * minute + 2 * second
3.03333333333 min
sage: 3 * minute + 2 * kilogram
...
DimensionMismatchError: Addition, dimensions were (s, ) (kg, )

It is possible to use quantities in mathematical functions such as exp, log and trigonometric functions, but only if the Quantity in question is dimensionless:

sage: exp(-2 * eV / (k * 0.4 * kelvin))
1.36855127326495e-25199
sage: sin(0.5 * pi * radian)
1.00000000000000
sage: arctan(4 * joule)
...
DimensionMismatchError: Argument of 'arctan' must be dimensionless, dimensions were (m^2 kg s^-2, )

All classes defined in this module have _latex_() methods which return a string representation of the object for use in LaTeX. Various class attributes of Quantity can be used to modify the way in which Quantities are typeset (see documentation for Quantity).

sage: (42*meter/second)._latex_()
'42 \, \mathrm{m} \, \mathrm{s}^{-1}'
class sage.dimpy.quantity.Dimension(*args, **keywords)

Stores the indices of the 7 basic SI unit dimensions (length, mass, etc.).

Initialise Dimension object with a vector or keywords, i.e. call as Dimension(list), Dimension(keywords) or Dimension(dim).

INPUT:
  • list - a list with the exponents of the 7 basic SI units
  • keywords - a sequence of keyword=value pairs where the keywords are names of SI dimensions or the corresponding standard units
  • dim - a dimension object to copy

NOTES:

A general user of DimPy will not need to use this class or its methods.

The 7 SI dimensions are (in order):

Length, Mass, Time, Electric Current, Temperature, Quantity of Substance, Luminosity

and can be referred to either by these names or their SI unit names, e.g. length, metre and m all refer to the same thing here.

A dimensionless dimension (i.e. all exponents are 0) prints as 1.

The arithmetic methods do not check the input types, so unexpected things may happen with the wrong input.

EXAMPLES:

The following are all definitions of the dimensions of force:

sage: a = Dimension(length=1, mass=1, time=-2)
sage: b = Dimension(m=1, kg=1, s=-2)
sage: c = Dimension([1,1,-2,0,0,0,0])
sage: a == b and b == c
True
get_dimension(d)

Return the power of d in self.

INPUT:
  • d - a string, the name of one of the 7 basic units or one of the corresponding standard unit symbols

OUTPUT: an integer, the exponent of d

EXAMPLES:

sage: dim = joule.get_dimensions()
sage: dim.get_dimension('meter')
2
sage: dim.get_dimension('Length') == dim.get_dimension('m')
True
sage: dim.get_dimension('second')
-2
sage: dim.get_dimension('Temperature')
0
is_dimensionless()

Return True if self is dimensionless, i.e. if the powers of all the SI base units are equal to 0.

OUTPUT: a bool

EXAMPLE:

sage: Dimension().is_dimensionless()
True
sage: Dimension(m=1).is_dimensionless()
False
set_dimension(d, value)

Set the power of d in self to value.

INPUT:
  • d - a string, the name of one of the 7 basic units or one of the corresponding standard unit symbols
  • value - an integer, the corresponding exponent

EXAMPLE:

sage: a = Dimension(meter=1)
sage: a
m
sage: a.set_dimension('s', -1)
sage: a
m s^-1
class sage.dimpy.quantity.Flydim(name='')

A unit with virtual dimensions that are created on-the-fly.

Use this to do calculations with dimensions outside the scope of normal physics, e.g. ‘person’, ‘euro’...

INPUT:
  • name - the dimension of the Flydim, if not specified, a dimensionless Flydim will be created

NOTES:

The dictionary self.dims of dimension_name:exponent pairs may be modified directly (see examples).

A dimensionless Flydim will print as the empty string.

If dimension names contain special characters, i.e. ones other than letters, numbers and .+-/(), there may be problems with LaTeX printing.

EXAMPLES:

Define the initial Flydim by a string, for example a has dimension “person = 1”:

sage: a = Flydim('person')
sage: b = Flydim('euro')

Multiplication and division combine the dimensions:

sage: a*b
person euro

Can define an empty Flydim for later use:

sage: c = Flydim()

Can then modify the contents directly:

sage: c.dims['garage'] = 2
sage: print c
garage^2

Can copy Flydims:

sage: c = a.copy()
sage: print c
person

Arithmetic: products of Flydims return Flydims, products with scalars or Quantities return Quantities:

sage: a.invert()
person^-1
sage: b/a
person^-1 euro
sage: a/meter**2
1.0 m^-2 person
sage: a/2
0.5 person
sage: 2/a
2 person^-1
copy()

Return a copy of self.

EXAMPLE:

sage: a = Flydim('orange')
sage: b = a.copy()
sage: a == b
True
sage: a is b
False 
dims
get_dimensions()

Return 1 if this Flydim is dimensionless, otherwise return the Flydim.

This is unlike the string representation which returns the empty string if the Flydim is dimensionless.

EXAMPLES:

sage: Flydim('coconut').get_dimensions()
coconut
sage: Flydim().get_dimensions()
1
invert()

Return the inverse of this Flydim.

Makes a copy of self and multiplies all exponents by -1.

EXAMPLES:

sage: a = Flydim('apple') * Flydim('banana')**2
sage: a.invert()
apple^-1 banana^-2
is_dimensionless()

Return True if this Flydim is dimensionless.

EXAMPLES:

sage: Flydim('coconut').is_dimensionless()
False
sage: Flydim().is_dimensionless()
True
exception sage.dimpy.quantity.DimensionMismatchError

Exception class for attempted operations with inconsistent dimensions.

INPUT:
  • desc - a string description of the type of operation being performed, e.g. ‘Addition’, ‘Multiplication’, etc.
  • dim - the dimensions of the objects involved in the operation, any number of them is possible

NOTES:

Raise as DimensionMismatchError(desc, dim1, dim2,...).

For example, 3*volt + 2*amp raises this exception. The purpose of this class is to help catch errors based on incorrect units. The exception will print a representation of the dimensions of the two inconsistent objects that were operated on. If you want to check for inconsistent units in your code, do something like:

try:
    ...
    your code here
    ...
except DimensionMismatchError, inst:
    ...
    cleanup code here, e.g.
    print "Found dimension mismatch, details:", inst
    ...

EXAMPLE:

sage: 1 * meter + 0 * candela
...
DimensionMismatchError: Addition, dimensions were (m, ) (cd, )
class sage.dimpy.quantity.Quantity(value=1, register=False)

A number with an associated physical dimension and flydim.

NOTES:

For a list of all pre-defined Quantities see Quantity.all_unit_names.

It is not necessary to deal with this class directly. Instead define new quantities using arithmetic and existing quantities. A DimensionMismatchError exception is raised if dimensions are inconsistent.

The most important methods are in_unit() and set_preferred() which allow the user to change the way the quantity prints. The method set_preferred() permanently specifies the units in terms of which the Quantity is printed, whereas in_unit() only changes the units temporarily.

Quantity(value) creates a new dimensionless Quantity with the given numerical value (default 1). For more customizable Quantity creation use Quantity.with_dimensions(). In each case the argument registered=True automatically registers the unit (see also register_new_units() and UnitRegistry)

CLASS ATTRIBUTES:

These can be set directly, for base_unit_set there is also a helper function. Some type checking is done before the values are used.

  • base_unit_set - a BaseUnitSet that can be used to express any physical quantity, or [] to use the SI units as the base set (see documentation for set_base_units() and BaseUnitSet)
  • engineering - whether to use the engineering convention rather than scientific notation in LaTeX output (default: False; the engineering convention uses only powers of 10 with an exponent divisible by 3)
  • imaginary_unit - a string determining what the square root of -1 prints as in LaTeX output (default: ‘i’)
  • precision - an integer, how many decimal places to print in LaTeX output (default: 2)
  • interval - a tuple of two positive numbers, any number outside that range is printed using scientific notation when in LaTeX mode (default: (0.01, 1000) )

NOTES on LaTeX typesetting:

The program automatically makes sure that exponents, indices and all pre-defined variable names print correctly in LaTeX mode.

It assumes that
  • display names will always be put inside a maths environment, so text needs to be enclosed in \mathrm{...} to make it print upright
  • an underscore in a display name always indicates a following index (with the exceptions of e_, h_ and h_bar)
  • indices always come before exponents
  • indices or exponents end at the characters ‘/’, ‘ ‘, ‘(‘ or ‘)’, which are always outside the index/exponent; words end at indices, exponents or one of the above characters

The names e_ and h_ are stripped of their trailing underscores and h_bar is replaced by the proper LaTeX code. ohm is replaced by \Omega and epsilon, mu and sigma are turned into proper Greek letters.

EXAMPLES:

sage: from sage.dimpy import *
sage: g = 9.81 * meter / second**2
sage: t = 2*second
sage: g * t**2 / 2
19.6200000000000 m

sage: Quantity(0.0005)._latex_()
'5.00 \times 10^{-4}'
sage: Quantity.engineering = True
sage: Quantity(0.0005)._latex_()
'500.0 \times 10^{-6}'
sage: Quantity.engineering = False  # go back to default to not break any later doctests
arccos()

Return the arccos of this Quantity if it is dimensionless.

EXAMPLES:

sage: from additional_units import eV
sage: arccos(10**11 * eV / joule)
1.5707963107731313
sage: arccos(0.7 * celsius)
...
DimensionMismatchError: Argument of 'arccos' must be dimensionless, dimensions were (K, )
arccot()

Return the arccot of this Quantity if it is dimensionless.

EXAMPLES:

sage: arccot(metre**3/(4.54609*10**-3*metre**3))
arccot(219.969248299088)
sage: arccot(metre**3)
...
DimensionMismatchError: Argument of 'arccot' must be dimensionless, dimensions were (m^3, )
arccsc()

Return the arccsc of this Quantity if it is dimensionless.

EXAMPLES:

sage: arccsc(kilogram/(0.45359237*kilogram))
arccsc(2.20462262184878)
sage: arccsc(kilogram)
...
DimensionMismatchError: Argument of 'arccsc' must be dimensionless, dimensions were (kg, )
arcsec()

Return the arcsec of this Quantity if it is dimensionless.

EXAMPLES:

sage: from additional_units import hour, minute
sage: arcsec(hour/minute)
1.5541288884268252
sage: arcsec(hour)
...
DimensionMismatchError: Argument of 'arcsec' must be dimensionless, dimensions were (s, )
arcsin()

Return the arcsin of this Quantity if it is dimensionless.

EXAMPLES:

sage: from additional_units import AU
sage: arcsin(10**9 * meter/AU)
0.0066846369056914661
sage: arcsin(AU)
...
DimensionMismatchError: Argument of 'arcsin' must be dimensionless, dimensions were (m, )
arctan()

Return the arctan of this Quantity if it is dimensionless.

EXAMPLES:

sage: from additional_units import usGal, impGal
sage: arctan(usGal/impGal)
0.69434914427813477
sage: arctan(usGal)
...
DimensionMismatchError: Argument of 'arctan' must be dimensionless, dimensions were (m^3, )
cos()

Return the cosine of this Quantity if it is dimensionless.

EXAMPLES:

sage: cos(2 * pi * radian)
1.0
sage: cos(3 * meter)
...
DimensionMismatchError: Argument of 'cos' must be dimensionless, dimensions were (m, )
cot()

Return the cot of this Quantity if it is dimensionless.

EXAMPLES:

sage: cot(1*radian)
cot(1)
sage: cot(4*newton/kilogram)
...
DimensionMismatchError: Argument of 'cot' must be dimensionless, dimensions were (m s^-2, )
csc()

Return the csc of this Quantity if it is dimensionless.

EXAMPLES:

sage: csc(0.5*radian)
2.08582964293349
sage: csc(pi*meter)
...
DimensionMismatchError: Argument of 'csc' must be dimensionless, dimensions were (m, )
exp()

Return the exponential of this Quantity if it is dimensionless.

EXAMPLES:

sage: from additional_units import amu, k
sage: exp(-amu*100*meter**2/second**2 / (k*2*kelvin))
0.99400443494374546
sage: exp(-amu*100*meter/second / (k*2*kelvin))
...
DimensionMismatchError: Argument of 'exp' must be dimensionless, dimensions were (m^-1 s, )
get_dimensions()

Return the physical dimensions of this object.

EXAMPLE:

sage: ohm.get_dimensions()
m^2 kg s^-3 A^-2
get_dispname()

Return the display name of this object.

EXAMPLES:

sage: meter.get_dispname()
'm'
sage: ohm.get_dispname()
'ohm'
get_flydims()

Return the flydims of this object.

EXAMPLE:

sage: ampere.get_flydims()
<BLANKLINE>
sage: (ampere / Flydim('person')).get_flydims()
person^-1
get_preferred()

Return the preferred unit of this object.

EXAMPLE:

sage: meter.get_preferred()
'self'
sage: (3 * kilogram).get_preferred()
''
has_same_dimensions(other)

Test if this object has the same dimensions and Flydims as another.

INPUT:
  • other - any dimensional object

EXAMPLES:

sage: metre.has_same_dimensions(Dimension(m=1))
True
sage: metre.has_same_dimensions(kelvin)
False
in_best_unit(*regs)

Return a copy of the object in the ‘best unit’, do not change the original.

INPUT:

  • *regs - the registries to check, defaults to user unit register, standard unit register, additional unit register in this order

OUTPUT: a Quantity with preferred_unit set to the best unit found

NOTES:

For more information, see the documentation for the UnitRegistry class. Essentially, this looks at the value of the quantity for all ‘known’ matching units and returns the one with the most compactrepresentation. Standard units are built in, but new units can be registered or old ones unregistered.

If no matching unit is found, the object will be printed in terms of the base units specified in Quantity.base_units or the 7 SI base units.

If no preferred unit is specified, the in_unit() function or the print functions automatically look for the best unit. What is different about using in_best_unit() directly is that registries and their order can be specified so that only those will be checked.

EXAMPLE:

Normally joule prints as J because it is a pre-defined unit. Looking for the best unit in all registers finds J, but now the numerical value is printed too. The only suitable unit in the additional unit register is eV.

sage: joule
J
sage: joule.in_best_unit()
1.0 J
sage: joule.in_best_unit(additional_unit_register)
6.24150947961e+18 eV
in_unit(unit, **kwargs)

Representation of the object in unit unit.

INPUT:

OUTPUT: a Quantity with the preferred unit set to unit

NOTES:

Returns a copy of the object with preferred_unit set to unit; does not change the original. The operator % has the same effect.

EXAMPLE:

sage: d = 15 * meter
sage: d
15 m
sage: d.in_unit('cm')
1500.0 cm
sage: d
15 m
sage: d % 'cm'
1500.0 cm
is_dimensionless()

Test whether this is a dimensionless object.

EXAMPLES:

sage: Quantity().is_dimensionless()
True
sage: metre.is_dimensionless()
False
log()

Return the natural logarithm of this Quantity if it is dimensionless.

EXAMPLES:

sage: log(30*0.514444444444*meter/second / (10*meter/second))
0.433944579429169
sage: log(30*meter/second)
...
DimensionMismatchError: Argument of 'log' must be dimensionless, dimensions were (m s^-1, )
sec()

Return the sec of this Quantity if it is dimensionless.

EXAMPLES:

sage: sec(0.4*metre/(1000 * metre))
1.00000008000001
sage: sec(99 * joule)
...
DimensionMismatchError: Argument of 'sec' must be dimensionless, dimensions were (m^2 kg s^-2, )
set_dimensions(*args, **kwargs)

Set the physical dimensions of this object.

For the accepted input see documentation for Dimension.

EXAMPLES:

sage: a = Quantity(2)
sage: a.set_dimensions(m=1)
sage: a
2 m
sage: a.set_dimensions(J=1)
...
KeyError: 'J'
set_dispname(dispname)

Set the display name of this object.

EXAMPLE:

sage: from additional_units import m_J
sage: mass_of_earth = 5.9736 * 10**24 * kilogram
sage: mass_of_earth.set_dispname('m_E')
sage: m_J % mass_of_earth
317.831793223517 m_E
set_flydims(*args, **kwargs)

Set the flydims of this object.

Can be used either with a Flydim or with keywords. See documentation for Flydim.

EXAMPLE:

sage: a = Quantity(2)
sage: a.set_flydims(pineapple=1)
sage: a
2 pineapple
set_preferred(unit, **kwargs)

Set the preferred unit of this object.

INPUT:
  • unit - either a Quantity or one of ‘’, ‘self’, ‘base’ or a parseable string
  • **kwargs - see notes.

NOTES:

The different types of input for unit are:

  • '' - self is printed using the best unit found in the registries (this is the default for new Quantities)
  • 'self' - self is printed using its own dispname, no numerical value is printed (this is useful for Quantities which are primarily used as units, it is the default setting for all pre-defined units)
  • 'base' – self is printed using the base units specified in Quantity.base_unit_set or the SI base units if there is no specified set
  • a Quantity - self is printed in terms of that object. The two Quantities must have the same dimensions.
  • a parseable string - a new quantity object will be created from the results of parsing, the string itself will become the dispname of that object. If any self-defined Quantities or Flydims are used in the string, the corresponding objects have to be made known to the function as keyword arguments of the form name_used_in_string=name_of_quantity. See also documentation for quantity_parser.set_preferred_product()

EXAMPLES:

There is no pre-defined unit for velocity, so a velocity is printed in terms of the base units unless otherwise specified:

sage: v = 10 * meter / second
sage: v
10 m s^-1
sage: v.set_preferred('m/s')
sage: v
10.0 m/s

There is a pre-defined unit of force, so that is used by default for any force:

sage: F = 3 * newton
sage: F
3 N
sage: F.set_preferred('base')
sage: F
3 m kg s^-2

Before setting the preferred unit to ‘self’, a display name must be specified for the Quantity, but just setting the display name will not influence how the Quantity itself prints.

sage: calorie = 4186.8 * joule
sage: calorie.set_dispname('kcal')
sage: calorie
4186.80000000000 J
sage: calorie.set_preferred('self')
sage: calorie
kcal
sin()

Return the sine of this Quantity if it is dimensionless.

EXAMPLES:

sage: sin(pi*500*metre/(1000*metre))
1.0
sage: sin(-67 * kelvin)
...
DimensionMismatchError: Argument of 'sin' must be dimensionless, dimensions were (K, )
sqrt()

Return the square root of this object.

EXAMPLES:

sage: sqrt(4 * joule/kilogram)
2.0 m s^-1.0
tan()

Return the tan of this Quantity if it is dimensionless.

EXAMPLES:

sage: tan(-0.2*newton*metre/joule)
-0.202710035508673
sage: tan(2/3 * coulomb)
...
DimensionMismatchError: Argument of 'tan' must be dimensionless, dimensions were (s A, )
with_dimensions

Static method for creating a Quantity object with dimensions and other attributes.

INPUT:
  • value - float or other scalar type
  • dim - a Dimension
  • fly - a Flydim (default: Flydim())
  • dispname - a string, sets the display name of the new quantity (default: ‘’)
  • preferred - a string, sets the preferred unit of the new quantity (default: ‘’); see documentation for Quantity.set_preferred()
  • register - if True, the new Quantity is put in the user unit registry; see documentation for UnitRegistry

OUTPUT: a Quantity with the given attributes

NOTES:

The user will not need to use this method as new quantities can be created simply through arithmetic.

EXAMPLES:

sage: x = Quantity.with_dimensions(2, Dimension(length=1))
sage: y = 2 * metre
sage: x == y
True
sage.dimpy.quantity.is_scalar_type(obj)

Test whether the object is a 1d number type including rationals and complex numbers.

INPUT:
  • obj - an object, e.g. a number, a symbolic expression or a Quantity

OUTPUT: a bool

NOTES:

This function is mostly used internally by the module for argument type checking. A scalar type can be considered a dimensionless quantity (see the documentation for Quantity for more information). Returns True also if obj is a symbolic Expression that can be converted into a complex number.

EXAMPLES:

These are scalar types:

sage: is_scalar_type(pi)
True
sage: is_scalar_type(2 + I)
True
sage: is_scalar_type(2/3)
True

These aren’t:

sage: is_scalar_type(3*meter)
False
sage: is_scalar_type(Flydim())
False
sage.dimpy.quantity.get_dimensions(obj)

Return the dimensions of an object.

INPUT:
  • obj - an object that passes is_scalar_type or a Dimension, Flydim or Quantity

OUTPUT: a tuple (physical dimensions, flydims)

NOTES:

More general than obj.get_dimensions() because it works on scalar types as well as Dimension, Flydim and Quantity. Returns both physical dimension and flydims. Will raise an error if obj is neither one of the dimensional types nor a scalar type.

EXAMPLES:

sage: person = Flydim('person')
sage: energy_usage = 125 * 3.6 * 10**6 * joule / person
sage: get_dimensions(energy_usage)
(m^2 kg s^-2, person^-1)
sage: get_dimensions(energy_usage)[1]
person^-1
sage: get_dimensions('meter')
...
TypeError: Cannot get dimensions for 'str'
sage.dimpy.quantity.register_new_unit(u)

Register a new unit for automatic displaying of quantities.

INPUT:
  • u - a Quantity or a parseable string

EXAMPLE:

sage: 2*farad/metre**2
2 m^-4 kg^-1 s^4 A^2
sage: register_new_unit('pF/mm^2')
sage: 2*farad/metre**2
2000000.0 pF/mm^2
sage.dimpy.quantity.have_same_dimensions(obj1, obj2)

Test if two objects have the same dimensions.

INPUT:
  • obj1, obj2 - two objects that can be assigned dimensions, i.e. numbers or Dimension, Flydim, Quantity

OUTPUT: a bool

EXAMPLES:

sage: have_same_dimensions(4, 2*radian)
True
sage: have_same_dimensions(3.5*meter, 4*second)
False
sage.dimpy.quantity.is_dimensionless(obj)

Test whether an object is dimensionless, returns a bool.

INPUT:
  • obj - a number or a Dimension, Flydim or Quantity

OUTPUT: a bool

EXAMPLES:

sage: is_dimensionless(CDF((-1)**(1/2)))
True
sage: is_dimensionless(6*meter/metre)
True
sage: is_dimensionless(Dimension(s=1))
False
sage.dimpy.quantity.get_value(obj)

Return the value of an object.

INPUT:
  • obj - a number or a Quantity

OUTPUT: a number, obj._value for a Quantity and obj for a number

NOTES:

Will return 1 for a Flydim and 0 for input None. The latter behaviour is used by the quant_matrix.qmatrix() function.

EXAMPLES:

sage: get_value(2/3)
2/3
sage: get_value(9*meter/(2*second))
4.5
sage: get_value(None)
0
sage: get_value('meter')
...
TypeError: Cannot get value for 'str'
sage: get_value(Flydim())
1
sage.dimpy.quantity.unregister_unit(u)

Remove all occurrences of a unit from the registries.

INPUT:
  • u - a Quantity, the unit to be removed from the registers

EXAMPLE:

sage: 5 * joule
5 J
sage: unregister_unit(joule)
sage: 5 * joule
3.1207547398e+19 eV
sage: register_new_unit(joule)   # so this doesn't break other tests
sage.dimpy.quantity.set_base_units(u0=m, u1=kg, u2=s, u3=A, u4=K, u5=mol, u6=cd)

Set the BaseUnitSet that determines how Quantities print for which there are no suitable units in the registers .

INPUT:
  • u0 to u6 - a collection of Quantities to be used as the base units. Default values are u0=meter, u1=kilogram, u2=second, u3=ampere, u4=kelvin, u5=mole, u6=candela.

NOTES:

It must be possible to express any Quantity in terms of these 7 reference Quantities and they must all have display names.

By default Quantities for which there are no suitable units in the registers will be displayed in the SI base units (metre, kilogram, second, ampere, kelvin, mole, candela). To customize the base unit set, use this function.

EXAMPLE:

sage: from sage.dimpy import *
sage: set_base_units(l_P, m_P, t_P, u4=T_P)
sage: 2 * meter / second
6.67128640831e-09 l_P t_P^-1
class sage.dimpy.quantity.BaseUnitSet(u0=m, u1=kg, u2=s, u3=A, u4=K, u5=mol, u6=cd)

A set of base units for displaying Quantities.

INPUT:
  • u0 to u6 - seven Quantities to be used as the base units; default values are u0=meter, u1=kilogram, u2=second, u3=ampere, u4=kelvin, u5=mole, u6=candela

OUTPUT: a BaseUnitSet that can be used to express any Quantity

NOTES:

The user will not need to interact with this class directly, use set_base_units().

EXAMPLE:

sage: from sage.dimpy import *
sage: set_base_units(meter, kWh, day)
sage: 15 * meter / second
1296000.0 m d^-1
sage: 100 * kilogram % 'base'
3.72108862978e-15 m^-2 kWh d^2
sage: 5 * kelvin
5 K
class sage.dimpy.quantity.UnitRegistry(name)

Stores known units for printing in best units

NOTES:

All a user needs to do is to use the register_new_unit() function. Units can be deleted from all registries using unregister_unit(). A quantity can be expressed in its best units using the method in_best_unit().

Default registries:

The units module defines three registries, the standard units, user units, and additional units. Finding best units is done by first checking user, then standard, then additional. New user units are added by using the register_new_unit() function.

Standard units includes all the basic non-compound unit names built in to the module, including volt, amp, etc. Additional units includes the non-SI units accepted for use with the SI system like hour, eV etc.

EXAMPLES:

sage: from sage.dimpy import *
sage: additional_unit_register
Additional Unit Register
sage: additional_unit_register[20*meter]
[AU, km, km]
sage: standard_unit_register[20*meter]
[m, m]
sage: standard_unit_register._latex_()
'\text{Standard Unit Register}'
add(u)

Add a unit to the registry.

Use register_new_unit() to add elements to the user unit register.

remove(u)

Remove a unit from the registry.

Use unregister_unit() to remove a unit from all registers.

Previous topic

Tutorial

Next topic

Non-SI units and some important physical constants

This Page

Quick search