Wolfram Language Home Page »

Units of Measurement Concepts and Configuration

The units of measurement used in System Modeler can be configured in several ways. Below, the central concepts are introduced, and how they relate and how they can be configured are described. To see the specific configuration of units for a library, open the documentation for the library's top-level package and use the links in the Library Units and Quantities section.

Overview

The definitions of units of measurement used for display unit conversions in System Modeler are the same definitions that are used to detect unit inconsistencies in models. In addition to ensuring consistency, this gives a dual benefit of configuring the units system based on the current application domain: domain-specific units can be used, while verifying consistent use of units, and values can be entered and displayed according to conventions in the domain.

Whenever working with a model (or any other kind of Modelica class), the active configuration of units of measurement is determined based on the model’s top-level parent class. For example, when working with IntroductoryExamples.MultiDomain.DCMotor, the active configuration is determined by IntroductoryExamples. The configuration is based on a combination of system defaults, configuration inherited through library dependencies, System Modeler–specific annotations, and information extracted from type definitions. This will be described in more detail below.

Using information in the currently active configuration, the user has some control over which units to include in user interface menus for unit selection. The user settings are described under Display Units View of the Options documentation, while the underlying information is also described below.

Concepts

The following concepts are central to the understanding of how System Modeler handles units of measurement and related features. The terminology used is to some extent specific to System Modeler, so it is recommended to become familiar with it before proceeding to the following sections.

Additional concepts that are less critical for understanding will be introduced later when first encountered.

Unit

Examples of a unit include meters, kilonewtons and meters per second. Both variables and expressions may have a unit, and there are rules regarding consistent use of units in a model.

A unit expression is a way to express a unit in terms of unit symbols, unit prefixes, multiplication, division and exponentiation. The expression is usually encoded as a string following a certain syntax. The strings corresponding to the examples above are "m", "kN" and "m/s", respectively.

A unit symbol is a compact name denoting some unit. For example, m is the symbol for meter, and N is the symbol for newton. Only a selection of unit symbols can be used with the SI system unit prefixes such as k; kN is a valid way to express kilonewtons, while min is not a valid way to express milli-inches.

The unit symbols are divided into base unit symbols and derived unit symbols. Every base unit corresponds to a separate dimension in the space of units, while a derived unit is defined in terms of other units. A derived unit definition is comprised of a unit expression, a scale and possibly an offset for interpretation of absolute quantities. For example, the in could be defined as the unit expression cm, the scale 2.54 and no offset. The offset will be described in more detail later.

Using the derived unit definitions, a unit expression can be evaluated to an equivalent canonical form only in terms of powers of base units and a scaling. The special unit 1 represents the unit where the canonical form has scale 1 and no base units with nonzero exponent.

When a variable has a unit attribute, the attribute determines the unit of the variable. Otherwise, the unit of the variable might be inferred from the unit consistency rules.

Quantity

A quantity is a property of a variable, giving a name identifying what is measured by the variable. In Modelica, connections require that connected variables have identical quantity when quantity is present. Quantities typically have names with uppercase initials, such as "Length" or "CurrentDensity".

In System Modeler, the quantity is also used to make a more intelligent selection of units to include as choices in menus.

A variable only has a quantity when the quantity attribute is present; System Modeler makes no inference of quantity. That the quantity generally cannot be inferred is due to the only requirement being that they are identical in connections. Consider three variables x, y and z that are related by equality in equations. It is allowed for x to be a "Torque" while z is a "Work", so if no quantity was specified for y, an inference mechanism would not be able to even infer the quantity for y based on equality with other variables. Further, the intention of multiplying a "Force" variable by a "Length" variable could be a "Torque", a "Work" or any other quantity compatible with the unit "N.m", showing that the quantity of an expression is not well defined.

Value of Quantity

A value of quantity is the combination of a numeric value and a unit. For example, 1.5 meters is a value of quantity, where the numeric value is 1.5 and the unit is meters. It is good modeling practice to express relations among values of quantity rather than in terms of the numeric values, as the incorporation of units allows many basic modeling mistakes to be detected, as well as enabling many user interface enhancements built around units. In Modelica, working with values of quantity is the same as working with variables having a unit, and the recommended way of giving units to variables is to use type definitions such as Modelica.Units.SI.Length that also come with a quantity or to rely on unit inference in general-purpose models that should be flexible in terms of units.

The numeric value of a model variable is often just referred to as the value of the variable, and when the variable has a unit, the variable represents a value of quantity.

This concept goes under many different many names in other contexts, but the more common alternatives are already given other meanings that cannot be changed in the present context.

Display Unit

In many situations, a display unit may be used when displaying or editing a value of quantity. System Modeler will then automatically convert between the display unit and the unit used to represent the value of quantity. For example, it is common to plot simulation results using a display unit rather than the variable's unit, and parameter values are often both displayed and edited using display units.

The displayUnit attribute of a variable suggests a display unit to use with the variable. It does not mean that the variable may only be displayed or edited using this unit. The amount of display unit propagation between models is not specified and might change between System Modeler versions.

