unitexpressions.tex

\chapter{Unit Expressions}\label{unit-expressions}

Unless otherwise stated, the syntax and semantics of unit expressions in Modelica conform with the international standards \emph{International System of Units (SI)} by BIPM superseding parts of ISO 31/0-1992 \emph{General principles concerning quantities, units and symbols} and ISO 1000-1992 \emph{SI units and recommendations for the use of their multiples and of certain other units}.
Unfortunately, these standards do not define a formal syntax for unit expressions.
There are recommendations and Modelica exploits them.

Note that this document uses the American spelling \emph{meter}, whereas the SI specification from BIPM uses the British spelling \emph{metre}.

Examples for the syntax of unit expressions used in Modelica: \lstinline!"N.m"!, \lstinline!"kg.m/s2"!, \lstinline!"kg.m.s-2"!, \lstinline!"1/rad"!, \lstinline!"mm/s"!.

\section{The Syntax of Unit Expressions}\label{the-syntax-of-unit-expressions}

The Modelica unit string syntax allows neither comments nor white-space, and a unit string shall match the \lstinline[language=grammar]!unit-expression! rule:
\begin{lstlisting}[language=grammar]
unit-expression :
   unit-numerator [ "/" unit-denominator ]

unit-numerator :
   "1" | unit-factors | "(" unit-expression ")"

unit-denominator:
   unit-factor | "(" unit-expression ")"
\end{lstlisting}

The unit of measure of a dimension free quantity is denoted by \lstinline!"1"!.
The SI standard does not define any precedence between multiplications and divisions.
The SI standard does not allow multiple units to the right of the division-symbol (\lstinline!/!) since the result is ambiguous; either the divisor shall be enclosed in parentheses, or negative exponents used instead of division, for example, \lstinline!"J/(kg.K)"! may be written as \lstinline!"J.kg-1.K-1"!.

\begin{lstlisting}[language=grammar]
unit-factors :
   unit-factor [ "." unit-factors ]
\end{lstlisting}

The SI standard specifies that a multiplication operator symbol is written as space or as a dot.
The SI standard requires that this \emph{dot} is a bit above the base line: `·', which is not part of ASCII.
The ISO standard also prefers `·', but Modelica supports the ISO alternative `.', which is an ordinary \emph{dot} on the base line.

For example, Modelica does not support \lstinline!"Nm"! for newton-meter, but requires it to be written as \lstinline!"N.m"!.

\begin{lstlisting}[language=grammar]
unit-factor :
  unit-operand [ unit-exponent ]

unit-exponent :
   [ "+" | "-" ] UNSIGNED-INTEGER
\end{lstlisting}

The SI standard uses super-script for the exponentation, and does thus not define any operator symbol for exponentiation.
A \lstinline[language=grammar]!unit-factor! consists of a \lstinline[language=grammar]!unit-operand! possibly suffixed by a possibly signed integer number, which is interpreted as an exponent.
There must be no spacing between the \lstinline[language=grammar]!unit-operand! and a possible \lstinline[language=grammar]!unit-exponent!.

\begin{lstlisting}[language=grammar]
unit-operand :
   unit-symbol | unit-prefix unit-symbol

unit-prefix :
   "Y" | "Z" | "E" | "P" | "T" | "G" | "M" | "k" | "h" | "da"
   | "d" | "c" | "m" | "u" | "n" | "p" | "f" | "a" | "z" | "y"

unit-symbol :
   unit-char { unit-char }

unit-char :
   NON-DIGIT
\end{lstlisting}

It is required that basic and derived units of the SI system are recognized, but tools are allowed to additionally support user-defined unit symbols.
The required unit symbols do not make use of Greek letters, but a unit such as $\Omega$ is spelled out as \lstinline!"Ohm"!.
Similarly degree is spelled out as \lstinline!"deg"!, both on its own (for angles) and as part of \lstinline!"degC"!, \lstinline!"degF"! and \lstinline!"degRk"! for temperatures (Celsius, Fahrenheit and Rankine).

