[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 50. ezunits

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 50.1 Introduction to ezunits

`ezunits` is a package for working with dimensional quantities, including some functions for dimensional analysis. `ezunits` can carry out arithmetic operations on dimensional quantities and unit conversions. The built-in units include Systeme Internationale (SI) and US customary units, and other units can be declared. See also `physical_constants`, a collection of physical constants. `load(ezunits)` loads this package. `demo(ezunits)` displays several examples.

An expression `a ` b` represents a dimensional quantity, with `a` indicating a nondimensional quantity and `b` indicating the dimensional units. A symbol can be used as a unit without declaring it as such; unit symbols need not have any special properties. The quantity and unit of an expression `a ` b` can be extracted by the `qty` and `units` functions, respectively.

A symbol may be declared to be a dimensional quantity, with specified quantity or specified units or both.

An expression `a ` b `` c` converts from unit `b` to unit `c`. `ezunits` has built-in conversions for SI base units, SI derived units, and some non-SI units. Unit conversions not already known to `ezunits` can be declared. The unit conversions known to `ezunits` are specified by the global variable `known_unit_conversions`, which comprises built-in and user-defined conversions. Conversions for products, quotients, and powers of units are derived from the set of known unit conversions.

As Maxima generally prefers exact numbers (integers or rationals) to inexact (float or bigfloat), so `ezunits` preserves exact numbers when they appear in dimensional quantities. All built-in unit conversions are expressed in terms of exact numbers; inexact numbers in declared conversions are coerced to exact.

There is no preferred system for display of units; input units are not converted to other units unless conversion is explicitly indicated. `ezunits` does not attempt to simplify units by prefixes (milli-, centi-, deci-, etc) unless such conversion is explicitly indicated.

Arithmetic operations on dimensional quantities are carried out by conventional rules for such operations.

`ezunits` does not require that units in a sum have the same dimensions; such terms are not added together, and no error is reported.

`ezunits` includes functions for elementary dimensional analysis, namely the fundamental dimensions and fundamental units of a dimensional quantity, and computation of dimensionless quantities and natural units. The functions for dimensional analysis were adapted from similar functions in another package, written by Barton Willis.

For the purpose of dimensional analysis, a list of fundamental dimensions and an associated list of fundamental units are maintained; by default the fundamental dimensions are length, mass, time, charge, temperature, and quantity, and the fundamental units are the associated SI units, but other fundamental dimensions and units can be declared.

Categories: Physical units · Share packages · Package ezunits

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 50.2 Introduction to physical_constants

`physical_constants` is a collection of physical constants, copied from CODATA 2006 recommended values. [1] `load(physical_constants)` loads this package, and loads `ezunits` also, if it is not already loaded.

A physical constant is represented as a symbol which has a property which is the constant value. The constant value is a dimensional quantity, as represented by `ezunits`. The function `constvalue` fetches the constant value; the constant value is not the ordinary value of the symbol, so the symbols persist in evaluated expressions until the value is fetched by `constvalue`.

`physical_constants` includes some auxilliary information such as a description string for each constant, an estimate of the error of its numerical value, and a property for TeX display. To identify physical constants, each symbol has the `physical_constant` property; `propvars(physical_constant)` therefore shows the list of all such symbols.

`physical_constants` comprises the following constants.

`%c`

  speed of light in vacuum

`%mu_0`

  magnetic constant

`%e_0`

  electric constant

`%Z_0`

  characteristic impedance of vacuum

`%G`

  Newtonian constant of gravitation

`%h`

  Planck constant

`%h_bar`

  Planck constant

`%m_P`

  Planck mass

`%T_P`

  Planck temperature

`%l_P`

  Planck length

`%t_P`

  Planck time

`%%e`

  elementary charge

`%Phi_0`

  magnetic flux quantum

`%G_0`

  conductance quantum

`%K_J`

  Josephson constant

`%R_K`

  von Klitzing constant

`%mu_B`

  Bohr magneton

`%mu_N`

  nuclear magneton

`%alpha`

  fine-structure constant

`%R_inf`

  Rydberg constant

`%a_0`

  Bohr radius

`%E_h`

  Hartree energy

`%ratio_h_me`

  quantum of circulation

`%m_e`

  electron mass

`%N_A`

  Avogadro constant

`%m_u`

  atomic mass constant

`%F`

  Faraday constant

`%R`

  molar gas constant

`%%k`

  Boltzmann constant

`%V_m`

  molar volume of ideal gas

`%n_0`

  Loschmidt constant

`%ratio_S0_R`

  Sackur-Tetrode constant (absolute entropy constant)

`%sigma`

  Stefan-Boltzmann constant

`%c_1`

  first radiation constant

`%c_1L`

  first radiation constant for spectral radiance

`%c_2`

  second radiation constant

`%b`

  Wien displacement law constant

`%b_prime`

  Wien displacement law constant

References:

[1] http://physics.nist.gov/constants

Examples:

The list of all symbols which have the `physical_constant` property.

    (%i1) load (physical_constants);
    (%i2) propvars (physical_constant);
    (%o2) [%c, %mu_0, %e_0, %Z_0, %G, %h, %h_bar, %m_P, %T_P, %l_P,
    %t_P, %%e, %Phi_0, %G_0, %K_J, %R_K, %mu_B, %mu_N, %alpha,
    %R_inf, %a_0, %E_h, %ratio_h_me, %m_e, %N_A, %m_u, %F, %R, %%k,
    %V_m, %n_0, %ratio_S0_R, %sigma, %c_1, %c_1L, %c_2, %b, %b_prime]

Properties of the physical constant `%c`.

    (%i1) load (physical_constants);
    (%i2) constantp (%c);
    (%o2)                         true
    (%i3) get (%c, description);
    (%o3)               speed of light in vacuum
    (%i4) constvalue (%c);
                                          m
    (%o4)                     299792458 ` -
                                          s
    (%i5) get (%c, RSU);
    (%o5)                           0
    (%i6) tex (%c);
    $$c$$
    (%o6)                         false

The energy equivalent of 1 pound-mass. The symbol `%c` persists until its value is fetched by `constvalue`. The joules to gigajoules conversion is not built-in, so it is declared.

    (%i1) load (physical_constants);
    (%i2) m * %c^2;
                                    2
    (%o2)                         %c  m
    (%i3) %, m = 1 ` lbm;
                                  2
    (%o3)                       %c  ` lbm
    (%i4) constvalue (%);
                                                2
                                           lbm m
    (%o4)              89875517873681764 ` ------
                                              2
                                             s
    (%i5) E : % `` J;
                         366838848464007200
    (%o5)                ------------------ ` J
                                 9
    (%i6) declare_unit_conversion (1 ` GJ = 10^9 ` J);
    (%o6)                         done
    (%i7) E `` GJ;
                          458548560580009
    (%o7)                 --------------- ` GJ
                             11250000
    (%i8) float (%);
    (%o8)              4.0759872051556356e+7 ` GJ

Categories: Physical units · Share packages · Package physical_constants

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 50.3 Functions and Variables for ezunits

Operator: `

  The dimensional quantity operator. An expression `a ` b` represents a dimensional quantity, with `a` indicating a nondimensional quantity and `b` indicating the dimensional units. A symbol can be used as a unit without declaring it as such; unit symbols need not have any special properties. The quantity and unit of an expression `a ` b` can be extracted by the `qty` and `units` functions, respectively.

  Arithmetic operations on dimensional quantities are carried out by conventional rules for such operations.

  `ezunits` does not require that units in a sum have the same dimensions; such terms are not added together, and no error is reported.

  `load(ezunits)` enables this operator.

  Examples:

  SI (Systeme Internationale) units.

      (%i1) foo : 10 ` m;
      (%o1)                        10 ` m
      (%i2) qty (foo);
      (%o2)                          10
      (%i3) units (foo);
      (%o3)                           m
      (%i4) dimensions (foo);
      (%o4)                        length

  "Customary" units.

      (%i1) bar : x ` acre;
      (%o1)                       x ` acre
      (%i2) dimensions (bar);
                                         2
      (%o2)                        length
      (%i3) fundamental_units (bar);
                                      2
      (%o3)                          m

  Units ad hoc.

      (%i1) load (ezunits);
      (%i2) baz : 3 ` sheep + 8 ` goat + 1 ` horse;
      (%o2)           8 ` goat + 3 ` sheep + 1 ` horse
      (%i3) subst ([sheep = 3*goat, horse = 10*goat], baz);
      (%o3)                       27 ` goat
      (%i4) baz2 : 1000`gallon/fortnight;
                                      gallon
      (%o4)                   1000 ` ---------
                                     fortnight
      (%i5) subst (fortnight = 14*d, baz2);
                                500   gallon
      (%o5)                     --- ` ------
                                 7      d

  Arithmetic operations on dimensional quantities.

      (%i1) 100 ` kg + 200 ` kg;
      (%o1)                       300 ` kg
      (%i2) 100 ` m^3 - 100 ` m^3;
                                        3
      (%o2)                        0 ` m
      (%i3) (10 ` kg) * (17 ` m/s^2);
                                       kg m
      (%o3)                      170 ` ----
                                         2
                                        s
      (%i4) (x ` m) / (y ` s);
                                    x   m
      (%o4)                         - ` -
                                    y   s
      (%i5) (a ` m)^2;
                                    2    2
      (%o5)                        a  ` m

  Categories: Package ezunits

Operator: "

  The unit conversion operator. An expression `a ` b `` c` converts from unit `b` to unit `c`. `ezunits` has built-in conversions for SI base units, SI derived units, and some non-SI units. Unit conversions not already known to `ezunits` can be declared. The unit conversions known to `ezunits` are specified by the global variable `known_unit_conversions`, which comprises built-in and user-defined conversions. Conversions for products, quotients, and powers of units are derived from the set of known unit conversions.

  There is no preferred system for display of units; input units are not converted to other units unless conversion is explicitly indicated. `ezunits` does not attempt to simplify units by prefixes (milli-, centi-, deci-, etc) unless such conversion is explicitly indicated.

  `load(ezunits)` enables this operator.

  Examples:

  The set of known unit conversions.

      (%i1) load (ezunits)$
      (%i2) display2d : false$
      (%i3) known_unit_conversions;
      (%o3) {acre = 4840*yd^2,Btu = 1055*J,cfm = ft^3/min,cm = m/100,
             d = 24*h,ft = 381*m/1250,g = kg/1000,gallon = 757*l/200,
             h = 60*min,Hz = 1/s,in = ft/12,km = 1000*m,l = m^3/1000,
             lbf = 32*ft*lbm/s^2,lbm = 200*kg/441,mi = 5280*ft,
             micron = m/1000000,min = 60*s,mm = m/1000,oz = lbm/16,
             Ohm = s*J/C^2,psi = lbf/in^2,Pa = N/m^2,Wb = J/A,
             yd = 3*ft,C = s*A,F = C^2/J,H = J/A^2,J = m*N,
             N = kg*m/s^2,R = 5*K/9,S = 1/Ohm,T = J/(m^2*A),V = J/C,
             W = J/s}

  Elementary unit conversions.

      (%i1) load (ezunits)$
      (%i2) 1 ` ft `` m;
                                  381
      (%o2)                       ---- ` m
                                  1250
      (%i3) %, numer;
      (%o3)                      0.3048 ` m
      (%i4) 1 ` kg `` lbm;
                                  441
      (%o4)                       --- ` lbm
                                  200
      (%i5) %, numer;
      (%o5)                      2.205 ` lbm
      (%i6) 1 ` W `` Btu/h;
                                  720   Btu
      (%o6)                       --- ` ---
                                  211    h
      (%i7) %, numer;
                                               Btu
      (%o7)                3.412322274881517 ` ---
                                                h
      (%i8) 100 ` degC `` degF;
      (%o8)                      212 ` degF
      (%i9) -40 ` degF `` degC;
      (%o9)                     (- 40) ` degC
      (%i10) 1 ` acre*ft `` m^3;
                              60228605349    3
      (%o10)                  ----------- ` m
                               48828125
      (%i11) %, numer;
                                                3
      (%o11)                1233.48183754752 ` m

  Coercing quantities in feet and meters to one or the other.

      (%i1) load (ezunits)$
      (%i2) 100 ` m + 100 ` ft;
      (%o2)                  100 ` m + 100 ` ft
      (%i3) (100 ` m + 100 ` ft) `` ft;
                                 163100
      (%o3)                      ------ ` ft
                                  381
      (%i4) %, numer;
      (%o4)                428.0839895013123 ` ft
      (%i5) (100 ` m + 100 ` ft) `` m;
                                  3262
      (%o5)                       ---- ` m
                                   25
      (%i6) %, numer;
      (%o6)                      130.48 ` m

  Dimensional analysis to find fundamental dimensions and fundamental units.

      (%i1) load (ezunits)$
      (%i2) foo : 1 ` acre * ft;
      (%o2)                      1 ` acre ft
      (%i3) dimensions (foo);
                                         3
      (%o3)                        length
      (%i4) fundamental_units (foo);
                                      3
      (%o4)                          m
      (%i5) foo `` m^3;
                              60228605349    3
      (%o5)                   ----------- ` m
                               48828125
      (%i6) %, numer;
                                                3
      (%o6)                 1233.48183754752 ` m

  Declared unit conversions.

      (%i1) load (ezunits)$
      (%i2) declare_unit_conversion (MMBtu = 10^6*Btu, kW = 1000*W);
      (%o2)                         done
      (%i3) declare_unit_conversion (kWh = kW*h, MWh = 1000*kWh, bell = 1800*s);
      (%o3)                         done
      (%i4) 1 ` kW*s `` MWh;
                                   1
      (%o4)                     ------- ` MWh
                                3600000
      (%i5) 1 ` kW/m^2 `` MMBtu/bell/ft^2;
                             1306449      MMBtu
      (%o5)                 ---------- ` --------
                            8242187500          2
                                         bell ft

  Categories: Package ezunits

