Merge pull request modelica#2864 from HansOlsson/RestrictedDerivative

Specify noDerivative and zeroDerivative.

chapters/functions.tex

@@ -1383,36 +1383,36 @@ \subsection{Using the Derivative Annotation}\label{using-the-derivative-annotati
 Assume that function \lstinline!f! takes a matrix and a scalar.
 Since the matrix argument is usually a parameter expression it is then
 useful to define the function as follows (the additional derivative =
-\lstinline!f_general_der! is optional and can be used when the derivative of
-the matrix or offset is non-zero). Note that \lstinline!f_der! must have
-\lstinline!zeroDerivative! for both \lstinline!y! and \lstinline!offset!, but \lstinline!f_general_der! shall not have
-\lstinline!zeroDerivative! for either of them (it may \lstinline!zeroDerivative! for \lstinline!x_der!,
+\lstinline!fGeneralDer! is optional and can be used when the derivative of
+the matrix or offset is non-zero). Note that the derivative annotation of \lstinline!fDer! must specify
+\lstinline!zeroDerivative! for both \lstinline!y! and \lstinline!offset! as below, but the derivative annotation of \lstinline!fGeneralDer! shall not have
+\lstinline!zeroDerivative! for either of them (it may specify \lstinline!zeroDerivative! for \lstinline!x_der!,
 \lstinline!y_der!, or \lstinline!offset_der!).
 
 \begin{lstlisting}[language=modelica]
 function f "Simple table lookup"
   input Real x;
   input Real y[:, 2];
-  input Real offset;
+  input Real offset "Shortened to o below";
   output Real z;
 algorithm
   $\ldots$
-  annotation(derivative(zeroDerivative=y, zeroDerivative=offset)= f_der,
-             derivative=f_general_der);
+  annotation(derivative(zeroDerivative=y, zeroDerivative=offset)= fDer,
+             derivative=fGeneralDer);
 end f;
 
-function f_der "Derivative of simple table lookup"
+function fDer "Derivative of simple table lookup"
   input Real x;
   input Real y[:, 2];
   input Real offset;
   input Real x_der;
   output Real z_der;
 algorithm
   $\ldots$
-  annotation(derivative(zeroDerivative=y, zeroDerivative=offset, order=2) = f_der2);
-end f_der;
+  annotation(derivative(zeroDerivative=y, zeroDerivative=offset, order=2) = fDer2);
+end fDer;
 
-function f_der2 "Second derivative of simple table lookup"
+function fDer2 "Second derivative of simple table lookup"
   input Real x;
   input Real y[:, 2];
   input Real offset;
@@ -1421,9 +1421,9 @@ \subsection{Using the Derivative Annotation}\label{using-the-derivative-annotati
   output Real z_der2;
 algorithm
   $\ldots$
-end f_der2;
+end fDer2;
 
-function f_general_der "Derivative of table lookup taking
+function fGeneralDer "Derivative of table lookup taking
 into account varying tables"
   input Real x;
   input Real y[:, 2];
@@ -1434,9 +1434,16 @@ \subsection{Using the Derivative Annotation}\label{using-the-derivative-annotati
   output Real z_der;
 algorithm
   $\ldots$
-  //annotation(derivative(order=2) = f_general_der2);
-end f_general_der;
-\end{lstlisting}
+  //annotation(derivative(order=2) = fGeneralDer2);
+end fGeneralDer;
+\end{lstlisting}
+In the example above \lstinline!zeroDerivative=y! and \lstinline!zeroDerivative=offset! imply that
+\begin{eqnarray*}
+\frac{d}{dt}f(x(t),y(t),o(t))&=&\frac{\partial f}{\partial x}\frac{dx}{dt}+\frac{\partial f}{\partial y}\frac{dy}{dt}+\frac{\partial f}{\partial o}\frac{do}{dt}\\
+&=&\frac{\partial f}{\partial x}\frac{dx}{dt}+\frac{\partial f}{\partial y}\cdot 0+\frac{\partial f}{\partial o}\cdot 0\\
+&=&\frac{\partial f}{\partial x}\frac{dx}{dt}\\
+&=&fDer\cdot\frac{dx}{dt}
+\end{eqnarray*}
 \end{nonnormative}
 
 \begin{itemize}
@@ -1468,20 +1475,28 @@ \subsection{Using the Derivative Annotation}\label{using-the-derivative-annotati
   output Real z;
 algorithm
   $\ldots$
-  annotation(derivative(noDerivative = y) = f_der);
+  annotation(derivative(noDerivative = y) = h);
 end f;
 
-function f_der
+function h
   input Real x;
   input Real y;
   input Real x_der;
   output Real z_der;
 algorithm
   $\ldots$
-end f_der;
+end h;
 \end{lstlisting}
 This is useful if \lstinline!g! represents the major computational
 effort of \lstinline!fg!.
+
+Therefore \lstinline!h! indirectly includes the derivative with respect to \lstinline!y! as follows:
+\begin{eqnarray*}
+\frac{d}{dt}fg(x(t))&=&\frac{d}{dt}f(x(t),g(x(t)))\\
+&=&\frac{\partial f}{\partial x}\frac{dx}{dt}+\frac{\partial f}{\partial y}\frac{\partial g}{\partial x}\frac{dx}{dt}\\
+&=&\left(\frac{\partial f}{\partial x}+\frac{\partial f}{\partial y}\frac{\partial g}{\partial x}\right)\frac{dx}{dt}\\
+&=&h(x,y)\frac{dx}{dt}
+\end{eqnarray*}
 \end{nonnormative}
 
 \subsection{Partial Derivatives of Functions}\label{partial-derivatives-of-functions}