Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
sub_simulation_control.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4#ifndef lethe_sub_simulation_control_h
5#define lethe_sub_simulation_control_h
6
7#include <deal.II/base/exceptions.h>
8
9using namespace dealii;
10
11/**
12 * @file sub_simulation_control.h
13 * @brief Controls smaller simulation blocks within simulations.
14 *
15 * Lethe simulations are controlled using the SimulationControl class and its
16 * derivative. However, some models contain a sub model with it's own
17 * time-stepping. This is the case for the CFD-DEM modules which needs to do a
18 * number of DEM iterations per CFD time-step. Whenever this is required, a sub
19 * simulation control is used. This file contains classes which are used for sub
20 * simulation control. The sub simulation control do not all depend from a
21 * base class because they are all very different and don't share a common
22 * architecture.
23 *
24 */
25
26/**
27 * @brief Controls DEM sub iteration logic.
28 *
29 * The SubSimulationControlDEM class is responsible for managing the progression
30 * of the DEM component of a CFD-DEM simulation.
31 *
32 * This class supports two approaches for the DEM iteration:
33 * - Fixed number of iterations: In this case, a fixed number of DEM iterations
34 * is carried out for each CFD time step. If the CFD uses adaptive time
35 * stepping, then the DEM simulation time step may change dynamically during the
36 * simulation.
37 * - Fixed fraction of Rayleigh characteristic time: In this case, the DEM time
38 * step is fixed to a fraction of the Rayleigh characteristic time step. This
39 * means that the number of DEM iterations per CFD time step is adjusted
40 * dynamically.
41 *
42 */
43
45{
46public:
47 /**
48 * @brief Type of iteration method for DEM sub simulation control
49 *
50 * Declares the types of sub simulation control that are available for CFD-DEM
51 * simulations.
52 */
53
55 {
56 /// Fixed number of DEM iterations per CFD time step.
58 /// DEM time step is fixed at a constant fraction of the Rayleigh time step.
60 };
61
62 /**
63 * @brief Construct a SubSimulationControlDEM object
64 *
65 * Depending on the iteration logic, the constructor calculates the total
66 * number of DEM iterations and the DEM time step. When using a fixed number
67 * of iterations, the time step is derived from the time interval and the
68 * coupling frequency. When using a fixed fraction of the Rayleigh
69 * characteristic time, the time step is set to the specified fraction and the
70 * number of iterations is derived accordingly.
71 *
72 * @param[in] iteration_logic The logic used to determine the DEM sub
73 * iteration time step and number of iterations.
74 * @param[in] time_interval The time interval over which the DEM sub
75 * iterations are to be carried out. This corresponds to the CFD time step.
76 * @param[in] coupling_frequency The number of DEM iterations per CFD time
77 * step. Only used when @p iteration_logic is
78 * DEMSubIterationLogic::fixed_number_of_iterations.
79 * @param[in] rayleigh_characteristic_time The Rayleigh characteristic time
80 * step of the particles.
81 * @param[in] fraction_of_rayleigh_characteristic_time The target fraction of
82 * the Rayleigh characteristic time to use as the DEM time step. Only used
83 * when @p iteration_logic is
84 * DEMSubIterationLogic::fixed_fraction_of_rayleigh_time_step.
85 */
88 const double time_interval,
89 const unsigned int coupling_frequency,
92
93
94 /**
95 * @brief Advance the DEM sub simulation by one iteration
96 *
97 * Increments the iteration counter by one and checks whether additional
98 * iterations are required to complete the DEM sub simulation within the
99 * current CFD time step. As long as this method returns true, the DEM
100 * simulation should continue iterating.
101 *
102 * @return true if more iterations are needed, false if the sub simulation is
103 * complete.
104 */
105 bool
106 iterate();
107
108 /**
109 * @brief Get the current DEM sub iteration number
110 *
111 * @return The current iteration number within the DEM sub simulation.
112 */
113 unsigned int
115 {
116 return iteration_number;
117 }
118
119 /**
120 * @brief Get the DEM sub simulation time step
121 *
122 * @return The time step used for the DEM sub iterations.
123 */
124 double
126 {
127 return time_step;
128 }
129
130 /**
131 * @brief Check if this is the first DEM sub iteration
132 *
133 * The first iteration corresponds to either the state before the sub
134 * simulation control has started iterating (iteration_number == 0) or the
135 * first iteration it is actually carrying out (iteration_number == 1).
136 *
137 * @return true if this is the first iteration, false otherwise.
138 */
139 bool
141 {
142 return (iteration_number == 0 || iteration_number == 1);
143 }
144
145 /**
146 * @brief Check if this is the last DEM sub iteration
147 *
148 * The last iteration is reached when the iteration number equals the total
149 * number of iterations required to complete the DEM sub simulation within
150 * the current CFD time step.
151 *
152 * @return true if this is the last iteration, false otherwise.
153 */
154 bool
159
160private:
161 /// Logic used for the DEM iterations
163
164 /// Time interval over which the time integration is to be carried out.
165 const double time_interval;
166
167 /// Coupling frequency. This is only used when
168 /// iteration_logic=fixed_number_of_iterations
169 const unsigned int coupling_frequency;
170
171 /// Rayleigh characteristic time for the particles
173
174 /// Targeted fraction of the Rayleigh characteristic time. This is only used
175 /// when iteration_logic=fixed_fraction_of_rayleigh_time_step
177
178 /// Current value of the sub iteration number. This is initialized to zero.
179 unsigned int iteration_number;
180
181 /// Total number of iterations. This is the number of iterations that is
182 /// required until the completion of the sub simulation control
184
185 /// Time step value of the sub time stepping
186 double time_step;
187};
188
189#endif
double time_step
Time step value of the sub time stepping.
unsigned int get_iteration() const
Get the current DEM sub iteration number.
double get_time_step() const
Get the DEM sub simulation time step.
unsigned int iteration_number
Current value of the sub iteration number. This is initialized to zero.
const DEMSubIterationLogic iteration_logic
Logic used for the DEM iterations.
const double rayleigh_characteristic_time
Rayleigh characteristic time for the particles.
SubSimulationControlDEM(const DEMSubIterationLogic iteration_logic, const double time_interval, const unsigned int coupling_frequency, const double rayleigh_characteristic_time, const double fraction_of_rayleigh_characteristic_time)
Construct a SubSimulationControlDEM object.
bool is_first_iteration() const
Check if this is the first DEM sub iteration.
DEMSubIterationLogic
Type of iteration method for DEM sub simulation control.
@ fixed_number_of_iterations
Fixed number of DEM iterations per CFD time step.
@ fixed_fraction_of_rayleigh_time_step
DEM time step is fixed at a constant fraction of the Rayleigh time step.
const double time_interval
Time interval over which the time integration is to be carried out.
const double fraction_of_rayleigh_characteristic_time
const unsigned int coupling_frequency
bool is_last_iteration() const
Check if this is the last DEM sub iteration.
bool iterate()
Advance the DEM sub simulation by one iteration.