annotations.tex

\chapter{Annotations}\label{annotations}

Annotations are intended for storing extra information about a model, such as graphics, documentation or versioning, etc.
A Modelica tool is free to define and use other annotations, in addition to those defined here, according to \cref{vendor-specific-annotations}.

Annotations are optional in the Modelica grammar, and when present, indicated using the \lstinline!annotation!\indexinline{annotation} keyword, see \lstinline[language=grammar]!annotation-clause! in the grammar (\cref{expressions1}).
The structure of the annotation content is the same as a class modification (\lstinline[language=grammar]!class-modification! in the grammar).
(For replaceable class declarations with a \lstinline[language=grammar]!constraining-clause! also refer to \cref{constraining-clause-annotations}.)
The specification in this document defines the semantic meaning if a tool implements any of these annotations.

\section{Notation for Annotation Definitions}\label{notation-for-annotation-definitions}

Annotations are defined using the syntactic forms of Modelica component declarations and record definitions, with the following special semantics.
If the annotation is described by a component declaration, the annotation is used in the form of a value modifier for the same name.
If the annotation is described by a \lstinline!record! \emph{class} the annotation is used in the form of a modifier for a \lstinline!record! \emph{component} with the same name.

A declaration equation for a component or record member specifies a default to be used when no corresponding annotation is given.
An array record member without declaration equation and with size specified by colon (\lstinline!:!) defaults to being empty.
Default behavior can also be specified in the text as an alternative to a declaration equation.
Component declaration annotations always have default behavior, as all annotations are optional.
When there is no declaration equation and no other explanation of default behavior in the text for a record member, an annotation modifier for the record must contain a modifier for that member.

When an annotation is defined with a component variability prefix (\cref{component-variability-prefixes-discrete-parameter-constant}), this restricts the allowed variability of corresponding annotation modifiers analogously to the rules in \cref{variability-of-expressions}.
If the annotation is declared as an \lstinline!/*evaluable*/ parameter! the corresponding modifier is further restricted to be evaluable.
If the annotation is declared as a \lstinline!/*literal*/ constant! the corresponding modifier is further restricted to be a literal value.

\section{Vendor-Specific Annotations}\label{vendor-specific-annotations}

A vendor may -- anywhere inside an annotation -- add specific, possibly undocumented, annotations which are not intended to be interpreted by other tools.
The only requirement is that any tool shall save files with all vendor-specific annotations (and all annotations from this chapter) intact.
Two variants of vendor-specific annotations\index{vendor-specific annotation} exist; one simple and one hierarchical.
Double underscore concatenated with a vendor name as initial characters of the identifier are used to identify vendor-specific annotations.

\begin{example}
\begin{lstlisting}[language=modelica]
annotation(
  Icon(coordinateSystem(extent = {{-100, -100}, {100, 100}}),
       graphics = {__NameOfVendor(Circle(center = {0, 0}, radius = 10))}));
\end{lstlisting}
This introduces a new graphical primitive \lstinline!Circle! using the
hierarchical variant of vendor-specific annotations.
\begin{lstlisting}[language=modelica]
annotation(
  Icon(coordinateSystem(extent = {{-100, -100}, {100, 100}}),
       graphics = {Rectangle(extent = {{-5, -5}, {7, 7}},
                             __NameOfVendor_shadow = 2)}));
\end{lstlisting}
This introduces a new attribute \lstinline!__NameOfVendor_shadow!
for the \lstinline!Rectangle! primitive using the simple variant of
vendor-specific annotations.
\end{example}

\section{Documentation}\label{annotations-for-documentation}\label{documentation}

The \fmtannotationindex{Documentation} annotation has the following contents, where the \lstinline!info! and \lstinline!revisions! annotations are described in \cref{annotation-info-revisions}, and the \lstinline!figures! annotation is described in \cref{annotations-for-figures}:
\begin{lstlisting}[language=modelica]
record Documentation
  /*literal*/ constant String info = "" "Description of the class";
  /*literal*/ constant String revisions = "" "Revision history";
  Figure[:] figures = {}; "Simulation result figures";
  /*literal*/ constant String[:] styleSheets = {} "Style sheets for documentation";
end Documentation;
\end{lstlisting}

The \lstinline!styleSheets! may also be given as a single string, see \cref{style-sheets}.

How the tool interprets the information in \lstinline!Documentation! is unspecified.

\subsection{Class Description and Revision History}\label{annotation-info-revisions}

Inside the \lstinline!Documentation! annotation, the \lstinline!info! annotation gives a textual description of the class, and the \lstinline!revisions! annotation gives a revision history.

\begin{nonnormative}
The \lstinline!revisions! documentation may be omitted in printed documentation.
\end{nonnormative}

If the string starts with the tag \lstinline!<html>! or \lstinline!<HTML>! the entire string is HTML encoded (and is assumed to end with \lstinline!</html>! or \lstinline!</HTML>! and shall be rendered as HTML even if the end-tags are missing), otherwise the entire string is rendered as is.
The HTML encoded content may contain links.
For external links, see \cref{external-resources}.
Links to Modelica classes may be defined with the HTML link command using scheme \lstinline!Modelica! (using its lower case form in the URI, see \cref{external-resources}), e.g.,
\begin{lstlisting}[language=modelica]
<a href="modelica:/MultiBody.Tutorial">MultiBody.Tutorial</a>
\end{lstlisting}

Together with scheme \lstinline!Modelica! the (URI) fragment specifiers
\lstinline!#diagram!, \lstinline!#info!, \lstinline!#text!, \lstinline!#icon! may be used to reference different
layers. User-defined fragment specifiers (anchors) may also be used, and they may be renamed
when generating HTML (in particular to avoid collisions).
Example:
\begin{lstlisting}[language=modelica]
<a href="modelica:/MultiBody.Joints.Revolute#info">Revolute</a>
\end{lstlisting}

\subsubsection{Style Sheets}\label{style-sheets}

Inside the \lstinline!Documentation! annotation, each element of the \lstinline!styleSheets! annotation array specifies a cascading style sheet.
The style sheets are used when displaying the \lstinline!info! and \lstinline!revisions! annotations found in the \lstinline!Documentation! annotations of the package.
The \lstinline!styleSheets! annotation is only considered for top-level packages, and applies to the entire package.
The style sheets will be cascaded in the given order.
Specifying just a string for \lstinline!styleSheets! has the same meaning as specifying a singleton array containing the string.
\begin{nonnormative}
It is recommended to use \lstinline[language=CSS]!class! and \lstinline[language=CSS]!id! selectors with a \lstinline[language=CSS]!$NameOfLibrary$-! prefix to avoid collisions when the content is included in a larger context.
\end{nonnormative}
The style sheet rules should not use type or universal selectors, due to possible interference with tool-specific styling.

Vendors should use a \lstinline[language=CSS]!$NameOfVendor$-! prefix to style vendor generated HTML content surrounding the user provided documentation.
If tools want to give users (of that tool) the possibility to override the tool-specific CSS they can document that.
The prefix is used to avoid this happening by accident.

\subsection{Figures}\label{annotations-for-figures}\label{figures}

Inside the \lstinline!Documentation! annotation, each element of the \lstinline!figures! annotation array has the following content:
\begin{lstlisting}[language=modelica]
record Figure
  /*literal*/ constant String title = "" "Title meant for display";
  /*literal*/ constant String identifier = "" "Identifier meant for programmatic access";
  /*literal*/ constant String group = "" "Name of figure group";
  /*literal*/ constant Boolean preferred = false "Automatically display figure after simulation";
  Plot[:] plots "Plots";
  /*literal*/ constant String caption = "" "Figure caption";
end Figure;
\end{lstlisting}

A \fmtannotationindex{Figure} is a graphical container that can contain several \lstinline!plots! described by \fmtannotationindex{Plot} annotations:
\begin{lstlisting}[language=modelica]
record Plot
  /*literal*/ constant String title "Title meant for display";
  /*literal*/ constant String identifier = "" "Identifier meant for programmatic access";
  Curve[:] curves "Plot curves";
  /*literal*/ constant Axis x "X axis properties";
  /*literal*/ constant Axis y "Y axis properties";
end Plot;
\end{lstlisting}

A \lstinline!Plot! can contain several \lstinline!curves!, see \cref{plot-curves}, that all share a common \lstinline!x! and \lstinline!y! axis with properties described in \cref{axis-properties}.

Both \lstinline!Figure! and \lstinline!Plot! can have an optional title.
When the \lstinline!Figure! \lstinline!title! is the empty string (the default), the tool must produce a non-empty title based on the figure content.
On the other hand, the \lstinline!Plot! \lstinline!title! has a tool-dependent default, but the default may be the empty string.
When the \lstinline!Plot! \lstinline!title! is the empty string, no title should be shown.
The plot title is not to be confused with the plot \emph{label} which is never empty, see below.
Variable replacements, as described in \cref{variable-replacements}, can be used in the \lstinline!title! of \lstinline!Figure! and \lstinline!Plot!.

The \lstinline!identifier! in \lstinline!Figure! and \lstinline!Plot! is a \lstinline!String! identifier, and is intended to identify the \lstinline!Figure! and \lstinline!Plot! for programmatic access.
The \lstinline!figures! annotation is inherited in the sense that each class has a collection of figures comprised by the contents of the \lstinline!figures! annotation in the class itself, as well as the \lstinline!figures! annotations from any base classes.
A \lstinline!Figure! must be uniquely identified by its \lstinline!identifier! and a class having it in its collection.
This means that a \lstinline!Figure! \lstinline!identifier! must be unique among all \lstinline!Figure! annotations within the same \lstinline!figures! annotation as well as among all \lstinline!figures! annotations from inherited classes.
A \lstinline!Plot! \lstinline!identifier! on the other hand is only required to be unique among the \lstinline!plots! in the the same \lstinline!Figure! annotation.
If an \lstinline!identifier! is an empty string it cannot be used for programmatic access and is exempt from the uniqueness requirements.

\begin{nonnormative}
For \lstinline!Figure!, this makes it possible to reference the plot from a tool-specific scripting environment.
For \lstinline!Plot!, this makes it possible to reference the plot in the figure caption, which becomes useful when the \lstinline!Figure! contains more than one \lstinline!Plot!.
\end{nonnormative}

% henrikt-ma 2020-06: Once there is Modelica URI support for referring to a figure in the collection of a class, it will be easier to explain
% the following statement.
Even though a \lstinline!Figure! annotation can be shared through inheritance between classes in a class hierarchy, note that each simulated class provides its own data to be displayed in the figure.

Every \lstinline!Plot! has an automatically generated \emph{label} which is required to be shown as soon as at least one \lstinline!Plot! in the \lstinline!Figure! has an \lstinline!identifier!.
A tool is free to choose both labeling scheme (such as \emph{a}, \emph{b}, \dots, or \emph{i}, \emph{ii}, \dots), placement in the plot, and styling in the plot itself as well as in other contexts.

When a \lstinline!Figure! defines a non-empty \lstinline!group!, it is used to organize figures similar to how \lstinline!group! is used in the \lstinline!Dialog! annotation (see \cref{annotations-for-the-graphical-user-interface}).
However, leaving \lstinline!group! at the default of an empty string does not mean that a group will be created automatically, but that the figure resides outside of any group.
The \lstinline!group! is both the key used for grouping, and the name of the group for display purposes.

The \lstinline!preferred! attribute of \lstinline!Figure! indicates whether the figure should be given preference when automatically determining which figures to show, and a class may define any number of \lstinline!preferred! figures.
For example, a tool might choose to automatically show all preferred figures when the class is simulated.

The \lstinline!caption! attribute of \lstinline!Figure! can use the restricted form of text markup described in \cref{text-markup-in-captions} as well as the variable replacements described in \cref{variable-replacements}.

\subsubsection{Axis Properties}\label{axis-properties}

Properties may be defined for each \lstinline!Plot! axis\annotationindex{Axis}:
\begin{lstlisting}[language=modelica]
record Axis
  /*literal*/ constant Real min "Axis lower bound, in 'unit'";
  /*literal*/ constant Real max "Axis upper bound, in 'unit'";
  /*literal*/ constant String unit = "" "Unit of axis tick labels";
  /*literal*/ constant String label "Axis label";
  /*literal*/ constant AxisScale scale = Linear() "Mapping between axis values and position on axis"
end Axis;
\end{lstlisting}

When an axis bound is not provided, the tool computes one automatically.

A non-empty \lstinline!unit! shall match \lstinline[language=grammar]!unit-expression! in \cref{unit-expressions}.
An empty \lstinline!unit! means that the axis is unitless, and each expression plotted against it may use its own unit determined by the tool.
The tool is responsible for conveying the information about choice of unit for the different variables, for instance by attaching this information to curve legends.

The Modelica tool is responsible for showing that values at the axis tick marks are expressed in \lstinline!unit!, so the axis \lstinline!label! shall not contain this information.

\begin{nonnormative}
When \lstinline!unit! is empty, and axis bounds are to be determined automatically, a natural choice of unit could be the variable's \lstinline!displayUnit!.  When axis bounds are specified by the user, on the other hand, a tool may choose a unit for the variable such that the range of the variable values (expressed in the chosen unit) fit nicely with the range of the unitless axis.
\end{nonnormative}

If a tool does not recognize the \lstinline!unit!, it is recommended to issue a warning and treat the \lstinline!unit! as if it was empty, as well as ignore any setting for \lstinline!min! and \lstinline!max!.

When \lstinline!label! is not provided, the tool produces a default label.
Providing the empty string as \lstinline!label! means that no label should be shown.
Variable replacements, as described in \cref{variable-replacements}, can be used in \lstinline!label!.
The Modelica tool is responsible for showing the unit used for values at the axis tick marks, so the axis \lstinline!label! shall not contain the unit.

The type of \lstinline!scale! is defined as an empty partial record:
\begin{lstlisting}[language=modelica]
partial record AxisScale
end AxisScale;
\end{lstlisting}%
\annotationindex{AxisScale}

The standardized annotations extending from \lstinline!AxisScale! are \lstinline!Linear! and  \lstinline!Log!, but it is also allowed to use a vendor-specific annotation.

Use \lstinline!Linear! for a linear mapping between axis values and position on axis:
\begin{lstlisting}[language=modelica]
record Linear
  extends AxisScale;
end Linear;
\end{lstlisting}%
\index{Linear@\robustinline{Linear} (axis scale)}

Use \lstinline!Log! for a logarithmic mapping between axis values and position on axis:
\begin{lstlisting}[language=modelica]
record Log
  extends AxisScale;
  /*literal*/ constant Integer base(min = 2) = 10;
end Log;
\end{lstlisting}%
\index{Log@\robustinline{Log} (axis scale)}

The \lstinline!base! of a \lstinline!Log! scale determines preferred positions of major axis ticks.
It is not required that the presentation of axis tick labels reflect the \lstinline!base! setting.
For example, when \lstinline!base! is 10, major axis ticks should preferrably be placed at integer powers of 10, and natural alternatives that a tool may use for major axis tick labels could look like $0.001$ or $10^{-3}$.
Under some circumstances, such as when the axis range does not span even a single order of magnitude, a tool may disregard the preference in order to get useful axis ticks.

\begin{example}
A \emph{symmetric log} axis scale is sometimes used for axes spanning across several orders of magnitude of both positive and negative values.
Details vary, but the mapping from value to linear position along axis is some variation of $y \mapsto \operatorname{sign}(y)\, \operatorname{log}(1 + \frac{\abs{y}}{10^{\alpha}})$.
A tool may implement this as a vendor-specific axis scale:
\begin{lstlisting}[language=modelica]
Axis(
  min = -1e5, max = 1e5,
  scale = __NameOfVendor_symlog(1),
)
\end{lstlisting}
\end{example}

\subsubsection{Plot Curves}\label{plot-curves}

