Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
sdirk_stage_data.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2025-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4#ifndef lethe_sdirk_stage_data_h
5#define lethe_sdirk_stage_data_h
6
7#include <core/parameters.h>
8
9#include <deal.II/lac/full_matrix.h>
10
11#include <vector>
12
13using namespace dealii;
14
15
16/**
17 * @brief Structure representing a Butcher tableau for a SDIRK method.
18 *
19 * A singly diagonally implicit Runge-Kutta (SDIRK) method is defined by
20 * a Butcher tableau composed of three components:
21 *
22 * - A: a lower triangular matrix of coefficients a_ij, used to compute each
23 * stage.
24 * - b: a vector of weights b_i, used to combine the stage values into the final
25 * solution.
26 * - c: a vector of stage times c_i, indicating at which time fraction (within a
27 * time step) each stage is evaluated.
28 *
29 * These coefficients fully define the behavior of an implicit Runge-Kutta time
30 * integration method and are specific to each SDIRK variant (e.g., SDIRK22,
31 * SDIRK33).
32 */
34{
35 FullMatrix<double> A;
36 std::vector<double> b;
37 std::vector<double> c;
38};
39
40/**
41 * @brief Construct the Butcher tableau (A, b, c) for a given SDIRK method.
42 *
43 * This function returns the Runge-Kutta coefficients for a singly diagonally
44 * implicit Runge-Kutta (SDIRK) time integration method: SDIRK22 and SDIRK33
45 * (Alexander's 2- and 3-stage methods) or SDIRK45 (SDIRK4 of Hairer and
46 * Wanner). All these methods are L-stable and stiffly accurate. These
47 * coefficients define the time-stepping scheme and are used in implicit time
48 * integration of ODEs or PDEs.
49 *
50 * The Butcher tableau is defined as follows:
51 * - A: the matrix of coefficients a_ij
52 * - b: the weights used in the final combination of stages
53 * - c: the time locations of each stage
54 *
55 * @param[in] method The time integration method (e.g.,
56 * TimeSteppingMethod::sdirk22, TimeSteppingMethod::sdirk33) selected from the
57 * Parameters::SimulationControl::TimeSteppingMethod enum.
58 *
59 * @return SDIRKTable A structure containing the Butcher tableau (A, b, c) for the requested method.
60 */
61
62// When referencing to SDIRK methods the pattern used is sdirkOrderStage. For
63// instance, sdirk22 indicates SDIRK method with order 2 and 2 stages
66
67
68
70{
71public:
72 /**
73 * @brief Extract the coefficients of a given stage from a SDIRK Butcher tableau.
74 *
75 * This function returns the data needed to compute the solution increment
76 * at a particular stage of a SDIRK (Singly Diagonally Implicit Runge-Kutta)
77 * method. The returned structure contains:
78 * - a_ij: the vector of coefficients from stage j to stage i (for j = 0 to
79 * i),
80 * - c_i: the time coefficient associated with stage i,
81 * - b_i: the weight for combining the result of stage i in the final
82 * solution.
83 *
84 * These coefficients are used to compute each stage value \‍( \boldsymbol{z}_i
85 * \‍) of the Runge-Kutta method according to the formula:
86 *
87 * \‍[
88 * \boldsymbol{z}_i = \mathcal{F}\left(t_n + c_i \Delta t, \boldsymbol{u}_n +
89 * \Delta t \sum_{j=1}^{i} a_{ij} \boldsymbol{z}_j \right)
90 * \‍]
91 *
92 * Then, the final solution at the next time step is obtained as:
93 *
94 * \‍[
95 * \boldsymbol{u}_{n+1} = \boldsymbol{u}_n + \Delta t \sum_{i=1}^{s} b_i
96 * \boldsymbol{z}_i
97 * \‍]
98 *
99 * where \‍( s \‍) is the total number of stages.
100 *
101 * Pay attention that the stage indices start from 1, but the indices
102 * for the matrix and the vectors start at 0.
103 *
104 *
105 * @param[in] table The SDIRK Butcher tableau (structure containing A, b, and
106 * c).
107 * @param[in] stage_i Index of the stage (starting from 1) for which the data
108 * is extracted.
109 * @throws dealii::ExcMessage if the tableau is inconsistent (e.g., wrong
110 * dimensions).
111 */
112 SDIRKStageData(const SDIRKTable &table, const unsigned int stage_i);
113
114 std::vector<double> a_ij;
115 double c_i;
116 double b_i;
117};
118
119#endif // SDIRK_STAGE_DATA_H
SDIRKStageData(const SDIRKTable &table, const unsigned int stage_i)
Extract the coefficients of a given stage from a SDIRK Butcher tableau.
std::vector< double > a_ij
SDIRKTable sdirk_table(const Parameters::SimulationControl::TimeSteppingMethod method)
Construct the Butcher tableau (A, b, c) for a given SDIRK method.
Structure representing a Butcher tableau for a SDIRK method.
std::vector< double > b
std::vector< double > c
FullMatrix< double > A