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 2024-07-20T18:16:01Z by OpenModelicaOpenModelica 1.23.1 using GenerateDoc.mos