A \lstinline[language=grammar]!unit-operand! should first be interpreted as a \lstinline[language=grammar]!unit-symbol! and only if not successful the second alternative assuming a prefixed operand should be exploited.
There must be no spacing between the \lstinline[language=grammar]!unit-symbol! and a possible \lstinline[language=grammar]!unit-prefix!.
The values of the prefixes are according to the ISO standard.
The letter \lstinline!u! is used as a symbol for the prefix \emph{micro}.

\begin{nonnormative}
A tool may present \lstinline!"Ohm"! as $\Omega$ and the prefix \lstinline!"u"! as $\mu$.
Exponents such as \lstinline!"m2"! may be presented as m\textsuperscript{2}.
Degrees may be presented as $^{\circ}$, both for \lstinline!"deg"! on its own (for angles) and for temperatures -- e.g., \lstinline!"degC"! can be presented as $^{\circ}$C.
Note that BIPM have specific recommendations for formatting using these symbols.
\end{nonnormative}

\begin{example}
The unit expression \lstinline!"m"! means meter and not milli (10\textsuperscript{-3}), since prefixes cannot be used in isolation.
For millimeter use \lstinline!"mm"! and for square meter, m\textsuperscript{2}, write \lstinline!"m2"!.

The expression \lstinline!"mm2"! means (10\textsuperscript{-3}m)\textsuperscript{2} = 10\textsuperscript{-6}m\textsuperscript{2}.
Note that exponentiation includes the prefix.

The unit expression \lstinline!"T"! means tesla, but note that the letter \lstinline!T! is also the symbol for the prefix tera which has a multiplier value of 10\textsuperscript{12}.
\end{example}


\section{Unit Checking}\label{unit-checking}

How to verify that units are used in compatible ways is current not fully determined by the specification.
This section gives rules for certain situations, but in general tools are expected to reason based on common sense.


\subsection{Empty and Undefined Units}\label{empty-and-undefined-units}

In situations where the specification does not prescribe how to determine the unit of an expression, the unit of that expression is said to be \firstuse[undefined unit]{undefined}.
It is then not possible for a tool to reject the equation (or other construct) with support in the specification, and options for the tool include silently not performing unit checking, or applying checks based on common sense.

The unit of an expression can also be defined as being \firstuse[empty unit]{empty}, see below.
In certain places (see below), expressions with empty unit can be implicitly cast to suitable units.
When an expression with empty unit is implicitly cast to some unit, that unit is referred to as the \firstuse{inferred unit} of the expression.


\subsection{Unit Inference}\label{unit-inference}

Where the empty unit has no other defined meaning, it can be implicitly cast to unit \lstinline!"1"!.

In some cases the empty unit can be implicitly cast to an inferred unit:
\begin{itemize}
\item
  In binding equations and modifications:
  \begin{itemize}
  \item The entire expression of the binding or modification.
  \item When the entire expression is an array construction, array concatenation and array range, then apply rules recursively for the direct subexpressions.
  \end{itemize}
\item
  The entire argument expression in a function call.
% To keep the design close to the bare minimum, this part is currently excluded:
%\item
%  For a translation-time constant with value 0.0:
%  \begin{itemize}
%  \item Expressions constituting the entire side of an equality or relation.
%  \item The right hand side of an assignment.
%  \item The direct subexpressions of array construction, array concatenation, and array range.
%  \end{itemize}
\end{itemize}


\subsection{Expressions with Empty Unit}\label{expressions-with-empty-unit}

This section describes conditions under which an expression has empty unit.
Conditions not given here must not be interpreted as definitely not implying empty unit; instead, the unit may be currently undefined for some expressions, allowing the unit to be properly defined in future versions of the specification.

Basic expressions defined to have empty unit:
\begin{itemize}
\item
  \lstinline!Real! literals.
\item
  \lstinline!Integer! expressions implicitly cast to \lstinline!Real!.
\end{itemize}

