diff --git a/chapters/annotations.tex b/chapters/annotations.tex index ba27336dc..8f84e940f 100644 --- a/chapters/annotations.tex +++ b/chapters/annotations.tex @@ -341,7 +341,6 @@ \section{Annotations for Code Generation}\label{annotations-for-code-generation} \hline \hline \lstinline!Evaluate! & Use parameter value for symbolic processing & \Cref{modelica:Evaluate}\\ -\lstinline!HideResult! & Don't show component's simulator result & \Cref{modelica:HideResult}\\ \hline \end{tabular} \end{center} @@ -366,6 +365,41 @@ \section{Annotations for Code Generation}\label{annotations-for-code-generation} \end{semantics} \end{annotationdefinition} + +\section{Annotations for Simulations}\label{annotations-for-simulations} + +The annotations listed below define how models can be checked, translated, and simulated. +\begin{center} +\begin{tabular}{l|l l} +\hline +\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\ +\hline +\hline +\lstinline!experiment! & Simulation experiment settings & \Cref{modelica:experiment}\\ +\lstinline!HideResult! & Don't show component's simulator result & \Cref{modelica:HideResult}\\ +\lstinline!TestCase! & Information for model used as test case & \Cref{modelica:TestCase}\\ +\hline +\end{tabular} +\end{center} + +\begin{annotationdefinition}[experiment] +% henrikt-ma 2021-04: Seems strange to allow 'experiment' completely without list of options -- what would it mean? +\begin{synopsis}[grammar]\begin{lstlisting} +"experiment" + [ "(" [ experimentOption { "," experimentOption } ] ")" ] + +experimentOption: + "StartTime" "=" [ "+" | "-" ] UNSIGNED-NUMBER + | "StopTime" "=" [ "+" | "-" ] UNSIGNED-NUMBER + | "Interval" "=" UNSIGNED-NUMBER + | "Tolerance" "=" UNSIGNED-NUMBER +\end{lstlisting}\end{synopsis} +\begin{semantics} +The \lstinline{experiment} annotation defines the default start time (\lstinline!StartTime!) in {[}s{]}, the default stop time (\lstinline!StopTime!) in {[}s{]}, the suitable time resolution for the result grid (\lstinline!Interval!) in {[}s{]}, and the default relative integration tolerance (\lstinline!Tolerance!) for simulation experiments to be carried out with the model or block at hand. +If \lstinline!StartTime! is not specified it is assumed to be \lstinline!0.0!. +\end{semantics} +\end{annotationdefinition} + \begin{annotationdefinition}[HideResult] \begin{synopsis}[grammar]\begin{lstlisting} "HideResult" "=" ( false | true ) @@ -383,43 +417,22 @@ \section{Annotations for Code Generation}\label{annotations-for-code-generation} \end{semantics} \end{annotationdefinition} - -\section{Annotations for Simulations}\label{annotations-for-simulations} - -These annotations define how models can be checked, translated, and simulated. - -\subsection{Annotations for Simulation Experiments}\label{annotations-for-simulation-experiments} - -\begin{lstlisting}[language=grammar] -experiment-annotation: - annotation "(" "experiment" [ "(" [experimentOption - {"," experimentOption}] ")" ] ")" - -experimentOption: - "StartTime" "=" [ "+" | "-" ] UNSIGNED-NUMBER | - "StopTime" "=" [ "+" | "-"] UNSIGNED-NUMBER | - "Interval" "=" UNSIGNED-NUMBER | - "Tolerance" "=" UNSIGNED-NUMBER -\end{lstlisting} - -The \fmtannotationindex{experiment} annotation defines the default start time (\lstinline!StartTime!) in {[}s{]}, the default stop time (\lstinline!StopTime!) in {[}s{]}, the suitable time resolution for the result grid (\lstinline!Interval!) in {[}s{]}, and the default relative integration tolerance (\lstinline!Tolerance!) for simulation experiments to be carried out with the model or block at hand. -If \lstinline!StartTime! is not specified it is assumed to be \lstinline!0.0!. - -\subsection{Annotation for Test Cases}\label{annotation-for-test-cases} - -\begin{lstlisting}[language=grammar] -testcase-annotation: - annotation "(" "TestCase" "(" "shouldPass" "=" ( false | true ) ")" ")" -\end{lstlisting}% -\annotationindex{TestCase} +\begin{annotationdefinition}[TestCase] +\begin{synopsis}[grammar]\begin{lstlisting} +"TestCase" "(" "shouldPass" "=" ( false | true ) ")" +\end{lstlisting}\end{synopsis} +\begin{semantics} If \lstinline!shouldPass! is \lstinline!false! it indicates that the translation or the simulation of the model should fail. If a tools checks a package where classes have \lstinline!shouldPass = false! they should not generate errors, and checking may even be skipped. On the other hand, models with \lstinline!shouldPass = false! may be useful for creation of negative tests in tool-specific ways. Similarly as a class with obsolete-annotation, a class with \lstinline!TestCase! annotation (regardless of the value of \lstinline!shouldPass!) shall not be used in other models, unless those models also have a \lstinline!TestCase! annotation. + \begin{nonnormative} The intent of the test-case can be included in the documentation of the class. This annotation can both be used for models intended as test-cases for implementations, and for models explaining detectable errors. \end{nonnormative} +\end{semantics} +\end{annotationdefinition} \section{Annotation for Single Use of Class}\label{annotation-for-single-use-of-class} diff --git a/chapters/revisions.tex b/chapters/revisions.tex index 64a8dec9b..31cec291b 100644 --- a/chapters/revisions.tex +++ b/chapters/revisions.tex @@ -175,7 +175,7 @@ \subsection{Main changes in Modelica 3.5}\label{main-changes-in-modelica-3-5} Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2145}{\#2145}. \item Clarified Evaluate annotation for hierarchical components, \cref{annotations-for-code-generation}. Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2288}{\#2288}. -\item Added test-case annotation for incorrect models, \cref{annotations-for-simulation-experiments}. +\item Added test-case annotation for incorrect models, \cref{modelica:TestCase}. Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2340}{\#2340}. \item Clarified choicesAllMatching, \cref{annotation-choices-for-suggested-redeclarations-and-modifications}. Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2693}{\#2693}. @@ -221,7 +221,7 @@ \subsection{Main changes in Modelica 3.5}\label{main-changes-in-modelica-3-5} Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2170}{\#2170}. \item Add iconVisible to be able to show/hide connectors in icon layer for public connectors, \cref{component-instance}. Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2200}{\#2200}. -\item Correct grammar for experiment and give default for startTime, \cref{annotations-for-simulation-experiments}. +\item Correct grammar for experiment and give default for \lstinline!StartTime!, \cref{modelica:experiment}. Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2224}{\#2224}. \item Clarified that versionBuild and dateModified can be used for uses annotation, \cref{version-handling}. Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/2239}{\#2239}. @@ -1111,8 +1111,7 @@ \subsection{Main changes in Modelica 3.3}\label{main-changes-in-modelica-3-3} \item Functions to generate events, \cref{annotations-for-code-generation}. \item - Experiments to specify a time-resolution of simulation result, - \cref{annotations-for-simulation-experiments}. + Experiments to specify a time-resolution of simulation result, \cref{modelica:experiment}. \item Single instance of class, \cref{annotation-for-single-use-of-class}. \item @@ -1265,10 +1264,7 @@ \subsection{Main changes in Modelica 3.2 Revision 2}\label{main-changes-in-model \item New built-in operator \lstinline!Connections.rooted(A.R)! to inquire whether an overdetermined type or record instance \lstinline!A.R! in a call to \lstinline!Connections.branch(A.R, B.R)! is closer to the root of the spanning tree than \lstinline!B.R!, \cref{overconstrained-equation-operators-for-connection-graphs} (used in MSL 3.2 to avoid algebraic loops in several components such as in \lstinline!Modelica.Mechanics.MultiBody.Joints.Revolute!). \item - Several new annotations where vendor-specific variants were used in - MSL 3.2; \cref{annotation-choices-for-suggested-redeclarations-and-modifications}, - \cref{annotations-for-documentation}, \cref{annotations-for-code-generation}, - \cref{annotations-for-simulation-experiments}, \cref{connections}, and \cref{annotations-for-the-graphical-user-interface}. + Several new annotations where vendor-specific variants were used in MSL 3.2; \cref{annotation-choices-for-suggested-redeclarations-and-modifications}, \cref{annotations-for-documentation}, \cref{annotations-for-code-generation}, \cref{modelica:experiment}, \cref{connections}, and \cref{annotations-for-the-graphical-user-interface}. \item Specified that Evaluate can also occur in types, since this is used in MSL and important for performance; \cref{annotations-for-code-generation}. Ticket @@ -2204,9 +2200,8 @@ \subsection{Main Changes in Modelica 3.0}\label{main-changes-in-modelica-3-0} New annotations \crefnameref{annotations-for-code-generation}:\\ \lstinline!Evaluate!, \lstinline!HideResult!, \lstinline!Inline!, \lstinline!LateInline!, \lstinline!smoothOrder! \item - New annotation \crefnameref{annotations-for-simulation-experiments}:\\ - \lstinline!StartTime!, \lstinline!StopTime!, \lstinline!Tolerance! to define important parameters of an - experiment setup. + New annotation \cref{modelica:experiment}:\\ + \lstinline!StartTime!, \lstinline!StopTime!, \lstinline!Tolerance! to define important parameters of an experiment setup. \item New annotations for graphical annotations in \cref{annotations-for-graphical-objects}:\\ New attribute \lstinline!Smooth = enumeration(None, Bezier)! for graphical objects diff --git a/chapters/scoping.tex b/chapters/scoping.tex index 818355027..1c63d376e 100644 --- a/chapters/scoping.tex +++ b/chapters/scoping.tex @@ -515,7 +515,7 @@ \subsubsection{Steps of Instantiation}\label{steps-of-instantiation} \begin{nonnormative} The annotations can be relevant for simulations, e.g.\ annotations for code generation (\cref{annotations-for-code-generation}.), simulation experiments -(\cref{annotations-for-simulation-experiments}) or functions (\cref{declaring-derivatives-of-functions}, \cref{declaring-inverses-of-functions} and \cref{external-function-interface}). +(\cref{modelica:experiment}) or functions (\cref{declaring-derivatives-of-functions}, \cref{declaring-inverses-of-functions} and \cref{external-function-interface}). \end{nonnormative} Extends clauses are not looked up, but empty extends clause nodes are created and inserted into the current instance (to be able to preserve the declaration order of components).