The information below has been updated and adapted from [Davies and Paredis, 2012]. That paper also offers suggestions as to how the approach might be better integrated in Modelica. For more information, please also see the documentation of the Quantities package.

**Introduction and Overview:**

Mathematical models of physical systems use 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 powers of other units, whether they are base units or units derived from the base units in the same manner.

In Modelica, a physical
quantity is represented by a variable which is an instance of the
`Real`

type. 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 referenced explicitly because
it is automatically returned when a variable 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 from 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 meter 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 apparent conflict is solved in FCSys by establishing units (including the
meter and the second) as mathematical entities and writing *v*
= 1 m/s (in code, `v = 1*U.m/U.s`

or simply ```
v
= U.m/U.s
```

). 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 handled naturally. The
essence of unit conversion is the phrase "value of a quantity in a
unit" typically means "value of a quantity divided by a unit."
Continuing with the previous example, *v* is divided by m/s in
order to display *v* in meters 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 nonlinear
transformations between the value of the quantity and the number;
these are described by functions besides simple division.

As another example, frequency is sometimes represented by a
variable in hertz or cycles per second (e.g., ν) and other times by
a variable in radians per second (e.g., ω). If the variable
represents the quantity directly, then there is no need to specify
which units it is in. The units are included; they have not been
factored out by division (or another function). A common variable
(e.g., *f*) can be used in both cases, which simplifies and
standardizes the equations of a model. The forms are algebraically
equivalent due to the relationships among units (e.g., 1 cycle
= 2π rad).

**Method:**

In FCSys, each unit is a constant quantity. The values of the units, like other quantities, is the product of a number and a unit. Therefore, units may be derived from other units (e.g., cycle = 2π rad). 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 meter (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 FCSys, the base units are established by universal physical constants (except the candela, which is physically arbitrary). The "particular example of the quantity" [BIPM2006] is an experiment that yields precise and universally repeatable results in determining a constant rather than a prototype (e.g., the International Prototype of the Kilogram) which is carefully controlled and distributed via replicas. This method of defining the base units from measured physical quantities (rather than vice versa) is natural and reflects the way that standards organizations (e.g., NIST) define units. A system of units is considered to be natural if all of its base units are established by universal physical constants. Often, those universal constants are defined to be equal to one, but the values can be chosen to scale the numerical values of variables during simulation.

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 and simulating those systems, it may
be advantageous 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. Products of this type are
often involved in initial conditions or parameter expressions,
which are not time-varying. Therefore, the number and the unit can
be multiplied before the dynamic simulation. During the simulation,
only the value is important. After the simulation, the trajectory
of the value may be divided by the unit for display. This scaling
is usually unnecessary due to the wide range and appropriate
distribution of the real numbers that are representable in floating
point. The Modelica language 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^{308} [Modelica2010,
p. 13]. However, in some cases it may be preferable to scale
the units and use lower precision for the sake of computational
performance. 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 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 define the Boltzmann constant to be equal
to one (*k*_{B} = 1) [http://en.wikipedia.org/wiki/Natural_units].
The unit K 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 units
kilogram, meter, and second (K ≈
1.381×10^{-23} kg m^{2}/s^{2}).

There are six independent units and constants in the Units package (see Units.Bases), but SI has seven
base units (m, kg, s, A, K, mol, and cd). In FCSys, two additional constraints are
imposed in order to simplify the model equations and allow
electrons and chemical species to be to represented by the same
base Species model.
First, the Faraday constant (*k*_{F} or
96485.3399 C/mol) is normalized to one. This implies that the
mole (mol) is proportional to the coulomb (C), which is considered
a number of reference particles given a charge number of one. Also,
the gas constant (R or 8.314472 J/(mol K)) is normalized
to one. Therefore, the kelvin (K) is proportional to the volt (V or
J/C). In addition, the radian (rad) is defined as a base constant.
However, it must be set equal to one in the current specification
of the International System of Units (SI) [BIPM2006].

**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 base constants and units, which
grouped in a `replaceable`

subpackage. The third section
establishes the constants and units which may be derived from the
base units and constants using accepted empirical relations. The
rest of the code establishes the SI prefixes and the remaining
derived units and constants. The SI prefixes are included in their
unabbreviated form in order to avoid naming conflicts. All of the
primary units of SI are included (Tables 1 and 3 of [BIPM2006])
except for °C, since it involves an offset. Other units such as the
atmosphere (atm) are included for convenience. Some units that
include prefixes are defined as well (e.g., kg, mm, and kPa).
However, most prefixes must be given as explicit factors (e.g.,
`U.kilo*U.m`

).

Besides the units and constants, this package also contains
functions (e.g., to_degC) that convert
quantities from the unit system defined in FCSys to quantities expressed in units.
These functions are included for units that involve offsets
. For conversions
that require just a scaling factor, it is simpler to use the units
directly. For example, to convert from potential in volts use
`v = v_V*U.V`

, where `v`

is potential and
`v_V`

is potential expressed in volts.

This package (Units) is
abbreviated as `U`

for convenience throughout the rest
of FCSys. For example, an
initial pressure might be defined as *p*_{IC} =
`U.atm`

.

An instance of the Environment model is usually included at the top level of a model. It records the base units and constants so that it is possible to re-derive all of the other units and constants. This is important in order to properly interpret simulation results if the base units and constants are later re-adjusted.

The Units.setup function establishes unit conversions using the values of the units, constants, and prefixes. These unit conversions may include offsets. The function also sets the default display units. It is automatically called when FCSys 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 or any subpackage. A spreadsheet (Resources/quantities.xls) 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 Modelica development environment. For convenience, the load.mos script automatically does this and saves the result as "units.mos" in the working directory.

Where the `der`

operator is used in models, it is
explicitly divided by the unit second (e.g.,
`der(x)/U.s`

). This is necessary because the global
variable `time`

is in seconds (i.e., `time`

is a number, not a quantity).

Although it is not necessary due to the acausal nature of Modelica, the declarations in this package are sorted so that they can be easily ported to imperative or causal languages (e.g., Python and C). In fact, this has been done in the included FCRes module for plotting and analysis.

**Licensed by the Hawaii Natural Energy Institute under the
Modelica License 2**

Copyright © 2007–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 FCSys.UsersGuide.License
or visit http://www.modelica.org/licenses/ModelicaLicense2.*

Name | Description |
---|---|

setup | Establish conversions to display quantities in units |

Examples | Examples |

Bases | Sets of base constants and units |

from_degC | Convert from temperature in degree Celsius to temperature as a quantity |

to_degC | Convert from temperature as a quantity to temperature in degree Celsius |

from_kPag | Convert from gauge pressure in kilopascals to absolute pressure as a quantity |

to_kPag | Convert from absolute pressure as a quantity to gauge pressure in kilopascals |

Generated at 2020-01-23T02:41:18Z by OpenModelicaOpenModelica 1.16.0~dev-120-g0c802bd using GenerateDoc.mos