Function: constvalue (x)
Function: declare_constvalue (a, x)

  Returns the declared constant value of a symbol, or value of an expression with declared constant values substituted for symbols.

  Constant values are declared by `declare_constvalue`. Note that constant values as recognized by `constvalue` are separate from values declared by `numerval` and recognized by `constantp`.

  The `physical_units` package declares constant values for a number of physical constants.

  `load(ezunits)` loads this function.

  Example:

  Constant value of a physical constant.

      (%i1) load (physical_constants)$
      (%i2) constvalue (%G);
                                           3
                                          m
      (%o2)                    6.67428 ` -----
                                             2
                                         kg s
      (%i3) get ('%G, 'description);
      (%o3)           Newtonian constant of gravitation

  Declaring a new constant.

      (%i1) load (ezunits)$
      (%i2) declare_constvalue (FOO, 100 ` lbm / acre);
                                       lbm
      (%o2)                      100 ` ----
                                       acre
      (%i3) FOO * (50 ` acre);
      (%o3)                     50 FOO ` acre
      (%i4) constvalue (%);
      (%o4)                      5000 ` lbm

  Categories: Package ezunits

Function: units (x)
Function: declare_units (a, u)

  Returns the units of a dimensional quantity x, or returns 1 if x is nondimensional.

  x may be a literal dimensional expression `a ` b`, a symbol with declared units, or an expression containing either or both of those.

  `load(ezunits)` loads these functions.

  `declare_units` declares that `units(a)` should return u, where u is an expression.

  Examples:

  `units` applied to literal dimensional expressions.

      (%i1) load (ezunits)$
      (%i2) foo : 100 ` kg;
      (%o2)                              100 ` kg
      (%i3) bar : x ` m/s;
                                               m
      (%o3)                                x ` -
                                               s
      (%i4) units (foo);
      (%o4)                                 kg
      (%i5) units (bar);
                                             m
      (%o5)                                  -
                                             s
      (%i6) units (foo * bar);
                                           kg m
      (%o6)                                ----
                                            s
      (%i7) units (foo / bar);
                                           kg s
      (%o7)                                ----
                                            m
      (%i8) units (foo^2);
                                              2
      (%o8)                                 kg

  `units` applied to symbols with declared units.

      (%i1) load (ezunits)$
      (%i2) linenum:0;
      (%o0)                                  0
      (%i1) units (aa);
      (%o1)                                  1
      (%i2) declare_units (aa, J);
      (%o2)                                  J
      (%i3) units (aa);
      (%o3)                                  J
      (%i4) units (aa^2);
                                             2
      (%o4)                                 J
      (%i5) foo : 100 ` kg;
      (%o5)                              100 ` kg
      (%i6) units (aa * foo);
      (%o6)                                kg J

  Categories: Package ezunits

Function: qty (x)
Function: declare_qty (a, x)

  `qty` returns the nondimensional part of a dimensional quantity x, or returns x if x is nondimensional. x may be a literal dimensional expression `a ` b`, a symbol with declared quantity, or an expression containing either or both of those.

  `declare_qty` declares that `qty(a)` should return x, where x is a nondimensional quantity.

  `load(ezunits)` loads these functions.

  Examples:

  `qty` applied to literal dimensional expressions.

      (%i1) load (ezunits)$
      (%i2) foo : 100 ` kg;
      (%o2)                       100 ` kg
      (%i3) qty (foo);
      (%o3)                          100
      (%i4) bar : v ` m/s;
                                        m
      (%o4)                         v ` -
                                        s
      (%i5) foo * bar;
                                        kg m
      (%o5)                     100 v ` ----
                                         s
      (%i6) qty (foo * bar);
      (%o6)                         100 v

  `qty` applied to symbols with declared quantity.

      (%i1) load (ezunits)$
      (%i2) declare_qty (aa, xx);
      (%o2)                          xx
      (%i3) qty (aa);
      (%o3)                          xx
      (%i4) qty (aa^2);
                                       2
      (%o4)                          xx
      (%i5) foo : 100 ` kg;
      (%o5)                       100 ` kg
      (%i6) qty (aa * foo);
      (%o6)                        100 xx

  Categories: Package ezunits

Function: unitp (x)

  Returns `true` if x is a literal dimensional expression, a symbol declared dimensional, or an expression in which the main operator is declared dimensional. `unitp` returns `false` otherwise.

  `load(ezunits)` loads this function.

  Examples:

  `unitp` applied to a literal dimensional expression.

      (%i1) load (ezunits)$
      (%i2) unitp (100 ` kg);
      (%o2)                         true

  `unitp` applied to a symbol declared dimensional.

      (%i1) load (ezunits)$
      (%i2) unitp (foo);
      (%o2)                         false
      (%i3) declare (foo, dimensional);
      (%o3)                         done
      (%i4) unitp (foo);
      (%o4)                         true

  `unitp` applied to an expression in which the main operator is declared dimensional.

      (%i1) load (ezunits)$
      (%i2) unitp (bar (x, y, z));
      (%o2)                         false
      (%i3) declare (bar, dimensional);
      (%o3)                         done
      (%i4) unitp (bar (x, y, z));
      (%o4)                         true

  Categories: Package ezunits

