From e34ad0ea93451541eb6022618be628d77fa379ad Mon Sep 17 00:00:00 2001 From: HOS Date: Fri, 29 Nov 2024 10:10:25 +0100 Subject: [PATCH 1/4] Start clearing up annotation syntax for functions. --- chapters/functions.tex | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/chapters/functions.tex b/chapters/functions.tex index 87bf5a57b..8bf87d1e3 100644 --- a/chapters/functions.tex +++ b/chapters/functions.tex @@ -1670,6 +1670,7 @@ \subsection{Using the Inverse Annotation}\label{using-the-inverse-annotation} \section{Function Inlining and Event Generation}\label{function-inlining-and-event-generation} The annotations listed below affect inlining of functions and the related topic of event generation inside functions. +For the semantics of the annotations see \cref{notation-for-annotation-definitions}. \begin{center} \begin{tabular}{l|l l} \hline @@ -1689,8 +1690,8 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve Hence, one needs to find the right balance between inlining too early (loss of provided derivatives and inverses) and too late (earlier stages of symbolic processing cannot benefit from symbolic simplifications). \begin{annotationdefinition}[Inline] -\begin{synopsis}[grammar]\begin{lstlisting} -"Inline" "=" ( false | true ) +\begin{synopsis}\begin{lstlisting} +/*literal*/ constant Boolean Inline; \end{lstlisting}\end{synopsis} \begin{semantics} Has only an effect within a function declaration. @@ -1700,6 +1701,8 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve If {\lstinline!Inline = false!}, the model developer proposes to not inline the function. +The default for inlining is tool-specific. + \begin{nonnormative} {\lstinline!Inline = true!} is for example used in {\lstinline!Modelica.Mechanics.MultiBody.Frames!} and in functions of {\lstinline!Modelica.Media!} to have no overhead for function calls such as resolving a vector in a different coordinate system and at the same time the function can be analytically differentiated, e.g., for index reduction needed for mechanical systems. \end{nonnormative} @@ -1707,8 +1710,8 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve \end{annotationdefinition} \begin{annotationdefinition}[LateInline] -\begin{synopsis}[grammar]\begin{lstlisting} -"LateInline" "=" ( false | true ) +\begin{synopsis}\begin{lstlisting} +/*literal*/ constant Boolean LateInline = false; \end{lstlisting}\end{synopsis} \begin{semantics} Has only an effect within a function declaration. @@ -1735,8 +1738,8 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve \end{annotationdefinition} \begin{annotationdefinition}[InlineAfterIndexReduction] -\begin{synopsis}[grammar]\begin{lstlisting} -"InlineAfterIndexReduction" "=" ( false | true ) +\begin{synopsis}\begin{lstlisting} +/*literal*/ constant Boolean InlineAfterIndexReduction = false; \end{lstlisting}\end{synopsis} \begin{semantics} Has only an effect within a function declaration. @@ -1747,8 +1750,8 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve \end{annotationdefinition} \begin{annotationdefinition}[GenerateEvents] -\begin{synopsis}[grammar]\begin{lstlisting} -"GenerateEvents" "=" ( false | true ) +\begin{synopsis}\begin{lstlisting} +/*literal*/ constant Boolean GenerateEvents = false; \end{lstlisting}\end{synopsis} \begin{semantics} Has only an effect within a function declaration. From 3f1bc072d109189abcc535f925342989af8411ad Mon Sep 17 00:00:00 2001 From: Hans Olsson Date: Mon, 9 Dec 2024 09:32:46 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Henrik Tidefelt --- chapters/functions.tex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chapters/functions.tex b/chapters/functions.tex index 8bf87d1e3..a5d6a8b4c 100644 --- a/chapters/functions.tex +++ b/chapters/functions.tex @@ -1670,7 +1670,7 @@ \subsection{Using the Inverse Annotation}\label{using-the-inverse-annotation} \section{Function Inlining and Event Generation}\label{function-inlining-and-event-generation} The annotations listed below affect inlining of functions and the related topic of event generation inside functions. -For the semantics of the annotations see \cref{notation-for-annotation-definitions}. +See \cref{notation-for-annotation-definitions} regarding the notation used to describe the annotations. \begin{center} \begin{tabular}{l|l l} \hline From 7331031c9e2695af32efa2191d5a2375a87cc557 Mon Sep 17 00:00:00 2001 From: HOS Date: Wed, 29 Jan 2025 16:19:34 +0100 Subject: [PATCH 3/4] Replace defaults in declarations by texts. Also provide smarter default for LateInline. --- chapters/functions.tex | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/chapters/functions.tex b/chapters/functions.tex index a5d6a8b4c..e6a54d8a8 100644 --- a/chapters/functions.tex +++ b/chapters/functions.tex @@ -1711,7 +1711,7 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve \begin{annotationdefinition}[LateInline] \begin{synopsis}\begin{lstlisting} -/*literal*/ constant Boolean LateInline = false; +/*literal*/ constant Boolean LateInline; \end{lstlisting}\end{synopsis} \begin{semantics} Has only an effect within a function declaration. @@ -1722,6 +1722,8 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve Late inlining is especially useful for differentiation and inversion of functions; for efficiency reasons it is then useful to replace all function calls with identical input arguments by one function call, before the inlining. \end{nonnormative} +The default for late inlining is tool-specific, in particular tools may automatically delay inlining to differentiate or possible invert the function before inlining it. + If {\lstinline!LateInline = false!}, the model developer proposes to not inline the function after symbolic transformations have been performed. {\lstinline!Inline = true, LateInline = false!} is identical to {\lstinline!Inline = true!}. @@ -1739,19 +1741,20 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve \begin{annotationdefinition}[InlineAfterIndexReduction] \begin{synopsis}\begin{lstlisting} -/*literal*/ constant Boolean InlineAfterIndexReduction = false; +/*literal*/ constant Boolean InlineAfterIndexReduction; \end{lstlisting}\end{synopsis} \begin{semantics} Has only an effect within a function declaration. If {\lstinline!true!}, the model developer proposes to inline the function after the function is differentiated for index reduction, and before any other symbolic transformations are performed. This annotation cannot be combined with annotations {\lstinline!Inline!} and {\lstinline!LateInline!}. +The default is to not perform this specific inlining. \end{semantics} \end{annotationdefinition} \begin{annotationdefinition}[GenerateEvents] \begin{synopsis}\begin{lstlisting} -/*literal*/ constant Boolean GenerateEvents = false; +/*literal*/ constant Boolean GenerateEvents; \end{lstlisting}\end{synopsis} \begin{semantics} Has only an effect within a function declaration. From 088ccca4c01e79d7772d54af2e1fd66220b8d8b2 Mon Sep 17 00:00:00 2001 From: HOS Date: Wed, 12 Feb 2025 11:48:12 +0100 Subject: [PATCH 4/4] Reviewed --- chapters/functions.tex | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/chapters/functions.tex b/chapters/functions.tex index e6a54d8a8..f0963f272 100644 --- a/chapters/functions.tex +++ b/chapters/functions.tex @@ -1722,8 +1722,6 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve Late inlining is especially useful for differentiation and inversion of functions; for efficiency reasons it is then useful to replace all function calls with identical input arguments by one function call, before the inlining. \end{nonnormative} -The default for late inlining is tool-specific, in particular tools may automatically delay inlining to differentiate or possible invert the function before inlining it. - If {\lstinline!LateInline = false!}, the model developer proposes to not inline the function after symbolic transformations have been performed. {\lstinline!Inline = true, LateInline = false!} is identical to {\lstinline!Inline = true!}. @@ -1732,6 +1730,9 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve {\lstinline!Inline = false, LateInline = true!} is identical to {\lstinline!LateInline = true!}. +The default for late inlining is tool-specific. +In particular, tools may automatically delay inlining in order to take advantage of function annotations for derivatives and inverses. + \begin{nonnormative} This annotation is for example used in {\lstinline!Modelica.Media.Water.IF97_Utilities.T_props_ph!} to provide in combination with common subexpression elimination the automatic caching of function calls. Furthermore, it is used in order that a tool is able to propagate specific enthalpy over connectors in the {\lstinline!Modelica.Fluid!} library. @@ -1747,8 +1748,9 @@ \section{Function Inlining and Event Generation}\label{function-inlining-and-eve Has only an effect within a function declaration. If {\lstinline!true!}, the model developer proposes to inline the function after the function is differentiated for index reduction, and before any other symbolic transformations are performed. -This annotation cannot be combined with annotations {\lstinline!Inline!} and {\lstinline!LateInline!}. The default is to not perform this specific inlining. + +This annotation cannot be combined with annotations {\lstinline!Inline!} and {\lstinline!LateInline!}. \end{semantics} \end{annotationdefinition}