packageUnits

Information

Below are details about the premise and the implementation of physical units in QCalc. For an overview of how to use QCalc, please see the top-level documentation and the getting started page. This text has been updated and adapted from [Davies2012]. That paper also suggests how the approach might be better integrated in the Modelica language. Please also see the documentation of the Quantities package.

Introduction:

In mathematical models, one uses variables to represent physical quantities. As stated by the Bureau International des Poids et Mesures (BIPM) [BIPM2006, p. 103]:

"The value of a quantity is generally expressed as the product of a number and a unit. The unit is simply a particular example of the quantity concerned which is used as a reference, and the number is the ratio of the value of the quantity to the unit."

In general, a unit may be the product of other units raised to various powers.

In Modelica, a physical quantity is represented by a Real variable. Its value attribute is a number associated with the value of the quantity (not the value of the quantity itself, as will be shown). Usually the value attribute is not explicitly referenced because it is automatically returned when the variable itself is referenced. The unit attribute is a string that describes the unit by which the value of the quantity has been divided to arrive at the number. The displayUnit attribute (also a string) describes the unit by which the value of the quantity should be divided to arrive at the number as it is entered by or presented to the user. The Real type contains other attributes as well, including the quantity string.

The SIunits package of the Modelica Standard Library contains types that extend the Real type. The type definitions modify the unit, displayUnit, and quantity attributes (among others) to represent various physical quantities. The unit and displayUnit attributes are based on the International System of Units (Système international d'unités, SI). The quantity string is the name of the physical quantity. For example, the Velocity type has a unit of "m/s" and a quantity of "Velocity". If an instance of Velocity has a value of one (v = 1), then it is meant that "the value of velocity is one metre per second." Again, the value attribute represents the number, or the value of the quantity divided by the unit, not the value of the quantity itself.

This conflict is solved in QCalc by establishing units as mathematical entities and writing v = 1 m/s (in code, v = 1*U.m/U.s or simply v = U.m/U.s, where U is an abbreviation for this package). Here, the variable v directly represents the quantity. Its value attribute is truly the value of the quantity in the context of the statement by BIPM (above). One advantage is that unit conversion is built in. The essence of unit conversion is that the phrase "value of quantity in unit" typically means "value of quantity divided by unit." Continuing with the previous example, v is divided by m/s in order to display v in metres per second (as a number). If another unit of length like the foot is established by the appropriate relation (ft ≈ 0.3048 m) and v is divided by ft/s, the result is velocity in feet per second (∼3.2894). Some units such as °C, Pag, and dB involve offsets or nonaffine transformations between the value of the quantity and the number; these are described by functions besides simple division.

Method:

In QCalc, each scalar unit is a constant quantity. The value of a unit, like other quantities, is the product of a number and a unit. Therefore, units may be derived from other units (e.g., Pa = N/m²). This recursive definition leaves several units (in SI, 7) that are locally independent and must be established universally. These base units are established by the "particular example of the quantity concerned which is used as a reference" quoted previously [BIPM2006]. The choice of the base units is somewhat arbitrary [Fritzson2004, p. 375], but regardless, there are a number of units that must be defined by example.

If only SI will be used, then it is easiest to set each of the base units of SI equal to one—the metre (m), kilogram (kg), second (s), ampere (A), kelvin (K), mole (mol), and candela (cd). This is implicitly the case in the SIunits package, but again, it hardly captures the idea that the value of a quantity is the product of a number and a unit.

Instead, in QCalc, the values of the base units are established from physical constants. This approach reflects the way that standards organizations (e.g., NIST) define modern units. The "particular example of the quantity" [BIPM2006] is an experiment that yields precise and universally repeatable results rather than a prototype (e.g., the international prototype kilogram) which is carefully controlled and distributed via replicas. This approach also makes it easy to normalize certain constants as in natural unit systems.

In addition, the values of the constants can be chosen to scale the values of variables. There are physical systems where typical quantities are many orders of magnitude larger or smaller than the related product of powers of base SI units (e.g., the domains of astrophysics and atomic physics). In modeling those systems, it may help to choose appropriately small or large values (respectively) for the corresponding base units so that the product of the number (large or small in magnitude) and the unit (small or large, respectively) is well-scaled. This scaling is usually unnecessary due to the wide range and appropriate distribution of the real numbers that are representable in floating point.¹ However, in some cases it may improve computational performance to scale the units and use lower precision. There are fields of research where, even today, simulations are sometimes performed in single precision [Brown2011, Hess2008] and where scaling is a concern [Rapaport2004, p. 29]. The number and the unit are usually multiplied before the dynamic simulation or even during translation because the product is often involved in initial conditions or parameter expressions. During the simulation, only the value is important, so there is no computational overhead. The value is divided by the display unit after the simulation.

The method is neutral with regards to not only the values of the base units, but also the choice of the base units and even the number of base units. This is an advantage because many systems of units besides SI are used in science and engineering. As mentioned previously, the choice of base units is somewhat arbitrary, and different systems of units are based on different choices. Some systems of units have fewer base units (lower rank) than SI, since additional constraints are added that exchange base units for derived units. For example, the Planck, Stoney, Hartree, and Rydberg systems of units set the Boltzmann constant equal to one (k_B = 1) [http://en.wikipedia.org/wiki/Natural_units]. The kelvin is eliminated [Greiner1995, p. 386] or, more precisely, considered a derived unit instead of a base unit. In SI, the kelvin would be derived from the kilogram, metre, and second, (K ≈ 1.381×10^-23 kg m²/s²). In this case, temperature is not an independent dimension.

There are seven base constants in the Units package (R_∞, c, k_J, R_K, k_F, R, and k_A'; see Units.Bases) and seven SI base units (m, s, kg, A, K, mol, and cd). The candela (cd) is decoupled from these constants by the luminosity function, but the radian (rad) is derived from them.

Implementation:

The units and constants are defined as variables in this Units package. Each is a constant of the appropriate type from the Quantities package. The first section of this package establishes mathematical constants. The next section establishes the independent base constants, which are grouped in a replaceable record. The third section derives other physical constants from the base constants. The fourth section establishes units from the base constants using transcendental and empirical relations. The rest of the code derives additional units and constants from those units. All of the units from [BIPM2006] are defined, which includes the SI units and some non-SI units. Other units are included for convenience. Some prefixed units are defined as well, but most must be expressed using separate factors (e.g., U.Prefixes.k*U.m).

Some units such as Celsius and decibel involve functions other than multiplication. These units are called lambda units and are defined via operator records. The * and / operators are overloaded to call the unit's transformation and its inverse, respectively.

This package (QCalc.Units) is abbreviated as U for convenience throughout the rest of QCalc, and QCalc.Quantities is abbreviated as Q.

The Units.setup function establishes unit conversions using the values of the units, constants, and prefixes. These conversions may include offsets. The function also sets the default display units. It is automatically called when QCalc is loaded from the load.mos script. It can also be called manually from the "Re-initialize the units" command available in the Modelica development environment from the Units package and its subpackages. A spreadsheet (Resources/quantities.xlsx) is available to help maintain the quantities, default units, and the setup function.

The values of the units, constants, and prefixes can be evaluated by translating the Units.Examples.Evaluate model. This defines the values in the workspace of the development environment. For convenience, the load.mos script automatically translates that model and saves the result as "units.mos" in the working directory.

In order to interpret the simulation results stored in a file, it is necessary to know the values of the base constants. Since these may be changed, it is a good idea to drop QCalc.Units.UnitSystem into your model to record the values of the base constants in the results.

Although it is not necessary since Modelica is acausal, the declarations in this package are sorted so that they can be easily ported to imperative/causal languages (e.g., Python and C).

Some notes on angle:

As mentioned on the getting started page and in the Quantities package, angle is a dimension. This is different from SI, where angle is considered dimensionless (rad = 1) [BIPM2006].² Units of angle such as the cycle (cyc), radian (rad), and degree (deg) must be explicitly included in the expression of quantities, but they often cancel in equations relating quantities. The following differences are noted from the traditional SI representation:

1. The radian is defined as the cycle divided by two pi (rad = cyc/2π), which is not necessarily one because angle is derived from the independent base constants (as mentioned above).
2. Solid angle has the dimensionality of squared angle. The streradian (sr) is defined as the squared radian (rad²), not one.
3. Frequency and rotational velocity have the dimensionality of angle per time. The hertz (Hz) is defined as cyc/s (not s^-1).
4. The cross product (×) introduces a factor of rad^-1. This means that:
   • Torque, defined as r×F, has the dimensionality of energy per angle. Where J or N m is traditionally used to express torque, J/rad (or N m/rad) should be used.
   • A factor of 2π appears in the the Maxwell-Faraday equation and Ampère's circuital law of Maxwell's equations:
     • ∇×E = -2π ∂B/∂t
     • ∇×B = 2π μ₀(J + ε₀ ∂E/∂t) (This formation is also based on other points below.)
     • Rotational momentum has a factor of angle in the denominator.
       • The Planck constant (h) can be expressed in J/Hz or J s/rad (but not J s):
         • h cyc ≈ 6.626×10^-34 J s (the traditional expression of the Planck constant [NIST2010])
         • h rad ≈ 1.055×10^-34 J s (the traditional expression of the reduced Planck constant [NIST2010])
       • The quantum of circulation (rotational momentum per mass) is expressed as:
         • kappa ≈ 3.637×10^-4 m²/(cyc s)
   • Rotational inertia has a factor of squared angle in the denominator. It can be expressed in kg m²/rad².
   • Wavenumber has the dimensionality of angle per length. Where m^-1 (or cm^-1, etc.) is traditionally used to express wavenumber, cyc/m (or cyc/cm, etc.) should be used instead. Reciprocally, wavelength has the dimensionality of length per angle and is expressed using m/cyc (or cm/cyc, etc.). This implies that:
     • R_∞ ≈ 10973732 cyc/m
     • c₂ = 1.439×10^-2 m K/cyc
     • c_3 λ ≈ 2.898×10^-3 m K/cyc
     • λ_e cyc ≈ 2.426×10^-12 m (The right side is the traditional expression of the electron's Compton wavelength [NIST2010].)
     • λ_e rad ≈ 386.2×10^-15 m (The right side is the traditional expression of the electron's Compton wavelength over 2 π [NIST2010].)
   • Magnetic flux and related quantities have a factor of angle in the denominator.
     • The weber (Wb) is defined as V/Hz or V s/cyc (not V s).
     • The von Klitzing constant and the characteristic impedance of vacuum are expressed as:
       • R_K ≈ 25813 Ω/cyc
       • Z₀ ≈ 376.7 Ω/cyc
       since they are quantities of magnetic flux per charge. Reciprocally, the conductance quantum has a factor of angle in the numerator:
       • G₀ ≈ 7.748×10^-5 S cyc
     • The fine-structure constant (k_A c/R_K) is therefore an angle:
       • α/rad ≈ 7.297×10^-3 (The right side is the traditional expression [NIST2010].)
     • A factor of cyc must be added to the denominator of the traditional symbolic expression of the atomic unit of magnetic flux density.
   • The magnetic constant has a factor of squared angle in the denominator:
     • μ₀ = 4π×10^-7 H/(m cyc²) = 2k_A/(cyc rad), where 2k_A is the factor in Ampère's force law.
     In the basic equation for the inductance of a solenoid in vacuum, N (the number of turns) is replaced by the angle of the wound coil (θ = N cyc):
     • L = μ₀ θ² A/ℓ.
5. The auxiliary magnetic field (H), magnetic moment, and related quantities have a factor of angle in the numerator.
   • The oersted is expressed as:
     • Oe = (10³/4π) AT/m, where AT is the ampere-turn (AT = A cyc)
     but the cycle or turn is traditionally neglected [BIPM].
   • A factor of cyc must be added to the traditional symbolic expression of the atomic unit of magnetic dipole moment.
6. It follows that magnetizability, the ratio between magnetic moment and magnetic flux density, has squared angle in the numerator. A factor of cyc² must be added to the traditional symbolic expression of the atomic unit of magnetizability.
7. The henry (H) is defined as V s/A (not Wb/A). Although it related to magnetics, the henry is applied to electrical circuits, so it does not include any factors of angle.
8. Traditional trigonometric functions accept angles in radians. Angles should be divided by the radian (U.rad) before passing to these functions (e.g., sin(theta/U.rad)) and the result of their inverses should be multiplied by the radian (e.g., asin(x)*U.rad).
9. The first radiation constant has a factor of angle to the fourth power in the denominator:
   • c₁ cyc⁴ ≈ 3.742×10^-16 W m² (The right side is the traditional expression [NIST2010].)

The explicit inclusion of angle has several advantages. First, it avoids a conflict in the definition of SI units. BIPM defines the hertz as the reciprocal second (Hz = s^-1), but states that "The SI unit of frequency is given as the hertz, implying the unit cycles per second" [BIPM2006]. Due to trigonometry (cyc = 2π rad), BIPM's definition of the radian as one (rad = 1) implies that the cycle is two pi (cyc = 2π) and the hertz is not cycles per second but rather cycles per second divided by two pi (Hz = cyc/(2π s)).

The second advantage is that the use of explicit angles avoids the potential confusion between energy and torque in SI [BIPM2006]. Torque is expressed as the cross product of force and radius. The cross product introduces a factor of rad^-1, so the result is energy per angle, which is clearly distinct from energy. The angle cancels in the expression of rotational power—the product of torque and rotational velocity (angle per time).

Also, the inclusion of angle avoids the need to use different variables depending on the chosen unit of angle. For example, frequency is sometimes represented by a variable in hertz (e.g., ν) and other times by a variable in radians per second (e.g., ω). If angle is explicit, then one variable will suffice (f = ν cyc/s = ω rad/s). As alluded to earlier, there is no need for the reduced Planck constant (i.e., h ≈ 6.6261×10^-34 J/Hz ≈ 1.0546×10^-34 J s/rad).

Fourth, if angle is counted as a dimension, the fine-structure constant is not dimensionless. This addresses the conundrum of a dimensionless constant that cannot be mathematically derived.

Another possible advantage appears if we define the size of a circle (S) as length per angle—radius per radian (r/rad) or, equivalently, circumference per cycle. This simplifies the representation of some common equations because explicit factors of 2π are eliminated. The circumference of one circle is S cyc. The surface area of one sphere is S² sp, where sp = 4π sr is the spat, a unit of solid angle.³ Coulomb's force law can be expressed using the electric constant (ε₀) without a explicit factor of 1/4π:

F = (1/ε₀) q₁q₂/(S² sp)

F = k_C q₁q₂/r²

1. The Modelica specification recommends that floating point numbers be represented in at least IEEE double precision, which covers magnitudes from ∼2.225×10^-308 to ∼1.798×10³⁰⁸ [Modelica2010, p. 13].↵

2. The common argument that angle is dimensionless ("angle is a ratio of lengths") is flawed. Angle is the not the ratio of arclength to radius. Rather, angle in radians is the ratio of arclength to radius (θ/rad = L/r). It is not necessary that angle (θ) is dimensionless, only that angle and radian (rad) have the same dimension. In QCalc, that dimension is called angle. The common (and correct) understanding is that the radian (rad) is a unit of angle, just as the metre (m) is a unit of length. The dimensionality of the radian is angle, just as the dimensionality of the metre is length.↵

3. The spat (sp) is the solid angle of one sphere, just as the cycle (cyc) is the angle of one circle. For mnemonic purposes, sp can be considered as the abbreviation for sphere as well as spat.↵

Licensed by the Hawaii Natural Energy Institute under the Modelica License 2
Copyright © 2009–2014, Hawaii Natural Energy Institute and Georgia Tech Research Corporation.

This Modelica package is free software and the use is completely at your own risk; it can be redistributed and/or modified under the terms of the Modelica License 2. For license conditions (including the disclaimer of warranty) see QCalc.UsersGuide.License or visit http://www.modelica.org/licenses/ModelicaLicense2.

Parameters

Contents

Name	Description
setup	Set up the units in Dymola
UnitSystem	Base constants for the unit system
Examples	Examples
Bases	Sets of base constants and units
Prefixes	SI prefixes
Interfaces	Partial classes