Update to v2.1.1

Author: ikorotkin

docs/CHANGELOG.md

@@ -8,12 +8,18 @@ nav_order: 11
 
 All notable user-facing changes to the `dae-cpp` project are documented in this page.
 
-## v2.1.0
+## v2.1.1
 
 New
 {: .label .label-green }
 
-Version 2.1 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.
+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.
+
+- 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
 
 - 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

docs/index.md

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

docs/prerequisites.md

@@ -30,4 +30,5 @@ using namespace daecpp;
 | `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 |
-| `daecpp::dual_type` | `autodiff::real` | Floating point "dual" number, used in the vector function for automatic differentiation |
+| `daecpp::state_value` | `autodiff::real1st` | Floating point "dual" number, used in the vector function for automatic differentiation |
+| `daecpp::dual_type` | `autodiff::real1st` | (DEPRECATED) Floating point "dual" number, used in the vector function for automatic differentiation |

docs/quick-start.md

@@ -164,6 +164,8 @@ my_system.solve(x0, t, MyJacobian()); // Starts the computation with Jacobian
 
 Defining the analytic Jacobian matrix can significantly speed up the computation (especially for big systems).
 
+If deriving the Jacobian matrix manually is not a feasible task (e.g., due to a very complex non-linear RHS), the solver allows the user to specify only the positions of non-zero elements of the Jacobian matrix (i.e., the Jacobian matrix shape). All the derivatives will be calculated automatically with a very small computation time penalty (compared to the manually derived analytic Jacobian).
+
 For more information about defining the Jacobian matrix, see [Jacobian Matrix class](jacobian-matrix.html) description.
 
 ### (Optional) Step 6. Tweak the solver options

docs/solver-options.md

@@ -26,6 +26,7 @@ The table below contains a complete list of all options accessible via the Solve
 | `is_mass_matrix_static` | `bool` | `false` | If `true`, the mass matrix will be updated only once (at the beginning of computation). Setting this option as `true` slightly speeds up the computation, but the mass matrix must be static (i.e., it must be independent on time). |
 | `max_Jacobian_updates` | `int` | `8` | Maximum number of the Jacobian matrix updates and factorizations per time step. If the algorithm fails to converge after `max_Jacobian_updates` Jacobian matrix updates and factorizations per time step, the Newton iterations will be considered as diverged. The solver will try to roll back and decrease the time step. |
 | `max_Newton_failed_attempts` | `unsigned` | `3` | If the Newton method fails to converge `max_Newton_failed_attempts` times in a row, the solver will try to update Jacobian matrix every single iteration next time step (for Quasi-Newton methods). |
+| `recover_from_linsolver_failure` | `bool` | `true` | If `true`, 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. |
 | `dt_increase_threshold_delta` | `int` | `0` | Time step amplification threshold delta. Can be negative or positive integer number. The solver increases the time step if the number of successful Newton iterations per time step is less than the threshold. <br> **Example:** If the solver increases the time step too often, decrease the time step amplification threshold by setting `dt_increase_threshold_delta` to `-1`. |
 | `dt_decrease_threshold_delta` | `int` | `0` | Time step reduction threshold delta. Can be negative or positive integer number. The solver decreases the time step if the number of successful Newton iterations per time step is greater than the threshold. <br> **Example:** If the solver struggles to converge but keeps doing many Newton iterations without reducing the time step, decrease the time step reduction threshold by setting `dt_decrease_threshold_delta` to `-1` (or `-2` and less). |
 | `solution_variability_control` | `bool` | `true` | Turns ON/OFF solution variability control. Solution variability control tightens up the adaptive time stepping algorithm, and it is ON by default. Switching it OFF can lead to a significant speed boost for big systems, but it can also lead to instability. |

docs/vector-function.md

@@ -92,7 +92,7 @@ The vector function from the [Examples](#examples) section above can be defined
 ```cpp
 struct UserDefinedVectorFunction : daecpp::VectorFunctionElements
 {
-    daecpp::dual_type equations(const daecpp::state_type &x, const double t, const daecpp::int_type i) const
+    daecpp::state_value equations(const daecpp::state_type &x, const double t, const daecpp::int_type i) const
     {
         if (i == 0)
             return x[2] + 1.0; // z + 1
@@ -114,7 +114,7 @@ This obviously comes with some computational time penalty compared to the case w
 However, defining the RHS element-by-element like in the example above will allow us to define only the positions of non-zero elements of the Jacobian without manually differentiating the entire vector function (which in some cases can be difficult and error-prone).
 
 {: .note }
-The class `VectorFunctionElements` is abstract, where `dual_type equations(const state_type &x, const double t, const int_type i) const` function must be implemented in the derived class.
+The class `VectorFunctionElements` is abstract, where `state_value equations(const state_type &x, const double t, const int_type i) const` function must be implemented in the derived class.
 
 After defining the vector function this way, define the [Jacobian matrix shape](jacobian-matrix.html#jacobian-matrix-shape).