diff --git a/chapters/operatorsandexpressions.tex b/chapters/operatorsandexpressions.tex index f5180ced6..cb317a42f 100644 --- a/chapters/operatorsandexpressions.tex +++ b/chapters/operatorsandexpressions.tex @@ -370,63 +370,76 @@ \section{Built-in Intrinsic Operators with Function Syntax}\label{built-in-intri \subsection{Numeric Functions and Conversion Functions}\label{numeric-functions-and-conversion-functions} -The following mathematical operators and functions, also including some -conversion functions, are predefined in Modelica, and are vectorizable -according to \cref{scalar-functions-applied-to-array-arguments}, except for the \lstinline!String! function. The -functions which do not trigger events are described in the table below, -whereas the event-triggering mathematical functions are described in -\cref{event-triggering-mathematical-functions}. - -\begin{operatordefinition*}[abs] +The mathematical functions and conversion operators are listed below do not generate events. + +\begin{center} +\begin{tabular}{l|l l} +\hline +\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\ +\hline +\hline +\lstinline!abs($v$)! & Absolute value (event-free). & \Cref{modelica:abs} \\ +\lstinline!sign($v$)! & Sign of argument (event-free). & \Cref{modelica:sign} \\ +\lstinline!sqrt($v$)! & Square root. & \Cref{modelica:sqrt} \\ +\lstinline!Integer($e$)! & Conversion from enumeration to \lstinline!Integer! & \Cref{modelica:integer-of-enumeration} \\ +\lstinline!EnumTypeName($i$)! & Conversion from \lstinline!Integer! to enumeration. & \Cref{modelica:enumeration-of-integer} \\ +\lstinline!String($\ldots$)! & Conversion to \lstinline!String!. & \Cref{modelica:to-String} \\ +\hline +\end{tabular} +\end{center} + +All of these except for the \lstinline!String! conversion operator are vectorizable according to \cref{scalar-functions-applied-to-array-arguments}. + +Additional non-event generating mathematical functions are described in \cref{built-in-mathematical-functions-and-external-built-in-functions}, whereas the event-triggering mathematical functions are described in \cref{event-triggering-mathematical-functions}. + +\begin{functiondefinition}[abs] \begin{synopsis}\begin{lstlisting} abs($v$) \end{lstlisting}\end{synopsis} \begin{semantics} Expands into \lstinline!noEvent(if $v$ >= 0 then $v$ else -$v$)!. Argument $v$ needs to be an \lstinline!Integer! or \lstinline!Real! expression. \end{semantics} -\end{operatordefinition*} +\end{functiondefinition} -\begin{operatordefinition*}[sign] +\begin{functiondefinition}[sign] \begin{synopsis}\begin{lstlisting} sign($v$) \end{lstlisting}\end{synopsis} \begin{semantics} Expands into \lstinline!noEvent(if $v$ > 0 then 1 else if $v$ < 0 then -1 else 0)!. Argument $v$ needs to be an \lstinline!Integer! or \lstinline!Real! expression. \end{semantics} -\end{operatordefinition*} +\end{functiondefinition} -\begin{operatordefinition*}[sqrt] +\begin{functiondefinition}[sqrt] \begin{synopsis}\begin{lstlisting} sqrt($v$) \end{lstlisting}\end{synopsis} \begin{semantics} Square root of $v$ if $v \geq 0$, otherwise an error occurs. Argument $v$ needs to be an \lstinline!Integer! or \lstinline!Real! expression. \end{semantics} -\end{operatordefinition*} +\end{functiondefinition} -\begin{operatordefinition*}[Integer] +\begin{operatordefinition*}[Integer]\label{modelica:integer-of-enumeration} \begin{synopsis}\begin{lstlisting} Integer($e$) \end{lstlisting}\end{synopsis} \begin{semantics} -Ordinal number of the expression $e$ of enumeration type that evaluates to the enumeration value \lstinline!E.enumvalue!, where \lstinline!Integer(E.e1) = 1!, \lstinline!Integer(E.en) = n!, -for an enumeration type \lstinline!E = enumeration(e1, ..., en)!. See also \cref{type-conversion-of-enumeration-values-to-string-or-integer}. +Ordinal number of the expression $e$ of enumeration type that evaluates to the enumeration value \lstinline!E.enumvalue!, where \lstinline!Integer(E.e1) = 1!, \lstinline!Integer(E.en) = n!, for an enumeration type \lstinline!E = enumeration(e1, ..., en)!. See also \cref{type-conversion-of-enumeration-values-to-string-or-integer}. \end{semantics} \end{operatordefinition*} -\begin{operatordefinition*}[] +\begin{operatordefinition*}[]\label{modelica:enumeration-of-integer} \begin{synopsis}\begin{lstlisting} EnumTypeName($i$) \end{lstlisting}\end{synopsis} \begin{semantics} -For any enumeration type \lstinline!EnumTypeName!, returns the enumeration value \lstinline!EnumTypeName.e! such that $\text{\lstinline!Integer(EnumTypeName.e)!} = i$. Refer to the definition of -\lstinline!Integer! above. +For any enumeration type \lstinline!EnumTypeName!, returns the enumeration value \lstinline!EnumTypeName.e! such that $\text{\lstinline!Integer(EnumTypeName.e)!} = i$. Refer to the definition of \lstinline!Integer! above. It is an error to attempt to convert values of $i$ that do not correspond to values of the enumeration type. See also \cref{type-conversion-of-integer-to-enumeration-values}. \end{semantics} \end{operatordefinition*} -\begin{operatordefinition*}[String] +\begin{operatordefinition*}[String]\label{modelica:to-String} \begin{synopsis}\begin{lstlisting} String($b$, ) String($i$, ) @@ -435,8 +448,7 @@ \subsection{Numeric Functions and Conversion Functions}\label{numeric-functions- String($e$, ) \end{lstlisting}\end{synopsis} \begin{semantics} -Convert a scalar non-\lstinline!String! expression to a \lstinline!String! representation. The first argument may be a \lstinline!Boolean! $b$, an \lstinline!Integer! $i$, a \lstinline!Real! $r$ or an -enumeration value $e$ (\cref{type-conversion-of-enumeration-values-to-string-or-integer}). The other arguments must use named arguments. For \lstinline!Real! expressions the output shall be according to the Modelica grammar. +Convert a scalar non-\lstinline!String! expression to a \lstinline!String! representation. The first argument may be a \lstinline!Boolean! $b$, an \lstinline!Integer! $i$, a \lstinline!Real! $r$ or an enumeration value $e$ (\cref{type-conversion-of-enumeration-values-to-string-or-integer}). The other arguments must use named arguments. For \lstinline!Real! expressions the output shall be according to the Modelica grammar. The optional \lstinline!! are: \begin{itemize} @@ -463,26 +475,34 @@ \subsection{Numeric Functions and Conversion Functions}\label{numeric-functions- \lstinline!(if leftJustified then "-" else "") + String(minimumLength) + "d"! \end{itemize} -Form of the \lstinline!format! string: According to ANSI-C the format string specifies one conversion specifier (excluding the leading \%), may not contain length modifiers, and may not use -`\lstinline!*!' for width and/or precision. For all numeric values the format specifiers `\lstinline!f!', `\lstinline!e!', `\lstinline!E!', `\lstinline!g!', `\lstinline!G!' are allowed. For -integral values it is also allowed to use the `\lstinline!d!', `\lstinline!i!', `\lstinline!o!', `\lstinline!x!', `\lstinline!X!', `\lstinline!u!', and `\lstinline!c!' format specifiers (for -non-integral values a tool may round, truncate or use a different format if the integer conversion characters are used). +Form of the \lstinline!format! string: According to ANSI-C the format string specifies one conversion specifier (excluding the leading \%), may not contain length modifiers, and may not use `\lstinline!*!' for width and/or precision. For all numeric values the format specifiers `\lstinline!f!', `\lstinline!e!', `\lstinline!E!', `\lstinline!g!', `\lstinline!G!' are allowed. For integral values it is also allowed to use the `\lstinline!d!', `\lstinline!i!', `\lstinline!o!', `\lstinline!x!', `\lstinline!X!', `\lstinline!u!', and `\lstinline!c!' format specifiers (for non-integral values a tool may round, truncate or use a different format if the integer conversion characters are used). The `\lstinline!x!'/`\lstinline!X!' formats (hexa-decimal) and \lstinline!c! (character) for \lstinline!Integer! values give results that do not agree with the Modelica grammar. \end{semantics} \end{operatordefinition*} -\subsubsection{Event Triggering Mathematical Functions}\label{event-triggering-mathematical-functions} +\subsection{Event Triggering Mathematical Functions}\label{event-triggering-mathematical-functions} -The built-in operators in this section trigger events if used outside of -a when-clause and outside of a clocked discrete-time partition (see -\cref{clocked-discrete-time-and-clocked-discretized-continuous-time-partition}). -These expression for \lstinline!div!, \lstinline!ceil!, \lstinline!floor!, and \lstinline!integer! are -event generating expression. The event generating expression for -\lstinline!mod(x,y)! is \lstinline!floor(x/y)!, and for \lstinline!rem(x,y)! it is \lstinline!div(x,y)! -- i.e.\ events -are not generated when \lstinline!mod! or \lstinline!rem! changes continuously in an interval, -but when they change discontinuously from one interval to the next. +The operators listed below trigger events if used outside of a when-clause and outside of a clocked discrete-time partition (see \cref{clocked-discrete-time-and-clocked-discretized-continuous-time-partition}). + +\begin{center} +\begin{tabular}{l|l l} +\hline +\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\ +\hline +\hline +\lstinline!div($x$, $y$)! & Division with truncation toward zero. & \Cref{modelica:div} \\ +\lstinline!mod($x$, $y$)! & Integer modulus. & \Cref{modelica:mod} \\ +\lstinline!rem($x$, $y$)! & Integer remainder. & \Cref{modelica:rem} \\ +\lstinline!ceil($x$)! & Smallest integer \lstinline!Real! not less than $x$. & \Cref{modelica:ceil} \\ +\lstinline!floor($x$)! & Largest integer \lstinline!Real! not greater than $x$. & \Cref{modelica:floor} \\ +\lstinline!integer($x$)! & Largest \lstinline!Intger! not greater than $x$. & \Cref{modelica:integer} \\ +\hline +\end{tabular} +\end{center} + +These expression for \lstinline!div!, \lstinline!ceil!, \lstinline!floor!, and \lstinline!integer! are event generating expression. The event generating expression for \lstinline!mod(x,y)! is \lstinline!floor(x/y)!, and for \lstinline!rem(x,y)! it is \lstinline!div(x,y)! -- i.e.\ events are not generated when \lstinline!mod! or \lstinline!rem! changes continuously in an interval, but when they change discontinuously from one interval to the next. \begin{nonnormative} If this is not desired, the \lstinline!noEvent! function can be applied to them. E.g.\ \lstinline!noEvent(integer(v))!. @@ -493,7 +513,7 @@ \subsubsection{Event Triggering Mathematical Functions}\label{event-triggering-m div($x$, $y$) \end{lstlisting}\end{synopsis} \begin{semantics} -Returns the algebraic quotient $x / y$ with any fractional part discarded (also known as truncation toward zero). +Algebraic quotient $x / y$ with any fractional part discarded (also known as truncation toward zero). \begin{nonnormative} This is defined for \lstinline!/! in C99; in C89 the result for negative numbers is implementation-defined, so the standard function \lstinline[language=C]!div! must be used. \end{nonnormative} @@ -506,7 +526,7 @@ \subsubsection{Event Triggering Mathematical Functions}\label{event-triggering-m mod($x$, $y$) \end{lstlisting}\end{synopsis} \begin{semantics} -Returns the integer modulus of $x / y$, i.e. \lstinline!mod($x$, $y$) = $x$ - floor($x$ / $y$) * $y$!. Result and arguments shall have type \lstinline!Real! or \lstinline!Integer!. If either of the arguments is \lstinline!Real! the result is \lstinline!Real! otherwise \lstinline!Integer!. +Integer modulus of $x / y$, i.e. \lstinline!mod($x$, $y$) = $x$ - floor($x$ / $y$) * $y$!. Result and arguments shall have type \lstinline!Real! or \lstinline!Integer!. If either of the arguments is \lstinline!Real! the result is \lstinline!Real! otherwise \lstinline!Integer!. \begin{nonnormative} Note, outside of a when-clause state events are triggered when the return value changes discontinuously. Examples: \lstinline!mod(3, 1.4) = 0.2!, \lstinline!mod(-3, 1.4) = 1.2!, \lstinline!mod(3, -1.4) = -1.2!. \end{nonnormative} @@ -518,7 +538,7 @@ \subsubsection{Event Triggering Mathematical Functions}\label{event-triggering-m rem($x$, $y$) \end{lstlisting}\end{synopsis} \begin{semantics} -Returns the integer remainder of $x / y$, such that \lstinline!div($x$, $y$) * $y$ + rem($x$, $y$) = $x$!. Result and arguments shall have type \lstinline!Real! or \lstinline!Integer!. If either of the arguments is \lstinline!Real! the result is \lstinline!Real! otherwise \lstinline!Integer!. +Integer remainder of $x / y$, such that \lstinline!div($x$, $y$) * $y$ + rem($x$, $y$) = $x$!. Result and arguments shall have type \lstinline!Real! or \lstinline!Integer!. If either of the arguments is \lstinline!Real! the result is \lstinline!Real! otherwise \lstinline!Integer!. \begin{nonnormative} Note, outside of a when-clause state events are triggered when the return value changes discontinuously. Examples: \lstinline!rem(3, 1.4) = 0.2!, \lstinline!rem(-3, 1.4) = -0.2!. \end{nonnormative} @@ -530,7 +550,7 @@ \subsubsection{Event Triggering Mathematical Functions}\label{event-triggering-m ceil($x$) \end{lstlisting}\end{synopsis} \begin{semantics} -Returns the smallest integer not less than $x$. Result and argument shall have type \lstinline!Real!. +Smallest integer not less than $x$. Result and argument shall have type \lstinline!Real!. \begin{nonnormative} Note, outside of a when-clause state events are triggered when the return value changes discontinuously. \end{nonnormative} @@ -542,7 +562,7 @@ \subsubsection{Event Triggering Mathematical Functions}\label{event-triggering-m floor($x$) \end{lstlisting}\end{synopsis} \begin{semantics} -Returns the largest integer not greater than $x$. Result and argument shall have type \lstinline!Real!. +Largest integer not greater than $x$. Result and argument shall have type \lstinline!Real!. \begin{nonnormative} Note, outside of a when-clause state events are triggered when the return value changes discontinuously. \end{nonnormative} @@ -554,16 +574,16 @@ \subsubsection{Event Triggering Mathematical Functions}\label{event-triggering-m integer($x$) \end{lstlisting}\end{synopsis} \begin{semantics} -Returns the largest integer not greater than $x$. The argument shall have type \lstinline!Real!. The result has type \lstinline!Integer!. +Largest integer not greater than $x$. The argument shall have type \lstinline!Real!. The result has type \lstinline!Integer!. \begin{nonnormative} Note, outside of a when-clause state events are triggered when the return value changes discontinuously. \end{nonnormative} \end{semantics} \end{operatordefinition} -\subsubsection{Built-in Mathematical Functions and External Built-in Functions}\label{built-in-mathematical-functions-and-external-built-in-functions} +\subsection{Built-in Mathematical Functions and External Built-in Functions}\label{built-in-mathematical-functions-and-external-built-in-functions} -The following built-in mathematical functions are available in Modelica +The functions listed below are built-in mathematical functions are available in Modelica and can be called directly without any package prefix added to the function name. They are also available as external built-in functions in the \lstinline!Modelica.Math! library. @@ -591,7 +611,7 @@ \subsubsection{Built-in Mathematical Functions and External Built-in Functions}\ \end{tabular} \end{center} -\begin{operatordefinition}[atan2] +\begin{functiondefinition}[atan2] \begin{synopsis}\begin{lstlisting} atan2($y$, $x$) \end{lstlisting}\end{synopsis} @@ -604,108 +624,124 @@ \subsubsection{Built-in Mathematical Functions and External Built-in Functions}\ \end{aligned} \end{equation*} \end{semantics} -\end{operatordefinition} +\end{functiondefinition} \subsection{Derivative and Special Purpose Operators with Function Syntax}\label{derivative-and-special-purpose-operators-with-function-syntax} -The following derivative operator and special purpose operators with -function syntax are predefined. The special purpose operators with -function syntax where the call below uses named arguments can be called -with named arguments (with the specified names), or with positional -arguments (the inputs of the functions are in the order given in the -calls below). +The operators below include the derivative operator and special purpose operators with function syntax. + +\begin{center} +\begin{tabular}{l|l l} +\hline +\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\ +\hline +\hline +\lstinline!der($\mathit{expr}$)! & Time derivative. & \Cref{modelica:der} \\ +\lstinline!delay($\mathit{expr}$, $\ldots$)! & Time delay. & \Cref{modelica:delay} \\ +\lstinline!cardinality($c$)! & Number of occurrences in connect-equations. & \Cref{modelica:cardinality} \\ +\lstinline!homotopy($\mathit{actual}$, $\mathit{simplified}$)! & Homotpy initialization. & \Cref{modelica:homotopy} \\ +\lstinline!semiLinear($x$, $k^{+}$, $k^{-}$)! & Sign-dependent slope. & \Cref{modelica:semiLinear} \\ +\lstinline!inStream($v$)! & Stream variable flow into component & \Cref{modelica:inStream} \\ +\lstinline!actualStream($v$)! & Actual value of stream variable. & \Cref{modelica:actualStream} \\ +\lstinline!spatialDistribution($\ldots$)! & Variable-speed transport. & \Cref{modelica:spatialDistribution} \\ +\lstinline!getInstanceName()! & Name of instance at call site. & \Cref{modelica:getInstanceName} \\ +\hline +\end{tabular} +\end{center} + +The special purpose operators with function syntax where the call below uses named arguments can be called with named arguments (with the specified names), or with positional arguments (the inputs of the functions are in the order given in the calls below). \begin{operatordefinition}[der] \begin{synopsis}\begin{lstlisting} -der(expr) +der($\mathit{expr}$) \end{lstlisting}\end{synopsis} \begin{semantics} -The time derivative of \lstinline!expr!. If the expression \lstinline!expr! is a scalar it needs to be a subtype of \lstinline!Real!. The expression and all its time-varying subexpressions must be continuous and semi-differentiable. If \lstinline!expr! is an array, the operator is applied to all elements of the array. For non-scalar arguments the function is vectorized according to \cref{vectorized-calls-of-functions}. +The time derivative of $\mathit{expr}$. If the expression $\mathit{expr}$ is a scalar it needs to be a subtype of \lstinline!Real!. The expression and all its time-varying subexpressions must be continuous and semi-differentiable. If $\mathit{expr}$ is an array, the operator is applied to all elements of the array. For non-scalar arguments the function is vectorized according to \cref{vectorized-calls-of-functions}. \begin{nonnormative} -For Real parameters and constants the result is a zero scalar or array of the same size as the variable. +For \lstinline!Real! parameters and constants the result is a zero scalar or array of the same size as the variable. \end{nonnormative} \end{semantics} \end{operatordefinition} \begin{operatordefinition}[delay] \begin{synopsis}\begin{lstlisting} -delay(expr, delayTime, delayMax) -delay(expr, delayTime) +delay($\mathit{expr}$, $\mathit{delayTime}$, $\mathit{delayMax}$) +delay($\mathit{expr}$, $\mathit{delayTime}$) \end{lstlisting}\end{synopsis} \begin{semantics} -Returns: \lstinline!expr(time - delayTime)! for \lstinline!time > time.start + delayTime! and \lstinline!expr(time.start)! for \lstinline!time <= time.start + delayTime!. The arguments, i.e., \lstinline expr!, \lstinline!delayTime! and \lstinline!delayMax!, need to be subtypes of \lstinline!Real!. \lstinline!delayMax! needs to be additionally a parameter expression. The following relation shall hold: \lstinline!0 <= delayTime <= delayMax!, otherwise an error occurs. If \lstinline!delayMax! is not supplied in the argument list, \lstinline!delayTime! needs to be a parameter expression. See also \cref{delay}. For non-scalar arguments the function is vectorized according to \cref{vectorized-calls-of-functions}. +Evaluates to \lstinline!$\mathit{expr}$(time - $\mathit{delayTime}$)! for $\text{\lstinline!time!} > \text{\lstinline!time.start!} + \mathit{delayTime}$ and \lstinline!$\mathit{expr}$(time.start)! for $\text{\lstinline!time!} \leq \text{\lstinline!time.start!} + \mathit{delayTime}$. The arguments, i.e., $\mathit{expr}$, $\mathit{delayTime}$ and $\mathit{delayMax}$, need to be subtypes of \lstinline!Real!. $\mathit{delayMax}$ needs to be additionally a parameter expression. The following relation shall hold: $0 \leq \mathit{delayTime} \leq \mathit{delayMax}$, otherwise an error occurs. If $\mathit{delayMax}$ is not supplied in the argument list, $\mathit{delayTime}$ needs to be a parameter expression. For non-scalar arguments the function is vectorized according to \cref{vectorized-calls-of-functions}. For further details, see \cref{delay}. \end{semantics} \end{operatordefinition} \begin{operatordefinition}[cardinality] \begin{synopsis}\begin{lstlisting} -cardinality(c) +cardinality($c$) \end{lstlisting}\end{synopsis} \begin{semantics} \begin{nonnormative} -This is a deprecated operator. It should no longer be used, since it will be removed in one of the next Modelica releases. +This is a deprecated operator. It should no longer be used, since it will be removed in one of the next Modelica releases. \end{nonnormative} -Returns the number of (inside and outside) occurrences of connector instance \lstinline!c! in a connect-equation as an \lstinline!Integer! number. See also \cref{cardinality-deprecated}. +Returns the number of (inside and outside) occurrences of connector instance $c$ in a connect-equation as an \lstinline!Integer! number. For further details, see \cref{cardinality-deprecated}. \end{semantics} \end{operatordefinition} \begin{operatordefinition}[homotopy] \begin{synopsis}\begin{lstlisting} -homotopy(actual=actual, simplified=simplified) +homotopy(actual=$\mathit{actual}$, simplified=$\mathit{simplified}$) \end{lstlisting}\end{synopsis} \begin{semantics} -The scalar expressions \lstinline!actual! and \lstinline!simplified! are subtypes of \lstinline!Real!. A Modelica translator should map this operator into either of the two forms: +The scalar expressions $\mathit{actual}$ and $\mathit{simplified}$ are subtypes of \lstinline!Real!. A Modelica translator should map this operator into either of the two forms: \begin{enumerate} \item - Returns \lstinline!actual! (trivial implementation). + Returns $\mathit{actual}$ (trivial implementation). \item In order to solve algebraic systems of equations, the operator might during the solution process return a combination of the two arguments, ending at actual. \begin{example} - \lstinline!actual * lambda + simplified * (1 - lambda)!, where \lstinline!lambda! is a homotopy parameter going from 0 to 1. + $\mathit{actual} \cdot \lambda + \mathit{simplified} \cdot (1 - \lambda)$, where $\lambda$ is a homotopy parameter going from 0 to 1. \end{example} - The solution must fulfill the equations for homotopy returning \lstinline!actual!. + The solution must fulfill the equations for homotopy returning $\mathit{actual}$. \end{enumerate} -See also \cref{homotopy}. For non-scalar arguments the function is vectorized according to \cref{scalar-functions-applied-to-array-arguments}. +For non-scalar arguments the function is vectorized according to \cref{scalar-functions-applied-to-array-arguments}. For further details, see \cref{homotopy}. \end{semantics} \end{operatordefinition} \begin{operatordefinition}[semiLinear] \begin{synopsis}\begin{lstlisting} -semiLinear(x, positiveSlope, negativeSlope) +semiLinear($x$, $k^{+}$, $k^{-}$) \end{lstlisting}\end{synopsis} \begin{semantics} -Returns: \lstinline!smooth(0, if x >= 0 then positiveSlope * x else negativeSlope * x)!. The result is of type \lstinline!Real!. See \cref{semilinear} (especially in the case when $x = 0$). For non-scalar arguments the function is vectorized according to \cref{vectorized-calls-of-functions}. +Returns: \lstinline!smooth(0, if $x$ >= 0 then $k^{+}$ * $x$ else $k^{-}$ * $x$)!. The result is of type \lstinline!Real!. For non-scalar arguments the function is vectorized according to \cref{vectorized-calls-of-functions}. For further details, see \cref{semilinear} (especially in the case when $x = 0$). \end{semantics} \end{operatordefinition} \begin{operatordefinition}[inStream] \begin{synopsis}\begin{lstlisting} -inStream(v) +inStream($v$) \end{lstlisting}\end{synopsis} \begin{semantics} -\lstinline!inStream(v)! is only allowed for stream variables \lstinline!v! defined in stream connectors, and is the value of the stream variable \lstinline!v! close to the connection point assuming that the flow is from the connection point into the component. This value is computed from the stream connection equations of the flow variables and of the stream variables. The operator is vectorizable. For more details see \cref{stream-operator-instream-and-connection-equations}. +\lstinline!inStream($v$)! is only allowed for stream variables $v$ defined in stream connectors, and is the value of the stream variable $v$ close to the connection point assuming that the flow is from the connection point into the component. This value is computed from the stream connection equations of the flow variables and of the stream variables. The operator is vectorizable. For further details, see \cref{stream-operator-instream-and-connection-equations}. \end{semantics} \end{operatordefinition} \begin{operatordefinition}[actualStream] \begin{synopsis}\begin{lstlisting} -actualStream(v) +actualStream($v$) \end{lstlisting}\end{synopsis} \begin{semantics} -\lstinline!actualStream(v)! returns the actual value of the stream variable \lstinline!v! for any flow direction. The operator is vectorizable. For more details, see \cref{stream-operator-actualstream}. +\lstinline!actualStream($v$)! returns the actual value of the stream variable $v$ for any flow direction. The operator is vectorizable. For further details, see \cref{stream-operator-actualstream}. \end{semantics} \end{operatordefinition} \begin{operatordefinition}[spatialDistribution] \begin{synopsis}\begin{lstlisting} spatialDistribution( - in0=in0, in1=in1, x=x, + in0=$\mathit{in0}$, in1=$\mathit{in1}$, x=$x$, positiveVelocity=$\ldots$, initialPoints=$\ldots$, initialValues=$\ldots$) \end{lstlisting}\end{synopsis} \begin{semantics} -\lstinline!spatialDistribution! allows approximation of variable-speed transport of properties, see \cref{spatialdistribution}. +\lstinline!spatialDistribution! allows approximation of variable-speed transport of properties. For further details, see \cref{spatialdistribution}. \end{semantics} \end{operatordefinition} @@ -714,7 +750,7 @@ \subsection{Derivative and Special Purpose Operators with Function Syntax}\label getInstanceName() \end{lstlisting}\end{synopsis} \begin{semantics} -Returns a string with the name of the model/block that is simulated, appended with the fully qualified name of the instance in which this function is called, see \cref{getinstancename}. +Returns a string with the name of the model/block that is simulated, appended with the fully qualified name of the instance in which this function is called. For further details, see \cref{getinstancename}. \end{semantics} \end{operatordefinition} @@ -730,7 +766,7 @@ \subsubsection{delay}\label{delay} further information, the complete time history of the delayed signals needs to be stored, because the delay time may change during simulation. To avoid excessive storage requirements and to enhance efficiency, the -maximum allowed delay time has to be given via \lstinline!delayMax!. +maximum allowed delay time has to be given via $\mathit{delayMax}$. This gives an upper bound on the values of the delayed signals which have to be stored. For real-time simulation where fixed step size @@ -857,7 +893,7 @@ \subsubsection{spatialDistribution}\label{spatialdistribution} The infinite-dimensional problem stated above can then be formulated in the following way: \begin{lstlisting}[language=modelica] der(x) = v; -(out0, out1) = spatialDistribution(in0, in1, x,v >=0, initialPoints, initialValues); +(out0, out1) = spatialDistribution(in0, in1, x, v >=0, initialPoints, initialValues); \end{lstlisting} Events are generated at the exact instants when the velocity @@ -1160,10 +1196,8 @@ \subsubsection{getInstanceName}\label{getinstancename} \subsection{Event-Related Operators with Function Syntax}\label{event-related-operators-with-function-syntax} -\Cref{tab:event-related-operators} gives an overview of the event-related operators with function syntax. The operators \lstinline!noEvent!, \lstinline!pre!, \lstinline!edge!, and \lstinline!change!, are vectorizable according to \cref{scalar-functions-applied-to-array-arguments}. +The operators listed below are event-related operators with function syntax. The operators \lstinline!noEvent!, \lstinline!pre!, \lstinline!edge!, and \lstinline!change!, are vectorizable according to \cref{scalar-functions-applied-to-array-arguments}. -\begin{table}[tb] -\caption{Event-related operators with function syntax.}\label{tab:event-related-operators} \begin{center} \begin{tabular}{l|l l} \hline @@ -1173,19 +1207,15 @@ \subsection{Event-Related Operators with Function Syntax}\label{event-related-op \lstinline!initial()! & Predicate for the initialization phase. & \Cref{modelica:initial}\\ \lstinline!terminal()! & Predicate for the end of a successful analysis. & \Cref{modelica:terminal}\\ \lstinline!noEvent($\mathit{expr}$)! & Evaluate $\mathit{expr}$ without triggering events. & \Cref{modelica:noEvent}\\ -\lstinline!smooth($p$, $\mathit{expr}$)! & Treat $\mathit{expr}$ as $p$ times continuously -differentiable. & \Cref{modelica:smooth}\\ -\lstinline!sample($\mathit{start}$, $\mathit{interval}$)! & Periodic triggering of events. & \Cref{modelica:sample}\\ +\lstinline!smooth($p$, $\mathit{expr}$)! & Treat $\mathit{expr}$ as $p$ times continuously differentiable. & \Cref{modelica:smooth}\\ +\lstinline!sample($\mathit{start}$, $\mathit{interval}$)! & Periodic triggering of events. & \Cref{modelica:event-sample}\\ \lstinline!pre($y$)! & Left limit $y(t^{-})$ of variable $y(t)$. & \Cref{modelica:pre}\\ \lstinline!edge($b$)! & Expands into \lstinline!($b$ and not pre($b$))!. & \Cref{modelica:edge}\\ \lstinline!change($v$)! & Expands into \lstinline!($v$ <> pre($v$))!. & \Cref{modelica:change}\\ -\lstinline!reinit($x$, $\mathit{expr}$)! & Reinitialize $x$ with -$\mathit{expr}$. & \Cref{modelica:reinit}\\ +\lstinline!reinit($x$, $\mathit{expr}$)! & Reinitialize $x$ with $\mathit{expr}$. & \Cref{modelica:reinit}\\ \hline \end{tabular} \end{center} -\end{table} - \begin{operatordefinition}[initial] \begin{synopsis}\begin{lstlisting} @@ -1246,14 +1276,14 @@ \subsection{Event-Related Operators with Function Syntax}\label{event-related-op \end{semantics} \end{operatordefinition} -\begin{operatordefinition}[sample] +\begin{operatordefinition*}[sample]\label{modelica:event-sample} \begin{synopsis}\begin{lstlisting} sample($\mathit{start}$, $\mathit{interval}$) \end{lstlisting}\end{synopsis} \begin{semantics} Returns \lstinline!true! and triggers time events at time instants $\mathit{start} + i \cdot \mathit{interval}$ for $i = 0,\, 1\, \ldots$, and is only true during the first event iteration at those times. At event iterations after the first one at each event and during continuous integration the operator always returns \lstinline!false!. The starting time $\mathit{start}$ and the sample interval $\mathit{interval}$ must be parameter expressions and need to be a subtype of \lstinline!Real! or \lstinline!Integer!. The sample interval $\mathit{interval}$ must be a positive number. \end{semantics} -\end{operatordefinition} +\end{operatordefinition*} \begin{operatordefinition}[pre] \begin{synopsis}\begin{lstlisting} @@ -1266,7 +1296,7 @@ \subsection{Event-Related Operators with Function Syntax}\label{event-related-op \end{nonnormative} The first value of \lstinline!pre($y$)! is determined in the initialization phase. -A new event is triggered if there is at least for one variable \lstinline!v! such that \lstinline!pre(v) <> v! after the active model equations are evaluated at an event instant. In this case the model is at once reevaluated. This evaluation sequence is called \emph{event iteration}. The integration is restarted, if for all \lstinline!v! appearing inside \lstinline!pre($\ldots$)!, the following condition holds: \lstinline!pre(v) == v!. +A new event is triggered if there is at least for one variable \lstinline!v! such that \lstinline!pre(v) <> v! after the active model equations are evaluated at an event instant. In this case the model is at once reevaluated. This evaluation sequence is called \emph{event iteration}. The integration is restarted once \lstinline!pre(v) == v! for all \lstinline!v! appearing inside \lstinline!pre($\ldots$)!. \begin{nonnormative} If \lstinline!v! and \lstinline!pre(v)! are only used in when-clauses, the translator might mask event iteration for variable \lstinline!v! since \lstinline!v! cannot change during event iteration. It is a \emph{quality of implementation} to find the minimal loops for event iteration, i.e., not all parts of the model need to be reevaluated. diff --git a/chapters/revisions.tex b/chapters/revisions.tex index 040f89d09..dc23615af 100644 --- a/chapters/revisions.tex +++ b/chapters/revisions.tex @@ -88,7 +88,7 @@ \subsection{Main changes in Modelica 3.4}\label{main-changes-in-modelica-3-4} \href{https://github.com/modelica/ModelicaSpecification/issues/1729}{\#1729}, and \href{https://github.com/modelica/ModelicaSpecification/issues/2166}{\#2166}. \item - Corrected typo for events, \cref{noevent-and-smooth}. Ticket + Corrected typo for events, \cref{modelica:smooth}. Ticket \href{https://github.com/modelica/ModelicaSpecification/issues/1657}{\#1657}. \item Clarified sample operator, \cref{event-related-operators-with-function-syntax}. Ticket diff --git a/chapters/synchronous.tex b/chapters/synchronous.tex index 15ff6b377..5bff27c7a 100644 --- a/chapters/synchronous.tex +++ b/chapters/synchronous.tex @@ -552,16 +552,27 @@ \section{Clock Constructors}\label{clock-constructors} \section{Clocked State Variables}\label{clocked-state-variables} -The previous value of a clocked variable can be accessed with the \lstinline!previous! operator. A variable to which \lstinline!previous! has been applied is called a \firstuse{clocked state variable}. +The previous value of a clocked variable can be accessed with the \lstinline!previous! operator, listed below. + +\begin{center} +\begin{tabular}{l|l l} +\hline +\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\ +\hline +\hline +\lstinline!previous($u$)! & Previous value of clocked state variable. & \Cref{modelica:previous} \\ +\hline +\end{tabular} +\end{center} + +A variable to which \lstinline!previous! has been applied is called a \firstuse{clocked state variable}. \begin{operatordefinition}[previous] \begin{synopsis}\begin{lstlisting} -previous(u) +previous($u$) \end{lstlisting}\end{synopsis} \begin{semantics} -The input argument is a \emph{component expression} (see \cref{argument-restrictions-component-expression}) or a parameter expression. The return argument has the same type as the input argument. -Input and return arguments are on the same clock. At the first tick of the clock of \lstinline!u! or after a reset transition (see \cref{reset-handling}), the start value of \lstinline!u! is -returned, see \cref{initialization-of-clocked-partitions}. At subsequent activations of the clock of \lstinline!u!, the value of \lstinline!u! from the previous clock activation is returned.\\ +The input argument $u$ is a \emph{component expression} (see \cref{argument-restrictions-component-expression}) or a parameter expression. The return argument has the same type as the input argument. Input and return arguments are on the same clock. At the first tick of the clock of $u$ or after a reset transition (see \cref{reset-handling}), the start value of $u$ is returned, see \cref{initialization-of-clocked-partitions}. At subsequent activations of the clock of $u$, the value of $u$ from the previous clock activation is returned. \end{semantics} \end{operatordefinition} @@ -572,33 +583,44 @@ \section{Partitioning Operators}\label{partitioning-operators} \subsection{Base-clock conversion operators}\label{base-clock-conversion-operators} -The following operators convert between a continuous-time and a -clocked-time representation and vice versa. +The operators listed below convert between a continuous-time and a clocked-time representation and vice versa. -\begin{operatordefinition}[sample] +\begin{center} +\begin{tabular}{l|l l} +\hline +\tablehead{Expression} & \tablehead{Description} & \tablehead{Details}\\ +\hline +\hline +\lstinline!sample($u$, $\mathit{clock}$)! & Sample continuous-time expression. & \Cref{modelica:clocked-sample} \\ +\lstinline!hold($u$)! & Zeroth order hold of clocked-time variable. & \Cref{modelica:clocked-sample} \\ +\hline +\end{tabular} +\end{center} + +\begin{operatordefinition*}[sample]\label{modelica:clocked-sample} \begin{synopsis}\begin{lstlisting} -sample(u, clock) +sample($u$, $\mathit{clock}$) \end{lstlisting}\end{synopsis} \begin{semantics} -Input argument \lstinline!u! is a continuous-time expression according to \cref{continuous-time-expressions}. The optional input argument \lstinline!clock! is of type \lstinline!Clock!, and can in a call be given as a named argument (with the name \lstinline!clock!), or as positional argument. The operator returns a clocked variable that has \lstinline!clock! as associated clock and has the value of the left limit of \lstinline!u! when \lstinline!clock! is active (that is the value of \lstinline!u! just before the event of \lstinline!c! is triggered). If argument \lstinline!clock! is not provided, it is inferred, see \cref{sub-clock-inferencing}. +Input argument $u$ is a continuous-time expression according to \cref{continuous-time-expressions}. The optional input argument $\mathit{clock}$ is of type \lstinline!Clock!, and can in a call be given as a named argument (with the name $\mathit{clock}$), or as positional argument. The operator returns a clocked variable that has $\mathit{clock}$ as associated clock and has the value of the left limit of $u$ when $\mathit{clock}$ is active (that is the value of $u$ just before the event of \lstinline!c! is triggered). If argument $\mathit{clock}$ is not provided, it is inferred, see \cref{sub-clock-inferencing}. \begin{nonnormative} -Since the operator returns the left limit of \lstinline!u!, it introduces an infinitesimal small delay between the continuous-time and the clocked partition. This corresponds to the reality, where a sampled data system cannot act infinitely fast and even for a very idealized simulation, an infinitesimal small delay is present. The consequences for the sorting are discussed below. +Since the operator returns the left limit of $u$, it introduces an infinitesimal small delay between the continuous-time and the clocked partition. This corresponds to the reality, where a sampled data system cannot act infinitely fast and even for a very idealized simulation, an infinitesimal small delay is present. The consequences for the sorting are discussed below. -Input argument \lstinline!u! can be a general expression, because the argument is continuous-time and therefore has always a value. It can also be a constant, a parameter or a piecewise constant expression. +Input argument $u$ can be a general expression, because the argument is continuous-time and therefore has always a value. It can also be a constant, a parameter or a piecewise constant expression. Note that \lstinline!sample! is an overloaded function: If \lstinline!sample! has two positional input arguments and the second argument is of type \lstinline!Real!, it is the operator from \cref{event-related-operators-with-function-syntax}. If \lstinline!sample! has one input argument, or it has two input arguments and the second argument if of type \lstinline!Clock!, it is the base-clock conversion operator from this section. \end{nonnormative} \end{semantics} -\end{operatordefinition} +\end{operatordefinition*} \begin{operatordefinition}[hold] \begin{synopsis}\begin{lstlisting} -hold(u) +hold($u$) \end{lstlisting}\end{synopsis} \begin{semantics} -Input argument \lstinline!u! is a clocked Component Expression (see \cref{argument-restrictions-component-expression}) or a parameter expression. The operator returns a piecewise constant signal of the same type of \lstinline!u!. When the clock of \lstinline!u! ticks, the operator returns \lstinline!u! and otherwise returns the value of \lstinline!u! from the last clock activation. Before the first clock activation of \lstinline!u!, the operator returns the start value of \lstinline!u!, see \cref{initialization-of-clocked-partitions}. +Input argument $u$ is a clocked Component Expression (see \cref{argument-restrictions-component-expression}) or a parameter expression. The operator returns a piecewise constant signal of the same type of $u$. When the clock of $u$ ticks, the operator returns $u$ and otherwise returns the value of $u$ from the last clock activation. Before the first clock activation of $u$, the operator returns the start value of $u$, see \cref{initialization-of-clocked-partitions}. \begin{nonnormative} -Since the input argument is not defined before the first tick of the clock of \lstinline!u!, the restriction is present, that it must be a \emph{component expression} (or a parameter expression), in order that the initial value of \lstinline!u! can be used in such a case. +Since the input argument is not defined before the first tick of the clock of $u$, the restriction is present, that it must be a \emph{component expression} (or a parameter expression), in order that the initial value of $u$ can be used in such a case. \end{nonnormative} \end{semantics} \end{operatordefinition} diff --git a/preamble.tex b/preamble.tex index d03870121..d18e472de 100644 --- a/preamble.tex +++ b/preamble.tex @@ -313,7 +313,7 @@ {\bfseries} % HEADFONT {\\} % HEADPUNCT {.75em} % HEADSPACE - {#1~#2\label{modelica:#3}} % CUSTOM-HEAD-SPEC {#1~#2. \texttt{#3}} + {#1~#2 \texttt{#3}\label{modelica:#3}} % CUSTOM-HEAD-SPEC {#1~#2. \texttt{#3}} \theoremstyle{modelicadefinition} \newtheorem{operatordefinition}{Operator}[chapter] \crefname{operatordefinition}{operator}{operators} @@ -330,11 +330,14 @@ {\bfseries} % HEADFONT {\\} % HEADPUNCT {.75em} % HEADSPACE - {#1 \texttt{#3}} % CUSTOM-HEAD-SPEC + {#1~#2 \texttt{#3}} % CUSTOM-HEAD-SPEC {#1~#2. \texttt{#3}} \theoremstyle{modelicadefinition*} -\newtheorem*{operatordefinition*}{Operator} +\newtheorem{operatordefinition*}[operatordefinition]{Operator} % Note: Not using \theoremstyle*, only difference is not adding \label. \crefname{operatordefinition*}{operator}{operators} \Crefname{operatordefinition*}{Operator}{Operators} +\newtheorem{functiondefinition*}[functiondefinition]{Function} +\crefname{functiondefinition*}{function}{functions} +\Crefname{functiondefinition*}{Function}{Functions} \lstdefinelanguage{synopsis}[]{modelica}{% Language for use with the \lstinline command. basicstyle=\upshape\ttfamily, % Same size as \lstinline