Unit System

Examples of unit systems include International System of Units and US Customary. System Modeler has a fixed set of unit systems, with knowledge about how they relate. In the Options Display Units View, unit systems can be enabled and disabled. Based on the settings, any unit expression can be classified as either enabled or disabled, which is used to filter the content of menus for unit selection.

A unit expression is enabled when all appearing unit symbols are enabled. For a base unit, the unit systems enabling its symbol must be explicitly defined. A derived unit may either be explicitly enabled similar to a base unit symbol, or implicitly enabled according to its defining unit expression.

Quantity Space

All values of quantity represent either an absolute or a relative quantity. This classification is called the quantity space of a value of quantity, with absolute quantities belonging to an affine (quantity) space and relative quantities belonging to a vector (quantity) space. When converting between units, unit offsets are only considered for affine spaces. Hence, while the numeric value zero stays zero when converting in a vector space, this is generally not the case in an affine space. Further, the meaningful operations in an affine space are limited to computing differences (which belong to a vector space) and offsetting values by a difference (vector).

When performing quantity space analysis, the absoluteValue annotation is a source of information, similarly to how the unit attribute is a source of information when performing unit analysis. However, a variable's quantity space can also be determined based on the unit attribute, as every unit expression defines a default quantity space for variables declared with that unit. A unit expression consisting of a single symbol has a quantity space configured for that symbol, while all other unit expressions come with vector space.

Based on rules for how affine values of quantity may be used, inference of quantity space is possible, similarly to how rules for unit checking allow inference of units. Also similarly to units, the quantity space cannot always be determined.

Configuration of Units

As mentioned above, all classes within the same package hierarchy share the same unit definitions. In the following, let P be the package at the root of such a hierarchy. The active unit definitions within P are determined using the mechanisms described below.

Unit Definition Tables

Cyclically dependent derived unit definitions are not allowed. It follows that the active set of unit definitions can be sorted such that unit definitions only depend on previously defined unit symbols (this is trivially true for base unit symbols, which do not depend on any other unit symbol).

The directed acyclic graph structure of allowed unit definitions is utilized in the definition of active units for a library, by using an intermediate representation in the form of a unit definition table where the directed acyclic structure is not enforced until the end. The topological sorting of the unit definitions is a straightforward process, making the important question how to define the unit definition table of P, which is the topic of the following subsections.

Uses Dependencies

When P has a uses annotation declaring a dependency on D, the latter package is said to be a uses dependency of P. By following the uses annotations from P, a package uses dependency graph is obtained. This graph is sorted topologically, and the main units in the unit table definition process are the strong components of the graph. Accordingly, the unit definition table of P is defined as the unit definition table of the strong component to which P belongs.

To simplify presentation, it will be assumed that each strong component consists of a single package, and a package name such as P will sometimes be used as a simplified reference to the strong component consisting of P. The simplifying assumption is rarely fulfilled in practice since, as of Version 4.0.0, the Modelica package is in the same strong component as ModelicaServices. However, by imagining that ModelicaServices does not exist, the simplified presentation is still applicable and accurate in most cases.

Inherited Unit Definitions

When a package P has uses dependencies, the unit definition tables are first determined for each of the dependencies and then inherited by P. When there is significant disagreement between inherited definitions of a symbol, this is an error unless P resolves the conflict. One way for P to resolve a conflict is to provide its own definition of the symbol using a Units annotation; see below.

System Defaults

System Modeler comes with a default unit definition table. This table provides units needed to use the Modelica package, as well as some additional units of general interest. A package without any uses dependencies will inherit units from the default unit definition table, in the same way that a package with uses dependencies inherits unit definition tables from the dependencies.

The Units Annotation

On top of inherited unit definitions, a top-level package may configure unit definitions using the System Modeler–specific Units annotation. The annotation allows new base units and derived units to be defined, allows inherited units to be removed and provides mechanisms for handling conflicting unit definitions. The supported way of editing the annotation is through the Library Units dialogs; see Editing Library Units.

In a unit definition, there are four string attributes that deserve special attention to ensure the unit is set up correctly. The mandatory Symbol is the identifier for the unit used in unit expression strings. The mandatory Name is the full name by which the unit is denoted, such as newton (note that the use of uppercase letters in unit names is very rare, even when units are named after persons) for the symbol N. The Unit Description is an optional description to be used only when there is a need to provide additional information beyond the Name to clearly convey the meaning or purpose of the unit. The Symbol Presentation is an optional Unicode string to be used instead of the Symbol in the display of unit expressions.

Configuration of Quantities and Display Units

The basis for providing a relevant selection of units in menus is the association of display units to quantities. Once the active set of unit definitions has been determined, the display units associated with a quantity are organized into equivalence classes based on unit conversion compatibility, so it is not a problem for a quantity to be associated with display units that are not conversion compatible to each other. It follows that merging different sources of quantity configuration cannot fail, making quantity configuration much simpler to handle than the configuration of units.

Similarly to unit definitions, the active quantity configuration within P is determined based on the uses dependencies, with a quantity configuration determined for each strong component in the uses dependency graph. The other mechanisms involved are described below.

