Version 2.2.0

Author: ikorotkin

docs/CHANGELOG.md

@@ -8,19 +8,37 @@ nav_order: 11
 
 All notable user-facing changes to the `dae-cpp` project are documented in this page.
 
-## v2.1.1
+## v2.2.0
 
 New
 {: .label .label-green }
 
-Version 2.1.x allows the user to define the shape (structure) of the Jacobian matrix. I.e., instead of providing analytic Jacobian (or not providing it at all, which is slow if the system is large enough), the user can specify the positions of non-zero elements in the Jacobian. The solver will use automatic differentiation for the specified elements only. This works nearly as fast as analytic Jacobian without requiring the user to differentiate the vector function manually.
+In version 2.2.x, the solver can reduce the time step size and redo the current time step until a certain condition is met.
+This is useful if the solver needs to stop when, for example, one of the variables should reach the given value, and the solver should not "overshoot".
+This version also includes several important updates, such as bug fixes and corrections for compiler warnings.
+
+- Added `solver_command::command` enum with [Solution Manager](solution-manager.html) functor return values. Used to send "commands" to the solver from the user-defined Solution Manager
+- The user can request the solver to decrease the time step size
+- The user can request the solver to decrease the time step size and then redo the current time step
+- Fix parentheses warning in `autodiff`
+- Fix `-Wall` and `-Wextra` warnings (e.g., "reorder" and "unused variable" warnings)
+- Switch from `uint32_t` to `int32_t` for `int_type`
+- Switch from `uint64_t` to `int64_t` for `int_type` if `DAECPP_LONG` is defined
+- Fix the relative error check
+- Fix situation when the solver can decrease and then immediately increase the time step
+- Fix tolerances for single precision
+
+## v2.1.1
 
 - Fixed bug when the solver could not recover from divergence and could not redo the last time step correctly
 - Type `dual_type` deprecated but supported, added `state_value` instead as it is clearer
 - Added `recover_from_linsolver_failure` solver option (`true` by default). Now the solver will try to recover from the linear solver failure (e.g., on the matrix decomposition step) by rolling back and decreasing the time step.
 
 ## v2.1.0
 
