![]() |
Lethe Open-Source Library version 1.2.0
Developer Guide
|
#include <simulation_control.h>
Public Member Functions | |
| SimulationControl (const Parameters::SimulationControl ¶m) | |
| virtual | ~SimulationControl ()=default |
| virtual bool | integrate ()=0 |
| virtual bool | is_at_end ()=0 |
| void | add_time_step (double p_timestep) |
| bool | is_at_start () const |
| bool | is_steady () const |
| bool | is_bdf () const |
| bool | is_sdirk () const |
| virtual double | calculate_time_step () |
| bool | is_refinement_step (const Parameters::MeshAdaptation &mesh_adaptation) |
| virtual void | print_progression (const ConditionalOStream &pcout)=0 |
| bool | output_enabled () const |
| virtual bool | is_output_iteration () |
| bool | get_output_boundaries () const |
| virtual bool | is_verbose_iteration () |
| virtual bool | is_first_assembly () |
| void | update_assembly_method () |
| void | set_CFL (const double p_CFL) |
| void | set_capillary_time_step_constraint (const double p_capillary_time_step_constraint) |
| void | set_current_time_step (const double new_time_step) |
| void | limit_initial_time_step_with_capillary_time_step_constraint () |
| void | set_current_capillary_time_step_ratio () |
| void | provide_residual (const double new_residual) |
| double | get_time_step () const |
| unsigned int | get_iteration_number () const |
| std::string | get_output_name () const |
| std::string | get_output_path () const |
| unsigned int | get_group_files () const |
| unsigned int | get_log_precision () const |
| double | get_current_time () const |
| double | get_previous_time () const |
| void | set_stage_time (const double c_i) |
| void | end_stages () |
| std::vector< double > | get_time_steps_vector () const |
| double | get_CFL () const |
| double | get_current_capillary_time_step_ratio () const |
| unsigned int | get_number_subdivision () const |
| unsigned int | get_log_frequency () const |
| Parameters::SimulationControl::TimeSteppingMethod | get_assembly_method () const |
| void | set_assembly_method (const Parameters::SimulationControl::TimeSteppingMethod a_method) |
| unsigned int | get_number_of_previous_solution_in_assembly () const |
| std::vector< double > | get_simulation_times () const |
| Vector< double > const & | get_bdf_coefficients () |
| virtual bool | is_adaptive_time_stepping () const =0 |
| virtual void | save (const std::string &prefix) |
| virtual void | read (const std::string &prefix) |
| std::vector< double > | get_checkpointed_simulation_control_info (const std::string &prefix) |
Static Public Member Functions | |
| static unsigned int | get_number_of_stages (const Parameters::SimulationControl::TimeSteppingMethod &method) |
Protected Member Functions | |
| void | update_bdf_coefficients () |
Protected Attributes | |
| Parameters::SimulationControl::TimeSteppingMethod | method |
| Parameters::SimulationControl::TimeSteppingMethod | assembly_method |
| double | current_time |
| double | previous_time |
| double | time_step |
| double | initial_time_step |
| double | end_time |
| bool | time_step_independent_of_end_time |
| std::vector< double > | time_step_vector |
| unsigned int | iteration_number |
| unsigned int | end_iteration |
| unsigned int | number_mesh_adapt |
| double | CFL |
| double | max_CFL |
| double | capillary_time_step_constraint |
| double | max_capillary_time_step_ratio |
| double | current_capillary_time_step_ratio |
| bool | adapt_with_capillary_time_step_ratio |
| double | residual |
| double | stop_tolerance |
| unsigned int | output_iteration_frequency |
| unsigned int | log_frequency |
| unsigned int | log_precision |
| unsigned int | subdivision |
| unsigned int | group_files |
| std::string | output_name |
| std::string | output_path |
| bool | output_boundaries |
| bool | first_assembly |
| Parameters::SimulationControl::BDFStartupMethods | bdf_start_method |
| double | startup_timestep_scaling |
| Vector< double > | bdf_coefs |
Static Protected Attributes | |
| static constexpr unsigned int | n_previous_time_steps = 4 |
Base class for controlling steady-state and transient simulations in Lethe.
The SimulationControl class is responsible for managing the progression of simulations carried out with Lethe. This is a pure virtual base class that cannot be instantiated directly. It stores core variables necessary for time-stepping control, output management, and serialization.
The class supports multiple time-stepping methods including:
Derived classes implement specific simulation control strategies for transient, steady-state, adjoint, and specialized simulations (e.g., DEM, ray tracing).
Definition at line 42 of file simulation_control.h.
| SimulationControl::SimulationControl | ( | const Parameters::SimulationControl & | param | ) |
Construct a SimulationControl object from parameter structure.
The simulation control class is constructed from a parameter structure from which it draws its arguments. This structure is not kept internally. This means that required information is copied from the struct to the class.
| [in] | param | Structure of the parameters for the simulation control |
Definition at line 15 of file simulation_control.cc.
References adapt_with_capillary_time_step_ratio, assembly_method, bdf_coefs, bdf_start_method, capillary_time_step_constraint, CFL, current_capillary_time_step_ratio, current_time, Parameters::SimulationControl::dt, end_iteration, end_time, first_assembly, group_files, initial_time_step, iteration_number, log_frequency, log_precision, max_capillary_time_step_ratio, max_CFL, method, n_previous_time_steps, number_mesh_adapt, output_boundaries, output_iteration_frequency, output_name, output_path, previous_time, residual, startup_timestep_scaling, stop_tolerance, subdivision, time_step, time_step_independent_of_end_time, and time_step_vector.
|
virtualdefault |
Default destructor.
References method.
| void SimulationControl::add_time_step | ( | double | p_timestep | ) |
Add a time step and store the previous one in the history.
This method updates the time step history by adding the new time step to the time_step_vector. The history is maintained for BDF methods that require knowledge of previous time steps.
| [in] | p_timestep | The new value of the time step for the present iteration |
Definition at line 59 of file simulation_control.cc.
References time_step, and time_step_vector.
|
inlinevirtual |
Calculate the next value of the time step.
The base function returns the value of the current time step, but derived classes may implement adaptive time stepping based on CFL conditions or other criteria.
Reimplemented in SimulationControlTransient.
Definition at line 426 of file simulation_control.h.
References time_step.
|
inline |
Restore the current time to \(t_{n+1}\) after all the stages of a multi-stage method have been solved. This reproduces exactly the value computed in integrate(), where current_time = previous_time + time_step.
Definition at line 731 of file simulation_control.h.
References current_time, previous_time, and time_step.
|
inline |
Get current assembly method.
Definition at line 797 of file simulation_control.h.
References assembly_method.
|
inline |
Get BDF coefficients.
Returns the BDF coefficients used for time integration. These coefficients are updated by update_bdf_coefficients() when the time step or assembly method changes.
Definition at line 861 of file simulation_control.h.
References bdf_coefs.
|
inline |
Get current CFL number.
Definition at line 753 of file simulation_control.h.
References CFL.
| std::vector< double > SimulationControl::get_checkpointed_simulation_control_info | ( | const std::string & | prefix | ) |
Read and return simulation control information from checkpoint without updating.
Reads and returns the simulation control information from the checkpoint file without updating the internal simulation control state. Useful for querying checkpoint information without modifying the current simulation state.
| [in] | prefix | The prefix of the checkpoint file for the simulation |
Definition at line 257 of file simulation_control.cc.
References check_file_exists(), and time_step_vector.
|
inline |
Get current capillary time-step ratio (Δt/Δt_σ).
Definition at line 764 of file simulation_control.h.
References current_capillary_time_step_ratio.
|
inline |
Get current simulation time.
Definition at line 693 of file simulation_control.h.
References current_time.
|
inline |
Get number of parallel files to generate for output.
Definition at line 671 of file simulation_control.h.
References group_files.
|
inline |
Get current iteration number.
Definition at line 638 of file simulation_control.h.
References iteration_number.
|
inline |
Get log frequency.
Definition at line 786 of file simulation_control.h.
References log_frequency.
|
inline |
Get log precision.
Definition at line 682 of file simulation_control.h.
References log_precision.
|
inline |
Get number of previous solutions required in assembly.
Returns the number of previous solution vectors required for the current time stepping method (e.g., 1 for BDF1, 2 for BDF2, etc.).
Definition at line 823 of file simulation_control.h.
References method, and number_of_previous_solutions().
|
static |
Return the number of stages associated with the time-stepping method. For SDIRK methods, the number of stages is given by the last digit of the method name. For other methods, the number of stages is 1.
| [in] | method | The time-stepping method for which the number of stages is requested. |
Definition at line 168 of file simulation_control.cc.
References method.
|
inline |
Get number of mesh subdivisions for output.
Definition at line 775 of file simulation_control.h.
References subdivision.
|
inline |
Check if the boundaries of the domain should be outputted when writing results.
Definition at line 478 of file simulation_control.h.
References output_boundaries.
|
inline |
Get output file name prefix.
Definition at line 649 of file simulation_control.h.
References output_name.
|
inline |
Get output directory path.
Definition at line 660 of file simulation_control.h.
References output_path.
|
inline |
Get previous simulation time.
Definition at line 704 of file simulation_control.h.
References previous_time.
|
inline |
Get simulation times for current and previous time steps.
Creates a vector containing the current time and previous times based on the time step history. The times are calculated by subtracting the accumulated time steps from the current time.
Definition at line 838 of file simulation_control.h.
References current_time, n_previous_time_steps, and time_step_vector.
|
inline |
Get current time step.
Definition at line 627 of file simulation_control.h.
References time_step.
|
inline |
Get time step history vector.
Definition at line 742 of file simulation_control.h.
References time_step_vector.
|
pure virtual |
Pure virtual function to control the progression of the simulation.
As long as integrate returns true, a simulation should proceed. The criteria used to stop/continue the simulation in integrate is a property of each individual time stepping control. For example, steady-state simulation will proceed until the number of required mesh adaptations has been performed.
Implemented in SimulationControlRayTracing, SimulationControlSteady, and SimulationControlTransient.
|
pure virtual |
Indicate if the simulation uses adaptive time stepping or not.
Pure virtual function to be implemented by derived classes based on their specific time stepping strategy.
Implemented in SimulationControlRayTracing, SimulationControlSteady, and SimulationControlTransient.
|
pure virtual |
Establishes if a simulation has reached its end.
The concrete implementation of the class decides what is the stopping criteria (iteration number, time_end reached, residual tolerance, etc.)
Implemented in SimulationControlAdjointSteady, SimulationControlRayTracing, SimulationControlSteady, and SimulationControlTransient.
|
inline |
Establish if the iteration is the first iteration or if the simulation has not begun.
Definition at line 366 of file simulation_control.h.
References iteration_number.
|
inline |
Establish if the method is a BDF method.
Definition at line 391 of file simulation_control.h.
References Parameters::SimulationControl::bdf1, Parameters::SimulationControl::bdf2, Parameters::SimulationControl::bdf3, method, and Parameters::SimulationControl::steady_bdf.
|
inlinevirtual |
Check if this is the first assembly of the present iteration.
If it indeed is the first assembly, then the first_assembly flag is set to false. This function is used when providing the residual to the simulation control object when using steady-bdf methods. Since the residual must be provided once per time step (and at the beginning), this function is used to identify that.
Definition at line 509 of file simulation_control.h.
References first_assembly.
|
virtual |
Check if the present iteration is an output iteration.
Determines whether output should be written at the current iteration based on the output control chosen (iteration-based or time-based).
Reimplemented in SimulationControlTransient.
Definition at line 71 of file simulation_control.cc.
References get_iteration_number(), and output_iteration_frequency.
| bool SimulationControl::is_refinement_step | ( | const Parameters::MeshAdaptation & | mesh_adaptation | ) |
Check if the current step is a refinement step.
| [in] | MeshAdaptation | Parameters that control dynamic mesh adaptation |
Definition at line 83 of file simulation_control.cc.
References Parameters::MeshAdaptation::frequency, get_iteration_number(), is_refinement_step(), and Parameters::MeshAdaptation::refinement_at_frequency.
|
inline |
Establish if the method is an SDIRK method.
Definition at line 406 of file simulation_control.h.
References method, Parameters::SimulationControl::sdirk22, Parameters::SimulationControl::sdirk33, and Parameters::SimulationControl::sdirk45.
|
inline |
Establish if the simulation is a steady-state simulation.
Definition at line 377 of file simulation_control.h.
References method, Parameters::SimulationControl::steady, and Parameters::SimulationControl::steady_bdf.
|
virtual |
Check if the present iteration is a verbose iteration.
Determines if output should be written to the terminal at the current iteration based on the log_frequency setting.
Definition at line 207 of file simulation_control.cc.
References get_iteration_number(), and log_frequency.
|
inline |
Update initial time step to respect the capillary time-step constraint. If the initial time step is already below the capillary time step, then we do not change it.
Definition at line 582 of file simulation_control.h.
References capillary_time_step_constraint, initial_time_step, max_capillary_time_step_ratio, and set_current_time_step().
|
inline |
Check if VTU/PVTU/PVD outputs are disabled.
Definition at line 456 of file simulation_control.h.
References output_iteration_frequency.
|
pure virtual |
Print the current progress status of the simulation.
Pure virtual function that prints simulation progress information to the terminal. The specific format and content depend on the derived class implementation.
| [in] | pcout | Parallel conditional output stream used to print the information |
Implemented in SimulationControlAdjointSteady, SimulationControlRayTracing, SimulationControlSteady, SimulationControlTransient, and SimulationControlTransientDEM.
|
inline |
Provide the value of the residual at the beginning of the iteration to the simulation controller.
Used primarily in adjoint time-stepping to track convergence.
| [in] | new_residual | Value of the residual at the beginning of an adjoint time-stepping time step |
Definition at line 616 of file simulation_control.h.
References residual.
|
virtual |
Read the simulation control information from a checkpoint file.
Reads and updates the time step vector, the CFL value, the time and the iteration number from a checkpoint file to restart the simulation.
| [in] | prefix | The prefix of the checkpoint file for the simulation |
Reimplemented in SimulationControlTransient.
Definition at line 231 of file simulation_control.cc.
References CFL, check_file_exists(), current_time, iteration_number, previous_time, time_step, and time_step_vector.
|
virtual |
Save the simulation control information to a checkpoint file.
Saves the time step vector, the CFL value, the time and the iteration number to enable restart capabilities.
| [in] | prefix | The prefix of the checkpoint file for the simulation |
Definition at line 213 of file simulation_control.cc.
References CFL, current_time, iteration_number, and time_step_vector.
|
inline |
Set the assembly method.
| [in] | a_method | The time stepping method to use for assembly |
Definition at line 808 of file simulation_control.h.
References assembly_method.
|
inline |
Set the value of the current capillary time-step constraint.
The solver computes and provides the current capillary time-step constraint to the SimulationControl for use in adaptive time-stepping.
| [in] | p_capillary_time_step_constraint | Value of the current capillary time-step constraint computed by the solver. |
Definition at line 550 of file simulation_control.h.
References capillary_time_step_constraint.
|
inline |
Set the value of the CFL condition.
The solver calculates and provides the CFL number to the simulation control for use in adaptive time stepping.
| [in] | p_CFL | Value of the CFL condition calculated by the solver |
Definition at line 535 of file simulation_control.h.
References CFL.
|
inline |
Set the current capillary time-step ratio (Δt/Δt_σ).
Definition at line 594 of file simulation_control.h.
References capillary_time_step_constraint, current_capillary_time_step_ratio, and time_step.
|
inline |
Manually force the value of the time step for the present iteration.
Sets the time step to a specific value. This time step is appended to the time step history.
| [in] | new_time_step | The new value of the time step |
Definition at line 567 of file simulation_control.h.
References time_step.
|
inline |
Move the current time to an intermediate stage of a multi-stage (SDIRK) method, \(t_{stage} = t_n + c_i \Delta t\), so that time-dependent functions (forcing, boundary conditions) are evaluated at the time of the stage being solved. end_stages() must be called once all the stages have been solved.
| [in] | c_i | Time fraction of the stage within the time step (c coefficient of the Butcher tableau). |
Definition at line 720 of file simulation_control.h.
References current_time, previous_time, and time_step.
| void SimulationControl::update_assembly_method | ( | ) |
Define the assembly method to use while integrating.
Used to start BDF2 and BDF3 schemes with lower-order methods before transitioning to the full-order scheme. This ensures stability during the initial time steps.
Definition at line 98 of file simulation_control.cc.
References assembly_method, Parameters::SimulationControl::bdf1, Parameters::SimulationControl::bdf2, Parameters::SimulationControl::bdf3, bdf_start_method, initial_time_step, iteration_number, method, Parameters::SimulationControl::multiple_step_bdf, set_current_time_step(), and startup_timestep_scaling.
|
inlineprotected |
Update the BDF coefficients.
It is necessary to update the coefficients when there is a change in the time step values or the time stepping scheme. This method recalculates the BDF coefficients based on the current assembly method and time step history.
Definition at line 282 of file simulation_control.h.
References assembly_method, bdf_coefs, calculate_bdf_coefficients(), and time_step_vector.
|
protected |
Enable adaptive time-stepping that respects the capillary time-step constraint.
For capillary-driven multiphase flows, stability of the solved problem can be ensured by respecting the capillary time-step constraint [1]. By default, this parameter is set to false and can only be used when simulating multiphase flows.
Reference:
[1] F. Denner, F. Evrard, and B. van Wachem, “Breaching the capillary time-step constraint using a coupled VOF method with implicit surface tension,” J. Comput. Phys., vol. 459, p. 111128, Jun. 2022, doi: 10.1016/j.jcp.2022.111128
Definition at line 187 of file simulation_control.h.
|
protected |
Current method used for the present assembly.
This is used to differentiate the substeps of SDIRK methods or to start-up BDF simulations. For example, BDF2 and BDF3 schemes may start with lower-order methods before transitioning to the full-order scheme.
Definition at line 56 of file simulation_control.h.
|
protected |
BDF coefficients used for time-stepping methods.
Definition at line 269 of file simulation_control.h.
|
protected |
The method used to start high-order BDF schemes.
Definition at line 258 of file simulation_control.h.
|
protected |
Capillary time-step constraint for simulation time-stepping.
Time-step constraint for capillary-driven multiphase flows. The constraint is computed according to [1]:
\[\Delta t_\sigma = \sqrt{\frac{(\rho_0 + \rho_1) h^3}{2 \pi \sigma}} \]
with \( \sigma\) the surface tension coefficient, \( \rho_0\) and \(\rho_1\) the densities of fluid 0 and 1 respectively, and \( h\) the smallest cell measure.
Reference:
[1] F. Denner, F. Evrard, and B. van Wachem, “Breaching the capillary time-step constraint using a coupled VOF method with implicit surface tension,” J. Comput. Phys., vol. 459, p. 111128, Jun. 2022, doi: 10.1016/j.jcp.2022.111128
Definition at line 146 of file simulation_control.h.
|
protected |
Courant-Friedrich-Levy (CFL) condition value.
Definition at line 112 of file simulation_control.h.
|
protected |
Computed ratio between the current time step and the capillary time-step constraint (Δt/Δt_σ).
Definition at line 169 of file simulation_control.h.
|
protected |
Time of the current iteration being solved for.
Definition at line 59 of file simulation_control.h.
|
protected |
Simulation end iteration.
Definition at line 100 of file simulation_control.h.
|
protected |
Simulation end time.
Definition at line 71 of file simulation_control.h.
|
protected |
Indicator to tell if this is the first assembly of a time step.
Definition at line 255 of file simulation_control.h.
|
protected |
Number of parallel files to generate for output.
Definition at line 238 of file simulation_control.h.
|
protected |
Initial time step given in the parameter file.
Definition at line 68 of file simulation_control.h.
|
protected |
Iteration number.
Iterations start at 0, but the first actual iteration is iteration 1.
Definition at line 97 of file simulation_control.h.
|
protected |
Log iteration frequency.
Controls the frequency at which the status of the simulation is written to the terminal.
Definition at line 224 of file simulation_control.h.
|
protected |
Log precision.
Controls the number of significant digits displayed on the standard outputs.
Definition at line 232 of file simulation_control.h.
|
protected |
The user inputted ratio between the time step and the capillary time-step constraint (Δt/Δt_σ).
When SimulationControl::adapt_with_capillary_time_step_ratio is set to true, the time step of the simulation should respect the following:
\[\Delta t \leq N_\text{CTR} \, \Delta t_\sigma \]
with \( \Delta t \) the computed time step, \( N_\text{CTR} \) the capillary time-step ratio, and \( \Delta t_\sigma \) the SimulationControl::capillary_time_step_constraint.
Definition at line 163 of file simulation_control.h.
|
protected |
Maximal CFL condition for adaptive time stepping.
This is used to control adaptive time stepping. In the case of constant time stepping or steady-state simulations, this parameter remains unused.
Definition at line 120 of file simulation_control.h.
|
protected |
Time stepping method used for the simulation (BDF, SDIRK, steady, etc.).
Definition at line 46 of file simulation_control.h.
|
staticconstexprprotected |
Number of time steps stored.
BDF methods require a number of previous time steps. This number is known a priori and depends on the method used. We do not keep all the time steps to prevent the accumulation within a large vector.
Definition at line 208 of file simulation_control.h.
|
protected |
Number of mesh adaptation iterations performed.
Definition at line 103 of file simulation_control.h.
|
protected |
Output boundaries flag.
Controls if the boundaries of the domain are outputted when writing results.
Definition at line 252 of file simulation_control.h.
|
protected |
Output iteration frequency.
Controls the output of the simulation results when the output is controlled by the iteration number. A value of 0 disables output.
Definition at line 216 of file simulation_control.h.
|
protected |
Output file name prefix.
Definition at line 241 of file simulation_control.h.
|
protected |
Output directory path.
Definition at line 244 of file simulation_control.h.
|
protected |
Time of the previous iteration.
Definition at line 62 of file simulation_control.h.
|
protected |
Current value of the norm of the right-hand side residual.
Definition at line 190 of file simulation_control.h.
|
protected |
The time scaling used for small time steps at the startup of the simulation.
This scaling factor is applied during the startup phase when using high-order BDF methods to gradually transition to the full-order scheme.
Definition at line 266 of file simulation_control.h.
|
protected |
Residual tolerance at which the simulation stops.
This is used when adjoint time-stepping is employed.
Definition at line 197 of file simulation_control.h.
|
protected |
Number of mesh subdivisions to be used when outputting the results.
Definition at line 235 of file simulation_control.h.
|
protected |
Time step linking the previous iteration and the current time.
Definition at line 65 of file simulation_control.h.
|
protected |
Boolean to keep the time step for the last iteration regardless of the end time.
When true, the last time step is not adjusted to match the end time exactly. Applies to both fixed time step and adaptive time step simulations.
Definition at line 80 of file simulation_control.h.
|
protected |
Time step vector storing previous time steps.
This vector accumulates the time steps of the previous iterations. This is required for multiple-step methods such as BDF schemes. The vector size is limited by n_previous_time_steps to prevent accumulation within a large vector.
Definition at line 90 of file simulation_control.h.