Function: declare_unit_conversion (u = v, ...)

  Appends equations u = v, ... to the list of unit conversions known to the unit conversion operator ````. Each equation is a equality of multiplicative terms, in which any variables are units, or literal dimensional expressions.

  At present, it is necessary to express conversions such that the left-hand side of each equation is a simple unit (not a multiplicative expression) or a literal dimensional expression with the quantity equal to 1 and the unit being a simple unit. It is foreseen that this limitation will be relaxed in future versions.

  `known_unit_conversions` is the list of known unit conversions.

  `load(ezunits)` loads this function.

  Examples:

  Unit conversions expressed by equations of multiplicative terms.

      (%i1) load (ezunits)$
      (%i2) declare_unit_conversion (nautical_mile = 1852 * m, fortnight = 14 * d);
      (%o2)                         done
      (%i3) 100 ` nautical_mile / fortnight `` m/s;
                                  463    m
      (%o3)                       ---- ` -
                                  3024   s

  Unit conversions expressed by equations of literal dimensional expressions.

  Categories: Package ezunits

Function: declare_dimensions (d_1, d_2, d_3, ...)
Function: remove_dimensions (d_1, d_2, d_3, ...)

  Categories: Package ezunits

Function: declare_fundamental_dimensions (d_1, d_2, d_3, ...)
Function: remove_fundamental_dimensions (d_1, d_2, d_3, ...)

  Categories: Package ezunits

