From 52750bf8e5b3fe5135ca938d0fac309e898d8087 Mon Sep 17 00:00:00 2001 From: HOS Date: Tue, 21 Nov 2023 13:32:39 +0100 Subject: [PATCH 01/37] More consistent non-syntax variant of definining annotations. --- chapters/annotations.tex | 43 ++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 597d6050e..523ed6feb 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -387,8 +387,8 @@ \section{Symbolic Processing}\label{annotations-for-symbolic-processing}\label{s \end{center} \begin{annotationdefinition}[Evaluate] -\begin{synopsis}[grammar]\begin{lstlisting} -"Evaluate" "=" ( false | true ) +\begin{synopsis}\begin{lstlisting} +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. @@ -478,8 +478,8 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \end{annotationdefinition} \begin{annotationdefinition}[HideResult] -\begin{synopsis}[grammar]\begin{lstlisting} -"HideResult" "=" ( false | true ) +\begin{synopsis}\begin{lstlisting} +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. @@ -495,8 +495,10 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \end{annotationdefinition} \begin{annotationdefinition}[TestCase] -\begin{synopsis}[grammar]\begin{lstlisting} -"TestCase" "(" "shouldPass" "=" ( false | true ) ")" +\begin{synopsis}\begin{lstlisting} +record TestCase + 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. @@ -518,7 +520,7 @@ \subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label For state machines it is useful to have single instances of local classes. This can be done using: \begin{lstlisting}[language=modelica] -annotation(singleInstance = true) +Boolean singleInstance = true; \end{lstlisting} The annotation \fmtannotationindex{singleInstance} 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. @@ -528,7 +530,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -annotation(mustBeConnected = "message"); +String mustBeConnected = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{mustBeConnected} @@ -556,7 +558,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -annotation(mayOnlyConnectOnce = "message"); +String mayOnlyConnectOnce = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{mayOnlyConnectOnce} @@ -1255,15 +1257,14 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte This section describes the annotations that are used to define properties of the graphical user interface. \begin{lstlisting}[language=modelica] -annotation(preferredView = $\mathit{view}$) +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}[language=grammar] - documentation-class-annotation: - annotation "(" DocumentationClass "=" true ")" +\begin{lstlisting} +Boolean DocumentationClass = true; \end{lstlisting}% \annotationindex{DocumentationClass} @@ -1276,7 +1277,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{nonnormative} \begin{lstlisting}[language=modelica] - annotation(defaultComponentName = "name") +String defaultComponentName = "$\mathit{name}$"; \end{lstlisting}% \annotationindex{defaultComponentName} @@ -1285,7 +1286,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte When automatically deriving a name, any trailing `\lstinline!1!' in the \lstinline!defaultComponentName! shall be disregarded. \begin{lstlisting}[language=modelica] -annotation(defaultComponentPrefixes = "prefixes") +String defaultComponentPrefixes = "$\mathit{prefixes}$"; \end{lstlisting}% \annotationindex{defaultComponentPrefixes} @@ -1304,7 +1305,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{nonnormative} \begin{lstlisting}[language=modelica] -annotation(missingInnerMessage = "message") +String missingInnerMessage = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{missingInnerMessage} @@ -1330,7 +1331,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A simple type or component of a simple type may have: \begin{lstlisting}[language=modelica] -annotation(absoluteValue = false); +Boolean absoluteValue; \end{lstlisting}% \annotationindex{absoluteValue} @@ -1343,7 +1344,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A model or block definition may contain: \begin{lstlisting}[language=modelica] -annotation(defaultConnectionStructurallyInconsistent = true) +Boolean defaultConnectionStructurallyInconsistent; \end{lstlisting}% \annotationindex{defaultConnectionStructurallyInconsistent} @@ -1358,7 +1359,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A class may have the following annotation: \begin{lstlisting}[language=modelica] -annotation(obsolete = "message"); +String obsolete = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{obsolete} @@ -1368,11 +1369,11 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -annotation(unassignedMessage = "message"); +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!"message"! can be used as a diagnostic message. +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! From 7842e890b1f7d15f1dda221b20beb86dd2fbd437 Mon Sep 17 00:00:00 2001 From: HOS Date: Tue, 21 Nov 2023 14:00:34 +0100 Subject: [PATCH 02/37] Need mathescape --- chapters/annotations.tex | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 523ed6feb..0ef30f50b 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -529,7 +529,7 @@ \subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: -\begin{lstlisting}[language=modelica] +\begin{lstlisting}[language=modelica, mathescape=true] String mustBeConnected = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{mustBeConnected} @@ -557,7 +557,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} \end{example} A connector component declaration may have the following annotation: -\begin{lstlisting}[language=modelica] +\begin{lstlisting}[language=modelica, mathescape=true] String mayOnlyConnectOnce = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{mayOnlyConnectOnce} @@ -1256,7 +1256,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte This section describes the annotations that are used to define properties of the graphical user interface. -\begin{lstlisting}[language=modelica] +\begin{lstlisting}[language=modelica, mathescape=true] String preferredView = $\mathit{view}$; \end{lstlisting} @@ -1276,7 +1276,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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] +\begin{lstlisting}[language=modelica, mathescape=true] String defaultComponentName = "$\mathit{name}$"; \end{lstlisting}% \annotationindex{defaultComponentName} @@ -1285,7 +1285,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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] +\begin{lstlisting}[language=modelica, mathescape=true] String defaultComponentPrefixes = "$\mathit{prefixes}$"; \end{lstlisting}% \annotationindex{defaultComponentPrefixes} @@ -1304,7 +1304,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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] +\begin{lstlisting}[language=modelica, mathescape=true] String missingInnerMessage = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{missingInnerMessage} @@ -1358,7 +1358,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{nonnormative} A class may have the following annotation: -\begin{lstlisting}[language=modelica] +\begin{lstlisting}[language=modelica, mathescape=true] String obsolete = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{obsolete} @@ -1368,7 +1368,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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] +\begin{lstlisting}[language=modelica, mathescape=true] String unassignedMessage = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{unassignedMessage} From efff72f095e4e91fdf5914f1e5f050d7138cd4a1 Mon Sep 17 00:00:00 2001 From: HOS Date: Wed, 22 Nov 2023 11:03:55 +0100 Subject: [PATCH 03/37] Remove bindings for these as well. --- chapters/annotations.tex | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 0ef30f50b..abd2db044 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -520,11 +520,12 @@ \subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label For state machines it is useful to have single instances of local classes. This can be done using: \begin{lstlisting}[language=modelica] -Boolean singleInstance = true; +Boolean singleInstance; \end{lstlisting} -The annotation \fmtannotationindex{singleInstance} 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 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} @@ -1264,11 +1265,11 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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} -Boolean DocumentationClass = true; +Boolean DocumentationClass; \end{lstlisting}% \annotationindex{DocumentationClass} -Only allowed as class annotation on any kind of class and implies that this class and all classes within it are treated as having the annotation \lstinline!preferredView = "info"!. +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} From 0d29c5f3e6ac9a5caadd4d218088ac3416225a7c Mon Sep 17 00:00:00 2001 From: HOS Date: Fri, 1 Dec 2023 16:42:41 +0100 Subject: [PATCH 04/37] Explain what annotation definitions mean. --- chapters/annotations.tex | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index abd2db044..10dce97ad 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -47,6 +47,11 @@ \section{Documentation}\label{annotations-for-documentation}\label{documentation How the tool interprets the information in \lstinline!Documentation! is unspecified. +\subsection{How to interpret annotation definitions} +If the annotation itself is described by a \lstinline!record! \emph{class} the annotation can be seen as a modifier for a \lstinline!record! \emph{component} with the same name. +If the annotation is declared as a parameter the corresponding modifier must be an evaluable parameter. +If the annotation is declared as a constant the corresponding modifier must be a literal value. + \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. From 65505e916873f552e0533d9d3126505f020b60a2 Mon Sep 17 00:00:00 2001 From: HOS Date: Fri, 1 Dec 2023 16:46:19 +0100 Subject: [PATCH 05/37] Apply it to the new annotations and some old. --- chapters/annotations.tex | 42 ++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 10dce97ad..9bbc68eba 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -39,8 +39,8 @@ \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 - String info = "" "Description of the class"; - String revisions = "" "Revision history"; + constant String info = "" "Description of the class"; + constant String revisions = "" "Revision history"; Figure[:] figures = {}; "Simulation result figures"; end Documentation; \end{lstlisting} @@ -393,7 +393,7 @@ \section{Symbolic Processing}\label{annotations-for-symbolic-processing}\label{s \begin{annotationdefinition}[Evaluate] \begin{synopsis}\begin{lstlisting} -Boolean Evaluate; +parameter 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. @@ -466,10 +466,10 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \begin{synopsis} \begin{lstlisting}[language=modelica] record experiment - Real StartTime(unit = "s") = 0; - Real StopTime(unit = "s"); - Real Interval(unit = "s"); - Real Tolerance(unit = "1"); + parameter Real StartTime(unit = "s") = 0; + parameter Real StopTime(unit = "s"); + parameter Real Interval(unit = "s"); + parameter Real Tolerance(unit = "1"); end experiment; \end{lstlisting} \end{synopsis} @@ -484,7 +484,7 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \begin{annotationdefinition}[HideResult] \begin{synopsis}\begin{lstlisting} -Boolean HideResult; +parameter 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. @@ -502,7 +502,7 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \begin{annotationdefinition}[TestCase] \begin{synopsis}\begin{lstlisting} record TestCase - Boolean shouldPass; + constant Boolean shouldPass; end TestCase; \end{lstlisting}\end{synopsis} \begin{semantics} @@ -525,7 +525,7 @@ \subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label For state machines it is useful to have single instances of local classes. This can be done using: \begin{lstlisting}[language=modelica] -Boolean singleInstance; +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. @@ -536,7 +536,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica, mathescape=true] -String mustBeConnected = "$\mathit{message}$"; +constant String mustBeConnected = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{mustBeConnected} @@ -564,7 +564,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica, mathescape=true] -String mayOnlyConnectOnce = "$\mathit{message}$"; +constant String mayOnlyConnectOnce = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{mayOnlyConnectOnce} @@ -1263,14 +1263,14 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte This section describes the annotations that are used to define properties of the graphical user interface. \begin{lstlisting}[language=modelica, mathescape=true] -String preferredView = $\mathit{view}$; +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} -Boolean DocumentationClass; +constant Boolean DocumentationClass; \end{lstlisting}% \annotationindex{DocumentationClass} @@ -1283,7 +1283,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{nonnormative} \begin{lstlisting}[language=modelica, mathescape=true] -String defaultComponentName = "$\mathit{name}$"; +constant String defaultComponentName = "$\mathit{name}$"; \end{lstlisting}% \annotationindex{defaultComponentName} @@ -1292,7 +1292,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte When automatically deriving a name, any trailing `\lstinline!1!' in the \lstinline!defaultComponentName! shall be disregarded. \begin{lstlisting}[language=modelica, mathescape=true] -String defaultComponentPrefixes = "$\mathit{prefixes}$"; +constant String defaultComponentPrefixes = "$\mathit{prefixes}$"; \end{lstlisting}% \annotationindex{defaultComponentPrefixes} @@ -1311,7 +1311,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{nonnormative} \begin{lstlisting}[language=modelica, mathescape=true] -String missingInnerMessage = "$\mathit{message}$"; +constant String missingInnerMessage = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{missingInnerMessage} @@ -1337,7 +1337,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A simple type or component of a simple type may have: \begin{lstlisting}[language=modelica] -Boolean absoluteValue; +constant Boolean absoluteValue; \end{lstlisting}% \annotationindex{absoluteValue} @@ -1350,7 +1350,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A model or block definition may contain: \begin{lstlisting}[language=modelica] -Boolean defaultConnectionStructurallyInconsistent; +constant Boolean defaultConnectionStructurallyInconsistent; \end{lstlisting}% \annotationindex{defaultConnectionStructurallyInconsistent} @@ -1365,7 +1365,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A class may have the following annotation: \begin{lstlisting}[language=modelica, mathescape=true] -String obsolete = "$\mathit{message}$"; +constant String obsolete = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{obsolete} @@ -1375,7 +1375,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A component declaration may have the following annotation: \begin{lstlisting}[language=modelica, mathescape=true] -String unassignedMessage = "$\mathit{message}$"; +constant String unassignedMessage = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{unassignedMessage} From b107f8101b48c624e730974e4ef38a6a50785656 Mon Sep 17 00:00:00 2001 From: HOS Date: Fri, 1 Dec 2023 16:47:26 +0100 Subject: [PATCH 06/37] Reduce it further --- chapters/annotations.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 9bbc68eba..32c7d5eed 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -466,10 +466,10 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \begin{synopsis} \begin{lstlisting}[language=modelica] record experiment - parameter Real StartTime(unit = "s") = 0; - parameter Real StopTime(unit = "s"); - parameter Real Interval(unit = "s"); - parameter Real Tolerance(unit = "1"); + Real StartTime(unit = "s") = 0; + Real StopTime(unit = "s"); + Real Interval(unit = "s"); + Real Tolerance(unit = "1"); end experiment; \end{lstlisting} \end{synopsis} From d07b419c445a86130d8dbf36b9eae030278e0adb Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Fri, 5 Jan 2024 13:02:39 +0100 Subject: [PATCH 07/37] Apply suggestions from code review Co-authored-by: Henrik Tidefelt --- chapters/annotations.tex | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 32c7d5eed..a656861ce 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -47,7 +47,7 @@ \section{Documentation}\label{annotations-for-documentation}\label{documentation How the tool interprets the information in \lstinline!Documentation! is unspecified. -\subsection{How to interpret annotation definitions} +\subsection{How to Interpret Annotation Definitions} If the annotation itself is described by a \lstinline!record! \emph{class} the annotation can be seen as a modifier for a \lstinline!record! \emph{component} with the same name. If the annotation is declared as a parameter the corresponding modifier must be an evaluable parameter. If the annotation is declared as a constant the corresponding modifier must be a literal value. @@ -535,7 +535,7 @@ \subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: -\begin{lstlisting}[language=modelica, mathescape=true] +\begin{lstlisting}[language=modelica] constant String mustBeConnected = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{mustBeConnected} @@ -563,7 +563,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} \end{example} A connector component declaration may have the following annotation: -\begin{lstlisting}[language=modelica, mathescape=true] +\begin{lstlisting}[language=modelica] constant String mayOnlyConnectOnce = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{mayOnlyConnectOnce} @@ -1262,7 +1262,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte This section describes the annotations that are used to define properties of the graphical user interface. -\begin{lstlisting}[language=modelica, mathescape=true] +\begin{lstlisting}[language=modelica] constant String preferredView = $\mathit{view}$; \end{lstlisting} @@ -1282,7 +1282,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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, mathescape=true] +\begin{lstlisting}[language=modelica] constant String defaultComponentName = "$\mathit{name}$"; \end{lstlisting}% \annotationindex{defaultComponentName} @@ -1291,7 +1291,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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, mathescape=true] +\begin{lstlisting}[language=modelica] constant String defaultComponentPrefixes = "$\mathit{prefixes}$"; \end{lstlisting}% \annotationindex{defaultComponentPrefixes} @@ -1310,7 +1310,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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, mathescape=true] +\begin{lstlisting}[language=modelica] constant String missingInnerMessage = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{missingInnerMessage} @@ -1364,7 +1364,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{nonnormative} A class may have the following annotation: -\begin{lstlisting}[language=modelica, mathescape=true] +\begin{lstlisting}[language=modelica] constant String obsolete = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{obsolete} @@ -1374,7 +1374,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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, mathescape=true] +\begin{lstlisting}[language=modelica] constant String unassignedMessage = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{unassignedMessage} From 5d43d2359fc0624d8949c56d6445f6ab9509fb59 Mon Sep 17 00:00:00 2001 From: HOS Date: Fri, 5 Jan 2024 13:08:16 +0100 Subject: [PATCH 08/37] Add description of what a default value in record means. --- chapters/annotations.tex | 1 + 1 file changed, 1 insertion(+) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index a656861ce..089053e31 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -49,6 +49,7 @@ \section{Documentation}\label{annotations-for-documentation}\label{documentation \subsection{How to Interpret Annotation Definitions} If the annotation itself is described by a \lstinline!record! \emph{class} the annotation can be seen as a modifier for a \lstinline!record! \emph{component} with the same name. +A default value for a record member will be used if there is no modifier for that record member. If the annotation is declared as a parameter the corresponding modifier must be an evaluable parameter. If the annotation is declared as a constant the corresponding modifier must be a literal value. From 1aafeb51073baf3cfdfa4a70f4525d4d5315ea46 Mon Sep 17 00:00:00 2001 From: HOS Date: Tue, 23 Jan 2024 17:06:41 +0100 Subject: [PATCH 09/37] Use constant instead of parameter for the time being. --- chapters/annotations.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 089053e31..aa1ea5afb 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -394,7 +394,7 @@ \section{Symbolic Processing}\label{annotations-for-symbolic-processing}\label{s \begin{annotationdefinition}[Evaluate] \begin{synopsis}\begin{lstlisting} -parameter Boolean Evaluate; +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. @@ -485,7 +485,7 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \begin{annotationdefinition}[HideResult] \begin{synopsis}\begin{lstlisting} -parameter Boolean HideResult; +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. From 61349faece41eda4f63a1f3ed47ea70cf42375ea Mon Sep 17 00:00:00 2001 From: HOS Date: Tue, 23 Jan 2024 17:20:56 +0100 Subject: [PATCH 10/37] Add constant everywhere where applicable, and parameter for the specific enable-case. --- chapters/annotations.tex | 108 +++++++++++++++++++-------------------- 1 file changed, 54 insertions(+), 54 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index aa1ea5afb..8b4041c11 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -83,23 +83,23 @@ \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 - String title = "" "Title meant for display"; - String identifier = "" "Identifier meant for programmatic access"; - String group = "" "Name of plot group"; - Boolean preferred = false "Automatically display figure after simulation"; + constant String title = "" "Title meant for display"; + constant String identifier = "" "Identifier meant for programmatic access"; + constant String group = "" "Name of plot group"; + constant Boolean preferred = false "Automatically display figure after simulation"; Plot[:] plots "Plots"; - String caption = "" "Figure caption"; + 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 - String title "Title meant for display"; - String identifier = "" "Identifier meant for programmatic access"; + constant String title "Title meant for display"; + constant String identifier = "" "Identifier meant for programmatic access"; Curve[:] curves "Plot curves"; - Axis x "X axis properties"; - Axis y "Y axis properties"; + constant Axis x "X axis properties"; + constant Axis y "Y axis properties"; end Plot; \end{lstlisting} @@ -145,11 +145,11 @@ \subsubsection{Axis Properties}\label{axis-properties} Properties may be defined for each \lstinline!Plot! axis\annotationindex{Axis}: \begin{lstlisting}[language=modelica] record Axis - Real min "Axis lower bound, in 'unit'"; - Real max "Axis upper bound, in 'unit'"; - String unit = "" "Unit of axis tick labels"; - String label "Axis label"; - AxisScale scale = Linear() "Mapping between axis values and position on axis" + constant Real min "Axis lower bound, in 'unit'"; + constant Real max "Axis upper bound, in 'unit'"; + constant String unit = "" "Unit of axis tick labels"; + constant String label "Axis label"; + constant AxisScale scale = Linear() "Mapping between axis values and position on axis" end Axis; \end{lstlisting} @@ -193,7 +193,7 @@ \subsubsection{Axis Properties}\label{axis-properties} \begin{lstlisting}[language=modelica] record Log extends AxisScale; - Integer base(min = 2) = 10; + constant Integer base(min = 2) = 10; end Log; \end{lstlisting}% \index{Log@\robustinline{Log} (axis scale)} @@ -222,7 +222,7 @@ \subsubsection{Plot Curves}\label{plot-curves} record Curve expression x = time "X coordinate values"; expression y "Y coordinate values"; - String legend "Legend"; + constant String legend "Legend"; end Curve; \end{lstlisting} @@ -467,10 +467,10 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \begin{synopsis} \begin{lstlisting}[language=modelica] record experiment - Real StartTime(unit = "s") = 0; - Real StopTime(unit = "s"); - Real Interval(unit = "s"); - Real Tolerance(unit = "1"); + constant Real StartTime(unit = "s") = 0; + constant Real StopTime(unit = "s"); + constant Real Interval(unit = "s"); + constant Real Tolerance(unit = "1"); end experiment; \end{lstlisting} \end{synopsis} @@ -692,10 +692,10 @@ \subsubsection{Coordinate Systems}\label{coordinate-systems} \begin{lstlisting}[language=modelica] record CoordinateSystem - Extent extent; - Boolean preserveAspectRatio = true; - Real initialScale = 0.1; - DrawingUnit grid[2]; + constant Extent extent; + constant Boolean preserveAspectRatio = true; + constant Real initialScale = 0.1; + constant DrawingUnit grid[2]; end CoordinateSystem; \end{lstlisting} @@ -861,13 +861,13 @@ \subsection{Extends-Clause}\label{extends-clause} \begin{lstlisting}[language=modelica] record IconMap - Extent extent = {{0, 0}, {0, 0}}; - Boolean primitivesVisible = true; + constant Extent extent = {{0, 0}, {0, 0}}; + constant Boolean primitivesVisible = true; end IconMap; record DiagramMap - Extent extent = {{0, 0}, {0, 0}}; - Boolean primitivesVisible = true; + constant Extent extent = {{0, 0}, {0, 0}}; + constant Boolean primitivesVisible = true; end DiagramMap; \end{lstlisting}% \annotationindex{IconMap}\annotationindex{DiagramMap} @@ -1405,21 +1405,21 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A component declaration or a short replaceable class definition may have the following annotation: \begin{lstlisting}[language=modelica] record Dialog - String tab = "General"; - String group = ""; - Boolean enable = true; - Boolean showStartAttribute = false; - Boolean colorSelector = false; - Selector loadSelector; - Selector saveSelector; - Selector directorySelector; - String groupImage = ""; - Boolean connectorSizing = false; + constant String tab = "General"; + constant String group = ""; + parameter Boolean enable = true; + constant Boolean showStartAttribute = false; + constant Boolean colorSelector = false; + constant Selector loadSelector; + constant Selector saveSelector; + constant Selector directorySelector; + constant String groupImage = ""; + constant Boolean connectorSizing = false; end Dialog; record Selector - String filter = ""; - String caption = ""; + constant String filter = ""; + constant String caption = ""; end Selector; \end{lstlisting}% \annotationindex{Dialog} @@ -1971,14 +1971,14 @@ \subsection{Version Date and Build Information}\label{version-date-and-build-inf 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] -String versionDate "UTC date of first version build (in format: YYYY-MM-DD)"; -Integer versionBuild "Larger number is a more recent maintenance update"; -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"; -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"; +constant String versionDate "UTC date of first version build (in format: YYYY-MM-DD)"; +constant Integer versionBuild "Larger number is a more recent maintenance update"; +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"; +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} @@ -2203,10 +2203,10 @@ \subsection{Licensing}\label{licensing} \begin{lstlisting}[language=modelica] record Protection $\ldots$ - String features[:] = fill("", 0) "Required license features"; + constant String features[:] = fill("", 0) "Required license features"; record License - String libraryKey; - String licenseFile = "" "Optional, default mapping if empty"; + constant String libraryKey; + constant String licenseFile = "" "Optional, default mapping if empty"; end License; end Protection; \end{lstlisting} @@ -2242,9 +2242,9 @@ \subsection{Licensing}\label{licensing} 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 Authorization - String licensor = "" "Optional string to show information about the licensor"; - String libraryKey "Matching the key in the class. Must be encrypted and not visible"; - License license[:] "Definition of the license options and of the access rights"; + constant String licensor = "" "Optional string to show information about the licensor"; + constant String libraryKey "Matching the key in the class. Must be encrypted and not visible"; + constant License license[:] "Definition of the license options and of the access rights"; end Authorization; record License From 32cc58db3711f3b9b5b57c47f49c758ddc3ae300 Mon Sep 17 00:00:00 2001 From: HOS Date: Tue, 23 Jan 2024 17:27:12 +0100 Subject: [PATCH 11/37] Move how-to-interpret earlier in the chapter. --- chapters/annotations.tex | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 8b4041c11..32215c619 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -8,6 +8,12 @@ \chapter{Annotations}\label{annotations} (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{How to Interpret Annotation Definitions}\label{how-to-interpret-annotation-definitions} +If the annotation itself is described by a \lstinline!record! \emph{class} the annotation can be seen as a modifier for a \lstinline!record! \emph{component} with the same name. +A default value for a record member will be used if there is no modifier for that record member. +If the annotation is declared as a parameter the corresponding modifier must be an evaluable parameter. +If the annotation is declared as a constant the corresponding modifier must 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. @@ -47,12 +53,6 @@ \section{Documentation}\label{annotations-for-documentation}\label{documentation How the tool interprets the information in \lstinline!Documentation! is unspecified. -\subsection{How to Interpret Annotation Definitions} -If the annotation itself is described by a \lstinline!record! \emph{class} the annotation can be seen as a modifier for a \lstinline!record! \emph{component} with the same name. -A default value for a record member will be used if there is no modifier for that record member. -If the annotation is declared as a parameter the corresponding modifier must be an evaluable parameter. -If the annotation is declared as a constant the corresponding modifier must be a literal value. - \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. From 93d01ebea3f4d745c218c598dc795c0dcbf54d93 Mon Sep 17 00:00:00 2001 From: HOS Date: Tue, 23 Jan 2024 17:32:15 +0100 Subject: [PATCH 12/37] Add note about annotation-syntax in Introduction. --- chapters/introduction.tex | 1 + 1 file changed, 1 insertion(+) diff --git a/chapters/introduction.tex b/chapters/introduction.tex index 800050b7f..198a746f1 100644 --- a/chapters/introduction.tex +++ b/chapters/introduction.tex @@ -53,6 +53,7 @@ \section{Scope of the Specification}\label{scope-of-the-specification} Initial setup of the model is specified using \lstinline!start!-attributes and equations that hold only during initialization. A Modelica class may also contain annotations, i.e., formal comments, which specify graphical representations of the class (icon and diagram), documentation text for the class, and version information. +See \cref{annotations} and note that this uses a special syntax according to \cref{how-to-interpret-annotation-definitions}. \section{Some Definitions}\label{some-definitions} From 498839debc68e7094d1d9bea3bf35acfba9be64f Mon Sep 17 00:00:00 2001 From: HOS Date: Thu, 15 Feb 2024 13:56:43 +0100 Subject: [PATCH 13/37] According to comments. --- chapters/introduction.tex | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/chapters/introduction.tex b/chapters/introduction.tex index 198a746f1..6d9fb8e91 100644 --- a/chapters/introduction.tex +++ b/chapters/introduction.tex @@ -53,7 +53,6 @@ \section{Scope of the Specification}\label{scope-of-the-specification} Initial setup of the model is specified using \lstinline!start!-attributes and equations that hold only during initialization. A Modelica class may also contain annotations, i.e., formal comments, which specify graphical representations of the class (icon and diagram), documentation text for the class, and version information. -See \cref{annotations} and note that this uses a special syntax according to \cref{how-to-interpret-annotation-definitions}. \section{Some Definitions}\label{some-definitions} @@ -168,3 +167,5 @@ \section{Notation}\label{notation} der "(" SOME-TOKEN ")" | "(" differentiated-expression "+" differentiated-expression ")" \end{lstlisting} + +Annotations are described in \cref{annotations} and use a special syntax according to \cref{how-to-interpret-annotation-definitions}. From ddd8df9613a416903337c30a4db0da2ae4fa6e15 Mon Sep 17 00:00:00 2001 From: HOS Date: Thu, 22 Feb 2024 17:10:08 +0100 Subject: [PATCH 14/37] According to decision, add comment in front. --- chapters/annotations.tex | 138 +++++++++++++++++++-------------------- 1 file changed, 69 insertions(+), 69 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 32215c619..ccf8aa89e 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -11,8 +11,8 @@ \chapter{Annotations}\label{annotations} \section{How to Interpret Annotation Definitions}\label{how-to-interpret-annotation-definitions} If the annotation itself is described by a \lstinline!record! \emph{class} the annotation can be seen as a modifier for a \lstinline!record! \emph{component} with the same name. A default value for a record member will be used if there is no modifier for that record member. -If the annotation is declared as a parameter the corresponding modifier must be an evaluable parameter. -If the annotation is declared as a constant the corresponding modifier must be a literal value. +If the annotation is declared as an \lstinline!/*evaluable*/ parameter! the corresponding modifier must be an evaluable parameter. +If the annotation is declared as a \lstinline!/*literal*/ constant! the corresponding modifier must be a literal value. \section{Vendor-Specific Annotations}\label{vendor-specific-annotations} @@ -45,8 +45,8 @@ \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 - constant String info = "" "Description of the class"; - constant String revisions = "" "Revision history"; + /*literal*/ constant String info = "" "Description of the class"; + /*literal*/ constant String revisions = "" "Revision history"; Figure[:] figures = {}; "Simulation result figures"; end Documentation; \end{lstlisting} @@ -83,23 +83,23 @@ \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 - constant String title = "" "Title meant for display"; - constant String identifier = "" "Identifier meant for programmatic access"; - constant String group = "" "Name of plot group"; - constant Boolean preferred = false "Automatically display figure after simulation"; + /*literal*/ constant String title = "" "Title meant for display"; + /*literal*/ constant String identifier = "" "Identifier meant for programmatic access"; + /*literal*/ constant String group = "" "Name of plot group"; + /*literal*/ constant Boolean preferred = false "Automatically display figure after simulation"; Plot[:] plots "Plots"; - constant String caption = "" "Figure caption"; + /*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 - constant String title "Title meant for display"; - constant String identifier = "" "Identifier meant for programmatic access"; + /*literal*/ constant String title "Title meant for display"; + /*literal*/ constant String identifier = "" "Identifier meant for programmatic access"; Curve[:] curves "Plot curves"; - constant Axis x "X axis properties"; - constant Axis y "Y axis properties"; + /*literal*/ constant Axis x "X axis properties"; + /*literal*/ constant Axis y "Y axis properties"; end Plot; \end{lstlisting} @@ -145,11 +145,11 @@ \subsubsection{Axis Properties}\label{axis-properties} Properties may be defined for each \lstinline!Plot! axis\annotationindex{Axis}: \begin{lstlisting}[language=modelica] record Axis - constant Real min "Axis lower bound, in 'unit'"; - constant Real max "Axis upper bound, in 'unit'"; - constant String unit = "" "Unit of axis tick labels"; - constant String label "Axis label"; - constant AxisScale scale = Linear() "Mapping between axis values and position on 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} @@ -193,7 +193,7 @@ \subsubsection{Axis Properties}\label{axis-properties} \begin{lstlisting}[language=modelica] record Log extends AxisScale; - constant Integer base(min = 2) = 10; + /*literal*/ constant Integer base(min = 2) = 10; end Log; \end{lstlisting}% \index{Log@\robustinline{Log} (axis scale)} @@ -222,7 +222,7 @@ \subsubsection{Plot Curves}\label{plot-curves} record Curve expression x = time "X coordinate values"; expression y "Y coordinate values"; - constant String legend "Legend"; + /*literal*/ constant String legend "Legend"; end Curve; \end{lstlisting} @@ -394,7 +394,7 @@ \section{Symbolic Processing}\label{annotations-for-symbolic-processing}\label{s \begin{annotationdefinition}[Evaluate] \begin{synopsis}\begin{lstlisting} -constant Boolean Evaluate; +/*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. @@ -467,10 +467,10 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \begin{synopsis} \begin{lstlisting}[language=modelica] record experiment - constant Real StartTime(unit = "s") = 0; - constant Real StopTime(unit = "s"); - constant Real Interval(unit = "s"); - constant Real Tolerance(unit = "1"); + /*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} @@ -485,7 +485,7 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \begin{annotationdefinition}[HideResult] \begin{synopsis}\begin{lstlisting} -constant Boolean HideResult; +/*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. @@ -503,7 +503,7 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} \begin{annotationdefinition}[TestCase] \begin{synopsis}\begin{lstlisting} record TestCase - constant Boolean shouldPass; + /*literal*/ constant Boolean shouldPass; end TestCase; \end{lstlisting}\end{synopsis} \begin{semantics} @@ -526,7 +526,7 @@ \subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label For state machines it is useful to have single instances of local classes. This can be done using: \begin{lstlisting}[language=modelica] -constant Boolean singleInstance; +/*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. @@ -537,7 +537,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -constant String mustBeConnected = "$\mathit{message}$"; +/*literal*/ constant String mustBeConnected = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{mustBeConnected} @@ -565,7 +565,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -constant String mayOnlyConnectOnce = "$\mathit{message}$"; +/*literal*/ constant String mayOnlyConnectOnce = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{mayOnlyConnectOnce} @@ -692,10 +692,10 @@ \subsubsection{Coordinate Systems}\label{coordinate-systems} \begin{lstlisting}[language=modelica] record CoordinateSystem - constant Extent extent; - constant Boolean preserveAspectRatio = true; - constant Real initialScale = 0.1; - constant DrawingUnit grid[2]; + /*literal*/ constant Extent extent; + /*literal*/ constant Boolean preserveAspectRatio = true; + /*literal*/ constant Real initialScale = 0.1; + /*literal*/ constant DrawingUnit grid[2]; end CoordinateSystem; \end{lstlisting} @@ -861,13 +861,13 @@ \subsection{Extends-Clause}\label{extends-clause} \begin{lstlisting}[language=modelica] record IconMap - constant Extent extent = {{0, 0}, {0, 0}}; - constant Boolean primitivesVisible = true; + /*literal*/ constant Extent extent = {{0, 0}, {0, 0}}; + /*literal*/ constant Boolean primitivesVisible = true; end IconMap; record DiagramMap - constant Extent extent = {{0, 0}, {0, 0}}; - constant Boolean primitivesVisible = true; + /*literal*/ constant Extent extent = {{0, 0}, {0, 0}}; + /*literal*/ constant Boolean primitivesVisible = true; end DiagramMap; \end{lstlisting}% \annotationindex{IconMap}\annotationindex{DiagramMap} @@ -1264,14 +1264,14 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte This section describes the annotations that are used to define properties of the graphical user interface. \begin{lstlisting}[language=modelica] -constant String preferredView = $\mathit{view}$; +/*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} -constant Boolean DocumentationClass; +/*literal*/ constant Boolean DocumentationClass; \end{lstlisting}% \annotationindex{DocumentationClass} @@ -1284,7 +1284,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{nonnormative} \begin{lstlisting}[language=modelica] -constant String defaultComponentName = "$\mathit{name}$"; +/*literal*/ constant String defaultComponentName = "$\mathit{name}$"; \end{lstlisting}% \annotationindex{defaultComponentName} @@ -1293,7 +1293,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte When automatically deriving a name, any trailing `\lstinline!1!' in the \lstinline!defaultComponentName! shall be disregarded. \begin{lstlisting}[language=modelica] -constant String defaultComponentPrefixes = "$\mathit{prefixes}$"; +/*literal*/ constant String defaultComponentPrefixes = "$\mathit{prefixes}$"; \end{lstlisting}% \annotationindex{defaultComponentPrefixes} @@ -1312,7 +1312,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{nonnormative} \begin{lstlisting}[language=modelica] -constant String missingInnerMessage = "$\mathit{message}$"; +/*literal*/ constant String missingInnerMessage = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{missingInnerMessage} @@ -1338,7 +1338,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A simple type or component of a simple type may have: \begin{lstlisting}[language=modelica] -constant Boolean absoluteValue; +/*literal*/ constant Boolean absoluteValue; \end{lstlisting}% \annotationindex{absoluteValue} @@ -1351,7 +1351,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A model or block definition may contain: \begin{lstlisting}[language=modelica] -constant Boolean defaultConnectionStructurallyInconsistent; +/*literal*/ constant Boolean defaultConnectionStructurallyInconsistent; \end{lstlisting}% \annotationindex{defaultConnectionStructurallyInconsistent} @@ -1366,7 +1366,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A class may have the following annotation: \begin{lstlisting}[language=modelica] -constant String obsolete = "$\mathit{message}$"; +/*literal*/ constant String obsolete = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{obsolete} @@ -1376,7 +1376,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -constant String unassignedMessage = "$\mathit{message}$"; +/*literal*/ constant String unassignedMessage = "$\mathit{message}$"; \end{lstlisting}% \annotationindex{unassignedMessage} @@ -1405,21 +1405,21 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A component declaration or a short replaceable class definition may have the following annotation: \begin{lstlisting}[language=modelica] record Dialog - constant String tab = "General"; - constant String group = ""; - parameter Boolean enable = true; - constant Boolean showStartAttribute = false; - constant Boolean colorSelector = false; - constant Selector loadSelector; - constant Selector saveSelector; - constant Selector directorySelector; - constant String groupImage = ""; - constant Boolean connectorSizing = false; + /*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 - constant String filter = ""; - constant String caption = ""; + /*literal*/ constant String filter = ""; + /*literal*/ constant String caption = ""; end Selector; \end{lstlisting}% \annotationindex{Dialog} @@ -1971,12 +1971,12 @@ \subsection{Version Date and Build Information}\label{version-date-and-build-inf 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] -constant String versionDate "UTC date of first version build (in format: YYYY-MM-DD)"; -constant Integer versionBuild "Larger number is a more recent maintenance update"; -constant String dateModified "UTC date and time of the latest change to the package +/*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"; -constant String revisionId "Revision identifier of the version management system used +/*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}% @@ -2203,10 +2203,10 @@ \subsection{Licensing}\label{licensing} \begin{lstlisting}[language=modelica] record Protection $\ldots$ - constant String features[:] = fill("", 0) "Required license features"; + /*literal*/ constant String features[:] = fill("", 0) "Required license features"; record License - constant String libraryKey; - constant String licenseFile = "" "Optional, default mapping if empty"; + /*literal*/ constant String libraryKey; + /*literal*/ constant String licenseFile = "" "Optional, default mapping if empty"; end License; end Protection; \end{lstlisting} @@ -2242,9 +2242,9 @@ \subsection{Licensing}\label{licensing} 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 Authorization - constant String licensor = "" "Optional string to show information about the licensor"; - constant String libraryKey "Matching the key in the class. Must be encrypted and not visible"; - constant License license[:] "Definition of the license options and of the access rights"; + /*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 From 8bc28a8c3988ea8e1f3ae48c4e9e9dc3c64d7c66 Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Tue, 12 Mar 2024 17:40:50 +0100 Subject: [PATCH 15/37] Apply suggestions from code review Co-authored-by: Henrik Tidefelt --- chapters/annotations.tex | 20 +++++++++++++++----- chapters/introduction.tex | 2 +- 2 files changed, 16 insertions(+), 6 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index ccf8aa89e..c3321210a 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -8,11 +8,21 @@ \chapter{Annotations}\label{annotations} (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{How to Interpret Annotation Definitions}\label{how-to-interpret-annotation-definitions} -If the annotation itself is described by a \lstinline!record! \emph{class} the annotation can be seen as a modifier for a \lstinline!record! \emph{component} with the same name. -A default value for a record member will be used if there is no modifier for that record member. -If the annotation is declared as an \lstinline!/*evaluable*/ parameter! the corresponding modifier must be an evaluable parameter. -If the annotation is declared as a \lstinline!/*literal*/ constant! the corresponding modifier must be a literal value. +\section{Notation for Annotation Definitions}\label{how-to-interpret-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. +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. +For an array record member, the special expression \lstinline!{}! in a declaration equation indicates that the array is empty by default. + +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} diff --git a/chapters/introduction.tex b/chapters/introduction.tex index 6d9fb8e91..03639d473 100644 --- a/chapters/introduction.tex +++ b/chapters/introduction.tex @@ -168,4 +168,4 @@ \section{Notation}\label{notation} | "(" differentiated-expression "+" differentiated-expression ")" \end{lstlisting} -Annotations are described in \cref{annotations} and use a special syntax according to \cref{how-to-interpret-annotation-definitions}. +Annotations are defined using the syntactic forms of Modelica record definitions and component declarations, but with special semantics given in \cref{how-to-interpret-annotation-definitions}. From 4ef0f65a50f68bda682a29d0cd1d10d348f1a6a5 Mon Sep 17 00:00:00 2001 From: HOS Date: Tue, 12 Mar 2024 17:45:17 +0100 Subject: [PATCH 16/37] More advanced suggestions from code review. --- chapters/annotations.tex | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index c3321210a..f81ac76e5 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -547,11 +547,12 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -/*literal*/ constant String mustBeConnected = "$\mathit{message}$"; +/*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} @@ -575,7 +576,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -/*literal*/ constant String mayOnlyConnectOnce = "$\mathit{message}$"; +/*literal*/ constant String mayOnlyConnectOnce; \end{lstlisting}% \annotationindex{mayOnlyConnectOnce} @@ -585,6 +586,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} \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}. @@ -1981,14 +1983,18 @@ \subsection{Version Date and Build Information}\label{version-date-and-build-inf 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"; +/*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} From 65f4cf4b0eb025e8885cd201401a9ca70d62ab01 Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Tue, 12 Mar 2024 17:46:11 +0100 Subject: [PATCH 17/37] Update chapters/annotations.tex Co-authored-by: Henrik Tidefelt --- chapters/annotations.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index f81ac76e5..45fae21f5 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -1419,7 +1419,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte record Dialog /*literal*/ constant String tab = "General"; /*literal*/ constant String group = ""; - /*evaluable* / parameter Boolean enable = true; + /*evaluable*/ parameter Boolean enable = true; /*literal*/ constant Boolean showStartAttribute = false; /*literal*/ constant Boolean colorSelector = false; /*literal*/ constant Selector loadSelector; From c59e23b123db7d8ba5874bc7590250ea72698bb9 Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Thu, 14 Mar 2024 10:56:44 +0100 Subject: [PATCH 18/37] Update chapters/annotations.tex --- chapters/annotations.tex | 1 - 1 file changed, 1 deletion(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index df286b0ed..2f7066b9f 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -18,7 +18,6 @@ \section{Notation for Annotation Definitions}\label{how-to-interpret-annotation- 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. -For an array record member, the special expression \lstinline!{}! in a declaration equation indicates that the array is empty by default. 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. From 94b19aacbf43b95de444074fb1bfeb439152f5fc Mon Sep 17 00:00:00 2001 From: HOS Date: Thu, 14 Mar 2024 16:24:46 +0100 Subject: [PATCH 19/37] Rename new label. --- chapters/annotations.tex | 2 +- chapters/introduction.tex | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 2f7066b9f..0ee6967e3 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -8,7 +8,7 @@ \chapter{Annotations}\label{annotations} (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{how-to-interpret-annotation-definitions} +\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. diff --git a/chapters/introduction.tex b/chapters/introduction.tex index 03639d473..8ecbded73 100644 --- a/chapters/introduction.tex +++ b/chapters/introduction.tex @@ -168,4 +168,4 @@ \section{Notation}\label{notation} | "(" differentiated-expression "+" differentiated-expression ")" \end{lstlisting} -Annotations are defined using the syntactic forms of Modelica record definitions and component declarations, but with special semantics given in \cref{how-to-interpret-annotation-definitions}. +Annotations are defined using the syntactic forms of Modelica record definitions and component declarations, but with special semantics given in \cref{notation-for-annotation-definitions}. From 3fdffb96464b46067faa21375a69987c1f4dc00a Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Thu, 14 Mar 2024 16:27:58 +0100 Subject: [PATCH 20/37] Apply suggestions from code review Co-authored-by: Elena Shmoylova --- chapters/annotations.tex | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 0ee6967e3..8a552be8c 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -567,9 +567,9 @@ \subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label /*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 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. +If \lstinline!false!, it has no impact. \subsection{Connection Restrictions}\label{connection-restrictions} @@ -1315,7 +1315,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \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"!. +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} From 73f5d9ecface584af639862156e4612fd0377e60 Mon Sep 17 00:00:00 2001 From: HOS Date: Thu, 14 Mar 2024 16:43:18 +0100 Subject: [PATCH 21/37] Cleanup based on comments. --- chapters/annotations.tex | 45 +++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 8a552be8c..019d4a7ca 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -57,7 +57,7 @@ \section{Documentation}\label{annotations-for-documentation}\label{documentation /*literal*/ constant String info = "" "Description of the class"; /*literal*/ constant String revisions = "" "Revision history"; Figure[:] figures = {}; "Simulation result figures"; - String[:] styleSheets = {} "Style sheets for documentation"; + /*literal*/ constant String[:] styleSheets = {} "Style sheets for documentation"; end Documentation; \end{lstlisting} @@ -2153,12 +2153,15 @@ \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] -type Access = - enumeration(hide, icon, documentation, diagram, +record Protection + /*literal*/ constant Access access; + $\ldots$ +end Protection; +type Access = enumeration(hide, icon, documentation, diagram, nonPackageText, nonPackageDuplicate, packageText, packageDuplicate); -annotation(Protection(access = Access.documentation)); \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} @@ -2305,14 +2308,16 @@ \subsection{Licensing}\label{licensing} defined to restrict the usage of the encrypted package: \begin{lstlisting}[language=modelica] record Protection - $\ldots$ + /*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. @@ -2344,20 +2349,22 @@ \subsection{Licensing}\label{licensing} 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 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 - String licensee = "" "Optional string to show information about the licensee"; - String id[:] "Unique machine identifications, e.g., MAC addresses"; - String features[:] = fill("", 0) "Activated library license features"; - String startDate = "" "Optional start date in UTCformat YYYY-MM-DD"; - String expirationDate = "" "Optional expiration date in UTCformat YYYY-MM-DD"; - String operations[:] = fill("", 0) "Library usage conditions"; -end License; +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} From d89907c504a8fdc0657587ef45e53de2c4f0992d Mon Sep 17 00:00:00 2001 From: HOS Date: Fri, 15 Mar 2024 08:44:14 +0100 Subject: [PATCH 22/37] WSRemoval --- chapters/annotations.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 019d4a7ca..fdf449cda 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -2310,7 +2310,7 @@ \subsection{Licensing}\label{licensing} 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"; From 8f5ca14865e0dfb8035453c5df2f7127438f84fc Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Mon, 8 Apr 2024 10:07:54 +0200 Subject: [PATCH 23/37] Update chapters/annotations.tex Co-authored-by: Henrik Tidefelt --- chapters/annotations.tex | 1 + 1 file changed, 1 insertion(+) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index fdf449cda..756da3c0f 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -15,6 +15,7 @@ \section{Notation for Annotation Definitions}\label{notation-for-annotation-defi 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. From e4ab6b759a0907e5e463a97fd291651b99125ff3 Mon Sep 17 00:00:00 2001 From: HOS Date: Fri, 31 May 2024 15:03:00 +0200 Subject: [PATCH 24/37] Clarify missing values. --- chapters/annotations.tex | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 756da3c0f..1c7a9c21b 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -18,6 +18,8 @@ \section{Notation for Annotation Definitions}\label{notation-for-annotation-defi 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 the default behavior corresponds to a specific value for annotation that is given as a default. +When the default value is missing the default behavior is generally explained in more detail. 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}. @@ -445,6 +447,8 @@ \section{Symbolic Processing}\label{annotations-for-symbolic-processing}\label{s 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. +If the annotation is missing for a parameter or constant the evaluation of the component is tool-dependent. + \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. @@ -551,6 +555,8 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} 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. +If the \lstinline!TestCase! annotation is missing it is a normal model -- there are thus no restriction on the use of the model, and the model should not contain errors. + \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. From d17708f0855d790b5eb012230da09da181ba114c Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Thu, 27 Jun 2024 16:00:13 +0200 Subject: [PATCH 25/37] Apply suggestions from code review Co-authored-by: Henrik Tidefelt --- chapters/annotations.tex | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index cfa05ae5a..38a5ee572 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -17,9 +17,10 @@ \section{Notation for Annotation Definitions}\label{notation-for-annotation-defi 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 the default behavior corresponds to a specific value for annotation that is given as a default. -When the default value is missing the default behavior is generally explained in more detail. +When the default behavior corresponds to a specific value for the annotation, it will be expressed using a declaration equation. +Otherwise, the default behavior will be described in the text. 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}. @@ -554,7 +555,7 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} 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 \lstinline!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. -If the \lstinline!TestCase! annotation is missing it is a normal model -- there are thus no restriction on the use of the model, and the model should not contain errors. +If the \lstinline!TestCase! annotation is missing it is a normal model -- there are thus no restriction on the use of the model, and the model shall not contain errors. \begin{nonnormative} The intent of the test-case can be included in the documentation of the class. @@ -570,7 +571,7 @@ \subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label 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; +/*literal*/ constant Boolean singleInstance = false; \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. From 9fc1b4d32dd6e4886d009bb1a95a6aaca9b77734 Mon Sep 17 00:00:00 2001 From: HOS Date: Thu, 27 Jun 2024 16:02:24 +0200 Subject: [PATCH 26/37] ReorderAsSuggested --- chapters/annotations.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 38a5ee572..83ebee3db 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -17,11 +17,11 @@ \section{Notation for Annotation Definitions}\label{notation-for-annotation-defi 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. +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. Component declaration annotations always have default behavior, as all annotations are optional. When the default behavior corresponds to a specific value for the annotation, it will be expressed using a declaration equation. Otherwise, the default behavior will be described in the text. -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. From 81816ccfc28f7cb9b9d87380bb5c50e60a21d13f Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Mon, 1 Jul 2024 09:34:05 +0200 Subject: [PATCH 27/37] Apply suggestions from code review Co-authored-by: Henrik Tidefelt --- chapters/annotations.tex | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 83ebee3db..95db69718 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -555,7 +555,7 @@ \section{Simulations}\label{annotations-for-simulations}\label{simulations} 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 \lstinline!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. -If the \lstinline!TestCase! annotation is missing it is a normal model -- there are thus no restriction on the use of the model, and the model shall not contain errors. +If the \lstinline!TestCase! annotation is missing it is a normal model -- there are thus no restrictions on the use of the model, and the model shall not contain errors. \begin{nonnormative} The intent of the test-case can be included in the documentation of the class. @@ -572,11 +572,11 @@ \subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label This can be done using: \begin{lstlisting}[language=modelica] /*literal*/ constant Boolean singleInstance = false; -\end{lstlisting} +\end{lstlisting}% +\annotationindex{singleInstance} -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. +Only has effect when \lstinline!true!, meaning 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} @@ -1296,7 +1296,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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}$; +/*literal*/ constant String preferredView; \end{lstlisting} The \fmtannotationindex{preferredView} annotation defines the default view when selecting the class. From 93e6e9628cccf7372499e2223024adcb074d2492 Mon Sep 17 00:00:00 2001 From: HOS Date: Mon, 1 Jul 2024 09:37:58 +0200 Subject: [PATCH 28/37] DefaultForDocumentationClass --- chapters/annotations.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 95db69718..3292da870 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -1303,7 +1303,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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; +/*literal*/ constant Boolean DocumentationClass = false; \end{lstlisting}% \annotationindex{DocumentationClass} From e0283ffd21f889465e42f01723b00e6800b62bfe Mon Sep 17 00:00:00 2001 From: HOS Date: Mon, 1 Jul 2024 09:39:05 +0200 Subject: [PATCH 29/37] DefaultViewHandling --- chapters/annotations.tex | 1 + 1 file changed, 1 insertion(+) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 3292da870..ee975a4b4 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -1301,6 +1301,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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''). +If not specified the default view is tool-specific. \begin{lstlisting} /*literal*/ constant Boolean DocumentationClass = false; From 4e13161dc9468cc25313b34069145d8385eca5e3 Mon Sep 17 00:00:00 2001 From: HOS Date: Mon, 1 Jul 2024 09:41:21 +0200 Subject: [PATCH 30/37] DefaultValue --- chapters/annotations.tex | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index ee975a4b4..4a1e064c6 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -582,11 +582,11 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -/*literal*/ constant String mustBeConnected; +/*literal*/ constant String mustBeConnected = ""; \end{lstlisting}% \annotationindex{mustBeConnected} -It makes it an error if the connector does not appear as an inside connector in any connect-equation (for a conditional connector this check is only active if the connector is enabled). +If non-empty it makes it an error if the connector does not appear as an inside connector in any connect-equation (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. @@ -611,11 +611,11 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -/*literal*/ constant String mayOnlyConnectOnce; +/*literal*/ constant String mayOnlyConnectOnce = ""; \end{lstlisting}% \annotationindex{mayOnlyConnectOnce} -It makes it an error if the connector is connected as an inside connector in a connect-equation and thus appears in a connection set if: +If non-empty it makes it an error if the connector is connected as an inside connector in a connect-equation and thus appears in a connection set if: \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). From d6dd28f612685b4a3f4423fd75360094e3d3619d Mon Sep 17 00:00:00 2001 From: HOS Date: Mon, 1 Jul 2024 09:43:02 +0200 Subject: [PATCH 31/37] SingleInstanceReformulation --- chapters/annotations.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 4a1e064c6..6339da87d 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -569,7 +569,7 @@ \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: +To this end a class may use the annotation: \begin{lstlisting}[language=modelica] /*literal*/ constant Boolean singleInstance = false; \end{lstlisting}% From aa6ce474bb2c502e465d1ceb270eeba26c56ce1b Mon Sep 17 00:00:00 2001 From: HOS Date: Tue, 10 Sep 2024 10:12:50 +0200 Subject: [PATCH 32/37] Remove the problematic defaults. --- chapters/annotations.tex | 44 ++++++++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 6339da87d..49adfbc08 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -16,7 +16,8 @@ \section{Notation for Annotation Definitions}\label{notation-for-annotation-defi 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. +Default behavior can also be specified in the text as an alternative to a declaration equation, or implicitly by saying "if specified". +If the description states the annotation only has an effect for specific values it implies that the default is a value that has no effect. 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. Component declaration annotations always have default behavior, as all annotations are optional. @@ -571,7 +572,7 @@ \subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label For state machines it is useful to have single instances of local classes. To this end a class may use the annotation: \begin{lstlisting}[language=modelica] -/*literal*/ constant Boolean singleInstance = false; +/*literal*/ constant Boolean singleInstance; \end{lstlisting}% \annotationindex{singleInstance} @@ -582,12 +583,12 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -/*literal*/ constant String mustBeConnected = ""; +/*literal*/ constant String mustBeConnected; \end{lstlisting}% \annotationindex{mustBeConnected} -If non-empty it makes it an error if the connector does not appear as an inside connector in any connect-equation (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. +If specified it makes it an error if the connector does not appear as an inside connector in any connect-equation (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, and should be non-empty. For an array of connectors it applies separately to each element. \begin{nonnormative} @@ -611,17 +612,17 @@ \subsection{Connection Restrictions}\label{connection-restrictions} A connector component declaration may have the following annotation: \begin{lstlisting}[language=modelica] -/*literal*/ constant String mayOnlyConnectOnce = ""; +/*literal*/ constant String mayOnlyConnectOnce ; \end{lstlisting}% \annotationindex{mayOnlyConnectOnce} -If non-empty it makes it an error if the connector is connected as an inside connector in a connect-equation and thus appears in a connection set if: +If specified it makes it an error if the connector is connected as an inside connector in a connect-equation and thus appears in a connection set if: \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. +The string value should provide the reason why it may only be connected once, and should be non-empty. \begin{nonnormative} This annotation is intended for non-causal connectors, see \cref{restrictions-of-connections-and-connectors}. @@ -1304,7 +1305,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte If not specified the default view is tool-specific. \begin{lstlisting} -/*literal*/ constant Boolean DocumentationClass = false; +/*literal*/ constant Boolean DocumentationClass; \end{lstlisting}% \annotationindex{DocumentationClass} @@ -1317,16 +1318,18 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{nonnormative} \begin{lstlisting}[language=modelica] -/*literal*/ constant String defaultComponentName = "$\mathit{name}$"; +/*literal*/ constant String defaultComponentName; \end{lstlisting}% \annotationindex{defaultComponentName} -When creating a component of the given class, the recommended component name is \emph{name}. +When creating a component of the given class, and the annotation is specified it gives the recommended component 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!. +It is an error if the string is not a valid identifier. When automatically deriving a name, any trailing `\lstinline!1!' in the \lstinline!defaultComponentName! shall be disregarded. +if not specified the recommended component name is tool-specific. \begin{lstlisting}[language=modelica] -/*literal*/ constant String defaultComponentPrefixes = "$\mathit{prefixes}$"; +/*literal*/ constant String defaultComponentPrefixes; \end{lstlisting}% \annotationindex{defaultComponentPrefixes} @@ -1337,6 +1340,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte The following prefixes may be included in the string \lstinline!prefixes!: \lstinline!inner!, \lstinline!outer!, \lstinline!replaceable!, \lstinline!constant!, \lstinline!parameter!, \lstinline!discrete!. +The default is an empty string. \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. @@ -1344,12 +1348,13 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{nonnormative} \begin{lstlisting}[language=modelica] -/*literal*/ constant String missingInnerMessage = "$\mathit{message}$"; +/*literal*/ constant String missingInnerMessage; \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}. +component, the literal string message may be used as part of a diagnostic message if specified (together with appropriate context), see \cref{instance-hierarchy-name-lookup-of-inner-declarations}. +The default is a tool-specific diagnostic message. \begin{example} \begin{lstlisting}[language=modelica] @@ -1377,6 +1382,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \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!. +For most types there is no unit offset and the annotation is not needed for them. \end{nonnormative} A model or block definition may contain: @@ -1385,7 +1391,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{lstlisting}% \annotationindex{defaultConnectionStructurallyInconsistent} -If \lstinline!true!, it is stated that a default connection will result in a structurally inconsistent model or block\footnote{% +Only has an effect if \lstinline!true!, when 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)!. @@ -1400,21 +1406,23 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A class may have the following annotation: \begin{lstlisting}[language=modelica] -/*literal*/ constant String obsolete = "$\mathit{message}$"; +/*literal*/ constant String obsolete; \end{lstlisting}% \annotationindex{obsolete} +Only has an effect if specified (and in that case the string should be non-empty). 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}$"; +/*literal*/ constant String unassignedMessage; \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. +Only has an effect if specified (and in that case the string should be non-empty). +When the variable to which this annotation is attached in the declaration cannot be computed due to the structure of the equations, the string 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. From 41f9c575c4522056ac0e0ed24e9b1864ce99ec49 Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Sun, 6 Oct 2024 23:13:11 +0200 Subject: [PATCH 33/37] Apply suggestions from code review Co-authored-by: Henrik Tidefelt --- chapters/annotations.tex | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 49adfbc08..e216a038f 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -16,13 +16,12 @@ \section{Notation for Annotation Definitions}\label{notation-for-annotation-defi 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, or implicitly by saying "if specified". +Default behavior can also be specified in the text as an alternative to a declaration equation, or implicitly by saying \emph{if specified}. If the description states the annotation only has an effect for specific values it implies that the default is a value that has no effect. 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. -Component declaration annotations always have default behavior, as all annotations are optional. -When the default behavior corresponds to a specific value for the annotation, it will be expressed using a declaration equation. -Otherwise, the default behavior will be described in the text. +As all annotations are optional, component declaration annotations will always have default behavior. +The default behavior is either the implicit absence of any of the effects for defined values of the annotation, or explicitly defined as corresponding to one of the valid values. 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. @@ -588,7 +587,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} \annotationindex{mustBeConnected} If specified it makes it an error if the connector does not appear as an inside connector in any connect-equation (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, and should be non-empty. +The string value must be non-empty and provide the reason why it must be connected. For an array of connectors it applies separately to each element. \begin{nonnormative} @@ -622,7 +621,7 @@ \subsection{Connection Restrictions}\label{connection-restrictions} \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, and should be non-empty. +The string value must be non-empty and 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}. @@ -1309,7 +1308,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \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"!. +Only allowed as class annotation on any kind of class and only having effect when \lstinline!true!, meaning 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} @@ -1326,7 +1325,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte 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!. It is an error if the string is not a valid identifier. When automatically deriving a name, any trailing `\lstinline!1!' in the \lstinline!defaultComponentName! shall be disregarded. -if not specified the recommended component name is tool-specific. +If not specified, the names of new components are tool-specific. \begin{lstlisting}[language=modelica] /*literal*/ constant String defaultComponentPrefixes; @@ -1410,7 +1409,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{lstlisting}% \annotationindex{obsolete} -Only has an effect if specified (and in that case the string should be non-empty). +Only has an effect if specified, and the string must then be non-empty. 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. @@ -1421,7 +1420,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \end{lstlisting}% \annotationindex{unassignedMessage} -Only has an effect if specified (and in that case the string should be non-empty). +Only has an effect if specified, and the string must then be non-empty. When the variable to which this annotation is attached in the declaration cannot be computed due to the structure of the equations, the string can be used as a diagnostic message. \begin{nonnormative} @@ -2245,7 +2244,7 @@ \subsection{Licensing}\label{licensing} \begin{lstlisting}[language=modelica] record Protection /*literal*/ constant Access access; - /*literal*/ constant String features[:] = fill("", 0) "Required license features"; + /*literal*/ constant String features[:] "Required license features"; record License /*literal*/ constant String libraryKey; @@ -2290,10 +2289,10 @@ \subsection{Licensing}\label{licensing} 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 features[:] "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"; + /*literal*/ String operations[:] "Library usage conditions"; end License; end Protection; \end{lstlisting}% From f3ce16eba999eda619987d37e489a69c9d1239e2 Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Sun, 6 Oct 2024 23:13:48 +0200 Subject: [PATCH 34/37] Update chapters/annotations.tex Co-authored-by: Henrik Tidefelt --- chapters/annotations.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index e216a038f..eee35afe8 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -17,7 +17,7 @@ \section{Notation for Annotation Definitions}\label{notation-for-annotation-defi 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, or implicitly by saying \emph{if specified}. -If the description states the annotation only has an effect for specific values it implies that the default is a value that has no effect. +If the description states that the annotation only has an effect for specific values it implies that the default is a value that has no effect. 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. As all annotations are optional, component declaration annotations will always have default behavior. From d8ec36a6ac0c382d2e79e58637632e385fa49e33 Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Mon, 7 Oct 2024 09:16:23 +0200 Subject: [PATCH 35/37] Update chapters/annotations.tex --- chapters/annotations.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index eee35afe8..54f32db68 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -1372,7 +1372,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A simple type or component of a simple type may have: \begin{lstlisting}[language=modelica] -/*literal*/ constant Boolean absoluteValue; +/*literal*/ constant Boolean absoluteValue=true; \end{lstlisting}% \annotationindex{absoluteValue} From de2bb83ccc5c4e701417fb1890ab20ff75700024 Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Mon, 7 Oct 2024 09:18:39 +0200 Subject: [PATCH 36/37] Update chapters/annotations.tex --- chapters/annotations.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 54f32db68..13453d027 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -1372,7 +1372,7 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte A simple type or component of a simple type may have: \begin{lstlisting}[language=modelica] -/*literal*/ constant Boolean absoluteValue=true; +/*literal*/ constant Boolean absoluteValue = true; \end{lstlisting}% \annotationindex{absoluteValue} From ff1af183330e1a3fe99cae4408a1091c12e3370e Mon Sep 17 00:00:00 2001 From: HOS Date: Mon, 7 Oct 2024 09:24:07 +0200 Subject: [PATCH 37/37] From review. --- chapters/annotations.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/chapters/annotations.tex b/chapters/annotations.tex index 13453d027..c22c34d09 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -1351,8 +1351,8 @@ \section{Graphical User Interface}\label{annotations-for-the-graphical-user-inte \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 if specified (together with appropriate context), see \cref{instance-hierarchy-name-lookup-of-inner-declarations}. +Only has an effect if specified, and the string must then be non-empty. +When specified and an \lstinline!outer! component of the class does not have a corresponding \lstinline!inner! component, the string message may be used as part of a diagnostic message (together with appropriate context), see \cref{instance-hierarchy-name-lookup-of-inner-declarations}. The default is a tool-specific diagnostic message. \begin{example}