The actual data to plot is specified in the \lstinline!curves!\annotationindex{Curve} of a \lstinline!Plot!:
\begin{lstlisting}[language=modelica]
record Curve
  expression x = time "X coordinate values";
  expression y "Y coordinate values";
  /*literal*/ constant String legend "Legend";
  /*literal*/ constant Integer zOrder = 0 "Drawing order control";
end Curve;
\end{lstlisting}

The mandatory \lstinline!x! and \lstinline!y! expressions are restricted to be result references in the form of \lstinline[language=grammar]!result-reference! in the grammar (\cref{expressions1}), referring to a scalar variable (or a derivative thereof) or \lstinline!time!.
It is an error if \lstinline!x! or \lstinline!y! does not designate a scalar result.
If \lstinline!x! or \lstinline!y! is a derivative, \lstinline!der(v, $n$)!, then $n$ must not exceed the maximum amount of differentiation applied to \lstinline!v! in the model.
A diagnostic is recommended in case the simulation result is missing a trajectory for a valid result reference.

\begin{nonnormative}
While the syntax for referring to a second order derivative is \lstinline!der(v, 2)!, the appearance is left for tools to decide.
For example, a tool might choose to present this as \lstinline!der(der(v))!.
\end{nonnormative}

When the \lstinline!unit! of an \lstinline!Axis! is non-empty, it is an error if the unit of the corresponding \lstinline!x! or \lstinline!y! expression (i.e., a variable's \lstinline!unit!, or second for \lstinline!time!) is incompatible with the axis unit.

When \lstinline!legend! is not provided, the tool produces a default based on \lstinline!x! and/or \lstinline!y!.
Providing the empty string as \lstinline!legend! means that the curve shall be omitted from the plot legend.
Variable replacements, as described in \cref{variable-replacements}, can be used in \lstinline!legend!.
The order of presentation within the plot legend corresponds to order of appearance in the \lstinline!curves! of a \lstinline!Plot!.

The \lstinline!zOrder! gives control over drawing order, with higher values corresponding to closer to front.
Ties are resolved using order of appearance in the \lstinline!curves! of a \lstinline!Plot!, with later appearance corresponding to closer to front.

\subsubsection{Escape Sequences}\label{text-markup-escape-sequences}

In an attribute inside a figure where the variable replacements of \cref{variable-replacements} or the text markup of \cref{text-markup-in-captions} can be used, the following use of \firstuse[text markup escape sequence]{text markup escape sequences}\index{escape sequence!text markup} applies.
These escape sequences are applied after the application of other markup, and is not applied at all inside some of the other markup, see details for the respective markup.

The percent character `\%' shall be encoded \lstinline!%%!.  The following are all the recognized escape sequences:
\begin{center}
\begin{tabular}{c c l}
\hline
\tablehead{Sequence} & \tablehead{Encoded character} & \tablehead{Comment}\\
\hline
\hline
{\lstinline!%%!} & `\%' & Only way to encode character. \\
{\lstinline!%]!} & `]'  & Prevents termination of markup delimited by {\lstinline![$\ldots$]!}. \\
\hline
\end{tabular}
\end{center}

\begin{nonnormative}
With the percent character being encoded as \lstinline!%%!, the behavior of \lstinline!%! appearing in any other way than the escape sequences above, for variable replacement (\cref{variable-replacements}), or for the text markup (\cref{text-markup-in-captions}) is undefined, and thus possible to define in the future without breaking backward compatibility.
\end{nonnormative}

\subsubsection{Variable Replacements}\label{variable-replacements}

In the places listed in \cref{attributes-with-variable-replacements} where text for display is defined, the final value of a result variable can be embedded by referring to the variable as \lstinline!%{inertia1.w}!.
This is similar to the \lstinline!Text! graphical primitive in \cref{text}.

\begin{table}[H]
\caption{Attributes that can use variable replacements.}
\label{attributes-with-variable-replacements}
\begin{center}
\begin{tabular}{l l}
\hline
\tablehead{Attribute} & \tablehead{Annotation}\\
\hline
\hline
{\lstinline!title!} & {\lstinline!Figure!} and {\lstinline!Plot!} \\
{\lstinline!caption!} & {\lstinline!Figure!} \\
{\lstinline!legend!} & {\lstinline!Curve!} \\
{\lstinline!label!} & {\lstinline!Axis!} \\
\hline
\end{tabular}
\end{center}
\end{table}

In \lstinline!%{$\mathit{variable}$}!, text markup escape sequences don't apply inside the $\mathit{variable}$, which has the form of \lstinline[language=grammar]!result-reference!.
This means that a complete \lstinline[language=grammar]!result-reference! shall be scanned before looking for the terminating closing brace.

\begin{example}
The variable replacement \lstinline!%{'%%'}! references the variable \lstinline!'%%'!, not the variable \lstinline!'%'!.
\end{example}

\begin{example}
The variable replacement \lstinline!%{foo . '}bar{'}! makes a valid reference to the variable\linebreak[4] \lstinline!foo.'}bar{'!.
\end{example}

Note that expansion to the final value means that expansion is not restricted to parameters and constants, so that values to be shown in a caption can be determined during simulation.

\begin{nonnormative}
By design, neither \lstinline!%class! nor \lstinline!%name! is supported in this context, as this information is expected to already be easily accessible (when applicable) in tool-specific ways.
(Titles making use of \lstinline!%class! or \lstinline!%name! would then only lead to ugly duplication of this information.)
\end{nonnormative}

\subsubsection{Text Markup in Captions}\label{text-markup-in-captions}

In addition to variable replacements, a very restricted form of text markup is used for the \lstinline!caption!.
Note that the text markup escape sequences described in \cref{text-markup-escape-sequences} generally apply inside \lstinline!caption!, with one exception given below for links.

Links take the form \lstinline!%[$\mathit{text}$]($\mathit{link}$)!, where the \lstinline![$\mathit{text}$]! part is optional, and text markup escape sequences don't apply inside the $\mathit{link}$.
The $\mathit{link}$ can be in either of the following forms, where the interpretation is given by the first matching form:
\begin{itemize}
\item
A \lstinline!variable:$\mathit{id}$!, where $\mathit{id}$ is a component reference in the form of \lstinline[language=grammar]!result-reference! in the grammar, such as \lstinline!inertia1.w!.
\item
% The 'plot:id' form below should be deprecated in favor of using an improved form of Modelica URI reference in the future, making 'variable:id' the only non-URI reference.
A \lstinline!plot:$\mathit{id}$!, where $\mathit{id}$ is the identifier of a \lstinline!Plot! in the current \lstinline!Figure!.
\item
% Use very short Modelica URI combined with carefully chosen wording below to deal with difficult line breaking.
A URI.
Well established schemes such as \lstinline[language={[nocomment]modelica}]!https://github.com/modelica! or \lstinline[language={[nocomment]modelica}]!modelica:/Modelica!, as well as lesser known schemes may be used.
(A tool that has no special recognition of a scheme can try sending the URI to the operating system for interpretation.)
\end{itemize}

When \lstinline![$\mathit{text}$]! is omitted, a Modelica tool is free to derive a default based on the $\mathit{link}$.

\begin{nonnormative}
Note that for the character `]' to appear in $\mathit{text}$, it needs to be encoded as the escape sequence \lstinline!%]!, or it would be interpreted as the terminating delimiter of the \lstinline![$\mathit{text}$]!.

Similarly, the closing parenthesis `)' must be handled with care in $\mathit{link}$ in order to not be interpreted as the terminating delimiter of the \lstinline!($\mathit{link}$)!.
\begin{itemize}
\item
For a \lstinline!variable:!, no special treatment is needed, as the component reference syntax of the $\mathit{id}$ allows parentheses to appear without risk of misinterpretation inside a quoted identifier.
For example, \lstinline"%(variable:'try)me!')" has a parenthesis in \lstinline"'try)me!'" that must not be mistaken for the end of the \lstinline!($\mathit{link}$)!.
% The following shortcoming would be resolved if the 'plot:id' form was replaced by a Modelica URI reference, thanks to URL encoding.
\item
For a \lstinline!plot:!, there is currently no way to reference a plot with `)' in its \lstinline!identifier!.
\item
For a URI, a closing parenthesis must be URL encoded in order to not be interpreted as the end of the \lstinline!($\mathit{link}$)!.
For example, the URL in \lstinline[language={[nocomment]modelica}]!%(http://example.org/(tryme))! is just \filename{http://example.org/(tryme}, and the entire link is followed by a stray closing parenthesis.
To make it work, one has to use URL encoding: \lstinline[language={[nocomment]modelica}]!%(http://example.org/%28tryme%29)! (using URL encoding of the opening parenthesis just for symmetry, and note that the \lstinline!%! of the percent-encoded sequences are not subject to text markup escape sequences).
\end{itemize}
\end{nonnormative}

The styling of the link text, as well as the link action, is left for each Modelica tool to decide.

\begin{nonnormative}
For example, \lstinline!%(variable:inertia1.w)! could be displayed as the text \lstinline!inertia1.w! formatted with upright monospaced font, and have a pop-up menu attached with menu items for plotting the variable, setting its start value, or investigating the equation system from which it is solved.
On the other hand, \lstinline!%[angular velocity](variable:inertia1.w)! could be formatted in the same style as the surrounding text, except some non-intrusive visual clue about it being linked.
\end{nonnormative}

\begin{nonnormative}
% This non-normative text explains why we don't want to assume that the 'link' must have a scheme.
Note that $\mathit{link}$ is currently not allowed to be a \emph{URI reference}, i.e., a URI or a \emph{relative reference} such as \lstinline!#foo!.
This is due to to the current inability to define a base URI referencing the current figure.
Once this becomes possible, the URI form of $\mathit{link}$ may be changed into a URI reference.
\end{nonnormative}

A sequence of one or more newlines (encoded either literally or using the \lstinline!\n! escape sequence) means a paragraph break.
(A line break within a paragraph is not supported, and any paragraph break before the first paragraph or after the last paragraph has no impact.)

\firstuse[vendor-specific markup]{Vendor-specific markup} takes the form \lstinline!%__$\mathit{nameOfVendor}_{1}$($\mathit{data}_{1}$)$\ldots$__$\mathit{nameOfVendor}_{n}$($\mathit{data}_{n}$)[$\mathit{text}$]!, where $n \geq 1$.
The $\mathit{nameOfVendor}$ consists of only digits and letters, and shall only convey the name of the vendor defining the meaning of the associated $\mathit{data}$.
Text markup escape sequences don't apply inside the $\mathit{data}$, implying that it cannot contain the closing parenthesis, `)'.
A tool which does not understand any of the vendor-specific meanings shall only display the mandatory $\mathit{text}$, but the $\mathit{text}$ may also be used together with the vendor-specific $\mathit{data}$.

\begin{example}
One application of vendor-specific markup is to prototype a feature that can later be turned into standardized markup.
For example, say that the tool AVendor wants to generalize the variable replacements such that the duration of a simulation can be substituted into a caption.
During the development, this could be represented as the vendor-specific markup \lstinline!%__AVendor(?duration)[10 s]!, if the simulation has a duration of 10~seconds at the time of writing the caption.
When AVendor renders this, it ignores the text \lstinline!10 s! and just displays the actual duration instead.
Later, if this would become supported by standard markup, it might take the form of something like \lstinline!%{experiment:duration}! instead (note that \lstinline!experiment:duration! is not in the form of a component reference, avoiding conflict with current use of variable replacements).

In a similar way, vendor-specific markup can be used to prototype a link for future inclusion in the link markup (either by extending the meaning of Modelica URIs, or by introducing another pseudo-scheme similar to \lstinline!variable:!).
This is an example where the vendor-specific markup could make use of the $\mathit{text}$ (for link text) together with the vendor-specific $\mathit{data}$ (describing the actual link).
\end{example}

\section{Symbolic Processing}\label{annotations-for-symbolic-processing}\label{symbolic-processing}

The annotation listed below, in addition to annotations described in \crefrange{derivatives-and-inverses-of-functions}{function-inlining-and-event-generation}, can influence the symbolic processing.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!Evaluate!} & Use parameter value for symbolic processing & \Cref{modelica:Evaluate}\\
\hline
\end{tabular}
\end{center}

\begin{annotationdefinition}[Evaluate]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant Boolean Evaluate;
\end{lstlisting}\end{synopsis}
\begin{semantics}
The annotation \lstinline!Evaluate! can occur in the component declaration, its type declaration, or a base class of the type-declaration.
In the case of multiple conflicting annotations it is handled similarly to modifiers (e.g., an \lstinline!Evaluate! annotation on the component declaration takes precedence).
In the case of hierarchical components it is applied to all components, overriding any \lstinline!Evaluate!-setting for specific components.
The annotation \lstinline!Evaluate! is only allowed for parameters and constants.

Setting \lstinline!Evaluate = true! for an evaluable parameter, means that it must be an evaluated parameter (i.e., its value must be determined during translation, similar to a constant).
For a non-evaluable parameter, it has no impact and it is recommended to issue a warning in most cases.
The exception for recommending this warning is when the parameter is non-evaluable due to dependency on a parameter with \lstinline!Evaluate = false!, as this could be a sign of intentional overriding of \lstinline!Evaluate = true!, see example below.
For both evaluable parameters and constants, the model developer further proposes to utilize the value for symbolic processing.
A constant can never be changed after translation, and it is normal for its value to be used for symbolic processing even without \lstinline!Evaluate = true!.

For a parameter, \lstinline!Evaluate = false! ensures that the parameter is a non-evaluable parameter according to \cref{component-variability} (meaning it is not allowed to be used where an evaluable expression (\cref{evaluable-expressions}) is expected).
For both parameters and constants -- even when the value can be determined during translation -- the model developer further proposes to not utilize the value for symbolic processing.

\begin{nonnormative}
\lstinline!Evaluate = true! is for example used for axis of rotation parameters in the \lstinline!Modelica.Mechanics.MultiBody! library in order to improve the efficiency of the generated code.

Conversely, a possible use of \lstinline!Evaluate = false! is to ensure that a parameter can be changed after translation, even when a tool might be tempted to evaluate it to improve the efficiency of the generated code.
\end{nonnormative}

\begin{example}
When a parameter has \lstinline!Evaluate = true! for optimization reasons (not because it needs to be evaluable), it is possible to prevent the value from being determined during translation without modifying the original model:
\begin{lstlisting}[language=modelica]
model M_evaluable
  /* Here, 'b' is evaluable, and will be evaluated. */
  parameter Boolean b = false annotation(Evaluate = true);
  Real x(start = 1.0, fixed = true);
equation
  if b then /* No need for b to be evaluable. */
    der(x) = x;
  else
    der(x) = -x;
  end if;
end M_evaluable;

model M_non_evaluable
  /* Here, 'bn' is non-evaluable, which in turn will cause 'b' to be
   * non-evaluable, thereby preventing it from being determined during
   * translation.
   */
  extends M_evaluable(b = bn);
  parameter Boolean bn = false annotation(Evaluate = false);
end M_non_evaluable;
\end{lstlisting}
\end{example}
\end{semantics}
\end{annotationdefinition}


\section{Simulations}\label{annotations-for-simulations}\label{simulations}

The annotations listed below define how models can be checked, translated, and simulated.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!experiment!} & Simulation experiment settings & \Cref{modelica:experiment}\\
{\lstinline!HideResult!} & Don't show component's simulation result & \Cref{modelica:HideResult}\\
{\lstinline!TestCase!} & Information for model used as test case & \Cref{modelica:TestCase}\\
\hline
\end{tabular}
\end{center}

\begin{annotationdefinition}[experiment]

\begin{synopsis}
\begin{lstlisting}[language=modelica]
record experiment
  /*literal*/ constant Real StartTime(unit = "s") = 0;
  /*literal*/ constant Real StopTime(unit = "s");
  /*literal*/ constant Real Interval(unit = "s");
  /*literal*/ constant Real Tolerance(unit = "1");