Function: declare_fundamental_units (u_1, u_2, u_3, ...)
Function: remove_fundamental_units (u_1, u_2, u_3, ...)

  Categories: Package ezunits

Function: dimensions (x)
Function: dimensions_as_list (x)

  `dimensions` returns the dimensions of the dimensional quantity x as an expression comprising products and powers of base dimensions.

  `dimensions_as_list` returns the dimensions of the dimensional quantity x as a list, in which each element is an integer which indicates the power of the corresponding base dimension in the dimensions of x.

  `load(ezunits)` loads these functions.

  Examples:

      (%i1) load (ezunits)$
      (%i2) dimensions (1000 ` kg*m^2/s^3);
                                      2
                                length  mass
      (%o2)                     ------------
                                       3
                                   time
      (%i3) declare_units (foo, acre*ft/h);
                                   acre ft
      (%o3)                        -------
                                      h
      (%i4) dimensions (foo);
                                         3
                                   length
      (%o4)                        -------
                                    time

      (%i1) load (ezunits)$
      (%i2) fundamental_dimensions;
      (%o2)  [length, mass, time, charge, temperature, quantity]
      (%i3) dimensions_as_list (1000 ` kg*m^2/s^3);
      (%o3)                 [2, 1, - 3, 0, 0, 0]
      (%i4) declare_units (foo, acre*ft/h);
                                   acre ft
      (%o4)                        -------
                                      h
      (%i5) dimensions_as_list (foo);
      (%o5)                 [3, 0, - 1, 0, 0, 0]

  Categories: Package ezunits

Function: fundamental_units (x)

  Categories: Package ezunits

Function: dimensionless (x)

  Categories: Package ezunits

Function: natural_unit (x)

  Categories: Package ezunits

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Robert Dodier on August, 10 2008 using texi2html 1.76.