Drop copied examples (#2042)

* Drop copied examples

The examples were copied to the implementers's guid in
modelica/fmi-guides#20. This commit should
prevent doubling of the examples.

Signed-off-by: Christian Wolf <[email protected]>

* fix typo

---------

Signed-off-by: Christian Wolf <[email protected]>
Co-authored-by: Christian Bertsch <[email protected]>

Author: christian-wolf-eks

docs/2_2_common_mechanisms.adoc

@@ -1188,40 +1188,7 @@ _Likewise `nSensitivity` is only equal to `nUnknowns` (resp., `nKnowns`) if all
 
 ===== Directional Derivatives [[directionDerivatives]]
 
-[[example-directional-derivatives]]
-_[Example:_ +
-_Assume an FMU has the output equations_
-
-[latexmath]
-++++
-\begin{bmatrix}
-y_1
-\\
-y_2
-\end{bmatrix}
-=
-\begin{bmatrix}
-g_1(x, u_1, u_3, u_4)
-\\
-g_2(x, u_1)
-\end{bmatrix}
-++++
-
-_and this FMU is connected, so that latexmath:[{y_1, u_1, u_3}] appear in an algebraic loop._
-_Then the nonlinear solver needs a Jacobian and this Jacobian can be computed (without numerical differentiation) provided the partial derivative of latexmath:[{y_1}] with respect to latexmath:[{u_1}] and latexmath:[{u_3}] is available._
-_Depending on the environment where the FMUs are connected, these <<derivative,`derivatives`>> can be provided:_
-
-(a) _with one wrapper function around function <<fmi3GetDirectionalDerivative>> to compute the directional derivatives with respect to these two variables (in other words, latexmath:[{v_{\mathit{unknown}} = y_1}], latexmath:[{v_{\mathit{known}} = \left \{ u_1, u_3 \right \}}]), and then the environment calls this wrapper function with latexmath:[{v_{\mathit{seed}} = \left \{ 1, 0 \right \}}] to compute the partial derivative with respect to latexmath:[{u_1}] and latexmath:[{v_{\mathit{seed}} = \left \{ 0, 1 \right \}}] to compute the partial derivative with respect to latexmath:[{u_3}], or_
-
-(b) _with two direct function calls of <<fmi3GetDirectionalDerivative>> (in other words, latexmath:[{v_{\mathit{unknown}} = y_1, v_{\mathit{known}} = u_1, v_{\mathit{seed}} = 1}]; and latexmath:[{v_{\mathit{unknown}} = y_1, v_{\mathit{known}} = u_3, v_{\mathit{seed}} = 1}])._
-
-_Note that a direct implementation of this function with analytic derivatives:_
-
-(a) _Provides the directional derivative for all <<input>> variables; so in the <<example-directional-derivatives,above example>>: latexmath:[{\Delta y_1 = \frac{\partial g_1}{\partial x} \cdot \Delta x + \frac{\partial g_1}{\partial u_1} \cdot \Delta u_1 + \frac{\partial g_1}{\partial u_3} \cdot \Delta u_3 + \frac{\partial g_1}{\partial u_4} \cdot \Delta u_4}]_
-
-(b) _Initializes all seed-values to zero; so in the <<example-directional-derivatives,above example>>: latexmath:[{\Delta x = \Delta u_1 = \Delta u_3 = \Delta u_4 = 0}]_
-
-(c) _Computes the directional derivative with the seed-values provided in the function arguments; so in the <<example-directional-derivatives,above example>>: latexmath:[{v_{\mathit{sensitivity}} = \Delta y_1 (\Delta x = 0, \Delta u_1 = 1, \Delta u_3 = 0, \Delta u_4 = 0)}] and latexmath:[{v_{\mathit{sensitivity}} = \Delta y_1 (\Delta x = 0, \Delta u_1 = 0, \Delta u_3 = 1, \Delta u_4 = 0)}]]_
+_[For some examples on the usage of <<fmi3GetDirectionalDerivative>>, please look at the https://modelica.github.io/fmi-guides/main/fmi-guide/#directionDerivatives[examples in the implementers' guide].]_
 
 _[Note, function <<fmi3GetDirectionalDerivative>> can be utilized for the following purposes:_
 
@@ -1233,111 +1200,6 @@ _[Note, function <<fmi3GetDirectionalDerivative>> can be utilized for the follow
 
 - _If the FMU is used as the model for an extended Kalman filter, latexmath:[{\frac{\partial \mathbf{f}}{\partial \mathbf{x}}}] and latexmath:[{\frac{\partial \mathbf{g}}{\partial \mathbf{x}}}] are needed._]
 
-_If a dense matrix shall be computed, the columns of the matrix can be easily constructed by successive calls of <<fmi3GetDirectionalDerivative>>._
-_For example, constructing the system Jacobian latexmath:[{\mathbf{J} = \frac{\partial \mathbf{f}}{\partial \mathbf{x}}}] as dense matrix can be performed in the following way:_
-
-[source, C]
-----
-include::Reference-FMUs/examples/jacobian.c[tags=GetJacobian]
-----
-
-_If the sparsity of a matrix shall be taken into account, then the matrix can be constructed in the following way:_
-
-- _The incidence information of the matrix (whether an element is zero or not zero) is extracted from the XML file from element <<ModelStructure>>._
-
-- _A so called graph coloring algorithm is employed to determine the columns of the matrix that can be computed by one call of `fmi3GetDirectionalDerivative`._
-
-- _For the columns determined in (2), one call to <<fmi3GetDirectionalDerivative>> is made._
-_After each such call, the elements of the resulting directional derivative vector are copied into their correct locations of the partial derivative matrix._
-
-_More details and implementational notes are available from <<ABL12>>._
-
-_Example:_
-
-_Directional derivatives for higher dimension variables are almost treated in the same way.
-Consider, for example, an FMU which calculates its output latexmath:[{Y}] by multiplying its 2x2 input latexmath:[{U}] with a 3x2 constant gain latexmath:[{K}], with_
-
-[latexmath]
-++++
-K=
-\begin{bmatrix}
-a, b
-\\
-c, d
-\\
-e, f
-\end{bmatrix}
-++++
-_The output latexmath:[{Y=K U}] is a matrix of size 3x2._
-_The directional derivative of an output element latexmath:[{Y(i,j)}] with respect to the input latexmath:[{U}] and the seed latexmath:[{\Delta U}] is:_
-
-[latexmath]
-++++
-\Delta Y(i,j) =
-\frac{\partial Y(i,j)}{\partial U(1,1)} \cdot \Delta U(1,1) +
-\frac{\partial Y(i,j)}{\partial U(1,2)} \cdot \Delta U(1,2) +
-\frac{\partial Y(i,j)}{\partial U(2,1)} \cdot \Delta U(2,1) +
-\frac{\partial Y(i,j)}{\partial U(2,2)} \cdot \Delta U(2,2)
-++++
-
-[latexmath]
-++++
-\Delta \mathbf{Y} =
-\begin{bmatrix}
-a \Delta U(1,1)+b \Delta U(2,1), a \Delta U(1,2)+ b \Delta U(2,2)
-\\
-c \Delta U(1,1)+d \Delta U(2,1), c \Delta U(1,2)+ d \Delta U(2,2)
-\\
-e \Delta U(1,1)+f \Delta U(2,1), e \Delta U(1,2)+ f \Delta U(2,2)
-\end{bmatrix}
-++++
-
-_To get the directional derivative of latexmath:[{Y}] with respect to latexmath:[{U(2,1)}] the command `fmi3GetDirectionalDerivative(m, vr_Y, 1, vr_U, 1, {0.0, 0.0, 1.0, 0.0}, 4, dd, 6)` can be used where `vr_Y` and `vr_U` are references of the variable latexmath:[{Y}] and latexmath:[{U}], respectively._
-_Note that in order to get the directional derivative of latexmath:[{Y}] with respect to latexmath:[{U(2,1)}], the seed value `{0, 0, 1.0, 0}` has been used._
-_The retrieved directional derivative `dd` is stored in a matrix of size 3x2, so `nSensitivity` is 6._
-
 ===== Adjoint Derivatives [[adjointDerivatives]]
 
-_[Adjoint derivatives are beneficial in several contexts:_
-
-* _in artificial intelligence (AI) frameworks the adjoint derivatives are called "vector gradient products" (VJPs)._
-_There adjoint derivatives are used in the backpropagation process to perform gradient-based optimization of parameters using reverse mode automatic differentiation (AD), see, e.g., <<BPRS15>>._
-
-* _in parameter estimation (see <<BKF17>>)_
-
-_Typically, reverse mode automatic differentiation (AD) is more efficient for these use cases than forward mode AD, as explained in the cited references._
-
-_If one would like to construct the full Jacobian matrix, one can use either <<fmi3GetDirectionalDerivative>> (to column-wise construct it) or <<fmi3GetAdjointDerivative>> (to row-wise construct it, possibly improved with coloring methods as mentioned above)._
-_However in the applications motivating the adjoint derivatives, one does not need the full Jacobian matrix latexmath:[\mathbf{J}], but vector  latexmath:[\mathbf{v}^T] multiplied from the left to the Jacobian, i.e. latexmath:[\mathbf{v}^T\mathbf{J}]._
-_For computing the full Jacobian matrix, the column-wise construct is generally more efficient.]_
-
-_Example:_ +
-_Assume an FMU has the output equations_
-
-[latexmath]
-++++
-\begin{bmatrix}
-y_1
-\\
-y_2
-\end{bmatrix}
-=
-\begin{bmatrix}
-g_1(u_1, u_2)
-\\
-g_2(u_1, u_2)
-\end{bmatrix}
-++++
-
-_and latexmath:[\left( w_1,  w_2 \right)^T \cdot \mathbf{ \frac{\partial g}{\partial u} }] for some vector latexmath:[\left( w_1,  w_2 \right)^T] is needed._
-_Then one can get this with one function call of <<fmi3GetAdjointDerivative>> (with arguments_ latexmath:[\mathbf{v}_{\mathit{unknown}} = \text{valueReferences of} \left \{ y_1, y_2 \right \},  \mathbf{v}_{\mathit{known}} = \text{valueReferences of} \left \{ u_1, u_2 \right \},  \mathbf{v}_{\mathit{seed}} = \left( w_1, w_2 \right)^T] _), while with <<fmi3GetDirectionalDerivative>> at least two calls would be necessary to first construct the Jacobian column-wise and then multiplying from the right with_ latexmath:[\left( w_1,  w_2 \right)^T] _._
-
-_If a dense matrix shall be computed, the rows of the matrix can be easily constructed by successive calls of <<fmi3GetAdjointDerivative>>._
-_For example, constructing the system Jacobian latexmath:[{\mathbf{J} = \frac{\partial \mathbf{f}}{\partial \mathbf{x}}}] as a dense matrix can be performed in the following way:_
-
-[source, C]
-----
-include::Reference-FMUs/examples/jacobian.c[tags=GetJacobianAdjoint]
-----
-
-_]_
+_[For some hints on adjoint derivatives, their calculation and usage, and an example, see the corresponding https://modelica.github.io/fmi-guides/main/fmi-guide/#adjointDerivatives[section in the implementers' guide].]_