### 57.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.

  - (x ` a) * (y ` b) is equal to (x * y) ` (a * b).
  - (x ` a) + (y ` a) is equal to (x + y) ` a.
  - (x ` a)^y is equal to x^y ` a^y when `y` is nondimensional.

  `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) load ("ezunits")$
      (%i2) foo : 10 ` m;
      (%o2)                        10 ` m
      (%i3) qty (foo);
      (%o3)                          10
      (%i4) units (foo);
      (%o4)                           m
      (%i5) dimensions (foo);
      (%o5)                        length

  "Customary" units.

      (%i1) load ("ezunits")$
      (%i2) bar : x ` acre;
      (%o2)                       x ` acre
      (%i3) dimensions (bar);
                                         2
      (%o3)                        length
      (%i4) fundamental_units (bar);
                                      2
      (%o4)                          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*day, baz2);
                                500   gallon
      (%o5)                     --- ` ------
                                 7     day

  Arithmetic operations on dimensional quantities.

      (%i1) load ("ezunits")$
      (%i2) 100 ` kg + 200 ` kg;
      (%o2)                       300 ` kg
      (%i3) 100 ` m^3 - 100 ` m^3;
                                        3
      (%o3)                        0 ` m
      (%i4) (10 ` kg) * (17 ` m/s^2);
                                       kg m
      (%o4)                      170 ` ----
                                         2
                                        s
      (%i5) (x ` m) / (y ` s);
                                    x   m
      (%o5)                         - ` -
                                    y   s
      (%i6) (a ` m)^2;
                                    2    2
      (%o6)                        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*yard^2,Btu = 1055*J,cfm = feet^3/minute,
             cm = m/100,day = 86400*s,feet = 381*m/1250,ft = feet,
             g = kg/1000,gallon = 757*l/200,GHz = 1000000000*Hz,
             GOhm = 1000000000*Ohm,GPa = 1000000000*Pa,
             GWb = 1000000000*Wb,Gg = 1000000*kg,Gm = 1000000000*m,
             Gmol = 1000000*mol,Gs = 1000000000*s,ha = hectare,
             hectare = 100*m^2,hour = 3600*s,Hz = 1/s,inch = feet/12,
             km = 1000*m,kmol = 1000*mol,ks = 1000*s,l = liter,
             lbf = pound_force,lbm = pound_mass,liter = m^3/1000,
             metric_ton = Mg,mg = kg/1000000,MHz = 1000000*Hz,
             microgram = kg/1000000000,micrometer = m/1000000,
             micron = micrometer,microsecond = s/1000000,
             mile = 5280*feet,minute = 60*s,mm = m/1000,
             mmol = mol/1000,month = 2629800*s,MOhm = 1000000*Ohm,
             MPa = 1000000*Pa,ms = s/1000,MWb = 1000000*Wb,
             Mg = 1000*kg,Mm = 1000000*m,Mmol = 1000000000*mol,
             Ms = 1000000*s,ns = s/1000000000,ounce = pound_mass/16,
             oz = ounce,Ohm = s*J/C^2,
             pound_force = 32*ft*pound_mass/s^2,
             pound_mass = 200*kg/441,psi = pound_force/inch^2,
             Pa = N/m^2,week = 604800*s,Wb = J/A,yard = 3*feet,
             year = 31557600*s,C = s*A,F = C^2/J,GA = 1000000000*A,
             GC = 1000000000*C,GF = 1000000000*F,GH = 1000000000*H,
             GJ = 1000000000*J,GK = 1000000000*K,GN = 1000000000*N,
             GS = 1000000000*S,GT = 1000000000*T,GV = 1000000000*V,
             GW = 1000000000*W,H = J/A^2,J = m*N,kA = 1000*A,
             kC = 1000*C,kF = 1000*F,kH = 1000*H,kHz = 1000*Hz,
             kJ = 1000*J,kK = 1000*K,kN = 1000*N,kOhm = 1000*Ohm,
             kPa = 1000*Pa,kS = 1000*S,kT = 1000*T,kV = 1000*V,
             kW = 1000*W,kWb = 1000*Wb,mA = A/1000,mC = C/1000,
             mF = F/1000,mH = H/1000,mHz = Hz/1000,mJ = J/1000,
             mK = K/1000,mN = N/1000,mOhm = Ohm/1000,mPa = Pa/1000,
             mS = S/1000,mT = T/1000,mV = V/1000,mW = W/1000,
             mWb = Wb/1000,MA = 1000000*A,MC = 1000000*C,
             MF = 1000000*F,MH = 1000000*H,MJ = 1000000*J,
             MK = 1000000*K,MN = 1000000*N,MS = 1000000*S,
             MT = 1000000*T,MV = 1000000*V,MW = 1000000*W,
             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;
      Computing conversions to base units; may take a moment.
                                  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/hour;
                                 720   Btu
      (%o6)                      --- ` ----
                                 211   hour
      (%i7) %, numer;
                                              Btu
      (%o7)               3.412322274881517 ` ----
                                              hour
      (%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;
      Computing conversions to base units; may take a moment.
                                 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;
      Computing conversions to base units; may take a moment.
                              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*hour, MWh = 1000*kWh,
                                     bell = 1800*s);
      (%o3)                         done
      (%i4) 1 ` kW*s `` MWh;
      Computing conversions to base units; may take a moment.
                                   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)

  Shows the value and the units of one of the constants declared by package `physical_constants`, which includes a list of physical constants, or of a new constant declared in package `ezunits` (see `declare_constvalue`).

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

  Example:

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

  Categories:Package ezunits ·

Function: declare_constvalue (a, x)

  Declares the value of a constant to be used in package `ezunits`. This function should be loaded with `load ("ezunits")`.

  Example:

      (%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: remove_constvalue (a)

  Reverts the effect of `declare_constvalue`. This function should be loaded with `load ("ezunits")`.

  Categories:Package ezunits ·

Function: units (x)

  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 via `declare_units`, or an expression containing either or both of those.

  This function should be loaded with `load ("ezunits")`.

  Example:

      (%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

  Categories:Package ezunits ·

Function: declare_units (a, u)

  Declares that `units` should return units u for a, where u is an expression. This function should be loaded with `load ("ezunits")`.

  Example:

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

  Categories:Package ezunits ·

Function: qty (x)

  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.

  This function should be loaded with `load ("ezunits")`.

  Example:

      (%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

  Categories:Package ezunits ·

Function: declare_qty (a, x)

  Declares that `qty` should return x for symbol a, where x is a nondimensional quantity. This function should be loaded with `load ("ezunits")`.

  Example:

      (%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 ``. u and v are both multiplicative terms, in which any variables are units, or both 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. This limitation might be relaxed in future versions.

  `known_unit_conversions` is the list of known unit conversions.

  This function should be loaded with `load ("ezunits")`.

  Examples:

  Unit conversions expressed by equations of multiplicative terms.

      (%i1) load ("ezunits")$
      (%i2) declare_unit_conversion (nautical_mile = 1852 * m,
                                     fortnight = 14 * day);
      (%o2)                         done
      (%i3) 100 ` nautical_mile / fortnight `` m/s;
      Computing conversions to base units; may take a moment.
                                  463    m
      (%o3)                       ---- ` -
                                  3024   s

  Unit conversions expressed by equations of literal dimensional expressions.

      (%i1) load ("ezunits")$
      (%i2) declare_unit_conversion (1 ` fluid_ounce = 2 ` tablespoon);
      (%o2)                         done
      (%i3) declare_unit_conversion (1 ` tablespoon = 3 ` teaspoon);
      (%o3)                         done
      (%i4) 15 ` fluid_ounce `` teaspoon;
      Computing conversions to base units; may take a moment.
      (%o4)                     90 ` teaspoon

  Categories:Package ezunits ·

Function: declare_dimensions (a_1, d_1, ..., a_n, d_n)

  Declares a_1, ..., a_n to have dimensions d_1, ..., d_n, respectively.

  Each a_k is a symbol or a list of symbols. If it is a list, then every symbol in a_k is declared to have dimension d_k.

  `load ("ezunits")` loads these functions.

  Examples:

      (%i1) load ("ezunits") $
      (%i2) declare_dimensions ([x, y, z], length, [t, u], time);
      (%o2)                         done
      (%i3) dimensions (y^2/u);
                                         2
                                   length
      (%o3)                        -------
                                    time
      (%i4) fundamental_units (y^2/u);
      0 errors, 0 warnings
                                      2
                                     m
      (%o4)                          --
                                     s

  Categories:Package ezunits ·

Function: remove_dimensions (a_1, ..., a_n)

  Reverts the effect of `declare_dimensions`. This function should be loaded with `load ("ezunits")`.

  Categories:Package ezunits ·

Function: declare_fundamental_dimensions (d_1, d_2, d_3, ...)
Function: remove_fundamental_dimensions (d_1, d_2, d_3, ...)
Global variable: fundamental_dimensions

  `declare_fundamental_dimensions` declares fundamental dimensions. Symbols d_1, d_2, d_3, ... are appended to the list of fundamental dimensions, if they are not already on the list.

  `remove_fundamental_dimensions` reverts the effect of `declare_fundamental_dimensions`.

  `fundamental_dimensions` is the list of fundamental dimensions. By default, the list comprises several physical dimensions.

  `load ("ezunits")` loads these functions.

  Examples:

      (%i1) load ("ezunits") $
      (%i2) fundamental_dimensions;
      (%o2) [length, mass, time, current, temperature, quantity]
      (%i3) declare_fundamental_dimensions (money, cattle, happiness);
      (%o3)                         done
      (%i4) fundamental_dimensions;
      (%o4) [length, mass, time, current, temperature, quantity,
                                              money, cattle, happiness]
      (%i5) remove_fundamental_dimensions (cattle, happiness);
      (%o5)                         done
      (%i6) fundamental_dimensions;
      (%o6) [length, mass, time, current, temperature, quantity, money]

  Categories:Package ezunits ·

Function: declare_fundamental_units (u_1, d_1, ..., u_n, d_n)
Function: remove_fundamental_units (u_1, ..., u_n)

  `declare_fundamental_units` declares u_1, ..., u_n to have dimensions d_1, ..., d_n, respectively. All arguments must be symbols.

  After calling `declare_fundamental_units`, `dimensions(u_k)` returns d_k for each argument u_1, ..., u_n, and `fundamental_units(d_k)` returns u_k for each argument d_1, ..., d_n.

  `remove_fundamental_units` reverts the effect of `declare_fundamental_units`.

  `load ("ezunits")` loads these functions.

  Examples:

      (%i1) load ("ezunits") $
      (%i2) declare_fundamental_dimensions (money, cattle, happiness);
      (%o2)                         done
      (%i3) declare_fundamental_units (dollar, money, goat, cattle,
                                       smile, happiness);
      (%o3)                 [dollar, goat, smile]
      (%i4) dimensions (100 ` dollar/goat/km^2);
                                   money
      (%o4)                    --------------
                                            2
                               cattle length
      (%i5) dimensions (x ` smile/kg);
                                  happiness
      (%o5)                       ---------
                                    mass
      (%i6) fundamental_units (money*cattle/happiness);
      0 errors, 0 warnings
                                 dollar goat
      (%o6)                      -----------
                                    smile

  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/hour);
                                   acre ft
      (%o3)                        -------
                                    hour
      (%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/hour);
                                   acre ft
      (%o4)                        -------
                                    hour
      (%i5) dimensions_as_list (foo);
      (%o5)                 [3, 0, - 1, 0, 0, 0]

  Categories:Package ezunits ·

Function: fundamental_units
`fundamental_units` (x)
`fundamental_units` ()

  `fundamental_units(x)` returns the units associated with the fundamental dimensions of x. as determined by `dimensions(x)`.

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

  `fundamental_units()` returns the list of all known fundamental units, as declared by `declare_fundamental_units`.

  `load ("ezunits")` loads this function.

  Examples:

      (%i1) load ("ezunits")$
      (%i2) fundamental_units ();
      (%o2)                 [m, kg, s, A, K, mol]
      (%i3) fundamental_units (100 ` mile/hour);
                                      m
      (%o3)                           -
                                      s
      (%i4) declare_units (aa, g/foot^2);
                                      g
      (%o4)                         -----
                                        2
                                    foot
      (%i5) fundamental_units (aa);
                                     kg
      (%o5)                          --
                                      2
                                     m

  Categories:Package ezunits ·

Function: dimensionless (L)

  Returns a basis for the dimensionless quantities which can be formed from a list L of dimensional quantities.

  `load ("ezunits")` loads this function.

  Examples:

      (%i1) load ("ezunits") $
      (%i2) dimensionless ([x ` m, y ` m/s, z ` s]);
      0 errors, 0 warnings
      0 errors, 0 warnings
                                     y z
      (%o2)                         [---]
                                      x

  Dimensionless quantities derived from fundamental physical quantities. Note that the first element on the list is proportional to the fine-structure constant.

      (%i1) load ("ezunits") $
      (%i2) load ("physical_constants") $
      (%i3) dimensionless([%h_bar, %m_e, %m_P, %%e, %c, %e_0]);
      0 errors, 0 warnings
      0 errors, 0 warnings
                                    2
                                 %%e        %m_e
      (%o3)                [--------------, ----]
                            %c %e_0 %h_bar  %m_P

  Categories:Package ezunits ·

Function: natural_unit (expr, [v_1, ..., v_n])

  Finds exponents e_1, ..., e_n such that `dimension(expr) = dimension(v_1^e_1 ... v_n^e_n)`.

  `load ("ezunits")` loads this function.

  Examples:

  Categories:Package ezunits ·