end experiment;
\end{lstlisting}
\end{synopsis}
\begin{semantics}
The \lstinline!experiment! annotation defines the start time (\lstinline!StartTime!) in {[}s{]}, the stop time (\lstinline!StopTime!) in {[}s{]}, the suitable time resolution for the result grid (\lstinline!Interval!) in {[}s{]}, and the relative integration tolerance (\lstinline!Tolerance!) for simulation experiments to be carried out with the model or block at hand.
When \lstinline!Interval! or \lstinline!Tolerance! is not provided, the tool is responsible for applying appropriate defaults.

The experiment options are inherited, and the derived class may override individual inherited options.
\begin{nonnormative}
The inheritance makes it useful to have an \lstinline!experiment! annotation also in partial models, e.g., a template for a number of similar test cases.
\end{nonnormative}

If \lstinline!StopTime! is set in a non-partial model, it is required to be a simulation model.
Tools can allow users to override these settings without modifying the model.
\end{semantics}
\end{annotationdefinition}

\begin{annotationdefinition}[HideResult]
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant Boolean HideResult;
\end{lstlisting}\end{synopsis}
\begin{semantics}
\lstinline!HideResult = true! defines that the model developer proposes to not show the simulation results of the corresponding component.

\lstinline!HideResult = false! defines that the developer proposes to show the corresponding component.

\begin{nonnormative}
For example, a tool is not expected to provide means to plot a variable with \lstinline!HideResult = true!.  If a variable is declared in a protected section, a tool might not include it in a simulation result. By setting \lstinline!HideResult = false!, the modeler would like to have the variable in the simulation result, even if in the protected section.

\lstinline!HideResult! is for example used in the connectors of the \lstinline!Modelica.StateGraph! library to not show variables to the modeler that are of no interest to him and would confuse him.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}

\begin{annotationdefinition}[TestCase]
\begin{synopsis}\begin{lstlisting}
record TestCase
  /*literal*/ constant Boolean shouldPass;
end TestCase;
\end{lstlisting}\end{synopsis}
\begin{semantics}
If \lstinline!shouldPass! is \lstinline!false! it indicates that the translation or the simulation of the model should fail.
If a tools checks a package where classes have \lstinline!shouldPass = false! they should not generate errors, and checking may even be skipped.
On the other hand, models with \lstinline!shouldPass = false! may be useful for creation of negative tests in tool-specific ways.
Similarly as a class with obsolete-annotation, a class with \lstinline!TestCase! annotation (regardless of the value of \lstinline!shouldPass!) shall not be used in other models, unless those models also have a \lstinline!TestCase! annotation.

\begin{nonnormative}
The intent of the test-case can be included in the documentation of the class.
This annotation can both be used for models intended as test-cases for implementations, and for models explaining detectable errors.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}


\section{Usage Restrictions}\label{usage-restrictions}
\subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label{single-use-of-class}

For state machines it is useful to have single instances of local classes.
This can be done using:
\begin{lstlisting}[language=modelica]
/*literal*/ constant Boolean singleInstance;
\end{lstlisting}

The annotation \fmtannotationindex{singleInstance}, if \lstinline!true!, in a class indicates that there should only be one component instance of the class, and it should be in the same scope as the class is defined.
The intent is to remove the class when the component is removed and to prevent duplication of the component.
If \lstinline!false!, it has no impact.

\subsection{Connection Restrictions}\label{connection-restrictions}

A connector component declaration may have the following annotation:
\begin{lstlisting}[language=modelica]
/*literal*/ constant String mustBeConnected;
\end{lstlisting}%
\annotationindex{mustBeConnected}

It makes it an error if the connector is not connected from the outside (for a conditional connector this check is only active if the connector is enabled).
The string value should provide the reason why it must be connected.
For an array of connectors it applies separately to each element.

\begin{nonnormative}
This annotation is intended for non-causal connectors, see \cref{restrictions-of-connections-and-connectors}.
It is particularly suited for stream connectors, see \cref{stream-connectors}.
\end{nonnormative}

\begin{example}
This can be used for some optional connectors that should be connected when conditionally enabled.
\begin{lstlisting}[language=modelica]
partial model PartialWithSupport
  Flange_b flange;
  parameter Boolean useSupport;
  Support support if useSupport
    annotation(
      mustBeConnected = "Support connector should be connected if activated.");
end PartialWithSupport;
\end{lstlisting}
The protected components and connections needed to internally handle the support-connector is omitted.
\end{example}

A connector component declaration may have the following annotation:
\begin{lstlisting}[language=modelica]
/*literal*/ constant String mayOnlyConnectOnce;
\end{lstlisting}%
\annotationindex{mayOnlyConnectOnce}

It makes it an error if the connector is connected from the outside and:
\begin{itemize}
\item For non-stream connectors the connection set has more than two elements.
\item For stream connectors (see \cref{stream-connectors}), the connection set has more than two elements whose flow variable may be negative (based on evaluation of the \lstinline!min!-attribute).
\end{itemize}
For an array of connectors it applies separately to each element.
The string value should provide the reason why it may only be connected once.

\begin{nonnormative}
This annotation is intended for non-causal connectors, see \cref{restrictions-of-connections-and-connectors}.
The connection handling operates on connection sets, and thus this restriction should also operate on those sets.
The set handling avoids the case where only one of two equivalent models generate diagnostics.
The stream connector part is primarily intended to exclude sensor-variables, see \cref{connection-of-3-stream-connectors-where-one-mass-flow-rate-is-identical-to-zero-n-3-and}, but also excludes non-reversible outgoing flows.
\end{nonnormative}

\begin{example}
This can be used for components that implement mixing of fluids where it is not desired to combine that with the normal stream-connector mixing.
\begin{lstlisting}[language=modelica]
partial model MultiPort
  parameter Integer n = 0 annotation(Dialog(connectorSizing = true));
  FluidPort_a port_a(redeclare package Medium = Medium);
  FluidPorts_b ports_b[n](redeclare each package Medium = Medium)
    annotation (mayOnlyConnectOnce = "Should only connect once per element!");
end MultiPort;
\end{lstlisting}
\end{example}

\section{Graphical Objects}\label{annotations-for-graphical-objects}\label{graphical-objects}

A graphical representation of a class consists of two abstraction
layers, icon layer and diagram layer showing graphical objects,
component icons, connectors and connection lines. The icon
representation typically visualizes the component by hiding hierarchical
details. The hierarchical decomposition is described in the diagram
layer showing icons of subcomponents and connections between these.

Graphical annotations described in this chapter ties into the Modelica
grammar as follows.
\begin{lstlisting}[language=grammar]
graphical-annotations :
  annotation "(" [ layer-annotations ] ")"

layer-annotations :
  ( icon-layer | diagram-layer ) [ "," layer-annotations ]
\end{lstlisting}
Layer descriptions (start of syntactic description):
\begin{lstlisting}[language=grammar]
icon-layer :
  "Icon" "(" [ coordsys-specification "," ] graphics ")"

diagram-layer :
  "Diagram" "(" [ coordsys-specification "," ] graphics ")"
\end{lstlisting}%
\annotationindex{Icon}\annotationindex{Diagram}

\begin{example}
\begin{lstlisting}[language=modelica]
annotation(
   Icon(coordinateSystem(extent = {{-100, -100}, {100, 100}}),
        graphics = {Rectangle(extent = {{-100, -100}, {100, 100}}),
                    Text(extent = {{-100, -100}, {100, 100}},
                         textString = "Icon")}));
\end{lstlisting}
\end{example}

The graphics is specified as an ordered sequence of graphical primitives described below.
Base class contents are drawn behind the graphical primitives of the current class, with base classes ordered from back to front according to the order of the \lstinline!extends!-clauses, and graphical primitives according to order of appearance in the annotation.

\begin{nonnormative}
Note that the ordered sequence is syntactically a valid Modelica annotation, although there
is no mechanism for defining an array of heterogeneous objects in Modelica.
\end{nonnormative}

These \lstinline!Icon!, \lstinline!Diagram!, and \lstinline!Documentation! annotations are only allowed directly in classes (e.g., not on components or connections).
The allowed annotations for a short class definition is the union of the allowed annotations in classes and on \lstinline!extends!-clauses.

\subsection{Common Definitions}\label{common-definitions}

The following common definitions are used to define graphical annotations in the later sections.
\begin{lstlisting}[language=modelica]
type DrawingUnit = Real(final unit="mm");
type Point = DrawingUnit[2] "{x, y}";
type Extent = Point[2] "Defines a rectangular area {{x1, y1}, {x2, y2}}";
\end{lstlisting}%
\annotationindex{DrawingUnit}\annotationindex{Point}\annotationindex{Extent}
The interpretation of \lstinline!unit! is with respect to printer output in natural size (not zoomed).

All graphical entities have a visible attribute which indicates if the entity should be shown.
\begin{lstlisting}[language=modelica]
partial record GraphicItem
  Boolean visible = true;
  Point origin = {0, 0};
  Real rotation(quantity="angle", unit="deg")=0;
end GraphicItem;
\end{lstlisting}%
\annotationindex{GraphicItem}
The \lstinline!origin! attribute specifies the origin of the graphical item in the coordinate system of the layer in which it is defined.
The origin is used to define the geometric information of the item and for all transformations applied to the item.
All geometric information is given relative the \lstinline!origin! attribute, which by default is \lstinline!{0, 0}!.

The \lstinline!rotation! attribute specifies the rotation of the graphical item
counter-clockwise around the point defined by the \lstinline!origin! attribute.

\subsubsection{Coordinate Systems}\label{coordinate-systems}

Each of the layers has its own coordinate system.\annotationindex{CoordinateSystem}
A coordinate system is defined by the coordinates of two points, the left (x1) lower (y1) corner and the right (x2) upper (y2) corner, where the coordinates of the first point shall be less than the coordinates of the second point.

The attribute \lstinline!preserveAspectRatio! specifies a hint for the shape of
components of the class, but does not actually influence the rendering of the component.
If \lstinline!preserveAspectRatio! is true, changing the
extent of components should preserve the current aspect ratio of the coordinate
system of the class.

The attribute \lstinline!initialScale! specifies the default component size as
\lstinline!initialScale! times the size of the coordinate system of the class. An
application may use a different default value of \lstinline!initialScale!.

The attribute \lstinline!grid! specifies the spacing between grid points which can
be used by tools for alignment of points in the coordinate system, e.g., ``snap-to-grid''.
Its use and default value is tool-dependent.

\begin{lstlisting}[language=modelica]
record CoordinateSystem
  /*literal*/ constant Extent extent;
  /*literal*/ constant Boolean preserveAspectRatio = true;
  /*literal*/ constant Real initialScale = 0.1;
  /*literal*/ constant DrawingUnit grid[2];
end CoordinateSystem;
\end{lstlisting}

\begin{example}
A coordinate system for an icon could for example be defined as:
\begin{lstlisting}[language=modelica]
CoordinateSystem(extent = {{-10, -10}, {10, 10}});
\end{lstlisting}
i.e., a coordinate system with width 20 units and height 20 units.
\end{example}

The coordinate systems for the icon and diagram layers are by default defined as follows; where the array of \lstinline!GraphicItem! represents an ordered list of graphical primitives.

\begin{lstlisting}[language=modelica]
record Icon "Representation of the icon layer"
  CoordinateSystem coordinateSystem(extent = {{-100, -100}, {100, 100}});
  GraphicItem[:] graphics;
end Icon;

record Diagram "Representation of the diagram layer"
  CoordinateSystem coordinateSystem(extent = {{-100, -100}, {100, 100}});
  GraphicItem[:] graphics;
end Diagram;
\end{lstlisting}
The coordinate system attributes (\lstinline!extent! and \lstinline!preserveAspectRatio!) of a class are separately defined by the following priority:
\begin{enumerate}
\item
  The coordinate system annotation given in the class (if specified).
\item
  The coordinate systems of the first base class where the extent on the \lstinline!extends!-clause specifies a null-region (if any).
  Note that null-region is the default for base classes, see \cref{extends-clause}.
\item
  The default coordinate system \lstinline!CoordinateSystem(preserveAspectRatio=true, extent = {{-100, -100}, {100, 100}})!.
\end{enumerate}

\subsubsection{Graphical Properties}\label{graphical-properties}

Properties of graphical objects and connection lines are described using the following attribute types.
\begin{lstlisting}[language=modelica]
type Color = Integer[3](min = 0, max = 255) "RGB representation";
constant Color Black = zeros(3);
type LinePattern = enumeration(None, Solid, Dash, Dot, DashDot, DashDotDot);
type FillPattern = enumeration(None, Solid, Horizontal, Vertical,
                               Cross, Forward, Backward, CrossDiag,
                               HorizontalCylinder, VerticalCylinder, Sphere);
type BorderPattern = enumeration(None, Raised, Sunken, Engraved);
type Smooth = enumeration(None, Bezier);
type EllipseClosure = enumeration(None, Chord, Radial);
\end{lstlisting}%
\annotationindex{Color}\annotationindex{LinePattern}\annotationindex{FillPattern}\annotationindex{BorderPattern}\annotationindex{Smooth}\annotationindex{EllipseClosure}
The \lstinline!LinePattern! attribute \lstinline!Solid! indicates a normal line, \lstinline!None! an invisible line, and the other attributes various forms of dashed/dotted lines.

The \lstinline!FillPattern! attributes \lstinline!Horizontal!, \lstinline!Vertical!, \lstinline!Cross!, \lstinline!Forward!, \lstinline!Backward! and \lstinline!CrossDiag! specify fill patterns drawn with the line color over the fill color.

The attributes \lstinline!HorizontalCylinder!, \lstinline!VerticalCylinder! and \lstinline!Sphere! specify
gradients that represent a horizontal cylinder, a vertical cylinder and
a sphere, respectively. The gradient goes from line color to fill color.

The border pattern attributes \lstinline!Raised!, \lstinline!Sunken! and \lstinline!Engraved! represent frames which are rendered in a tool-dependent way --- inside the extent of the filled shape.

\begin{figure}[H]
  \begin{center}
    \includegraphics{bezierpoints}
  \end{center}
  \caption{Line with \lstinline!smooth = Bezier!.  The four line points $P_{1}$, \ldots{}, $P_{4}$ result in two quadratic splines and two straight line segments.}\label{fig:smooth-bezier}
\end{figure}

The \lstinline!smooth! attribute specifies that a line can be drawn as straight line segments (\lstinline!None!) or using a spline (\lstinline!Bezier!), where the line's points specify control points of a quadratic Bezier curve, see \cref{fig:smooth-bezier}.

For lines with only two points, the \lstinline!smooth! attribute has no effect.

For lines with three or more points ($P_{1}$, $P_{2}$, \ldots{}, $P_{n}$), the middle point of each line segment ($P_{12}$, $P_{23}$, \ldots{}, $P_{(n-1)n}$) becomes the starting point and ending
points of each quadratic Bezier curve.  For each quadratic Bezier curve, the common point of the two line segment becomes the control point. For instance, point $P_{2}$ becomes the control point for
the Bezier curve starting at $P_{12}$ and ending at $P_{23}$.  A straight line is drawn between the starting point of the line and the starting point of the first quadratic Bezier curve, as well as
between the ending point of the line and the ending point of the last quadratic Bezier curve.

In the illustration above, the square points ($P_{1}$, $P_{2}$, $P_{3}$, and $P_{4}$) represent the points that define the line, and the circle points ($P_{12}$, $P_{23}$, and $P_{34}$) are the
calculated middle points of each line segment.  Points $P_{12}$, $P_{2}$, and $P_{23}$ define the first quadratic Bezier curve, and the points $P_{23}$, $P_{3}$, and $P_{34}$ define the second
quadratic Bezier curve.  Finally a straight line is drawn between points $P_{1}$ and $P_{12}$ as well as between $P_{34}$ and $P_{4}$.

