Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Start clearing up annotation syntax for functions. #3617

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Start clearing up annotation syntax for functions. #3617

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e34ad0e
Start clearing up annotation syntax for functions.
HansOlsson Nov 29, 2024
3f1bc07
Apply suggestions from code review
HansOlsson Dec 9, 2024
7331031
Replace defaults in declarations by texts.
HansOlsson Jan 29, 2025
088ccca
Reviewed
HansOlsson Feb 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions chapters/functions.tex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
See \cref{notation-for-annotation-definitions} regarding the notation used to describe the annotations.
\begin{center}
\begin{tabular}{l|l l}
\hline
Expand All @@ -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.
Expand All @@ -1700,15 +1701,17 @@ \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}
\end{semantics}
\end{annotationdefinition}

\begin{annotationdefinition}[LateInline]
\begin{synopsis}[grammar]\begin{lstlisting}
"LateInline" "=" ( false | true )
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant Boolean LateInline;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Has only an effect within a function declaration.
Expand All @@ -1727,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.
Expand All @@ -1735,20 +1741,22 @@ \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;
\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.
The default is to not perform this specific inlining.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about swapping order with the previous sentence, and then have a paragraph break before the rule about combining annotations?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should be done now.


This annotation cannot be combined with annotations {\lstinline!Inline!} and {\lstinline!LateInline!}.
\end{semantics}
\end{annotationdefinition}

\begin{annotationdefinition}[GenerateEvents]
\begin{synopsis}[grammar]\begin{lstlisting}
"GenerateEvents" "=" ( false | true )
\begin{synopsis}\begin{lstlisting}
/*literal*/ constant Boolean GenerateEvents;
\end{lstlisting}\end{synopsis}
\begin{semantics}
Has only an effect within a function declaration.
Expand Down