+Version 2.1.x allows the user to define the shape (structure) of the Jacobian matrix. I.e., instead of providing analytic Jacobian (or not providing it at all, which is slow if the system is large enough),
+the user can specify the positions of non-zero elements in the Jacobian. The solver will use automatic differentiation for the specified elements only. This works nearly as fast as analytic Jacobian without requiring the user to differentiate the vector function manually.
+
 - Added [`daecpp::JacobianMatrixShape`](jacobian-matrix.html#jacobian-matrix-shape) and [`daecpp::VectorFunctionElements`](vector-function.html#element-by-element-vector-function-to-define-the-jacobian-shape) helper classes to define the Jacobian matrix shape and the vector function
 - Added [`daecpp::JacobianCompare`](jacobian-matrix.html#jacobian-matrix-check) class that helps the user to compare the user-defined Jacobian (either defined explicitly or using Jacobian shape) with the one computed automatically from the system RHS
 - Added [Jacobian shape](https://github.com/dae-cpp/dae-cpp/blob/master/examples/jacobian_shape/jacobian_shape.cpp) and [Jacobian compare](https://github.com/dae-cpp/dae-cpp/blob/master/examples/jacobian_compare/jacobian_compare.cpp) examples

docs/examples.md

@@ -4,9 +4,6 @@ layout: default
 nav_order: 10
 ---
 
-Work in progress
-{: .label .label-red }
-
 # Examples
 
 ## Quick Start

docs/index.md

@@ -4,7 +4,7 @@ layout: home
 nav_order: 1
 ---
 
-![version](https://img.shields.io/badge/version-2.1.1-blue)
+![version](https://img.shields.io/badge/version-2.2.0-blue)
 
 <p align="center">
 <img src="../assets/images/logo.png" alt="dae-cpp logo" width="250"/>

docs/prerequisites.md

@@ -26,7 +26,7 @@ using namespace daecpp;
 
 | Type | Equivalent to | Note |
 | ---- | ------------- | ---- |
-| `daecpp::int_type` | `uint32_t` (default), <br> `uint64_t` if `DAECPP_LONG` is defined | Unsigned integer type, used for sparse matrix indices |
+| `daecpp::int_type` | `int32_t` (default), <br> `int64_t` if `DAECPP_LONG` is defined | 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`](https://autodiff.github.io/) package |

docs/solution-manager.md

@@ -6,7 +6,14 @@ nav_order: 6
 
 # Solution Manager class
 
-The Solution Manager class can serve as a solution observer and/or as an event function that stops computation when a certain event occurs. Solution Manager functor will be called every time step, providing the time `t` and the corresponding solution vector `x` for the user for further post-processing. If the functor returns an integer which is not equal to `0` (i.e., `true`), the computation will immediately stop.
+The Solution Manager class can serve as a solution observer and/or as an event function that stops computation (or reduces the time step) when a certain event occurs. Solution Manager functor will be called every time step, providing the time `t` and the corresponding solution vector `x` for the user for further post-processing. If the functor returns an integer which is not equal to `0` (or `daecpp::solver_command::continue_integration`), the solver behaviour will depend on the return value of the functor:
+
+- If the functor returns `daecpp::solver_command::stop_intergration` (or any other integer except defined below), the computation will immediately stop.
+- `daecpp::solver_command::decrease_time_step`: the solver will continue integration but the next time step will be reduced by a factor of `dt_decrease_factor` from the `SolverOptions` class.
+- `daecpp::solver_command::decrease_time_step_and_redo`: the solver will abort the current time step and will redo it with the decreased (by a factor of `dt_decrease_factor`) time step.
+
+The solver commands can be useful in the situations when the solver needs to stop once one of the variables reaches the given value, and the solver should not "overshoot".
+An example of the Solution Manager class that "tells" the solver to decrease the time step and stop when the variable reaches the given value with the given tolerance is provided [below](#example-2).
 
 The solver provides a derived from the Solution Manager class called [`daecpp::Solution`](#solution-class), which writes the solution vector `x` and time `t` every time step or every specific times defined by the user into the [Solution Holder](#solution-holder) object. The user can access this object for further post-processing, printing the solution on the screen or writing it to a file.
 
@@ -26,19 +33,19 @@ public:
     {
         // Solution Manager definition
 
-        return 0; // Returns 0 by default or an integer != 0 to stop the computation
+        return 0; // Returns 0 by default (or `daecpp::solver_command::continue_integration`)
     }
 };
 ```
 
 The operator `()` will be called every time step, providing the user with the current state `x` and the corresponding time `t`.
-If the functor returns non-zero integer, the computation will stop.
+If the functor returns `daecpp::solver_command::stop_intergration`, the computation will stop.
 The user is free to define the solution container and save the solution within the Solution Manager class. The solver provides [`SolutionHolder`](#solution-holder) helper class that stores solution vectors `x` and the corresponding times `t`.
 
 {: .note }
 The type of vector `x` in the class definition above is `daecpp::state_vector`, which is an alias of `std::vector<float_type>` type. See [`dae-cpp` types](https://dae-cpp.github.io/prerequisites.html#dae-cpp-types) section for more information.
 
-## Example
+## Example 1
 
 In the following example, we define a custom Solution Manager that performs the following 3 tasks:
 
@@ -80,6 +87,60 @@ Vectors `x_sol` and `t_sol` should be defined before calling the `UserDefinedSol
 
 Similar to the mass matrix, vector function and Jacobian matrix definitions, inhereting the `daecpp::SolutionManager` class is a good practice (it serves as a blueprint), but it is not necessary. The user is allowed to define custom Solution Managers without inhereting `daecpp::SolutionManager`.
 
+## Example 2
+
+In the example below, consider the analytic solution is `x[0] = 2 - t`, so `x[0] = 1` at time `t = 1`.
+Imagine we need to stop integration when `x[0] = 1` exactly (with the given tolerance).
+Here is an example of the Solution Manager class that can be used to achieve that:
+
+```cpp
+constexpr double tol{1e-6}; // Tolerance
+
+class UserDefinedSolutionManager
+{
+    daecpp::SolutionHolder &m_sol;
+
+    bool m_keep_reducing_time_step{false};
+
+    void m_save_solution(const daecpp::state_vector &x, const double t)
+    {
+        m_sol.x.emplace_back(x);
+        m_sol.t.emplace_back(t);
+    }
+
+public:
+    UserDefinedSolutionManager(daecpp::SolutionHolder &sol) : m_sol(sol) {}
+
+    int operator()(const daecpp::state_vector &x, const double t)
+    {
+        // Stop once x[0] == 1.0 (with the given tolerance)
+        if (std::abs(x[0] - 1.0) < tol)
+        {
+            m_save_solution(x, t);
+            return daecpp::solver_command::stop_intergration;
+        }
+
+        // In case the solver "overshoots" and x[0] is below 1.0
+        if (x[0] < 1.0)
+        {
+            m_keep_reducing_time_step = true;
+            return daecpp::solver_command::decrease_time_step_and_redo;
+        }
+
+        m_save_solution(x, t);
+
+        // The x[0] value is getting close to 1.0 but we need to reduce the time step
+        // to avoid "overshooting"
+        if (m_keep_reducing_time_step)
+        {
+            return daecpp::solver_command::decrease_time_step;
+        }
+
+        return daecpp::solver_command::continue_integration;
+    }
+};
+```
+
 ----
 
 # Solution Holder class

docs/utilities.md

@@ -32,7 +32,7 @@ daecpp::version_patch
 The timer measures time spent by the program in the given scope and saves it in **milliseconds** in a variable of type `double`:
 
 ```cpp
-double time{0.0}; // Stores time (in ms)
+double time{}; // Stores time (in ms)
 {
     daecpp::Timer timer(&time); // Starts the timer