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 3 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
22 changes: 14 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 @@ -1719,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.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Trying to fix some language:

Suggested change
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.
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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

ok, handled both of the ones above.


Copy link
Collaborator

Choose a reason for hiding this comment

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

Above, the default was described after giving the meaning of Inline = false. It would make sense to be consistent and describe the default after the meaning of LateInline = false.

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!}.
Expand All @@ -1735,20 +1740,21 @@ \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.
This annotation cannot be combined with annotations {\lstinline!Inline!} and {\lstinline!LateInline!}.
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.

\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