Inherited Display Units

When a package P has uses dependencies, the quantity configurations are first determined for each of the uses dependencies and then inherited by P. The only information that can be lost in the merging process is the origin of an associated display unit when it is inherited from several sources.

System Defaults

System Modeler comes with a default quantity configuration. Among other things, this quantity configuration provides display units for most quantities appearing in the Modelica package. A package without any uses dependencies will inherit the default quantity configuration, in the same way that a package with uses dependencies inherits quantity configurations from the dependencies.

Type Alias Extraction

Display units are extracted from types extending the built-in Real type and having a quantity attribute. However, since a type can at most associate two different units (one for the unit attribute, and one for the displayUnit attribute) with the quantity, the extraction only serves to provide a minimal level of convenience for packages that are not covered well by the system defaults and that have not been tailored using the System Modeler–specific annotation described below.

The Units Annotation

On top of inherited quantity configurations and type alias extraction, a top-level package may configure quantities and display units using the System Modeler–specific Units annotation. The annotation is organized by quantity. For each quantity, new display units may be added, and inherited display units can be removed. The supported way of editing the annotation is through the Library Units dialogs; see Editing Library Units.

Known Quantities

A quantity is considered known as soon as it has been associated with some display unit.

Avoid Overriding Unit Definitions

The ability to configure the unit definitions in System Modeler is powerful enough to, for instance, make the radian a base unit, make a system without offset temperature scales (see below) or make the mole a pure numeric scaling unit. These are all examples of advanced configurations that can be used to get as close as possible to the unit conventions within specific domains. However, the implications for model reuse should be considered before attempting such advanced configuration:

• Downstream unit conflicts. If the custom definitions are inherited by a third package that also inherits a non-customized package such as Modelica, the third package may need to resolve unit conflicts due to the multiple, incompatible, unit definitions.

• Unit inconsistency in existing models. Models developed with the standard unit definitions in mind might no longer be unit consistent if unit symbols change meaning.

• Tool portability. To use models with the same meaning of units in another Modelica tool will require additional tool-specific customization, which may not even be supported by the other tool.

Of the many ways in which units can be customized, the most likely one to cause problems is to override an inherited unit definition. When possible, it is therefore recommended to make use of less advanced unit configuration, where new and clearly named unit symbols are introduced instead of overriding existing symbol definitions.

Quantity Space Consistency and Traditional Use of Kelvin

In engineering and science domains where the only recognized unit of temperature is kelvin, there is no need to keep track of whether the temperature scale offsets of degree Celsius and degree Fahrenheit should be considered in unit conversions. The default unit definitions in System Modeler, however, have been set up to support domains where it is important to keep track of when to consider the temperature scale offsets, requiring special attention when dealing with some formulas and equations where the use of kelvin only is traditionally taken for granted.

The Problem

Hence, temperature is traditionally treated as a vector quantity (as opposed to affine quantity; see above) in these domains, allowing temperatures to be handled with the same simplicity as all the other quantities where none of the commonly used units come with offset. Important well-known examples of this are the ideal gas law:

as well as the Stefan–Boltzmann law:

In both of these laws, the temperature is used multiplicatively, meaning it must be a vector quantity. The Modelica Standard Library provides TemperatureDifference for this purpose:

model StefanBoltzmann_TemperatureDifference
  import Modelica.Units.SI.*;
  import Modelica.Constants.sigma;
  parameter TemperatureDifference T = 293.15;
  RadiantExitance M0;
equation
  M0 = sigma * T^4;  
end StefanBoltzmann_TemperatureDifference;

On the other hand, users of System Modeler may expect the convenience of being able to enter any temperature in degree Celsius or degree Fahrenheit, when using equations like the ones above. When using StefanBoltzmann_TemperatureDifference, it is easy to make the mistake of thinking that a temperature entered as 20 °C will have the same effect as 293.15 K. However, since T is a vector quantity, 20 °C has the same effect as 20 K.

Solutions

A drastic solution to the problem above would be to remove all temperature units with offset and make all remaining temperature units create vector quantities by default. Unfortunately, the Modelica Standard Library has type definitions making use of both "degC" and "degF", making the applicability of this approach rather limited due to its incompatibility with the Modelica Standard Library.

A better solution is to use Temperature (which is affine) for T to get the expected unit conversions and then modify the equation so that the multiplicative operation is performed on the vector quantity T - T_zero_K, where the constant T_zero_K denotes the temperature 0 K. In System Modeler, a definition of T_zero_K is provided as SystemModelerExtras.Experimental.Units.

model StefanBoltzmann_Temperature
  import Modelica.Units.SI.*;
  import Modelica.Constants.sigma;
  import SystemModelerExtras.Experimental.Units.T_zero_K;
  parameter Temperature T = 293.15;
  RadiantExitance M0;
equation
  M0 = sigma * (T - T_zero_K)^4;  
end StefanBoltzmann_Temperature;

The trick of subtracting T_zero_K is widely applicable for addressing errors due to illegal use of affine temperatures.