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).


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×10308 [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 (kB = 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 m2/s2).

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 (kF 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].


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 pIC = 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.


setupEstablish conversions to display quantities in units
BasesSets of base constants and units
from_degCConvert from temperature in degree Celsius to temperature as a quantity
to_degCConvert from temperature as a quantity to temperature in degree Celsius
from_kPagConvert from gauge pressure in kilopascals to absolute pressure as a quantity
to_kPagConvert 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