Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
sdirk_stage_data.cc
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#include <core/parameters.h>
6
7#include <deal.II/base/exceptions.h>
8
9#include <deal.II/lac/full_matrix.h>
10
11#include <numbers>
12#include <vector>
13
14using namespace dealii;
15
16/// Function to construct the Butcher's table for a given SDIRK method
17// The coefficients are fixed data during the simulation.
20{
21 SDIRKTable table;
22
23 // When referencing to SDIRK methods the pattern used is sdirkOrderStage. For
24 // instance, sdirk22 indicates SDIRK method with order 2 and 2 stages
26 {
27 // SDIRK22 - Alexander's method (L-stable)
28 // Reference: R. Alexander, Diagonally implicit Runge–Kutta methods for
29 // stiff ODEs, SIAM Journal on Numerical Analysis, 14(6), 1006–1021, 1977.
30 // DOI: https://doi.org/10.1137/0714068
31
32 // alpha is a constant coefficient chosen to ensure the method is stable
33 // and consistent
34 constexpr double alpha = (2. - std::numbers::sqrt2) / 2.;
35
36 table.A.reinit(2, 2);
37 table.A(0, 0) = alpha;
38 table.A(1, 0) = 1.0 - alpha;
39 table.A(1, 1) = alpha;
40
41 table.c.resize(2);
42 table.c[0] = alpha;
43 table.c[1] = 1.0;
44
45 table.b.resize(2);
46 table.b[0] = 1.0 - alpha;
47 table.b[1] = alpha;
48
49 return table;
50 }
51
53 {
54 // SDIRK33 - 3-stage, 3rd-order, L-stable and stiffly-accurate method
55 // (Alexander's method). References:
56 // R. Alexander, Diagonally implicit Runge–Kutta methods for stiff ODEs,
57 // SIAM Journal on Numerical Analysis, 14(6), 1006–1021, 1977.
58 // DOI: https://doi.org/10.1137/0714068
59 // C. A. Kennedy and M. H. Carpenter, "Diagonally Implicit Runge-Kutta
60 // Methods for Ordinary Differential Equations. A Review"
61 // NASA/TM–2016–219173, March 2016. No DOI available URL :
62 // https://ntrs.nasa.gov/api/citations/20160005923/downloads/20160005923.pdf
63
64 // gamma is the root of gamma^3 - 3 gamma^2 + 3/2 gamma - 1/6 = 0 that
65 // makes the method L-stable. All the other coefficients are expressed
66 // in closed form from gamma so that the order conditions are satisfied
67 // to machine precision.
68 constexpr double gamma = 0.43586652150845899941601945;
69 constexpr double c2 = (1.0 + gamma) / 2.0;
70 constexpr double b1 = -(6.0 * gamma * gamma - 16.0 * gamma + 1.0) / 4.0;
71 constexpr double b2 = (6.0 * gamma * gamma - 20.0 * gamma + 5.0) / 4.0;
72
73 table.A.reinit(3, 3);
74 table.A(0, 0) = gamma;
75 table.A(1, 0) = c2 - gamma;
76 table.A(1, 1) = gamma;
77 table.A(2, 0) = b1;
78 table.A(2, 1) = b2;
79 table.A(2, 2) = gamma;
80
81 table.c.resize(3);
82 table.c[0] = gamma;
83 table.c[1] = c2;
84 table.c[2] = 1.0;
85
86 table.b.resize(3);
87 table.b[0] = b1;
88 table.b[1] = b2;
89 table.b[2] = gamma;
90
91 return table;
92 }
93
95 {
96 // SDIRK45 - 5-stage, 4th-order, L-stable and stiffly-accurate method
97 // (SDIRK4 of Hairer and Wanner).
98 // Reference: E. Hairer and G. Wanner, "Solving Ordinary Differential
99 // Equations II: Stiff and Differential-Algebraic Problems", 2nd edition,
100 // Springer, 1996, Section IV.6, Table 6.5.
101 // DOI: https://doi.org/10.1007/978-3-642-05221-7
102 //
103 // The method also has an embedded 3rd-order solution, with weights
104 // b_hat = (59/48, -17/96, 225/32, -85/12, 0), which could be used to
105 // estimate the time integration error.
106 //
107 // Some coefficients of the method are large compared to gamma (up to
108 // |a_ij / gamma| = 31.25). The error of the non-linear solver at a stage
109 // is thus amplified in the following stages, so a tight non-linear
110 // tolerance should be used with this method.
111 constexpr double gamma = 1.0 / 4.0;
112
113 table.A.reinit(5, 5);
114 table.A(0, 0) = gamma;
115
116 table.A(1, 0) = 1.0 / 2.0;
117 table.A(1, 1) = gamma;
118
119 table.A(2, 0) = 17.0 / 50.0;
120 table.A(2, 1) = -1.0 / 25.0;
121 table.A(2, 2) = gamma;
122
123 table.A(3, 0) = 371.0 / 1360.0;
124 table.A(3, 1) = -137.0 / 2720.0;
125 table.A(3, 2) = 15.0 / 544.0;
126 table.A(3, 3) = gamma;
127
128 table.A(4, 0) = 25.0 / 24.0;
129 table.A(4, 1) = -49.0 / 48.0;
130 table.A(4, 2) = 125.0 / 16.0;
131 table.A(4, 3) = -85.0 / 12.0;
132 table.A(4, 4) = gamma;
133
134 table.c.resize(5);
135 table.c[0] = 1.0 / 4.0;
136 table.c[1] = 3.0 / 4.0;
137 table.c[2] = 11.0 / 20.0;
138 table.c[3] = 1.0 / 2.0;
139 table.c[4] = 1.0;
140
141 // The method is stiffly accurate: the weights b are the last row of A
142 table.b.resize(5);
143 for (unsigned int j = 0; j < 5; ++j)
144 table.b[j] = table.A(4, j);
145
146 return table;
147 }
148
149 else
150 {
151 AssertThrow(false, ExcMessage("Unknown SDIRK method in sdirk_table()."));
152 }
153}
154
155
156// Function to extract the coefficients of a given stage from a SDIRK Butcher's
157// table
158
160 const unsigned int stage_i)
161{
162 AssertThrow(table.c.size() == table.b.size(),
163 ExcMessage("b and c vectors must have the same size."));
164
165 AssertThrow(table.A.m() == table.b.size(),
166 ExcMessage(
167 "Matrix A dimensions must match size of b and c vectors."));
168
169 // The stages take the values 1, ..., nstages
170
171 a_ij.resize(stage_i);
172
173 for (unsigned int j = 0; j < stage_i; ++j)
174 // The Butcher's table starts at index 0 whereas the stages take the values
175 // 1, ..., nstages
176 a_ij[j] = table.A(stage_i - 1, j);
177
178 c_i = table.c[stage_i - 1];
179 b_i = table.b[stage_i - 1];
180}
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)
Function to construct the Butcher's table 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