The values of the \lstinline!EllipseClosure! enumeration specify if and how the endpoints of an elliptical arc are to be joined (see \cref{ellipse}).

\begin{lstlisting}[language=modelica]
type Arrow = enumeration(None, Open, Filled, Half);
type TextStyle = enumeration(Bold, Italic, UnderLine);
type TextAlignment = enumeration(Left, Center, Right);
\end{lstlisting}%
\annotationindex{Arrow}\annotationindex{TextStyle}\annotationindex{TextAlignment}

Filled shapes have the following attributes for the border and interior.
\begin{lstlisting}[language=modelica]
record FilledShape "Style attributes for filled shapes"
  Color lineColor = Black "Color of border line";
  Color fillColor = Black "Interior fill color";
  LinePattern pattern = LinePattern.Solid "Border line pattern";
  FillPattern fillPattern = FillPattern.None "Interior fill pattern";
  DrawingUnit lineThickness = 0.25 "Line thickness";
end FilledShape;
\end{lstlisting}%
\annotationindex{FilledShape}
The extent/points of the filled shape describe the theoretical zero-thickness filled shape, and the actual rendered border is then half inside and half outside the extent.

\subsection{Component Instance}\label{component-instance}

A component instance can be placed within a diagram or icon layer.
It has an annotation with a \lstinline!Placement! modifier to describe the placement.
Placements are defined in terms of coordinate system transformations:
\begin{lstlisting}[language=modelica]
record Transformation
  Extent extent;
  Real rotation(quantity = "angle", unit = "deg") = 0;
  Point origin = {0, 0};
end Transformation;
\end{lstlisting}%
\annotationindex{Transformation}
The attributes are applied in the order \lstinline!extent!, \lstinline!rotation!, \lstinline!origin!, as follows:
\begin{enumerate}
\item
  The \lstinline!extent! of the component icon is mapped to the \lstinline!extent! rectangle (possibly shifting, scaling, and flipping contents).
\item
  The \lstinline!rotation! specifies counter-clockwise rotation around the origin (that is \lstinline!{0, 0}!, not the \lstinline!origin! attribute).
\item
  The \lstinline!origin! specifies a shift (moving \lstinline!{0, 0}! to \lstinline!origin!).
\end{enumerate}

\begin{lstlisting}[language=modelica]
record Placement
  Boolean visible = true;
  Transformation transformation "Placement in the diagram layer";
  Boolean iconVisible "Visible in icon layer; for public connector";
  Transformation iconTransformation
    "Placement in the icon layer; for public connector";
end Placement;
\end{lstlisting}%
\annotationindex{Placement}
If no \lstinline!iconTransformation! is given the \lstinline!transformation! is also used for placement in the icon layer.
If no \lstinline!iconVisible! is given for a public connector the \lstinline!visible! is also used for visibility in the icon layer.

\begin{nonnormative}
A connector can be shown in both an icon layer and a diagram
layer of a class. Since the coordinate systems typically are different,
placement information needs to be given using two different coordinate
systems. More flexibility than just using scaling and translation is
needed since the abstraction views might need different visual placement
of the connectors. The attribute \lstinline!transformation! gives the placement in
the diagram layer and \lstinline!iconTransformation! gives the placement in the icon
layer. When a connector is shown in a diagram layer, its diagram layer
is shown to facilitate opening up a hierarchical connector to allow
connections to its internal subconnectors.
\end{nonnormative}

For connectors, the icon layer is used to represent a connector when it
is shown in the icon layer of the enclosing model. The diagram layer of
the connector is used to represent it when shown in the diagram layer of
the enclosing model. Protected connectors are only shown in the diagram
layer. Public connectors are shown in both the diagram layer and the
icon layer. Non-connector components are only shown in the diagram
layer.

\subsection{Extends-Clause}\label{extends-clause}

Each \lstinline!extends!-clause (and short class definition, as stated in \cref{annotations-for-graphical-objects}) may have layer specific annotations which describe the rendering of the base class' icon and diagram layers in the derived class.

\begin{lstlisting}[language=modelica]
record IconMap
  /*literal*/ constant Extent extent = {{0, 0}, {0, 0}};
  /*literal*/ constant Boolean primitivesVisible = true;
end IconMap;

record DiagramMap
  /*literal*/ constant Extent extent = {{0, 0}, {0, 0}};
  /*literal*/ constant Boolean primitivesVisible = true;
end DiagramMap;
\end{lstlisting}%
\annotationindex{IconMap}\annotationindex{DiagramMap}
All graphical objects are by default inherited from a base class.
If the \lstinline!primitivesVisible! attribute is false, components and connections are visible but graphical primitives are not.

\begin{itemize}
\item
  If the \lstinline!extent! is \lstinline!{{0, 0}, {0, 0}}! (the default), the base class contents is mapped to the same coordinates in the derived class, and the coordinate system (including \lstinline!preserveAspectRatio!) can be inherited as described in \cref{coordinate-systems}.
\item
  For any other \lstinline!extent!, the base class coordinate system is mapped to this region, with the exception that \lstinline!preserveAspectRatio = true! in the base class requires that the mapping shall preserve the aspect ratio.
  The base class coordinate system (and \lstinline!preserveAspectRatio!) is not inherited.
\end{itemize}

\begin{nonnormative}
A zero area \lstinline!extent! other than \lstinline!{{0, 0}, {0, 0}}! will result in none of the base class contents being visible.
By affecting components and connections as well as graphical primitives, this is different from setting \lstinline!primitivesVisible = false!.

Reversed corners of the \lstinline!extent! will result in mirrored (rotated if reversed in both direction) base class contents.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica]
model A
  extends B annotation(
    IconMap(extent = {{-100, -100}, {100, 100}}, primitivesVisible = false),
    DiagramMap(extent = {{-50, -50}, {0, 0}}, primitivesVisible = true)
  );
end A;

model B
  extends C annotation(DiagramMap(primitivesVisible = false));
  $\ldots$
end B;
\end{lstlisting}
In this example the diagram of \lstinline!A! contains the graphical primitives
from \lstinline!A! and \lstinline!B! (but not from \lstinline!C! since they were hidden in \lstinline!B!) -- the ones
from \lstinline!B! are rescaled, and the icon of \lstinline!A! contains the graphical primitives
from \lstinline!A! (but neither from \lstinline!B! nor from \lstinline!C!).
\end{example}

\subsection{Connections}\label{connections1}

A connection is specified with an annotation containing a \lstinline!Line!\index{Line@\robustinline{Line}!\robustinline{connect} annotation} primitive and optionally a \lstinline!Text! primitive, as specified below.

\begin{example}
\begin{lstlisting}[language=modelica]
connect(a.x, b.x)
  annotation(Line(points = {{-25, 30}, {10, 30}, {10, -20}, {40, -20}}));
\end{lstlisting}
\end{example}

The optional \lstinline!Text!\index{Text@\robustinline{Text}!\robustinline{connect} annotation} primitive defines a text that will be written on the connection line.
It has the following definition (it is not equal to the \lstinline!Text! primitive as part of graphics -- the differences are marked after \emph{Note} in the description-strings):
\begin{lstlisting}[language=modelica]
record Text
  extends GraphicItem;
  Extent extent;
  String string "Note: different name";
  Real fontSize = 0 "unit pt";
  String fontName;
  TextStyle textStyle[:];
  Color textColor = Black;
  TextAlignment horizontalAlignment =
    if index < 0 then TextAlignment.Right else TextAligment.Left "Note: different default";
  Integer index "Note: new";
end Text;
\end{lstlisting}

The \lstinline!index! is one of the points of Line (numbered 1, 2, 3, \ldots{} where negative numbers count from the end, thus -1 indicate the last one).
The \lstinline!string! may use the special symbols \lstinline!"%first"! and \lstinline!"%second"! to indicate the connectors in the \lstinline!connect!-equation.

The \lstinline!extent! and \lstinline!rotation! are relative to the \lstinline!origin! (default \lstinline!{0, 0}!) and the \lstinline!origin! is relative to the point on the \lstinline!Line!.

The \lstinline!textColor! attribute defines the color of the text.  The text is drawn with transparent background and no border around the text (and without outline).  The contents inherited from \lstinline!FilledShape! is deprecated, but kept for compatibility reasons.  The default value for \lstinline!horizontalAlignment! is deprecated.  Having a zero size for the \lstinline!extent! is deprecated and is handled as if upper part is moved up an appropriate amount.

\begin{example}
\begin{lstlisting}[language=modelica]
connect(controlBus.axisControlBus1, axis1.axisControlBus)
  annotation(
    Text(string = "%first", index = -1, extent = [-6, 3; -6, 7]),
    Line(points = {{41, 30}, {50, 30}, {50, 50}, {58, 50}})
  );
\end{lstlisting}
Draws a connection line and adds the text \emph{axisControlBus1} ending at $(-6,\, 3) + (58,\, 50)$ and 4 vertical units of space for the text.
Using a height of zero, such as \lstinline!extent = [-6, 3; -6, 3]! is deprecated, but gives similar result.
\end{example}

\subsection{Graphical Primitives}\label{graphical-primitives}

This section describes the graphical primitives that can be used to
define the graphical objects in an annotation.

\subsubsection{Line}\label{line}

A line is specified as follows:
\begin{lstlisting}[language=modelica]
record Line
  extends GraphicItem;
  Point points[:];
  Color color = Black;
  LinePattern pattern = LinePattern.Solid;
  DrawingUnit thickness = 0.25;
  Arrow arrow[2] = {Arrow.None, Arrow.None} "{start arrow, end arrow}";
  DrawingUnit arrowSize = 3;
  Smooth smooth = Smooth.None "Spline";
end Line;
\end{lstlisting}%
\annotationindex{Line}
Note that the \lstinline!Line! primitive is also used to specify the graphical representation of a connection.

For arrows:
\begin{itemize}
\item
  The arrow is drawn with an aspect ratio of 1/3 for each arrow half, i.e., if the arrow-head is 3~mm long an arrow with \lstinline!Half! will extend 1~mm from the mid-line and with \lstinline!Open! or \lstinline!Filled! extend 1~mm to each side, in total making the base 2~mm wide.
\item
  The \lstinline!arrowSize! gives the width of the arrow (including the imagined other half for \lstinline!Half!) so that \lstinline!lineThickness = 10! and \lstinline!arrowSize = 10! will touch at the outer parts.
\item
  All arrow variants overlap for overlapping lines.
\item
  The lines for the \lstinline!Open! and \lstinline!Half! variants are drawn with \lstinline!lineThickness!.
\end{itemize}

\subsubsection{Polygon}\label{polygon}

A polygon is specified as follows:
\begin{lstlisting}[language=modelica]
record Polygon
  extends GraphicItem;
  extends FilledShape;
  Point points[:];
  Smooth smooth = Smooth.None "Spline outline";
end Polygon;
\end{lstlisting}%
\annotationindex{Polygon}
The polygon is automatically closed, if the first and the last points are not identical.

\subsubsection{Rectangle}\label{rectangle}

A rectangle is specified as follows:
\begin{lstlisting}[language=modelica]
record Rectangle
  extends GraphicItem;
  extends FilledShape;
  BorderPattern borderPattern = BorderPattern.None;
  Extent extent;
  DrawingUnit radius = 0 "Corner radius";
end Rectangle;
\end{lstlisting}%
\annotationindex{Rectangle}
The \lstinline!extent! attribute specifies the bounding box of the rectangle.
If the \lstinline!radius! attribute is specified, the rectangle is drawn with rounded corners of the given radius.

\subsubsection{Ellipse}\label{ellipse}

An ellipse is specified as follows:
\begin{lstlisting}[language=modelica]
record Ellipse
  extends GraphicItem;
  extends FilledShape;
  Extent extent;
  Real startAngle(quantity = "angle", unit = "deg") = 0;
  Real endAngle(quantity = "angle", unit = "deg") = 360;
  EllipseClosure closure =
    if startAngle == 0 and endAngle == 360 then
      EllipseClosure.Chord
    else
      EllipseClosure.Radial;
end Ellipse;
\end{lstlisting}%
\annotationindex{Ellipse}
The \lstinline!extent! attribute specifies the bounding box of the ellipse.

Partial ellipses can be drawn using the \lstinline!startAngle! and \lstinline!endAngle! attributes.  These specify the endpoints of the arc prior to the stretch and rotate operations.  The arc is drawn counter-clockwise from \lstinline!startAngle! to \lstinline!endAngle!, where \lstinline!startAngle! and \lstinline!endAngle! are defined counter-clockwise from 3 o'clock (the positive x-axis).

The closure attribute specifies whether the endpoints specified by \lstinline!startAngle! and \lstinline!endAngle! are to be joined by lines to the center of the extent (\lstinline!closure = EllipseClosure.Radial!), joined by a single straight line between the end points (\lstinline!closure = EllipseClosure.Chord!), or left unconnected (\lstinline!closure = EllipseClosure.None!).  In the latter case, the ellipse is treated as an open curve instead of a closed shape, and the \lstinline!fillPattern! and \lstinline!fillColor! are not applied (if present, they are ignored).

The default closure is \lstinline!EllipseClosure.Chord! when \lstinline!startAngle! is 0 and \lstinline!endAngle! is 360, or \lstinline!EllipseClosure.Radial! otherwise.

\begin{nonnormative}
The default for a closed ellipse is not \lstinline!EllipseClosure.None!, since that would result in \lstinline!fillColor!
and \lstinline!fillPattern! being ignored, making it impossible to draw a filled ellipse. \lstinline!EllipseClosure.Chord!
is equivalent in this case, since the chord will be of zero length.
\end{nonnormative}

\subsubsection{Text}\label{text}

A text string is specified as follows:
\begin{lstlisting}[language=modelica]
record Text
  extends GraphicItem;
  Extent extent;
  String textString;
  Real fontSize = 0 "unit pt";
  String fontName;
  TextStyle textStyle[:];
  Color textColor = Black;
  TextAlignment horizontalAlignment = TextAlignment.Center;
end Text;
\end{lstlisting}%
\annotationindex{Text}
The \lstinline!textColor! attribute defines the color of the text.
The text is drawn with transparent background and no border around the text (and without outline).

There are a number of common macros that can be used in the text, and they should be replaced when displaying the text as follows (in order such that the earliest ones have precedence, and using the longest sequence of identifier characters -- alphanumeric and underscore):
\begin{itemize}
\item
  \%\% replaced by \%
\item
  \%name replaced by the name of the component (i.e., the identifier for it in the enclosing class).
\item
  \%class replaced by the name of the class (only the last part of the hierarchical name).
\item
  \%\emph{par} and \%\{\emph{par}\} replaced by the value of the parameter \lstinline!par!.
  If the value is numeric, tools shall display the value with \lstinline!displayUnit!, formatted according to the BIPM specification.
  E.g., for
\begin{lstlisting}[language=modelica]
parameter Real t(unit = "s", displayUnit = "ms") = 0.1
\end{lstlisting}
  tools shall display \emph{100 ms}.
  The intent is that the text is easily readable, thus if \lstinline!par! is of an enumeration type, replace \%\emph{par} by the item name, not by the full name.
  \begin{example}
  If \lstinline!par = "Modelica.Blocks.Types.Enumeration.Periodic"!, then \%\emph{par} should be displayed as \emph{Periodic}.
  \end{example}
  When quoted identifiers (e.g., \lstinline!rec.'}'.'quoted ident'!) are involved, the form \%\{\emph{par}\} must be used.
  Here, \emph{par} is a general \lstinline[language=grammar]!component-reference!, and the macro can be directly followed by a letter.
  Thus \lstinline!%{w}x%{h}! gives the value of \lstinline!w! directly followed by \emph{x} and the value of \lstinline!h!, while \lstinline!%wxh! gives the value of the parameter \lstinline!wxh!.
  If the parameter does not exist it is an error.
