Write vector function page

Author: ikorotkin

docs/prerequisites.md

@@ -29,4 +29,4 @@ using namespace daecpp;
 | `daecpp::int_type` | `uint32_t` (default), <br> `uint64_t` if `DAECPP_LONG` is defined | Unsigned integer type, used for sparse matrix indices |
 | `daecpp::float_type` | `double` (default), <br> `float` if `DAECPP_SINGLE` is defined | Floating point scalar, used for sparse matrix coefficients |
 | `daecpp::state_vector` | `std::vector<float_type>` | State vector, used, for example, to define the initial condition |
-| `daecpp::state_type` | `autodiff::VectorXreal` | State vector, used for the [vector function](vector-function.html) definition so that it can be automatically (algorithmically) differentiated using `autodiff` package |
+| `daecpp::state_type` | `autodiff::VectorXreal` | State vector, used for the [vector function](vector-function.html) definition so that it can be automatically (algorithmically) differentiated using [`autodiff`](https://autodiff.github.io/) package |

docs/vector-function.md

@@ -4,13 +4,75 @@ layout: default
 nav_order: 4
 ---
 
-Work in progress
-{: .label .label-red }
+# Vector Function class
 
-# Vector Function (the RHS) class
+Vector function class defines the (nonlinear) vector function (the RHS) $$\mathbf{f}(\mathbf{x}, t)$$ of the DAE system written in the matrix-vector form:
 
-Text
+$$\mathbf{M}(t) \frac{\mathrm{d}\mathbf{x}}{\mathrm{d}t} = \mathbf{f}(\mathbf{x}, t).$$
 
-## Subtitle
+The vector function depends on the state vector $$\mathbf{x}$$ and time $$t$$.
 
-Text
+## Vector function definition
+
+The main vector function class `daecpp::VectorFunction` is an abstract class that provides an interface to define the vector function $$\mathbf{f}(\mathbf{x}, t)$$.
+In order to make use of this class, the user should inherit it and overload the `()` operator:
+
+```cpp
+class UserDefinedVectorFunction : public daecpp::VectorFunction
+{
+public:
+    void operator()(daecpp::state_type &f, const daecpp::state_type &x, const double t) const
+    {
+        // Vector function definition
+    }
+};
+```
+
+The operator `()` takes the state vector `x` at time `t` and updates the vector function `f`.
+Vector `f` is already pre-allocated with `f.size() == x.size()` and should be used in the function directly (without pre-allocation and `push_back`-like methods).
+The elements of vectors `x` and `f` can be accessed using square brackets `[]`.
+
+{: .note }
+The type of vectors `f` and `x` is `daecpp::state_type`, which is an [`autodiff`](https://autodiff.github.io/)'s type used to perform automatic (algorithmic) differentiation of the vector function `f`. See [`dae-cpp` types](https://dae-cpp.github.io/prerequisites.html#dae-cpp-types) section.
+
+## Examples
+
+Consider the following vector function $$\mathbf{f}(\mathbf{x}, t)$$, where $$\mathbf{x} = \{x,y,z\}$$, as an example:
+
+$$
+\mathbf{f}(\mathbf{x}, t) =
+\begin{vmatrix}
+z + 1 \\
+x^2 + y \\
+2t
+\end{vmatrix}.
+$$
+
+In the code, this vector function can be defined as
+
+```cpp
+class UserDefinedVectorFunction : public daecpp::VectorFunction
+{
+public:
+    void operator()(daecpp::state_type &f, const daecpp::state_type &x, const double t) const
+    {
+        f[0] = x[2] + 1.0;         // z + 1
+        f[1] = x[0] * x[0] + x[1]; // x*x + y
+        f[2] = 2.0 * t;            // 2*t
+    }
+};
+```
+
+Inhereting the `daecpp::VectorFunction` class is a good practice (it serves as a blueprint), however, the user is allowed to define vector functions using their own custom classes, for example:
+
+```cpp
+struct UserDefinedVectorFunction
+{
+    void operator()(daecpp::state_type &f, const daecpp::state_type &x, const double t)
+    {
+        f[0] = x[2] + 1.0;         // z + 1
+        f[1] = x[0] * x[0] + x[1]; // x*x + y
+        f[2] = 2.0 * t;            // 2*t
+    }
+};
+```