Expressions defined to \emph{not} propagate the empty unit, thereby forcing inference of unit \lstinline!"1"!:
\begin{itemize}
\item
  Addition, subtraction, multiplication and division operators when either operand has non-empty unit.
\item
  Right operand of binary exponentiation.
\item
  Component references outside of functions, where the component's declared \lstinline!unit!-attribute is \lstinline!""! (possibly by not being specified).
  (Unit checking involving user-defined functions with empty unit on inputs and outputs is currently not defined.)
\end{itemize}

Built-in non-array operators, functions, and special expressions that propagate any unit (including empty):
\begin{itemize}
\item
  When all operands have the same unit: negation, addition, and subtraction (scalar or element-wise).
\end{itemize}

Special situations in which the empty unit can be propagated up the expression tree:
\begin{itemize}
\item
  Multiplication and division when both operands have empty unit.
\end{itemize}

\begin{example}
Consider unit checking of the following declaration equation:
\begin{lstlisting}[language=modelica]
Real y(unit = "m") = 1 + 2.5 * 3;
\end{lstlisting}
The unit of the declaration equation right-hand side is determined as follows:
\begin{itemize}
\item The \lstinline!Real! literal \lstinline!2.5! has empty unit.
\item The \lstinline!Integer! literals \lstinline!1! and \lstinline!3! are implicitly cast to \lstinline!Real!, and therefore have empty unit.
\item The multiplication \lstinline!2.5 * 3! has empty unit, as multiplication can propagate the empty unit of both operands.
\item The addition \lstinline!1 + (2.5 * 3)! has empty unit, as addition can propagate any unit as long as both operands have the same unit.
\item The entire right-hand side expression gets inferred unit \lstinline!"m"! in order to be compatible with the component's declared \lstinline!unit!.
\end{itemize}
\end{example}

\begin{example}
Consider unit checking of the following erroneous declaration equation for \lstinline!y!:
\begin{lstlisting}[language=modelica]
Real x(unit = "m") = 1.0;
Real y(unit = "m") = x^2 / 2;
\end{lstlisting}
The unit of the declaration equation right-hand side is determined as follows:
\begin{itemize}
\item The unit of \lstinline!x! is \lstinline!"m"!, and common sense gives that \lstinline!x^2! has unit \lstinline!"m2"!
\item The \lstinline!Real! literal \lstinline!1.0! has empty unit, and gets inferred unit \lstinline!"m"!.
\item As the left operand of \lstinline!x^2 / 2! is non-empty, the right operand cannot be empty, and hence empty unit of \lstinline!2! is implicitly cast to \lstinline!"1"!.
\item Common sense then gives that the unit of \lstinline!x^2 / 2! is \lstinline!"m2"!, which is an error due to the required unit being \lstinline!"m"!.
\end{itemize}
\end{example}

\begin{example}
Consider the potential consequences of an undefined unit in the following declaration equation:
\begin{lstlisting}[language=modelica]
Real y(unit = "m") = sin(1.57);
\end{lstlisting}
To see that the unit of the declaration equation right-hand side is undefined, note that:
\begin{itemize}
\item The \lstinline!Real! literal \lstinline!1.57! has empty unit.
\item The expression \lstinline!sin(1.57)! is not covered by the specification, and hence has undefined unit.
\end{itemize}
If a tool wants to proceed according to ``common sense'', alternatives include:
\begin{itemize}
\item
  Assume that \lstinline!sin! is a mapping from unit \lstinline!"1"! to unit \lstinline!"1"!.
  The unit of \lstinline!1.57! then defaults to \lstinline!"1"! (alternatively, the same unit could be obtained by inference).
  The unit of \lstinline!sin(1.57)! is then found to be \lstinline!"1"!, which is an error due to the required unit being \lstinline!"m"!.
\item
  Assume that \lstinline!sin! preserves both the unit \lstinline!"1"! and the empty unit.
  The empty unit of \lstinline!1.57! gets propagated to \lstinline!sin(1.57)!, which in turn gets inferred unit \lstinline!"m"!.
\end{itemize}
\end{example}