\end{itemize}

The style attribute \lstinline!fontSize! specifies the font size.
If the \lstinline!fontSize! attribute is 0 the text is scaled to fit its extent.
Otherwise, the size specifies the absolute size.
The text is vertically centered in the extent.

If the \lstinline!extent! specifies a box with zero width and positive height the height is used as height for the text (unless \lstinline!fontSize! attribute is non-zero -- which specifies the absolute size), and the text is not truncated (the \lstinline!horizontalAlignment! is still used in this case).

\begin{nonnormative}
A zero-width \lstinline!extent! is convenient for handling texts where the width is unknown.
\end{nonnormative}

If the string \lstinline!fontName! is empty, the tool may choose a font.
The font names \lstinline!"serif"!, \lstinline!"sans-serif"!, and \lstinline!"monospace"! shall be recognized.
If possible the correct font should be used -- otherwise a reasonable match, or treat as if \lstinline!fontName! was empty.

The style attribute \lstinline!textStyle! specifies variations of the font.

\subsubsection{Bitmap}\label{bitmap}

A bitmap image is specified as follows:
\begin{lstlisting}[language=modelica]
record Bitmap
  extends GraphicItem;
  Extent extent;
  String fileName "Name of bitmap file";
  String imageSource "Base64 representation of bitmap";
end Bitmap;
\end{lstlisting}%
\annotationindex{Bitmap}
The \lstinline!Bitmap! primitive renders a graphical bitmap image.
The data of the image can either be stored on an external file or in the annotation itself.
The image is scaled to fit the extent.
Given an extent \lstinline!{{$x_{1}$, $y_{1}$}, {$x_{2}$, $y_{2}$}}!, $x_{2} < x_{1}$ defines horizontal flipping and $y_{2} < y_{1}$ defines vertical flipping around the center of the object.

The graphical operations are applied in the order: scaling, flipping and rotation.

When the attribute \lstinline!fileName! is specified, the string refers to an
external file containing image data. The mapping from the string to the
file is specified for some URIs in \cref{external-resources}. The supported file
formats include \lstinline!PNG!, \lstinline!BMP!, \lstinline!JPEG!,
and \lstinline!SVG!.

