Skip to content

Commit 33db0b4

Browse files
ikorotkinikorotkin
committed
Write the solve page
1 parent a929707 commit 33db0b4

File tree

1 file changed

+157
-12
lines changed

1 file changed

+157
-12
lines changed

‎docs/solve.md

+157-12
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,6 @@ layout: default
44
nav_order: 8
55
---
66

7-
Work in progress
8-
{: .label .label-red }
9-
107
# Solving DAE system
118

129
Once the DAE system is defined (see [Classes to define DAE system](classes.html)), we are ready to start solving it.
@@ -17,20 +14,168 @@ Generally, there are two ways of calling the main `dae-cpp` solver from the prog
1714

1815
In this section, we consider both approaches to start the computation.
1916

20-
## `System` class
17+
----
18+
19+
# System class
20+
21+
The `System` class serves as a wrapper for lower level [`daecpp::solve(...)`](#daecppsolve-function) function calls. Contains the [Solver Options](solver-options.html) and [Solution Holder](solution-manager.html#solution-holder-class) objects.
22+
23+
## System class public members
24+
25+
| Object | Type | Description |
26+
| ------ | ---- | ----------- |
27+
| `opt` | `SolverOptions` | Solver Options object. Provides default solver options which can be redefined by the user. See [Solver Options](solver-options.html) section. |
28+
| `sol` | `SolutionHolder` | Solution Holder object. Stores solution vector and the corresponding time for the user. See [Solution Holder](solution-manager.html#solution-holder-class) section. |
29+
| `status` | `daecpp::exit_code` | Exit code of the `solve(...)` method. See [Exit codes](#exit-codes) below. |
30+
31+
## System class constructor
32+
33+
The `System` class constructor is straightforward:
34+
35+
```cpp
36+
daecpp::System(Mass mass, RHS rhs);
37+
```
38+
39+
It takes the user-defined mass matrix object `mass` (see [Mass Matrix class](mass-matrix.html) section) and the vector function (the RHS of the system) object `rhs` (see [Vector Function class](vector-function.html) section). These two objects define the entire DAE system.
40+
41+
## System class `solve(...)` method
42+
43+
The `solve(...)` method initiates the DAE system solving algorithm, starts computation, and returns `daecpp::exit_code` (see [Exit codes](#exit-codes)) upon completion. The exit code will be also saved in the `status` public variable.
44+
45+
Here is the summary of the `solve(...)` method:
46+
47+
## `daecpp::exit_code solve(x0, t, [jacobian]);`
48+
49+
<br>
50+
51+
| Parameter | Type(s) | Description |
52+
| --------- | ------- | ----------- |
53+
| `x0` | `const daecpp::state_vector &` | The initial condition (initial state vector) |
54+
| `t` | `const double` **or** `const std::vector<double> &` | Integration interval `[0, t]` **or** a vector of integration times (useful if the user need the output at particular times `t`) |
55+
| `jacobian` | User-defined [Jacobian Matrix](jacobian-matrix.html) | **(Optional)** Jacobian matrix (matrix of the RHS derivatives) |
56+
57+
## Examples
58+
59+
A complete example is provided in the [Quick Start](quick-start.html) section.
60+
Here are a few simplified examples of how to use the `System` class:
61+
62+
```cpp
63+
MyMassMatrix mass; // Mass matrix object
64+
MyRHS rhs; // Vector-function object
65+
66+
daecpp::System my_system(mass, rhs); // Defines the DAE system object
67+
68+
state_vector x0{0, 1}; // The initial state vector (initial condition)
69+
double t{1.0}; // The integration interval: t = [0, 1.0]
70+
71+
my_system.solve(x0, t); // Solves the system with the given initial condition `x0` and time `t`
72+
```
73+
74+
Another example:
75+
76+
```cpp
77+
daecpp::System my_system((MyMassMatrix()), (MyRHS())); // Note the parentheses
78+
79+
my_system.opt.verbosity = daecpp::verbosity::normal; // Update solver options
80+
81+
int status = my_system.solve({0, 1}, 1.0, MyJacobian()); // Solves the system with Jacobian
82+
83+
if(!status)
84+
{
85+
my_system.sol.print(); // Prints solution on screen
86+
}
87+
```
88+
89+
Solution vector of vectors `x` and the corresponding vector of times `t` will be stored in `my_system.sol.x` and `my_system.sol.t`, respectively.
90+
91+
The entire C++ code is provided in the [Quick Start example](https://github.com/dae-cpp/dae-cpp/blob/master/examples/quick_start/quick_start.cpp).
92+
93+
----
94+
95+
# `daecpp::solve(...)` function
96+
97+
Integrates the system of DAEs with the given mass matrix, vector function (the RHS), Jacobian, initial state, time interval(s), solver options, and the given solution manager (observer and event function).
98+
99+
As in the `System` class, the `daecpp::solve(...)` function initiates the DAE system solving algorithm, starts computation, and returns `daecpp::exit_code` (see [Exit codes](#exit-codes)) upon completion.
100+
101+
Here is the summary of the `solve(...)` function:
102+
103+
## `daecpp::exit_code solve(mass, rhs, [jac], x0, t, sol_mgr, [opt]);`
104+
105+
<br>
106+
107+
| Parameter | Type(s) | Description |
108+
| --------- | ------- | ----------- |
109+
| `mass` | User-defined [Mass Matrix](mass-matrix.html) | Mass matrix of the DAE system |
110+
| `rhs` | User-defined [Vector Function](vector-function.html) | Vector function (the RHS) of the DAE system |
111+
| `jac` | User-defined [Jacobian Matrix](jacobian-matrix.html) | **(Optional)** Jacobian matrix (matrix of the RHS derivatives) |
112+
| `x0` | `const daecpp::state_vector &` | The initial condition (initial state vector) |
113+
| `t` | `const double` **or** `const std::vector<double> &` | Integration interval `[0, t]` **or** a vector of integration times (useful if the user need the output at particular times `t`) |
114+
| `sol_mgr` | User-defined [Solution Manager](solution-manager.html) | Solution manager (solution observer and/or event function) |
115+
| `opt` | `const daecpp::SolverOptions &` | **(Optional)** Solver options |
116+
117+
## Exit codes
118+
119+
The `solve(...)` function can produce the following exit codes upon computation completion:
120+
121+
| Exit code | Value | Description |
122+
| --------- | ----- | ----------- |
123+
| `exit_code::success` | `0` | Solving completed successfully |
124+
| `exit_code::diverged` | `1` | Solution diverged (Newton method diverged) |
125+
| `exit_code::linsolver_failed_decomposition` | `2` | Linear solver: failed matrix decomposition |
126+
| `exit_code::linsolver_failed_solving` | `3` | Linear solver: failed linear system solving |
127+
| `exit_code::unknown` | `10` | Unknown error (can be a bug, should never happen) |
128+
129+
## Examples
130+
131+
An example of using `daecpp::solve(...)` function is provided in the [simple_dae.cpp](https://github.com/dae-cpp/dae-cpp/blob/master/examples/simple_dae/simple_dae.cpp) source file.
132+
133+
Without user-defined Jacobian matrix and solver options:
134+
135+
```cpp
136+
int main()
137+
{
138+
daecpp::state_vector x0{0, 1}; // Initial condition: x = 0, y = 1
139+
double t_end{1.0}; // Solution interval: t = [0, t_end]
140+
141+
daecpp::state_vector error; // Absolute error (defined in MyObserver class)
142+
143+
// Solves the DAE system
144+
int status = daecpp::solve(MyMassMatrix(), MyRHS(),
145+
x0, t_end,
146+
MyObserver(error));
147+
148+
// Prints the error at the very end of computation
149+
std::cout << "Abs. error: " << error.back() << '\n';
21150
22-
Serves as a wrapper for lower level [`daecpp::solve(...)`](#daecppsolve-function) function calls. Contains the [Solver Options](solver-options.html) and [Solution Holder](solution-manager.html#solution-holder-class) objects.
151+
return status;
152+
}
153+
```
23154

24-
### `System` class public members
155+
With analytic Jacobian and a few redefined solver options:
25156

26-
### `System` class constructor
157+
```cpp
158+
int main()
159+
{
160+
daecpp::state_vector x0{0, 1}; // Initial condition: x = 0, y = 1
161+
double t_end{1.0}; // Solution interval: t = [0, t_end]
27162

28-
### `System` class `solve(...)` method
163+
daecpp::state_vector error; // Absolute error (defined in MyObserver class)
29164

30-
### Example
165+
// To add user-defined solver options:
166+
daecpp::SolverOptions opt;
167+
opt.verbosity = daecpp::verbosity::extra;
168+
opt.dt_max = 0.01;
31169

32-
## `daecpp::solve(...)` function
170+
// Solves the DAE system
171+
int status = daecpp::solve(MyMassMatrix(), MyRHS(), MyJacobian(),
172+
x0, t_end,
173+
MyObserver(error),
174+
opt);
33175

34-
Integrates the system of DAEs.
176+
// Prints the error at the very end of computation
177+
std::cout << "Abs. error: " << error.back() << '\n';
35178

36-
### Example
179+
return status;
180+
}
181+
```

0 commit comments

Comments
 (0)