When the attribute \lstinline!imageSource! is specified, the string contains the
image data, and the image format is determined based on the contents.
The image is represented as a Base64 encoding of the image file format
(see RFC~4648, \url{http://tools.ietf.org/html/rfc4648}).

The image is uniformly scaled (preserving the aspect ratio) so it exactly fits within the extent (touching the
extent along one axis).  The center of the image is positioned at the center of the extent.

\subsection{Variable Graphics and Schematic Animation}\label{variable-graphics-and-schematic-animation}

Any value (coordinates, color, text, etc.) in graphical annotations can be dependent on class variables using \lstinline!DynamicSelect!.
\lstinline!DynamicSelect! has the syntax of a function call with two arguments, where the first argument specifies the value of the editing state and the second argument the value of the non-editing state.
The first argument must be a literal expression.
The second argument may contain references to variables to enable a dynamic behavior.

\begin{example}
The level of a tank could be animated by a rectangle expanding in vertical direction and its color depending on a variable overflow:
\begin{lstlisting}[language=modelica]
annotation(Icon(graphics = {
  Rectangle(
    extent =
      DynamicSelect({{0, 0}, {20, 20}},
                    {{0, 0}, {20, level}}),
    fillColor =
      DynamicSelect({0, 0, 255},
                    if overflow then {255, 0, 0} else {0, 0, 255})
  )}));
\end{lstlisting}
\end{example}

\subsection{User Input}\label{user-input}

It is possible to interactively modify variables during a simulation.  The variables may either be parameters, discrete-time variables or states.  New numeric values can be given, a mouse click can change a \lstinline!Boolean! variable or a mouse movement can change a \lstinline!Real! variable.  Input fields may be associated with a \lstinline!GraphicItem! or a component as an array named \lstinline!interaction!.  The \lstinline!interaction! array may occur as an attribute of a graphic primitive, an attribute of a component annotation or as an attribute of the layer annotation of a class.

\subsubsection{Mouse Input}\label{mouse-input}

A \lstinline!Boolean! variable can be changed when the cursor is held over a graphical item or component and the selection button is pressed if the interaction annotation contains \fmtannotationindex{OnMouseDownSetBoolean}:
\begin{lstlisting}[language=modelica]
record OnMouseDownSetBoolean
  Boolean variable "Name of variable to change when mouse button pressed";
  Boolean value "Assigned value";
end OnMouseDownSetBoolean;
\end{lstlisting}

\begin{example}
A button can be represented by a rectangle changing color depending on a \lstinline!Boolean! variable \lstinline!on! and toggles the
variable when the rectangle is clicked on:
\begin{lstlisting}[language=modelica]
annotation(Icon(
  graphics = {
    Rectangle(extent = [0, 0; 20, 20],
              fillColor = if on then {255, 0, 0} else {0, 0, 255})},
  interaction = {OnMouseDownSetBoolean(on, not on)}));
\end{lstlisting}
\end{example}

In a similar way, a variable can be changed when the mouse button is \emph{released}:
\begin{lstlisting}[language=modelica]
record OnMouseUpSetBoolean
  Boolean variable "Name of variable to change when mouse button released";
  Boolean value "Assigned value";
end OnMouseUpSetBoolean;
\end{lstlisting}%
\annotationindex{OnMouseUpSetBoolean}

Note that several interaction objects can be associated with the same graphical item or component.
\begin{example}
\begin{lstlisting}[language=modelica]
interaction = {OnMouseDownSetBoolean(on, true),
               OnMouseUpSetBoolean(on, false)}
\end{lstlisting}
\end{example}

The \fmtannotationindex{OnMouseMoveXSetReal} interaction object sets the variable to the position of the cursor in X direction in the local coordinate system mapped to the interval defined by the \lstinline!minValue! and \lstinline!maxValue! attributes.
\begin{lstlisting}[language=modelica]
record OnMouseMoveXSetReal
  Real xVariable "Name of variable to change when cursor moved in x direction";
  Real minValue;
  Real maxValue;
end OnMouseMoveXSetReal;
\end{lstlisting}

The \fmtannotationindex{OnMouseMoveYSetReal} interaction object works in a corresponding way as the \lstinline!OnMouseMoveXSetReal! object but in the Y direction.
\begin{lstlisting}[language=modelica]
record OnMouseMoveYSetReal
  Real yVariable "Name of variable to change when cursor moved in y direction";
  Real minValue;
  Real maxValue;
end OnMouseMoveYSetReal;
\end{lstlisting}

\subsubsection{Edit Input}\label{edit-input}

The \fmtannotationindex{OnMouseDownEditInteger} interaction object presents an input field when the graphical item or component is clicked on.
The field shows the actual value of the variable and allows changing the value.
If a too small or too large value according to the \lstinline!min! and \lstinline!max! parameter values of the variable is given, the input is rejected.
\begin{lstlisting}[language=modelica]
record OnMouseDownEditInteger
  Integer variable "Name of variable to change";
end OnMouseDownEditInteger;
\end{lstlisting}

The \fmtannotationindex{OnMouseDownEditReal} interaction object presents an input field when the graphical item or component is clicked on.
The field shows the actual value of the variable and allows changing the value.
If a too small or too large value according to the \lstinline!min! and \lstinline!max! parameter values of the variable is given, the input is rejected.
\begin{lstlisting}[language=modelica]
record OnMouseDownEditReal
  Real variable "Name of variable to change";
end OnMouseDownEditReal;
\end{lstlisting}

The \fmtannotationindex{OnMouseDownEditString} interaction object presents an input field when the graphical item or component is clicked on.
The field shows the actual value of the variable and allows changing the value.
\begin{lstlisting}[language=modelica]
record OnMouseDownEditString
  String variable "Name of variable to change";
end OnMouseDownEditString;
\end{lstlisting}

\section{Graphical User Interface}\label{annotations-for-the-graphical-user-interface}\label{graphical-user-interface}

This section describes the annotations that are used to define properties of the graphical user interface.

\begin{lstlisting}[language=modelica]
/*literal*/ constant String preferredView = $\mathit{view}$;
\end{lstlisting}

The \fmtannotationindex{preferredView} annotation defines the default view when selecting the class.
The $\mathit{view}$ is a \lstinline!String! literal where \lstinline!"info"! means class documentation (``information''), \lstinline!"diagram"! means diagram view, \lstinline!"icon"! means icon view, and \lstinline!"text"! means Modelica source code (``text'').

\begin{lstlisting}
/*literal*/ constant Boolean DocumentationClass;
\end{lstlisting}%
\annotationindex{DocumentationClass}

Only allowed as class annotation on any kind of class and, if set to \lstinline!true!, implies that this class and all classes within it are treated as having the annotation \lstinline!preferredView = "info"!.
If the annotation \lstinline!preferredView! is explicitly set for a class, it has precedence over a \lstinline!DocumentationClass! annotation.

\begin{nonnormative}
A tool may display such classes in special ways.  For example, the description texts of the classes might be displayed instead
of the class names, and if no icon is defined, a special information default icon may be displayed in the package browser.
\end{nonnormative}

\begin{lstlisting}[language=modelica]
/*literal*/ constant String defaultComponentName = "$\mathit{name}$";
\end{lstlisting}%
\annotationindex{defaultComponentName}

When creating a component of the given class, the recommended component name is \emph{name}.
If the default name cannot be used (e.g., since it is already in use), another name based on \lstinline!defaultComponentName! shall be derived automatically, except as described under \lstinline!defaultComponentPrefixes!.
When automatically deriving a name, any trailing `\lstinline!1!' in the \lstinline!defaultComponentName! shall be disregarded.

\begin{lstlisting}[language=modelica]
/*literal*/ constant String defaultComponentPrefixes = "$\mathit{prefixes}$";
\end{lstlisting}%
\annotationindex{defaultComponentPrefixes}

When creating a component, it is recommended to generate a declaration of the form
\begin{lstlisting}[language=grammar]
type-prefix type-specifier component-declaration
\end{lstlisting}

The following prefixes may be included in the string \lstinline!prefixes!: \lstinline!inner!,
\lstinline!outer!, \lstinline!replaceable!, \lstinline!constant!, \lstinline!parameter!, \lstinline!discrete!.

\begin{nonnormative}
In combination with \lstinline!defaultComponentName! it can be used to make it easy for users to create \lstinline!inner! components
matching the \lstinline!outer! declarations; see also example below.  If the prefixes contain \lstinline!inner! or \lstinline!outer!
and the default name cannot be used (e.g., since it is already in use) it is recommended to give a diagnostic.
\end{nonnormative}

\begin{lstlisting}[language=modelica]
/*literal*/ constant String missingInnerMessage = "$\mathit{message}$";
\end{lstlisting}%
\annotationindex{missingInnerMessage}

When an \lstinline!outer! component of the class does not have a corresponding \lstinline!inner!
component, the literal string message may be used as part of a diagnostic message (together with appropriate context), see
\cref{instance-hierarchy-name-lookup-of-inner-declarations}.

\begin{example}
\begin{lstlisting}[language=modelica]
model World
  $\ldots$
  annotation(defaultComponentName = "world",
  defaultComponentPrefixes = "inner replaceable",
  missingInnerMessage = "The World object is missing");
end World;
\end{lstlisting}
When an instance of model \lstinline!World! is dragged in to the diagram layer, the
following declaration is generated:
\begin{lstlisting}[language=modelica]
inner replaceable World world;
\end{lstlisting}
\end{example}

A simple type or component of a simple type may have:
\begin{lstlisting}[language=modelica]
/*literal*/ constant Boolean absoluteValue;
\end{lstlisting}%
\annotationindex{absoluteValue}

If \lstinline!false!, then the variable defines a relative quantity, and if \lstinline!true! an absolute quantity.

\begin{nonnormative}
When converting between units (in the user-interface for plotting and entering parameters), the unit offset must be ignored for a variable defined with annotation \lstinline!absoluteValue = false!.
This annotation is used in the Modelica Standard Library, for example in \lstinline!Modelica.Units.SI! for the type definition \lstinline!TemperatureDifference!.
\end{nonnormative}

A model or block definition may contain:
\begin{lstlisting}[language=modelica]
/*literal*/ constant Boolean defaultConnectionStructurallyInconsistent;
\end{lstlisting}%
\annotationindex{defaultConnectionStructurallyInconsistent}

If \lstinline!true!, it is stated that a default connection will result in a structurally inconsistent model or block\footnote{%
  For the precise definition of \emph{structurally inconsistent}, see \textcite{Pantelides1988ConsistentInitialization}.}%
.
A "default connection" is constructed by instantiating the respective \lstinline!model! or \lstinline!block! and for every input \lstinline!u! providing an equation \lstinline!0 = f(u)!, and for every (potential, flow) pair of the form \lstinline!(v, i)!, providing an equation of the form \lstinline!0 = f(v, i)!.

\begin{nonnormative}
It is useful to check all models/blocks of a Modelica package in a simple way.  One check is to default connect every model/block and to check whether the resulting class is structurally consistent (which is a stronger requirement than being balanced).  It is rarely needed; but is for example used in \lstinline!Modelica.Blocks.Math.InverseBlockConstraints!, in order to prevent a wrong error message.  Additionally, when a user defined model is structurally inconsistent, a tool should try to pinpoint in which class the error is present.  This annotation avoids then to show a wrong error message.
\end{nonnormative}

A class may have the following annotation:
\begin{lstlisting}[language=modelica]
/*literal*/ constant String obsolete = "$\mathit{message}$";
\end{lstlisting}%
\annotationindex{obsolete}

It indicates that the class ideally should not be used anymore and gives a message indicating the recommended action.
This annotation is not inherited, the assumption is that if a class uses an obsolete class (as a base class or as the class of one of the components) that shall be updated -- ideally without impacting users of the class.
If that is not possible the current class can have also have an \lstinline!obsolete! annotation.

A component declaration may have the following annotation:
\begin{lstlisting}[language=modelica]
/*literal*/ constant String unassignedMessage = "$\mathit{message}$";
\end{lstlisting}%
\annotationindex{unassignedMessage}

When the variable to which this annotation is attached in the declaration cannot be computed due to the structure of the equations, the string \lstinline!"$\mathit{message}$"! can be used as a diagnostic message.

\begin{nonnormative}
When using BLT partitioning, this means if a variable \lstinline!a! or one of its aliases \lstinline!b = a! or \lstinline!b = -a!
cannot be assigned, the message is displayed.  This annotation is used to provide library specific error messages.
\end{nonnormative}

\begin{example}
\begin{lstlisting}[language=modelica]
connector Frame "Frame of a mechanical system"
  $\ldots$
  flow Modelica.Units.SI.Force f[3]
  annotation(unassignedMessage =
      "All Forces cannot be uniquely calculated. The reason could be that the
     mechanism contains a planar loop or that joints constrain the same motion.
     For planar loops, use in one revolute joint per loop the option
     PlanarCutJoint=true in the Advanced menu.
     ");
end Frame;
\end{lstlisting}
\end{example}

A component declaration or a short replaceable class definition may have the following annotation:
\begin{lstlisting}[language=modelica]
record Dialog
  /*literal*/ constant String tab = "General";
  /*literal*/ constant String group = "";
  /*evaluable*/ parameter Boolean enable = true;
  /*literal*/ constant Boolean showStartAttribute = false;
  /*literal*/ constant Boolean colorSelector = false;
  /*literal*/ constant Selector loadSelector;
  /*literal*/ constant Selector saveSelector;
  /*literal*/ constant Selector directorySelector;
  /*literal*/ constant String groupImage = "";
  /*literal*/ constant Boolean connectorSizing = false;
end Dialog;

record Selector
  /*literal*/ constant String filter = "";
  /*literal*/ constant String caption = "";
end Selector;
\end{lstlisting}%
\annotationindex{Dialog}

For a short replaceable class definition only the fields \lstinline!tab!, \lstinline!group!, \lstinline!enable! and \lstinline!groupImage! are allowed.

In the organization of a tool's user interface, the \lstinline!tab! shall correspond to a major divisioning of ``tabs'', and \lstinline!group! correspond to sub-divisioning of ``groups'' within each tab.
An empty \lstinline!group! (the default) means tool-specific choice of group.
The order of components (and class definitions) within each group and the order of the groups and tabs are according to the declaration order, where inherited elements are added at the place of the extends.

A component shall have at most one of \lstinline!showStartAttribute=true!, \lstinline!colorSelector=true!, \lstinline!loadSelector!, \lstinline!saveSelector!, \lstinline!directorySelector!, or \lstinline!connectorSizing=true!.

\begin{example}
When \lstinline!group! is empty, a tool may place parameters in the group ``Parameters'', and place variables with \lstinline!showStartAttribute = true! in the group ``Start Attributes''.
\end{example}

If \lstinline!enable = false!, the input field may be disabled and no input can be given.

If \lstinline!showStartAttribute = true! the dialog should allow the user to set the \lstinline!start!- and \lstinline!fixed!-attributes for the variable instead of the value of the variable.

\begin{nonnormative}
The \lstinline!showStartAttribute = true! is primarily intended for non-parameter values and avoids introducing a separate parameter for the \lstinline!start!-attribute of the variable.
\end{nonnormative}

If \lstinline!colorSelector = true!, it suggests the use of a color selector to pick an \textsc{rgb} color as a vector of three values in the range 0..255 (the color selector should be useable both for vectors of \lstinline!Integer! and \lstinline!Real!).

The presence of \lstinline!loadSelector! or \lstinline!saveSelector! specifying \fmtannotationindex{Selector} suggests the use of a file dialog to select a file.
Setting \lstinline!filter! will in the dialog only show files that fulfill the given pattern.
Setting \lstinline!text1 (*.ext1);;text2 (*.ext2)! will only show files with file extension \filename{ext1} or \filename{ext2} with the corresponding description texts \lstinline!text1! and \lstinline!text2!, respectively.
\lstinline!caption! is a caption for display in the file dialog.
\lstinline!loadSelector! is used to select an existing file for reading, whereas \lstinline!saveSelector! is used to define a file for writing.

The presence of \lstinline!directorySelector! specifying \lstinline!Selector! suggests the use of a dialog to select an existing directory.
The selected directory does not need to exist at the time of opening the dialog; it is allowed to let the dialog be used to create directory before selecting it.
The \lstinline!filter! may not be used.
The \lstinline!caption! is a caption for display in the file dialog.

The \lstinline!groupImage! references an image using an URI (see \cref{external-resources}), and the image is intended to be shown together with the entire group (only one image per group is supported).
Disabling the input field will not disable the image.
The background of the \lstinline!groupImage! and any image used in HTML-documentation is recommended to be transparent (intended to be a light color) or white.

The \lstinline!connectorSizing! is described separately in \cref{connector-sizing}.

\begin{example}
\begin{lstlisting}[language=modelica]
model DialogDemo
  parameter Boolean b = true "Boolean parameter";
  parameter Modelica.Units.SI.Length length "Real parameter with unit";
  parameter Real r1 "Real parameter in Group 1"
     annotation(Dialog(group = "Group 1"));
  parameter Real r2 "Disabled Real parameter in Group 1"
     annotation(Dialog(group = "Group 1", enable = not b));
  parameter Real r3 "Real parameter in Tab 1"
     annotation(Dialog(tab = "Tab 1"));
  parameter Real r4 "Real parameter in Tab 1 and Group 2"
     annotation(Dialog(tab = "Tab 1", group = "Group 2"));
  $\ldots$
end DialogDemo;
\end{lstlisting}
When clicking on an instance of model \lstinline!DialogDemo!, a dialog is shown that may have the following layout (other layouts are also possible, this is vendor specific).

\begin{center}
\includegraphics[scale=0.5]{disabledparameter}
\quad
\includegraphics[scale=0.5]{tabparameter}\\
\end{center}
\end{example}

\subsection{Connector Sizing}\label{connector-sizing}

This section describes the \lstinline!connectorSizing! annotation inside a \lstinline!Dialog! annotation.
The value of \lstinline!connectorSizing! must be a literal \lstinline!false! or \lstinline!true!.
If \lstinline!connectorSizing = false!, this annotation has no effect.
If \lstinline!connectorSizing = true!, the corresponding variable must be declared with the \lstinline!parameter! prefix, must be a subtype of a scalar \lstinline!Integer! and must have a literal default value of zero.

\begin{nonnormative}
The reason why \lstinline!connectorSizing! must be given a literal value is that if the value is an expression,
the \lstinline!connectorSizing! functionality is conditional and this will then lead easily to wrong models.

The default value of the variable must be zero since this annotation
is designed for a parameter that is used as vector dimension, and the
dimension of the vector should be zero when the component is dragged or
redeclared.  Furthermore, when a tool does not support the
\lstinline!connectorSizing! annotation, dragging will still result in a correct
model.
\end{nonnormative}

If \lstinline!connectorSizing = true!, a tool may set the parameter value in a modifier automatically, if used as dimension size of a vector of connectors.
In that case the parameter should not be modified by the user, and a tool may choose to not display that parameter in the dialog or display it with disabled input field.

\begin{nonnormative}
The \lstinline!connectorSizing! annotation is used in cases
where connections to a vector of connectors shall be made and a new
connection requires to resize the vector and to connect to the new index
(unary connections). The annotation allows a tool to perform these two
actions in many cases automatically. This is, e.g., very useful for
state machines and for certain components of fluid libraries.
\end{nonnormative}

\begin{nonnormative}
The following part is non-normative text and describes a useful
way to handle the \lstinline!connectorSizing! annotation in a tool (still a tool may
use another strategy and/or may handle other cases than described
below).
The recommended rules are clarified at hand of the following
example which represents a connector and a model from the
\lstinline!Modelica.StateGraph! library (note that they may be modified or renamed in future versions):
\begin{lstlisting}[language=modelica]
connector Step_in // Only 1:1 connections are possible since input used
  output Boolean occupied;
  input Boolean set;
end Step_in;

block Step
  // nIn cannot be set through the dialog (but maybe shown)
  parameter Integer nIn=0 annotation(Dialog(connectorSizing=true));
  Step_in inPorts[nIn];
  $\ldots$
end Step;
\end{lstlisting}
If the parameter is used as dimension size of a vector of
connectors, it is automatically updated according to the following
rules:
\begin{enumerate}
\item \label{connectorSizing:addVector}
  If a new connection line is drawn between one outside and one
  inside vector of connectors both dimensioned with (\lstinline!connectorSizing!)
  parameters, a connection between the two vectors is performed and the
  (\lstinline!connectorSizing!) parameter is propagated from connector to component.
  Other types of outside connections do not lead to an automatic update
  of a (\lstinline!connectorSizing!) parameter. \emph{Example:} Assume there is a
  connector \lstinline!inPorts! and a component \lstinline!step1!:
\begin{lstlisting}[language=modelica]
parameter Integer nIn=0 annotation(Dialog(connectorSizing=true));
Step_in inPorts[nIn];
Step step1(nIn=0);
\end{lstlisting}
  Drawing a connection line between connectors \lstinline!inPorts! and
  \lstinline!step1.inPorts! results in:
\begin{lstlisting}[language=modelica]
  parameter Integer nIn=0 annotation(Dialog(connectorSizing=true));
  Step_in inPorts[nIn];
  Step step1(nIn=nIn); // nIn=0 changed to nIn=nIn
equation
  connect(inPorts, step1.inPorts); // new connect-equation
\end{lstlisting}
\item\label{connectorSizing:deleteVector}
  If a connection line is deleted between one outside and one inside vector of connectors both dimensioned with (\lstinline!connectorSizing!) parameters, the \lstinline!connect!-equation is removed and the (\lstinline!connectorSizing!) parameter of the component is set to zero or the modifier is removed.
  \emph{Example:} Assume the connection line in the resulting example in case~\ref{connectorSizing:addVector} is removed.
  This results in:
\begin{lstlisting}[language=modelica]
parameter Integer nIn=0 annotation(Dialog(connectorSizing=true));
Step_in inPorts[nIn];
Step step1; // modifier nIn=nIn is removed
\end{lstlisting}
\item \label{connectorSizing:addScalar}
  If a new connection line is drawn to an inside connector with
  \lstinline!connectorSizing! and case~\ref{connectorSizing:addVector} does not apply then, the parameter is
  incremented by one and the connection is performed for the new highest
  index. \emph{Example:} Assume that 3 connections are present and a new
  connection is performed. The result is:
\begin{lstlisting}[language=modelica]
  Step step1(nIn=4); // index changed from nIn=3 to nIn=4
equation
  connect($\ldots$, step1.inPorts[4]); // new connect-equation
\end{lstlisting}
  In some applications, like state machines, the vector index is
  used as a priority, e.g., to define which transition is firing if
  several transitions become active at the same time instant. It is then
  not sufficient to only provide a mechanism to always connect to the
  last index. Instead, some mechanism to select an index conveniently
  should be provided.
\item \label{connectorSizing:deleteScalar}
  If a connection line is deleted to an inside connector with
  \lstinline!connectorSizing! and case~\ref{connectorSizing:deleteVector} does not apply then, then the
  (\lstinline!connectorSizing!) parameter is decremented by one and all connections
  with index above the deleted connection index are also decremented by
  one. \emph{Example:}Assume there are 4 connections:
\begin{lstlisting}[language=modelica]
  Step step1(nIn=4);
equation
  connect(a1, step1.inPorts[1]);
  connect(a2, step1.inPorts[2]);
  connect(a3, step1.inPorts[3]);
  connect(a4, step1.inPorts[4]);
\end{lstlisting}
  and the connection from \lstinline!a2! to \lstinline!step1!. \lstinline!inPorts[2]! is deleted.
  This results in
\begin{lstlisting}[language=modelica]
  Step step1(nIn=3);
equation
  connect(a1, step1.inPorts[1]);
  connect(a3, step1.inPorts[2]);
  connect(a4, step1.inPorts[3]);
\end{lstlisting}
\end{enumerate}

These rules also apply if the connectors and/or components are defined in superclass.

\emph{Example:} Assume that \lstinline!step1! is defined in superclass \lstinline!MyCompositeStep! with 3 connections, and a new connection is performed in a derived class.
The result is:
\begin{lstlisting}[language=modelica]
  extends MyCompositeStep(step1(nIn=4)); // new modifier nIn=4
equation
  connect($\ldots$, step1.inPorts[4]);  // new connect-equation
\end{lstlisting}
\end{nonnormative}

\section{Versions}\label{annotations-for-version-handling}\label{versions}

A top-level package or model can specify the version of top-level
classes it uses, its own version number, and if possible how to convert
from previous versions. This can be used by a tool to guarantee that
consistent versions are used, and if possible to upgrade usage from an
earlier version to a current one.

\subsection{Version Numbering}\label{version-numbering}

Version numbers are of the forms:
\begin{itemize}
\item
  Main release versions: \lstinline[language=grammar]!""" UNSIGNED-INTEGER { "." UNSIGNED-INTEGER } """!\\
  Example: \lstinline!"2.1"!
\item
  Pre-release versions: \lstinline[language=grammar]!""" UNSIGNED-INTEGER { "." UNSIGNED-INTEGER } " " {S-CHAR} """!\\
  Example: \lstinline!"2.1 Beta 1"!
\item
  Un-ordered versions: \lstinline[language=grammar]!""" NON-DIGIT {S-CHAR} """!\\
  Example: \lstinline!"Test 1"!
\end{itemize}

The main release versions are ordered using the hierarchical numerical
names, and follow the corresponding pre-release versions. The
pre-release versions of the same main release version are internally
ordered alphabetically.

\subsection{Version Handling}\label{version-handling}

In a top-level class, the version number and the dependency to earlier versions of this class are defined using one or more of the following annotations:
% TODO: Syntax below is a mess: neither Modelica, pseudo-code record, nor grammar.
\begin{itemize}
\item
  \lstinline!version = CURRENT-VERSION-NUMBER!\annotationindex{version}\\
  Defines the version number of the model or package.
  All classes within this top-level class have this version number.
\item
  \lstinline!conversion(noneFromVersion = VERSION-NUMBER)!\annotationindex{conversion}\\
  Defines that user models using the \lstinline!VERSION-NUMBER! can be upgraded to the \lstinline!CURRENT-VERSION-NUMBER! of the current class without any changes.
\item
  \lstinline!conversion(from(version = Versions, [to=VERSION-NUMBER,] Convert))!\\
  where \emph{Versions} is \lstinline!VERSION-NUMBER! \textbar{} \lstinline!{VERSION-NUMBER, VERSION-NUMBER, $\ldots$}! and \lstinline!Convert! is \lstinline!script="$\ldots$"! \textbar{} \lstinline!change={conversionRule(), $\ldots$, conversionRule()}!\\*[.5ex]
  Defines that user models using the \lstinline!VERSION-NUMBER! or any of the given \lstinline!VERSION-NUMBER! can be upgraded to the given \lstinline!VERSION-NUMBER! (if the to-tag is missing this is the \lstinline!CURRENT-VERSION-NUMBER!) of the current class by applying the given conversion rules.
  The script consists of an unordered sequence of \lstinline!conversionRule();! (and optionally Modelica comments).
  The \lstinline!conversionRule! functions are defined in \cref{conversion-rules}.

  \begin{nonnormative}
  The to-tag is added for clarity and optionally allows a tool to convert in multiple steps.
  \end{nonnormative}
\item
  \lstinline!uses(IDENT (version = VERSION-NUMBER [, versionBuild=INTEGER] [, dateModified=STRING] ) )!\annotationindex{uses}\\
  Defines that classes within this top-level class uses version \lstinline!VERSION-NUMBER! of classes within the top-level class \lstinline!IDENT!.
\end{itemize}

The annotations \lstinline!uses! and \lstinline!conversion! may contain several different sub-entries.

\begin{example}
\begin{lstlisting}[language=modelica]
package Modelica
  $\ldots$
  annotation(
    version = "3.1",
    conversion(
      noneFromVersion = "3.1 Beta 1",
      noneFromVersion = "3.1 Beta 2",
      from(version = {"2.1", "2.2", "2.2.1"},
           script = "convertTo3.mos"),
      from(version = "1.5",
           script = "convertFromModelica1_5.mos")));
end Modelica;

model A
  $\ldots$
  annotation(
    version = "1.0",
    uses(Modelica(version = "1.5")));
end A;

model B
  $\ldots$
  annotation(
    uses(Modelica(version = "3.1 Beta 1")));
end B;
\end{lstlisting}
In this example the model \lstinline!A! uses an older version of the Modelica library and can be upgraded using the given script, and model \lstinline!B! uses an older version of the Modelica library but no changes are required when upgrading.
\end{example}

\subsubsection{Conversion Rules}\label{conversion-rules}

% Using mbox to avoid having line starting with ","
There are a number of functions: \lstinline!convertClass!, \lstinline!convertClassIf!,
\lstinline!convertElement!, \mbox{\lstinline!convertModifiers!,} \lstinline!convertMessage! defined as follows. The
calls of these functions do not directly convert, instead they define
conversion rules as below.
It is recommended, but not required, to terminate each such function call with a semi-colon.
The order between the function calls does not matter, instead the longer paths (in terms of number of hierarchical names)
are used first as indicated below, and it is an error if there are any
ambiguities.

The conversion should generate correct Modelica models using the new version of the library
corresponding to the old version.

\begin{nonnormative}
Whenever possible tools should preserve the original style of the model, e.g., use of imports.
Conversions should be applied in all places where named element are used in code, including Modelica URIs (for example, in \lstinline!Documentation! annotations).
\end{nonnormative}

These functions can be called with literal strings or array of strings
and vectorize according to \cref{scalar-functions-applied-to-array-arguments}.

All of these convert-functions only use inheritance among user models, and not in the library that is used for the conversion -- thus conversions of base classes will require multiple conversion calls; this ensures that the conversion is independent of the new library structure.
The name of the class used as argument to \lstinline!convertElement! and \lstinline!convertModifiers! is similarly the old name of the class, i.e., the name before it is possibly converted by \lstinline!convertClass!.

\begin{nonnormative}
Specifying conversions using the old name of a class allows the conversion to be done without access to the old
version of the library (by suitable modifications of the lookup).  Another alternative is to use the old version
of the library during the conversion.
\end{nonnormative}

\paragraph*{convertClass("OldClass", "NewClass")}\label{convertclassoldclassnewclass}\annotationindex{convertClass}

Convert class \lstinline!OldClass! to \lstinline!NewClass!.

Match longer path first, so if converting both \lstinline!A! to \lstinline!C! and \lstinline!A.B! to \lstinline!D! then \lstinline!A.F! is converted to \lstinline!C.F! and \lstinline!A.B.E! to \lstinline!D.E!. This is considered before \lstinline!convertMessage! for the same \lstinline!OldClass!.

\begin{example}
Consider the following as part of a conversion script:
\begin{lstlisting}[language=modelica]
convertClass("Modelica.SIunits", "Modelica.Units.SI");
convertClass("Modelica.SIunits.Icons", "Modelica.Units.Icons");
\end{lstlisting}
This ensures that for example \lstinline!Modelica.SIunits.Length! is converted to \lstinline!Modelica.Units.SI.Length!
and \lstinline!Modelica.SIunits.Icons! is converted to \lstinline!Modelica.Units.Icons!.
\end{example}

\paragraph*{convertClassIf("OldClass", "oldElement", "whenValue", "NewClass")}\label{convertclassifoldclass-oldelement-whenvalue-newclass}\annotationindex{convertClassIf}

Convert class \lstinline!OldClass! to \lstinline!NewClass! if the literal modifier for
\lstinline!oldElement! has the value \lstinline!whenValue!, and also remove the modifier for
\lstinline!oldElement!.

These are considered before \lstinline!convertClass! and \lstinline!convertMessage! for the same \lstinline!OldClass!.

The old element should be of a \lstinline!Boolean!, \lstinline!Integer!, \lstinline!String!, or enumeration
type and the match is based on the literal value of the modifier.
For string elements the value argument to \lstinline!convertClassIf! shall be up-quoted, e.g., \lstinline!"\"My String\""!,
and for enumeration literals only the enumeration literal part of the old value matters, e.g., \lstinline!red!
for \lstinline!"Colors.red"!.

\paragraph*{convertElement("OldClass", "OldName", "NewName")}\label{convertelementoldclassoldnamenewname}\annotationindex{convertElement}

In \lstinline!OldClass!, convert element \lstinline!OldName! to \lstinline!NewName!.  Both \lstinline!OldName! and \lstinline!NewName! normally refer to components, but they may also refer to
class-parameters, or hierarchical names.  For hierarchical names, the longest match is used first.

For replaceable classes in packages (and replaceable classes in other classes) \lstinline!convertElement! shall
be used if the class is renamed within the package (or class), whereas \lstinline!convertClass! shall only be used if the class
is placed outside of the package (or class).

\begin{nonnormative}
The latter case indicates a problem with overuse of replaceable classes in the previous design of the library.
\end{nonnormative}

\begin{example}
Consider the following as part of a conversion script:
\begin{lstlisting}[language=modelica]
convertElement({"Modelica.Mechanics.MultiBody.World",
                "Modelica.Mechanics.MultiBody.World.gravityAcceleration"},
                "mue", "mu");
\end{lstlisting}
This implies that
\begin{lstlisting}[language=modelica]
Modelica.Mechanics.MultiBody.World world(mue=2);
function f=Modelica.Mechanics.MultiBody.World.gravityAcceleration(mue=4);
\end{lstlisting}
is converted to:
\begin{lstlisting}[language=modelica]
Modelica.Mechanics.MultiBody.World world(mu=2);
function f=Modelica.Mechanics.MultiBody.World.gravityAcceleration(mu=4);
\end{lstlisting}
\end{example}

\paragraph*{convertModifiers}\label{convertmodifiers}\annotationindex{convertModifiers}
\ % Dummy paragraph content to ensure listing below starts on a fresh line.

\begin{lstlisting}[language=modelica]
convertModifiers("OldClass",
  {"OldModifier1=default1", "OldModifier2=default2", $\ldots$},
  {"NewModifier1=$\ldots$%OldModifier2%$\ldots$", "NewModifier2=$\ldots$", $\ldots$}
  [, simplify=true]);
\end{lstlisting}

Normal case; if any modifier among \lstinline!OldModifier! exist then replace all of them with the list of\linebreak[4] \lstinline!NewModifiers!.
The \lstinline!$\ldots$%OldModifier2%$\ldots$! indicate an expression that may involve the values of the old modifiers (tools are responsible for adding parentheses if needed).
The lists of old and new modifiers can have different lengths.
The defaults (if present) are used if there are multiple \lstinline!OldModifier! and not all are set in the component instance.
The defaults are optional if there is at most one \lstinline!OldModifier! element, and should otherwise be provided.

If \lstinline!simplify! is specified and true then perform obvious simplifications
to clean up the new modifier; otherwise leave as is.

\begin{nonnormative}
Note: \lstinline!simplify! is primarily intended for converting enumerations and emulated enumerations that naturally lead to large nested \lstinline!if!-expressions.
The simplifications may also simplify parts of the original expression.
\end{nonnormative}

If the modifiers contain literal string values they must be quoted.

Behaviour in unusual cases:
\begin{itemize}
\item
  if \lstinline!NewModifier! list is empty then the modifier is just removed
\item
  If \lstinline!OldModifer! list is empty it is added for all uses of the class
\item
  If \lstinline!OldModifier$i$! is \lstinline!cardinality(a) = 0! the conversion will only be applied for a component comp if there are no inside connections to \lstinline!comp.a!. This can be combined with other modifiers that are handled in the usual way.
\item
  If \lstinline!OldModifier$i$! is \lstinline!cardinality(a) = 1! the conversion will only be applied for a component comp if there are any inside connections to \lstinline!comp.a!.
\end{itemize}

The converted modifiers and existing modifiers are merged such that the existing modifiers take precedence over the result of \lstinline!convertModifiers!.
A diagnostic is recommended if this merging removes some modifiers unless those modifiers are identical or it is the special case of an empty \lstinline!OldModifier! list.
\begin{nonnormative}
This can be used to handle the case where the default value was changed.
\end{nonnormative}

Converting modifiers with cardinality is used to remove the deprecated operator \lstinline!cardinality! from model libraries, and replace tests on cardinality in models by parameters explicitly enabling the different cases.
The case where the old class is used as a base class, and there exist outside connections to \lstinline!a!, and there is \lstinline!convertModifiers! involving the cardinality of \lstinline!a! is not handled.

\begin{nonnormative}
Having a parameter for explicitly enabling the different cases means that instead of model \lstinline!A! internally testing if its
connector \lstinline!B! is connected, there will be a parameter for enabling connector \lstinline!B!, and the conversion ensures that
each component of model \lstinline!A! will have this parameter set accordingly.

In case a parameter is simply renamed it is preferable to use \lstinline!convertElement!, since that also handles, e.g., binding equations
using the parameter.
\end{nonnormative}

\begin{example}
The conversion
\begin{lstlisting}[language=modelica]
convertClass("Modelica.Thermal.FluidHeatFlow.Components.IsolatedPipe",
             "Modelica.Thermal.FluidHeatFlow.Components.Pipe");
convertModifiers({"Modelica.Thermal.FluidHeatFlow.Components.IsolatedPipe"},
                 fill("", 0), {"useHeatPort=false"});

convertClass("Modelica.StateGraph.Temporary.NumericValue",
             "Modelica.Blocks.Interaction.Show.RealValue");
convertModifiers("Modelica.StateGraph.Temporary.NumericValue",
                 {"Value"}, {"number=%Value%"});
convertModifiers("Modelica.StateGraph.Temporary.NumericValue",
                 {"hideConnector"}, {"use_numberPort=not %hideConnector%"});

convertModifiers("Modelica.Blocks.Math.LinearDependency",
   {"y0=0", "k1=0", "k2=0"}, {"y0=%y0%", "k1=%y0%*%k1%", "k2=%y0%*%k2%"},
   true);

convertClass("My.Library.BadPackage",
             "My.Library.Package");
convertElement("My.Library.BadPackage.PartialBase",
               "bad", "correct");
convertElement("My.Library.BadPackage.ActualClass",
               "bad", "correct");
\end{lstlisting}
converts
\begin{lstlisting}[language=modelica]
Modelica.Thermal.FluidHeatFlow.Components.IsolatedPipe pipe1;
Modelica.StateGraph.Temporary.NumericValue tempValue(
  Value = 10, hideConnector = true);
Modelica.Blocks.Math.LinearDependency linearDep(y0 = 2, k2 = 1);
model A
  import My.Library;
  extends Library.BadPackage.ActualClass;
end A;
model B
  extends A;
  Boolean b = bad;
end B;
\end{lstlisting}
to
\begin{lstlisting}[language=modelica]
Modelica.Thermal.FluidHeatFlow.Components.Pipe pipe1(useHeatPort = false);
Modelica.Blocks.Interaction.Show.RealValue(
  number = 10, use_numberPort = not true);
Modelica.Blocks.Math.LinearDependency linearDep(y0 = 2, k1 = 0, k2 = 2);
model A
  import My.Library;
  extends Library.Package.ActualClass;
end A;
model B
  extends A;
  Boolean b = correct;
end B;
\end{lstlisting}
The \lstinline!convertElement! call for \lstinline!ActualClass! is needed to avoid relying on base classes in the original library where \lstinline!ActualClass! inherits from \lstinline!PartialBase!.
However, the inheritance among the models to convert (in this case \lstinline!B! inherits from \lstinline!A!) should be handled.
Note that conversion works regardless of the import of \lstinline!My.Library!.
\end{example}

\paragraph*{convertMessage("OldClass", "Failed Message")}\label{convertmessageoldclass-failed-message}\annotationindex{convertMessage}

For any use of \lstinline!OldClass! (or element of \lstinline!OldClass!) report that conversion
could not be applied with the given message.

\begin{nonnormative}
This may be useful if there is no possibility to convert a specific class. An alternative is to construct \lstinline!ObsoleteLibraryA! for problematic
cases, which may be more work but allows users to directly run the models after the conversion and later convert them.
\end{nonnormative}

\paragraph*{convertMessage("OldClass", "Failed Message", "oldElement")}\label{convertmessageoldclass-failed-message2}

For any use of \lstinline!oldElement! in \lstinline!OldClass! report that conversion
could not be applied with the given message.

\begin{nonnormative}
This is useful if there is no possibility to convert a specific parameter (or other element), especially if it rarely modified.  If the parameter had no impact on the model it can be removed using \lstinline!convertModifiers!, see \cref{convertmodifiers}.
\end{nonnormative}

\subsection{Versions in the File System}\label{mapping-of-versions-to-file-system}\label{versions-in-the-File-System}

A top-level class, \lstinline!IDENT!, with version \lstinline!VERSION-NUMBER! can be stored in
one of the following ways in a directory given in the \lstinline!MODELICAPATH!:
\begin{itemize}
\item
  The file \lstinline!IDENT ".mo"!\\
  Example: \filename{Modelica.mo}
\item
  The file \lstinline!IDENT " " VERSION-NUMBER ".mo"!\\
  Example: \filename{Modelica 2.1.mo}
\item
  The directory \lstinline!IDENT! with the file \filename{package.mo} directly inside it\\
  Example: \filename{Modelica/package.mo}
\item
  The directory \lstinline!IDENT " " VERSION-NUMBER! with the file \filename{package.mo} directly inside it\\
  Example: \filename{Modelica 2.1/package.mo}
\end{itemize}

This allows a tool to access multiple versions of the same package.

\subsection{Version Date and Build Information}\label{version-date-and-build-information}

Besides version information, a top-level class can have additionally the following top-level annotations to specify associated information to the version number:%
\begin{lstlisting}[language=modelica]
/*literal*/ constant String versionDate
   "UTC date of first version build (in format: YYYY-MM-DD)";
/*literal*/ constant Integer versionBuild
   "Larger number is a more recent maintenance update";
/*literal*/ constant String dateModified
   "UTC date and time of the latest change to the package
    in the following format (with one space between date
    and time): YYYY-MM-DD hh:mm:ssZ";
/*literal*/ constant String revisionId
   "Revision identifier of the version management system used
    to manage this library. It marks the latest submitted
    change to any file belonging to the package";
\end{lstlisting}%
\annotationindex{versionDate}\annotationindex{versionBuild}\annotationindex{dateModified}\annotationindex{revisionId}

\begin{example}
\begin{lstlisting}[language=modelica,mathescape=false,escapechar=!]
package Modelica
  !\ldots!
  annotation(
    version = "3.0.1",
    versionDate = "2008-04-10",
    versionBuild = 4,
    dateModified = "2009-02-15 16:33:14Z",
    revisionId = "$Id:: package.mo 2566 2009-05-26 13:25:54Z #$");
end Modelica;

model M1
  annotation(
    uses(Modelica(version = "3.0.1"))); // Common case
end M1

model M2
  annotation(
    uses(Modelica(version = "3.0.1", versionBuild = 4)));
end M2
\end{lstlisting}
\end{example}

The meanings of these annotations are:
\begin{itemize}
\item
  \lstinline!version! is the version number of the released library,
  see \cref{version-handling}.
\item
  \lstinline!versionDate! is the date in UTC format (according to ISO
  8601) when the library was released. This string is updated by the
  library author to correspond with the version number.
\item
  \lstinline!versionBuild! is the optional build number of the library.
  When a new version is released \lstinline!versionBuild! should be omitted or
  \lstinline!versionBuild = 1!. There might be bug fixes to the library that do
  not justify a new library version. Such maintenance changes are called
  a \emph{build} release of the library. For every new maintenance change,
  the \lstinline!versionBuild! number is increased. A \lstinline!versionBuild! number $A$
  that is higher than \lstinline!versionBuild! number $B$, is a newer release of the
  library. There are no conversions between the same versions with
  different build numbers.

  Two releases of a library with the same \lstinline!version! but different \lstinline!versionBuild! are in general assumed to be compatible.
  In special cases, the \lstinline!uses!-clause of a model may specify \lstinline!versionBuild! and/or \lstinline!dateModified!.
  In such a case the tool is expected to give a warning if there is a mismatch between library and model.
\item
  \lstinline!dateModified! is the UTC date and time (according to ISO
  8601) of the last modification of the package.

  \begin{nonnormative}
  The intention is that a Modelica tool updates this annotation whenever the package or part of it was modified and is saved on
  persistent storage (like file or database system).
  \end{nonnormative}
\item
  \lstinline!revisionId! is a tool specific revision identifier
  possibly generated by a source code management system (e.g., Subversion
  or CVS). This information exactly identifies the library
  source code in the source code management system.
\end{itemize}

The \lstinline!versionBuild! and \lstinline!dateModified! annotations can also be specified in
the \lstinline!uses! annotation (together with the version number).

\begin{nonnormative}
It is recommended that tools do not automatically store \lstinline!versionBuild! and \lstinline!dateModified! in the \lstinline!uses! annotation.
\end{nonnormative}

\section{Access Control to Protect Intellectual Property}\label{annotations-for-access-control-to-protect-intellectual-property}\label{access-control-to-protect-intellectual-property}

This section presents annotations to define the protection and the
licensing of packages. The goal is to unify basic mechanisms to control
the access to a package in order to protect the intellectual property
contained in it. This information is used to encrypt a package and bind
it optionally to a particular target machine, and/or restrict the usage
for a particular period of time.

\begin{nonnormative}
Protecting the intellectual property of a Modelica package is
considerably more difficult than protecting code from a programming
language. The reason is that a Modelica tool needs the model equations
in order that it can process the equations symbolically, as needed for
acausal modeling. Furthermore, if a Modelica tool generates C-code of
the processed equations, this code is then potentially available for
inspection by the user. Finally, the Modelica tool vendors have to be
trusted, that they do not have a backdoor in their tools to store the
(internally) decrypted classes in human readable format. The only way to
protect against such misuse is legally binding warranties of the tool
vendors.

The intent of this section is to enable a library vendor to
maintain one source version of their Modelica library that can be
encrypted and used with several different Modelica tools, using
different encryption formats.
\end{nonnormative}

The following definitions relate to access control.

\begin{definition}[Protection]\index{protection!access control}
Define what parts of a class are visible.
\end{definition}

\begin{definition}[Obfuscation]\index{obfuscation!access control}
Changing a Modelica class or generated code so that it is difficult to inspect by a user (e.g., by automatically renaming variables to non-meaningful names).
\end{definition}

\begin{definition}[Encryption]\index{encryption!access control}
Encoding of a model or a package in a form so that the modeler cannot inspect any content of a class without an appropriate key.  An encrypted package that has the \lstinline!Protection! annotation
is read-only; the way to modify it is to generate a new encrypted version.
\end{definition}

\begin{definition}[Licensing]\index{licensing!access control}
Restrict the use of an encrypted package for particular users for a specified period of time.
\end{definition}

In this section annotations are defined for protection and licensing.  Obfuscation and encryption are not standardized.

Protection and licensing are both defined inside the \fmtannotationindex{Protection} annotation:
\begin{lstlisting}[language=modelica]
annotation(Protection($\ldots$));
\end{lstlisting}

\subsection{Protection of Classes}\label{protection-of-classes}

A class may have the following annotations to define what parts of a class are visible, and only the parts explicitly listed as visible below can be accessed (if a class is encrypted and no \lstinline!Protection! annotation is defined, the access annotation has the default value \lstinline!Access.documentation!):
\begin{lstlisting}[language=modelica]
record Protection
  /*literal*/ constant Access access;
  $\ldots$
end Protection;
type Access = enumeration(hide, icon, documentation, diagram,
              nonPackageText, nonPackageDuplicate,
              packageText, packageDuplicate);
\end{lstlisting}
The other members of this record are given in \cref{licensing}.

The items of the \fmtannotationindex{Access} enumeration have the following meanings:
\begin{enumerate}
\item
  \lstinline!Access.hide!\\
  Do not show the class anywhere (it is not possible to inspect any part
  of the class).
\item
  \lstinline!Access.icon!\\
  The class can be instantiated and public parameter, constant, input, output variables as well as public connectors can be accessed, as well as the \lstinline!Icon! annotation, as defined in \cref{annotations-for-graphical-objects} (the declared information of these elements can be shown).
  Additionally, the class name and its description text can be accessed.
\item
  \lstinline!Access.documentation!\\
  Same as \lstinline!Access.icon! and additionally the \lstinline!Documentation! annotation (as defined in \cref{annotations-for-documentation}) can be accessed.
  HTML-generation in the \lstinline!Documentation! annotation is normally performed before encryption, but the generated HTML is intended to be used with the encrypted package.
  Thus the HTML-generation should use the same access as the encrypted version -- even before encryption.
\item
  \lstinline!Access.diagram!\\
  Same as \lstinline!Access.documentation! and additionally, the \lstinline!Diagram! annotation, and all components and \lstinline!connect!-equations that have a graphical annotation can be accessed.
\item
  \lstinline!Access.nonPackageText!\\
  Same as \lstinline!Access.diagram! and additionally if it is not a package: the whole class definition can be accessed (but that text cannot be copied, i.e., you can see but not copy the source code).
\item
  \lstinline!Access.nonPackageDuplicate!\\
  Same as \lstinline!Access.nonPackageText! and additionally if it is not a package: the class, or part of the class, can be copied.
\item
  \lstinline!Access.packageText!\\
  Same as \lstinline!Access.diagram! (note: \emph{not} including all rights of \lstinline!Access.nonPackageDuplicate!) and additionally the whole class definition can be accessed (but that text cannot be copied, i.e., you can see but not copy the source code).
\item
  \lstinline!Access.packageDuplicate!\\
  Same as \lstinline!Access.packageText! and additionally the class, or part of the class, can be copied.
\end{enumerate}

The \lstinline!access! annotation holds for the respective class and all classes that are hierarchically on a lower level, unless overridden by a \lstinline!Protection! annotation with \lstinline!access!.
Overriding \lstinline!access=Access.hide! or \lstinline!access=Access.packageDuplicate! has no effect.

\begin{example}
If the annotation is given on the top level of a package and at no other class in this package, then the \lstinline!access! annotation holds for all classes in this package.
\end{example}

Classes should not use other classes in ways that contradict this protection.
Tools must ensure that protected contents are not shown, even if classes do not meet this requirement.

\begin{example}
For instance a class with \lstinline!Access.hide! should not be used in the diagram layer of a class with \lstinline!Access.diagram!, and there should not be hyperlinks to classes with \lstinline!Access.icon! (from classes with visible documentation).

Consider the following invalid use of a class with \lstinline!Access.hide!:
\begin{lstlisting}[language=modelica]
package P
  block MySecret
    RealOutput y = time;
    annotation(Protection(access = Access.hide));
  end MySecret;
  model M
    MySecret mySecret
     annotation(Placement(
       transformation(origin = {30, 30}, extent = {{-10, -10}, {10, 10}})));
    Integrator integrator
     annotation(Placement(
       transformation(origin = {70, 30}, extent = {{-10, -10}, {10, 10}})));
  equation
    connect(mySecret.y, integrator.u)
      annotation(Line(origin = {49.5, 30}, points = {{-8.5, 0}, {8.5, -0}}));
    annotation(Protection(access = Access.diagram));
  end M;

  model M2
    // The class MySecret is a simpler Modelica.Blocks.Sources.ContinuousClock
    MySecret mySecret annotation(Placement(
       transformation(origin = {30, 30}, extent = {{-10, -10}, {10, 10}})));
    annotation(Protection(access = Access.packageDuplicate));
  end M2;
end P;
\end{lstlisting}
In order to not reveal the existence of the class \lstinline!P.MySecret! in \lstinline!P.M!, a tool may choose to show the diagram of \lstinline!P.M! with both \lstinline!mySecret! and all connections to it removed.
(The tool could also choose to not show the diagram of \lstinline!P.M! at all, or even reject to load the package \lstinline!P! altogether.)
As long as the invalid use of \lstinline!P.MySecret! occurs within the same top level package as where the class is defined (here, \lstinline!P!), a tool is allowed to silently ignore the use for purposes of model translation.
When simulating \lstinline!P.M!, the tool must not store \lstinline!mySecret.y!.

It is not specified whether a tool hides the entire text of \lstinline!P.M2!, hides just the declaration, or shows the entire text of the \lstinline!P.M2!.
In order to support development of valid protected packages, it is of course OK and expected that a tool will report the invalid use of \lstinline!P.MySecret! in \lstinline!P.M! and \lstinline!P.M2! (revealing its existence in a diagnostic) during development of the package.
\end{example}

\begin{example}
With the same package \lstinline!P! as in the previous example, consider the following invalid use outside of \lstinline!P!:
\begin{lstlisting}[language=modelica]
model My
  // There exist a class P.MySecret
  P.MySecret a
    annotation(Placement(
       transformation(origin = {30, 30}, extent = {{-10, -10}, {10, 10}})));
end My;
\end{lstlisting}
Regardless of the protection of \lstinline!My!, a tool must act as if \lstinline!P.MySecret! did not exist.
For example, translation of \lstinline!My! must fail with a standard error message about reference to the non-existing class \lstinline!P.MySecret!.
Further, just like when being misused inside the package \lstinline!P!, the tool must not reveal that it knows about the icon of \lstinline!P.MySecret!.
With such precautions taken, showing the text or diagram of \lstinline!My! is permitted as it doesn't reveal the actual existence of \lstinline!P.MySecret!.
\end{example}

\begin{nonnormative}
It is currently not standardized which result variables are accessible for plotting.
It seems natural to not introduce new flags for this, but reuse the \lstinline!Access.XXX! definition.
For instance:
\begin{itemize}
\item For \lstinline!Access.icon! only the variables can be stored in a result file that can also be inspected in the class.
\item For \lstinline!Access.nonPackageText! all public and protected variables can be stored in a result file, because all variables can be inspected in the class.
\end{itemize}

\begin{lstlisting}[language=modelica]
package CommercialFluid // Access icon, documentation, diagram
  package Examples // Access icon, documentation, diagram
    model PipeExample // Access everything, can be copied
    end PipeExample;

    package Circuits // Access icon, documentation, diagram
      model ClosedCircuit // Access everything, can be copied
      end ClosedCircuit;
    end Circuits;

    model SecretExample // No access
      annotation(Protection(access=Access.hide));
    end SecretExample;
    annotation(Protection(access=Access.nonPackageDuplicate));
  end Examples;

  package Pipe // Access icon
    model StraightPipe // Access icon
    end StraightPipe;
    annotation(Protection(access=Access.icon));
  end Pipe;

  package Vessels // Access icon, documentation, diagram
    model Tank // Access icon, documentation, diagram, text
    end Tank;
  end Vessels;
  annotation(Protection(access=Access.nonPackageText));
end CommercialFluid;
\end{lstlisting}
\end{nonnormative}

\subsection{Licensing}\label{licensing}

In this section annotations within the \lstinline!Protection! annotation are
defined to restrict the usage of the encrypted package:
\begin{lstlisting}[language=modelica]
record Protection
  /*literal*/ constant Access access;
  /*literal*/ constant String features[:] = fill("", 0) "Required license features";

  record License
    /*literal*/ constant String libraryKey;
    /*literal*/ constant String licenseFile = "" "Optional, default mapping if empty";
  end License;
end Protection;
\end{lstlisting}
See \cref{protection-of-classes} for a description of \lstinline!access!, and note that licensing information uses another record \lstinline!Protection! with different contents given below.
The \fmtannotationindex{License} annotation has only an effect on the top of an encrypted class and is then valid for the whole class hierarchy.
(Usually the licensed class is a package.)
The \lstinline!libraryKey! is a secret string from the library vendor and is the protection mechanism so that a user cannot generate his/her own authorization file since the \lstinline!libraryKey! is unknown to him/her.

The \lstinline!features! annotation defines the required license options. If the
features vector has more than one element, then at least a license
feature according to one of the elements must be present. As with the
other annotations, the \lstinline!features! annotation holds for the respective
class and for all classes that are hierarchically on a lower level,
unless further restricted by a corresponding annotation. If no license
according to the \lstinline!features! annotation is provided in the
authorization file, the corresponding classes are not visible and cannot
be used, not even internally in the package.

\begin{example}
\begin{lstlisting}[language=modelica]
// Requires license feature "LicenseOption"
annotation(Protection(features={"LicenseOption"}));

// Requires license features "LicenseOption1" or "LicenseOption2"
annotation(Protection(features={"LicenseOption1", "LicenseOption2"}));

// Requires license features ("LicenseOption1" and "LicenseOption2") or "LicenseOption3"
annotation(Protection(features={"LicenseOption1 LicenseOption2", "LicenseOption3"}));
\end{lstlisting}
\end{example}

In order that the protected class can be used either a tool specific license manager, or a license file (called \lstinline!licenseFile!) must be present.
The license file is standardized.
It is a Modelica package without classes that has a \lstinline!Protection! annotation of the following form which specifies a sequence of target records, which makes it natural to define start/end dates for different sets of targets individually:
\begin{lstlisting}[language=modelica]
record Protection
  record Authorization
    /*literal*/ constant String licensor = "" "Optional string to show information about the licensor";
    /*literal*/ constant String libraryKey "Matching the key in the class. Must be encrypted and not visible";
    /*literal*/ constant License license[:] "Definition of the license options and of the access rights";
  end Authorization;

  record License
    /*literal*/ String licensee = "" "Optional string to show information about the licensee";
    /*literal*/ String id[:] "Unique machine identifications, e.g., MAC addresses";
    /*literal*/ String features[:] = fill("", 0) "Activated library license features";
    /*literal*/ String startDate = "" "Optional start date in UTCformat YYYY-MM-DD";
    /*literal*/ String expirationDate = "" "Optional expiration date in UTCformat YYYY-MM-DD";
    /*literal*/ String operations[:] = fill("", 0) "Library usage conditions";
  end License;
end Protection;
\end{lstlisting}%
\index{Authorization@\robustinline{Authorization}!license file}\index{License@\robustinline{License}!license file}

The format of the strings used for \lstinline!libraryKey! and \lstinline!id! are not specified
(they are vendor specific). The \lstinline!libraryKey! is a secret of the library
developer. The \lstinline!operations! define the usage conditions and the following
are default names:
\begin{itemize}
\item
  \lstinline!"ExportBinary"! Binary code generated from the Modelica code of the
  library can be included in binaries produced by a simulation
  tool.
\item
  \lstinline!"ExportSource"! Source code generated from the Modelica code of the
  library can be included in sources produced by a simulation tool.
\end{itemize}

Additional tool-specific names can also be used. To protect the
\lstinline!libraryKey! and the target definitions, the authorization file must
be encrypted and must never show the \lstinline!libraryKey!.

\begin{nonnormative}
All other information, especially licensor and license should be visible, in order
that the user can get information about the license. It is useful to
include the name of the tool in the authorization file name with which
it was encrypted. Note, it is not useful to store this information in
the annotation, because only the tool that encrypted the \lstinline!Authorization!
package can also decrypt it.
\end{nonnormative}

\begin{example}
(Before encryption:)
\begin{lstlisting}[language=modelica]
// File MyLibrary\package.mo
package MyLibrary
  annotation(Protection(License(libraryKey="15783-A39323-498222-444ckk4ll",
  licenseFile="MyLibraryAuthorization_Tool.mo_lic"), $\ldots$));
end MyLibrary;

// File MyLibrary\MyLibraryAuthorization_Tool.mo\
// (authorization file before encryption)
package MyLibraryAuthorization_Tool
  annotation(Authorization(
  libraryKey="15783-A39323-498222-444ckk4ll",
  licensor ="Organization A\nRoad, Country",
 license={
  License(licensee="Organization B, Mr.X",
    id ={"lic:1269"}), // tool license number
  License(licensee="Organization C, Mr. Y",
    id ={"lic:511"}, expirationDate="2010-06-30",
   operations={"ExportBinary"}),
  License(licensee="Organization D, Mr. Z",
    id ={"mac:0019d2c9bfe7"}) // MAC address
  }));
end MyLibraryAuthorization_Tool;
\end{lstlisting}
\end{example}


\section{Functions}\label{annotations-for-functions}

See \crefnameref{derivatives-and-inverses-of-functions}, \crefnameref{function-inlining-and-event-generation}, and \crefnameref{annotations-for-external-libraries-and-include-files}.


\section{Choices for Modifications and Redeclarations}\label{annotation-choices-for-modifications-and-redeclarations}\label{choices-for-modifications-and-redeclarations}

See \crefnameref{annotation-choices-for-suggested-redeclarations-and-modifications}.