Lethe Open-Source Library version 1.2.0
Developer Guide
Loading...
Searching...
No Matches
simulation_control.h
Go to the documentation of this file.
1// SPDX-FileCopyrightText: Copyright (c) 2019-2026 The Lethe Authors
2// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception OR LGPL-2.1-or-later
3
4/**
5 * @file simulation_control.h
6 * @brief Simulation control classes for managing time-stepping and iteration control in Lethe
7 *
8 * This file defines the simulation control hierarchy used in Lethe to manage
9 * steady-state and transient simulations. The SimulationControl base class and
10 * its derived classes handle time-stepping methods (including BDF and SDIRK),
11 * adaptive time stepping, output control, and simulation progression logic.
12 */
13
14#ifndef lethe_simulation_control_h
15#define lethe_simulation_control_h
16
17#include <core/bdf.h>
18#include <core/parameters.h>
19
20#include <deal.II/particles/particle_handler.h>
21
22/**
23 * @brief Base class for controlling steady-state and transient simulations in Lethe
24 *
25 * The SimulationControl class is responsible for managing the progression of
26 * simulations carried out with Lethe. This is a pure virtual base class that
27 * cannot be instantiated directly. It stores core variables necessary for
28 * time-stepping control, output management, and serialization.
29 *
30 * The class supports multiple time-stepping methods including:
31 * - Backward Differentiation Formula (BDF) methods: BDF1, BDF2, BDF3
32 * - Singly Diagonally Implicit Runge-Kutta (SDIRK) methods
33 * - Steady-state methods
34 *
35 * Derived classes implement specific simulation control strategies for
36 * transient, steady-state, adjoint, and specialized simulations (e.g., DEM, ray
37 * tracing).
38 *
39 * @note This class handles serialization through save() and read() methods
40 * to enable checkpointing and restart capabilities.
41 */
43{
44protected:
45 /// Time stepping method used for the simulation (BDF, SDIRK, steady, etc.)
47
48 /**
49 * @brief Current method used for the present assembly
50 *
51 * This is used to differentiate the substeps of SDIRK methods or
52 * to start-up BDF simulations. For example, BDF2 and BDF3 schemes
53 * may start with lower-order methods before transitioning to the
54 * full-order scheme.
55 */
57
58 /// Time of the current iteration being solved for
60
61 /// Time of the previous iteration
63
64 /// Time step linking the previous iteration and the current time
65 double time_step;
66
67 /// Initial time step given in the parameter file
69
70 /// Simulation end time
71 double end_time;
72
73 /**
74 * @brief Boolean to keep the time step for the last iteration regardless of the end time
75 *
76 * When true, the last time step is not adjusted to match the end time
77 * exactly. Applies to both fixed time step and adaptive time step
78 * simulations.
79 */
81
82 /**
83 * @brief Time step vector storing previous time steps
84 *
85 * This vector accumulates the time steps of the previous iterations.
86 * This is required for multiple-step methods such as BDF schemes.
87 * The vector size is limited by n_previous_time_steps to prevent
88 * accumulation within a large vector.
89 */
90 std::vector<double> time_step_vector;
91
92 /**
93 * @brief Iteration number
94 *
95 * Iterations start at 0, but the first actual iteration is iteration 1.
96 */
97 unsigned int iteration_number;
98
99 /// Simulation end iteration
100 unsigned int end_iteration;
101
102 /// Number of mesh adaptation iterations performed
103 unsigned int number_mesh_adapt;
104
105 /**
106 * @brief Courant-Friedrich-Levy (CFL) condition value
107 *
108 * @remark Since the SimulationControl is unaware of the information
109 * propagation mechanism (for instance the velocity), the current CFL must be
110 * set by the solver itself using set_CFL().
111 */
112 double CFL;
113
114 /**
115 * @brief Maximal CFL condition for adaptive time stepping
116 *
117 * This is used to control adaptive time stepping. In the case of constant
118 * time stepping or steady-state simulations, this parameter remains unused.
119 */
120 double max_CFL;
121
122 /**
123 * @brief Capillary time-step constraint for simulation time-stepping
124 *
125 * Time-step constraint for capillary-driven multiphase flows. The constraint
126 * is computed according to [1]:
127 * \f[
128 * \Delta t_\sigma = \sqrt{\frac{(\rho_0 + \rho_1) h^3}{2 \pi \sigma}}
129 * \f]
130 *
131 * with \f$ \sigma\f$ the surface tension coefficient, \f$ \rho_0\f$ and \f$
132 * \rho_1\f$ the densities of fluid 0 and 1 respectively, and \f$ h\f$ the
133 * smallest cell measure.
134 *
135 * @remark Since SimulationControl is unaware of the physical properties and
136 * cells dimensions, the current capillary time-step constraint must be set
137 * through SimulationControl::set_capillary_time_step_constraint.
138 *
139 * Reference:
140 *
141 * [1] F. Denner, F. Evrard, and B. van Wachem, “Breaching the capillary
142 * time-step constraint using a coupled VOF method with implicit surface
143 * tension,” J. Comput. Phys., vol. 459, p. 111128, Jun. 2022,
144 * doi: 10.1016/j.jcp.2022.111128
145 */
147
148 /**
149 * @brief The user inputted ratio between the time step and the capillary
150 * time-step constraint (Δt/Δt_σ).
151 *
152 * When SimulationControl::adapt_with_capillary_time_step_ratio is set to
153 * @p true, the time step of the simulation should respect the following:
154 *
155 * \f[
156 * \Delta t \leq N_\text{CTR} \, \Delta t_\sigma
157 * \f]
158 *
159 * with \f$ \Delta t \f$ the computed time step, \f$ N_\text{CTR} \f$ the
160 * capillary time-step ratio, and \f$ \Delta t_\sigma \f$ the
161 * SimulationControl::capillary_time_step_constraint.
162 */
164
165 /**
166 * @brief Computed ratio between the current time step and the capillary
167 * time-step constraint (Δt/Δt_σ).
168 */
170
171 /**
172 * @brief Enable adaptive time-stepping that respects the capillary time-step
173 * constraint.
174 *
175 * For capillary-driven multiphase flows, stability of the solved problem can
176 * be ensured by respecting the capillary time-step constraint [1].
177 * By default, this parameter is set to false and can only be used when
178 * simulating multiphase flows.
179 *
180 * Reference:
181 *
182 * [1] F. Denner, F. Evrard, and B. van Wachem, “Breaching the capillary
183 * time-step constraint using a coupled VOF method with implicit surface
184 * tension,” J. Comput. Phys., vol. 459, p. 111128, Jun. 2022,
185 * doi: 10.1016/j.jcp.2022.111128
186 */
188
189 /// Current value of the norm of the right-hand side residual
190 double residual;
191
192 /**
193 * @brief Residual tolerance at which the simulation stops
194 *
195 * This is used when adjoint time-stepping is employed.
196 */
198
199 /**
200 * @brief Number of time steps stored
201 *
202 * BDF methods require a number of previous time steps. This number is known a
203 * priori and depends on the method used. We do not keep all the time steps to
204 * prevent the accumulation within a large vector.
205 *
206 * @note Currently set to 4 to support up to BDF3 methods.
207 */
208 static constexpr unsigned int n_previous_time_steps = 4;
209
210 /**
211 * @brief Output iteration frequency
212 *
213 * Controls the output of the simulation results when the output is controlled
214 * by the iteration number. A value of 0 disables output.
215 */
217
218 /**
219 * @brief Log iteration frequency
220 *
221 * Controls the frequency at which the status of the simulation is written to
222 * the terminal.
223 */
224 unsigned int log_frequency;
225
226 /**
227 * @brief Log precision
228 *
229 * Controls the number of significant digits displayed on the standard
230 * outputs.
231 */
232 unsigned int log_precision;
233
234 /// Number of mesh subdivisions to be used when outputting the results
235 unsigned int subdivision;
236
237 /// Number of parallel files to generate for output
238 unsigned int group_files;
239
240 /// Output file name prefix
241 std::string output_name;
242
243 /// Output directory path
244 std::string output_path;
245
246 /**
247 * @brief Output boundaries flag
248 *
249 * Controls if the boundaries of the domain are outputted when writing
250 * results.
251 */
253
254 /// Indicator to tell if this is the first assembly of a time step
256
257 /// The method used to start high-order BDF schemes
259
260 /**
261 * @brief The time scaling used for small time steps at the startup of the simulation
262 *
263 * This scaling factor is applied during the startup phase when using
264 * high-order BDF methods to gradually transition to the full-order scheme.
265 */
267
268 /// BDF coefficients used for time-stepping methods
269 Vector<double> bdf_coefs;
270
271 /**
272 * @brief Update the BDF coefficients
273 *
274 * It is necessary to update the coefficients when there is a change in the
275 * time step values or the time stepping scheme. This method recalculates
276 * the BDF coefficients based on the current assembly method and time step
277 * history.
278 *
279 * @see calculate_bdf_coefficients
280 */
281 void
286
287public:
288 /**
289 * @brief Construct a SimulationControl object from parameter structure
290 *
291 * The simulation control class is constructed from a parameter structure
292 * from which it draws its arguments. This structure is not kept internally.
293 * This means that required information is copied from the struct to the
294 * class.
295 *
296 * @param[in] param Structure of the parameters for the simulation control
297 */
299
300 /**
301 * @brief Default destructor.
302 */
303 virtual ~SimulationControl() = default;
304
305
306 /**
307 * @brief Return the number of stages associated with the time-stepping method.
308 * For SDIRK methods, the number of stages is given by the last digit of the
309 * method name. For other methods, the number of stages is 1.
310 *
311 * @param[in] method The time-stepping method for which the number of stages
312 * is requested.
313 *
314 * @return The number of stages associated with the time-stepping method.
315 */
316 static unsigned int
319
320
321 /**
322 * @brief Pure virtual function to control the progression of the simulation
323 *
324 * As long as integrate returns true, a simulation should proceed. The
325 * criteria used to stop/continue the simulation in integrate is a property of
326 * each individual time stepping control. For example, steady-state simulation
327 * will proceed until the number of required mesh adaptations has been
328 * performed.
329 *
330 * @return true if the simulation should continue, false otherwise
331 */
332 virtual bool
334
335 /**
336 * @brief Establishes if a simulation has reached its end
337 *
338 * The concrete implementation of the class decides what is the stopping
339 * criteria (iteration number, time_end reached, residual tolerance, etc.)
340 *
341 * @return true if the simulation has reached its end condition, false otherwise
342 */
343 virtual bool
345
346 /**
347 * @brief Add a time step and store the previous one in the history
348 *
349 * This method updates the time step history by adding the new time step
350 * to the time_step_vector. The history is maintained for BDF methods that
351 * require knowledge of previous time steps.
352 *
353 * @param[in] p_timestep The new value of the time step for the present
354 * iteration
355 */
356 void
357 add_time_step(double p_timestep);
358
359
360 /**
361 * @brief Establish if the iteration is the first iteration or if the simulation has not begun
362 *
363 * @return true if iteration_number <= 1, false otherwise
364 */
365 bool
367 {
368 return iteration_number <= 1;
369 }
370
371 /**
372 * @brief Establish if the simulation is a steady-state simulation
373 *
374 * @return true if the method is steady or steady_bdf, false otherwise
375 */
376 bool
384
385 /**
386 * @brief Establish if the method is a BDF method
387 *
388 * @return true if the method is BDF1, BDF2, BDF3, or steady BDF, false otherwise
389 */
390 bool
399
400 /**
401 * @brief Establish if the method is an SDIRK method
402 *
403 * @return true if the method is sdirk22, sdirk33, or sdirk45, false otherwise
404 */
405 bool
414
415
416 /**
417 * @brief Calculate the next value of the time step
418 *
419 * The base function returns the value of the current time step, but derived
420 * classes may implement adaptive time stepping based on CFL conditions or
421 * other criteria.
422 *
423 * @return The calculated time step value
424 */
425 virtual double
427 {
428 return time_step;
429 }
430
431 /**
432 * @brief Check if the current step is a refinement step
433 *
434 * @param[in] MeshAdaptation Parameters that control dynamic mesh adaptation
435 */
436 bool
437 is_refinement_step(const Parameters::MeshAdaptation &mesh_adaptation);
438
439 /**
440 * @brief Print the current progress status of the simulation
441 *
442 * Pure virtual function that prints simulation progress information to the
443 * terminal. The specific format and content depend on the derived class
444 * implementation.
445 *
446 * @param[in] pcout Parallel conditional output stream used to print the
447 * information
448 */
449 virtual void
450 print_progression(const ConditionalOStream &pcout) = 0;
451
452 /**
453 * @brief Check if VTU/PVTU/PVD outputs are disabled
454 */
455 bool
457 {
458 return output_iteration_frequency != 0;
459 }
460
461 /**
462 * @brief Check if the present iteration is an output iteration
463 *
464 * Determines whether output should be written at the current iteration
465 * based on the output control chosen (iteration-based or time-based).
466 *
467 * @return true if output should be written at this iteration, false otherwise
468 */
469 virtual bool
471
472 /**
473 * @brief Check if the boundaries of the domain should be outputted when writing results
474 *
475 * @return true if boundaries should be included in output, false otherwise
476 */
477 bool
479 {
480 return output_boundaries;
481 }
482
483 /**
484 * @brief Check if the present iteration is a verbose iteration
485 *
486 * Determines if output should be written to the terminal at the current
487 * iteration based on the log_frequency setting.
488 *
489 * @return true if verbose output should be written at this iteration, false otherwise
490 */
491 virtual bool
493
494 /**
495 * @brief Check if this is the first assembly of the present iteration
496 *
497 * If it indeed is the first assembly, then the first_assembly flag is set to
498 * false. This function is used when providing the residual to the simulation
499 * control object when using steady-bdf methods. Since the residual must be
500 * provided once per time step (and at the beginning), this function is used
501 * to identify that.
502 *
503 * @return true if this is the first assembly, false otherwise
504 *
505 * @note This method has a side effect: it sets first_assembly to false after
506 * being called when it returns true.
507 */
508 virtual bool
510 {
511 bool return_value = first_assembly;
512 first_assembly = false;
513 return return_value;
514 }
515
516 /**
517 * @brief Define the assembly method to use while integrating
518 *
519 * Used to start BDF2 and BDF3 schemes with lower-order methods before
520 * transitioning to the full-order scheme. This ensures stability during
521 * the initial time steps.
522 */
523 void
525
526 /**
527 * @brief Set the value of the CFL condition
528 *
529 * The solver calculates and provides the CFL number to the simulation control
530 * for use in adaptive time stepping.
531 *
532 * @param[in] p_CFL Value of the CFL condition calculated by the solver
533 */
534 void
535 set_CFL(const double p_CFL)
536 {
537 CFL = p_CFL;
538 }
539
540 /**
541 * @brief Set the value of the current capillary time-step constraint
542 *
543 * The solver computes and provides the current capillary time-step
544 * constraint to the SimulationControl for use in adaptive time-stepping.
545 *
546 * @param[in] p_capillary_time_step_constraint Value of the current capillary
547 * time-step constraint computed by the solver.
548 */
549 void
551 const double p_capillary_time_step_constraint)
552 {
553 capillary_time_step_constraint = p_capillary_time_step_constraint;
554 }
555
556 /**
557 * @brief Manually force the value of the time step for the present iteration
558 *
559 * Sets the time step to a specific value. This time step is appended to the
560 * time step history.
561 *
562 * @param[in] new_time_step The new value of the time step
563 *
564 * @pre new_time_step must be positive (cannot go backward in time)
565 */
566 void
567 set_current_time_step(const double new_time_step)
568 {
569 Assert(
570 time_step > 0,
571 ExcMessage(
572 "You are trying to set a null or negative time step in a SimulationControl. This is not allowed, we cannot go backward in time."));
573 time_step = new_time_step;
574 }
575
576 /**
577 * @brief Update initial time step to respect the capillary time-step
578 * constraint. If the initial time step is already below the capillary
579 * time step, then we do not change it.
580 */
581 void
589
590 /**
591 * @brief Set the current capillary time-step ratio (Δt/Δt_σ)
592 */
593 void
595 {
596 AssertThrow(
598 ExcMessage(
599 "The current value of the capillary time-step constraint is set to a null or negative value.\n"
600 "This is not allowed. Make sure that the 'capillary_time_step_constraint' is computed and\n"
601 "that the parameter 'adapt time step to respect CTR' is set to 'true'."));
602
605 }
606
607 /**
608 * @brief Provide the value of the residual at the beginning of the iteration to the simulation controller
609 *
610 * Used primarily in adjoint time-stepping to track convergence.
611 *
612 * @param[in] new_residual Value of the residual at the beginning of an
613 * adjoint time-stepping time step
614 */
615 void
616 provide_residual(const double new_residual)
617 {
618 residual = new_residual;
619 }
620
621 /**
622 * @brief Get current time step
623 *
624 * @return Current time step value
625 */
626 double
628 {
629 return time_step;
630 }
631
632 /**
633 * @brief Get current iteration number
634 *
635 * @return Current iteration number
636 */
637 unsigned int
639 {
640 return iteration_number;
641 }
642
643 /**
644 * @brief Get output file name prefix
645 *
646 * @return Output file name prefix
647 */
648 std::string
650 {
651 return output_name;
652 }
653
654 /**
655 * @brief Get output directory path
656 *
657 * @return Output directory path
658 */
659 std::string
661 {
662 return output_path;
663 }
664
665 /**
666 * @brief Get number of parallel files to generate for output
667 *
668 * @return Number of parallel output files
669 */
670 unsigned int
672 {
673 return group_files;
674 }
675
676 /**
677 * @brief Get log precision
678 *
679 * @return Number of significant digits displayed on the standard outputs
680 */
681 unsigned int
683 {
684 return log_precision;
685 }
686
687 /**
688 * @brief Get current simulation time
689 *
690 * @return Current simulation time
691 */
692 double
694 {
695 return current_time;
696 }
697
698 /**
699 * @brief Get previous simulation time
700 *
701 * @return Previous simulation time
702 */
703 double
705 {
706 return previous_time;
707 }
708
709 /**
710 * @brief Move the current time to an intermediate stage of a multi-stage
711 * (SDIRK) method, \f$t_{stage} = t_n + c_i \Delta t\f$, so that
712 * time-dependent functions (forcing, boundary conditions) are evaluated at
713 * the time of the stage being solved. end_stages() must be called once all
714 * the stages have been solved.
715 *
716 * @param[in] c_i Time fraction of the stage within the time step (c
717 * coefficient of the Butcher tableau).
718 */
719 void
720 set_stage_time(const double c_i)
721 {
723 }
724
725 /**
726 * @brief Restore the current time to \f$t_{n+1}\f$ after all the stages of a
727 * multi-stage method have been solved. This reproduces exactly the value
728 * computed in integrate(), where current_time = previous_time + time_step.
729 */
730 void
735
736 /**
737 * @brief Get time step history vector
738 *
739 * @return Vector containing previous time steps
740 */
741 std::vector<double>
743 {
744 return time_step_vector;
745 }
746
747 /**
748 * @brief Get current CFL number
749 *
750 * @return Current CFL condition value
751 */
752 double
753 get_CFL() const
754 {
755 return CFL;
756 }
757
758 /**
759 * @brief Get current capillary time-step ratio (Δt/Δt_σ)
760 *
761 * @return Current capillary time-step ratio (Δt/Δt_σ) value
762 */
763 double
768
769 /**
770 * @brief Get number of mesh subdivisions for output
771 *
772 * @return Number of mesh subdivisions to be used when outputting the results
773 */
774 unsigned int
776 {
777 return subdivision;
778 }
779
780 /**
781 * @brief Get log frequency
782 *
783 * @return Frequency at which the status of the simulation is written to the terminal
784 */
785 unsigned int
787 {
788 return log_frequency;
789 }
790
791 /**
792 * @brief Get current assembly method
793 *
794 * @return Current time stepping method used for assembly
795 */
798 {
799 return assembly_method;
800 }
801
802 /**
803 * @brief Set the assembly method
804 *
805 * @param[in] a_method The time stepping method to use for assembly
806 */
807 void
813
814 /**
815 * @brief Get number of previous solutions required in assembly
816 *
817 * Returns the number of previous solution vectors required for the current
818 * time stepping method (e.g., 1 for BDF1, 2 for BDF2, etc.).
819 *
820 * @return Number of previous solutions needed for the current method
821 */
822 unsigned int
827
828 /**
829 * @brief Get simulation times for current and previous time steps
830 *
831 * Creates a vector containing the current time and previous times based on
832 * the time step history. The times are calculated by subtracting the
833 * accumulated time steps from the current time.
834 *
835 * @return Vector of simulation times (current and previous)
836 */
837 std::vector<double>
839 {
840 // Create a vector of the previous times
841 std::vector<double> times(n_previous_time_steps + 1);
842 for (unsigned int i = 0; i < n_previous_time_steps + 1; ++i)
843 {
844 times[i] = current_time;
845 for (unsigned int j = 0; j < i; ++j)
846 times[i] -= time_step_vector[j];
847 }
848 return times;
849 }
850
851 /**
852 * @brief Get BDF coefficients
853 *
854 * Returns the BDF coefficients used for time integration. These coefficients
855 * are updated by update_bdf_coefficients() when the time step or assembly
856 * method changes.
857 *
858 * @return Const reference to the BDF coefficients vector
859 */
860 Vector<double> const &
862 {
863 return bdf_coefs;
864 }
865
866 /**
867 * @brief Indicate if the simulation uses adaptive time stepping or not
868 *
869 * Pure virtual function to be implemented by derived classes based on their
870 * specific time stepping strategy.
871 *
872 * @return true if the simulation has adaptive time stepping, false otherwise
873 */
874 virtual bool
876
877 /**
878 * @brief Save the simulation control information to a checkpoint file
879 *
880 * Saves the time step vector, the CFL value, the time and the iteration
881 * number to enable restart capabilities.
882 *
883 * @param[in] prefix The prefix of the checkpoint file for the simulation
884 */
885 virtual void
886 save(const std::string &prefix);
887
888 /**
889 * @brief Read the simulation control information from a checkpoint file
890 *
891 * Reads and updates the time step vector, the CFL value, the time and the
892 * iteration number from a checkpoint file to restart the simulation.
893 *
894 * @param[in] prefix The prefix of the checkpoint file for the simulation
895 */
896 virtual void
897 read(const std::string &prefix);
898
899 /**
900 * @brief Read and return simulation control information from checkpoint without updating
901 *
902 * Reads and returns the simulation control information from the checkpoint
903 * file without updating the internal simulation control state. Useful for
904 * querying checkpoint information without modifying the current simulation
905 * state.
906 *
907 * @param[in] prefix The prefix of the checkpoint file for the simulation
908 *
909 * @return A vector containing the last checkpointed iteration number and time step
910 */
911 std::vector<double>
912 get_checkpointed_simulation_control_info(const std::string &prefix);
913};
914
915
916/**
917 * @brief Simulation control for transient simulations
918 *
919 * This class extends SimulationControl to handle transient (time-dependent)
920 * simulations. It implements adaptive time stepping based on CFL conditions,
921 * time-based output control, and ensures the simulation progresses until the
922 * end criterion is reached.
923 *
924 * Key features:
925 * - Adaptive time stepping with CFL-based control
926 * - Time-based or iteration-based output control
927 * - Specific output times capability
928 * - Maximum time step limiting
929 */
931{
932protected:
933 /**
934 * Boolean indicating if adaptive time-stepping is enabled.
935 * To enable it, enable either SimulationControlTransient::adapt_with_cfl or
936 * SimulationControl::adapt_with_capillary_time_step_ratio.
937 */
939
940 /**
941 * Boolean indicating if the CFL condition should be controlling the
942 * simulation time step.
943 */
945
946 /**
947 * @brief Time step scaling factor for adaptive time stepping
948 *
949 * Used to scale the time step based on the ratio of max_CFL to current CFL
950 * when adaptive time stepping is enabled.
951 */
953
954 /// Maximum allowed time step
955 double max_dt;
956
957 /**
958 * @brief Relative tolerance used to decide whether an output time has been
959 * reached
960 *
961 * An output time that lies within this tolerance after the current time is
962 * considered as reached. This prevents round-off errors accumulated in the
963 * current time from delaying or skipping an output. With an output time
964 * frequency, the tolerance is relative to the output time frequency, so that
965 * it does not change from one iteration to the next and every output time is
966 * attributed to exactly one iteration. It also applies to the bounds of the
967 * output time interval. With specific output times, the tolerance is relative
968 * to the time step.
969 */
970 static constexpr double output_time_tolerance = 1e-6;
971
972 /// Output frequency for time-based output control
974
975 /**
976 * @brief Specific output times for time output control
977 *
978 * Vector containing specific times at which output should be generated.
979 */
980 std::vector<double> output_times_vector;
981
982 /**
983 * @brief Flag to override the time step with the set value upon restart
984 */
986
987 /**
988 * @brief Time interval for output of transient iterations
989 *
990 * Used with either time output control or iteration control to define
991 * intervals for output generation.
992 */
993 std::vector<double> output_time_interval;
994
995 /// End control type: iteration-based or time-based
997
998 /// Output control type: iteration-based or time-based
1000
1001 /**
1002 * @brief Calculate the next value of the time step
1003 *
1004 * If SimulationControlTransient::adapt_with_cfl is enabled, the time step is
1005 * calculated to ensure that the CFL condition is bounded by the maximal CFL
1006 * value. If SimulationControl::adapt_with_capillary_time_step_ratio is
1007 * enabled, the time step is calculated to ensure that it is bounded
1008 * by the maximal CTR value. The new time step is scaled by
1009 * SimulationControlTransient::adaptative_time_step_scaling. If the
1010 * SimulationControl::time_step_independent_of_end_time is set to @p false, the
1011 * time step is adjusted to meet exactly the end time; the default is to not
1012 * modify the time step.
1013 *
1014 * @return The calculated time-step value
1015 */
1016 virtual double
1017 calculate_time_step() override;
1018
1019public:
1020 /**
1021 * @brief Construct a transient simulation control object
1022 *
1023 * @param[in] param Structure of the parameters for the simulation control
1024 */
1026
1027 /**
1028 * @brief Print the current progress status of the simulation
1029 *
1030 * @param[in] pcout Parallel conditional output stream used to print the
1031 * information
1032 */
1033 virtual void
1034 print_progression(const ConditionalOStream &pcout) override;
1035
1036 /**
1037 * @brief Indicate if the simulation uses adaptive time stepping or not
1038 *
1039 * @return true if the simulation has adaptive time stepping, false otherwise
1040 */
1041 bool
1043 {
1045 }
1046
1047 /**
1048 * @brief Proceed with the simulation until the end condition is reached
1049 *
1050 * Advances the simulation by incrementing time and iteration number.
1051 *
1052 * @return true if the simulation should continue, false otherwise
1053 */
1054 virtual bool
1055 integrate() override;
1056
1057 /**
1058 * @brief End the simulation when the end condition is reached
1059 *
1060 * @return true if the current time or transient iteration has reached or exceeded the end time or transient iteration, false otherwise
1061 */
1062 virtual bool
1063 is_at_end() override;
1064
1065 /**
1066 * @brief Check if the current iteration is an output iteration
1067 *
1068 * Output iterations are determined based on the value of the output time,
1069 * the output interval, and the output frequency within the interval.
1070 *
1071 * When an output time frequency is used, the output times are
1072 * \f$t_k = t_{\text{start}} + k \Delta t_{\text{output}}\f$, where
1073 * \f$t_{\text{start}}\f$ is the lower bound of the output time interval. An
1074 * iteration is an output iteration if the time step that leads to it reaches
1075 * or crosses one of these output times. The initial iteration and the last
1076 * iteration are also output iterations. In all cases, the current time must
1077 * lie within the output time interval. Both the output times and the bounds
1078 * of the interval are considered as reached up to
1079 * SimulationControlTransient::output_time_tolerance times the output time
1080 * frequency.
1081 *
1082 * When specific output times are used, they may be given in any order. An
1083 * iteration is an output iteration if the time step that leads to it, or
1084 * the next time step, reaches or crosses one of these output times. Since
1085 * the output times do not necessarily correspond to the time of an
1086 * iteration, the iterations before and after each output time are thus
1087 * written. At the initial iteration, only the output times equal to the
1088 * current time are considered. Several output times may lie within the same
1089 * time step.
1090 *
1091 * These criteria only depend on the current, previous and next times, so
1092 * calling this function several times within the same iteration always
1093 * returns the same result.
1094 *
1095 * @return true if output should be written at this iteration, false otherwise
1096 */
1097 virtual bool
1098 is_output_iteration() override;
1099
1100 /**
1101 * @brief Read the simulation control information from a checkpoint file
1102 *
1103 * Reads and updates the time step vector, the CFL value, the time and the
1104 * iteration number. Allows changing the time step if adaptive time stepping
1105 * is disabled.
1106 *
1107 * @param[in] prefix The prefix of the checkpoint file for the simulation
1108 */
1109 void
1110 read(const std::string &prefix) override;
1111};
1112
1113/**
1114 * @brief Transient simulation control tailored for the Discrete Element Method (DEM)
1115 *
1116 * This class specializes SimulationControlTransient for DEM simulations.
1117 * It provides DEM-specific progress reporting and output formatting.
1118 */
1120{
1121public:
1122 /**
1123 * @brief Construct a DEM transient simulation control object
1124 *
1125 * @param[in] param Structure of the parameters for the simulation control
1126 */
1128
1129 /**
1130 * @brief Print the current progress status of the DEM simulation
1131 *
1132 * Provides DEM-specific formatting and information in the progress output.
1133 *
1134 * @param[in] pcout Parallel conditional output stream used to print the
1135 * information
1136 */
1137 virtual void
1138 print_progression(const ConditionalOStream &pcout) override;
1139};
1140
1141/**
1142 * @brief Simulation control for steady-state simulations
1143 *
1144 * This class handles steady-state simulations where time integration is not
1145 * required. The simulation progresses through iterations until the specified
1146 * number of mesh adaptations is reached or the maximum number of iterations
1147 * is completed.
1148 *
1149 * @note Steady-state simulations do not use adaptive time stepping.
1150 */
1152{
1153public:
1154 /**
1155 * @brief Construct a steady-state simulation control object
1156 *
1157 * @param[in] param Structure of the parameters for the simulation control
1158 */
1160
1161 /**
1162 * @brief Print the current progress status of the steady-state simulation
1163 *
1164 * @param[in] pcout Parallel conditional output stream used to print the
1165 * information
1166 */
1167 virtual void
1168 print_progression(const ConditionalOStream &pcout) override;
1169
1170 /**
1171 * @brief Indicate if the simulation uses adaptive time stepping
1172 *
1173 * @return false (steady-state simulations do not use adaptive time stepping)
1174 */
1175 bool
1177 {
1178 return false;
1179 }
1180
1181 /**
1182 * @brief Proceed with the simulation until the end condition is reached
1183 *
1184 * Advances the simulation by incrementing the iteration number.
1185 *
1186 * @return true if the simulation should continue, false otherwise
1187 */
1188 virtual bool
1189 integrate() override;
1190
1191 /**
1192 * @brief End the simulation when the number of mesh adaptations is reached
1193 *
1194 * @return true if the required number of mesh adaptations has been completed, false otherwise
1195 */
1196 virtual bool
1197 is_at_end() override;
1198};
1199
1200/**
1201 * @brief Simulation control for adjoint steady-state simulations
1202 *
1203 * This class manages adjoint simulations that use a pseudo-transient approach
1204 * to converge to a steady state. The simulation terminates when the residual
1205 * reaches a specified tolerance (stop_tolerance).
1206 *
1207 * The class inherits from SimulationControlTransient to leverage time-stepping
1208 * mechanisms, but applies them in the context of an adjoint problem where time
1209 * is a pseudo-parameter for convergence.
1210 */
1212{
1213public:
1214 /**
1215 * @brief Construct an adjoint steady-state simulation control object
1216 *
1217 * @param[in] param Structure of the parameters for the simulation control
1218 */
1220
1221 /**
1222 * @brief Print the current progress status of the adjoint simulation
1223 *
1224 * @param[in] pcout Parallel conditional output stream used to print the
1225 * information
1226 */
1227 virtual void
1228 print_progression(const ConditionalOStream &pcout) override;
1229
1230 /**
1231 * @brief End the simulation when the desired residual tolerance is reached
1232 *
1233 * @return true if the residual has reached the stop_tolerance, false otherwise
1234 */
1235 virtual bool
1236 is_at_end() override;
1237};
1238
1239
1240/**
1241 * @brief Simulation control for ray tracing simulations
1242 *
1243 * This class manages ray tracing simulations where photons are traced through
1244 * a computational domain. The simulation terminates when all photons have
1245 * exited the triangulation or been absorbed.
1246 *
1247 * Ray tracing simulations do not use time stepping in the traditional sense;
1248 * instead, iterations represent photon propagation steps until all photons
1249 * have completed their trajectories.
1250 */
1252{
1253public:
1254 /**
1255 * @brief Construct a ray tracing simulation control object
1256 *
1257 * @param[in] param Structure of the parameters for the simulation control
1258 * @param[in] input_photon_handler The particle handler containing the photons
1259 * to be traced
1260 */
1262 const Parameters::SimulationControl &param,
1263 Particles::ParticleHandler<3> &input_photon_handler);
1264
1265 /**
1266 * @brief Proceed with the simulation until the end condition is reached
1267 *
1268 * Advances the ray tracing simulation by incrementing the iteration number.
1269 *
1270 * @return true if the simulation should continue, false otherwise
1271 */
1272 virtual bool
1273 integrate() override;
1274
1275 /**
1276 * @brief End the simulation when there are no longer any photons in the triangulation
1277 *
1278 * @return true if all photons have exited or been absorbed, false otherwise
1279 */
1280 bool
1281 is_at_end() override;
1282
1283 /**
1284 * @brief Indicate if the simulation uses adaptive time stepping
1285 *
1286 * @return false (ray tracing simulations do not use adaptive time stepping)
1287 */
1288 bool
1290 {
1291 return false;
1292 }
1293
1294 /**
1295 * @brief Print the current progress status of the ray tracing simulation
1296 *
1297 * @param[in] pcout Parallel conditional output stream used to print the
1298 * information
1299 */
1300 void
1301 print_progression(const ConditionalOStream &pcout) override;
1302
1303 /**
1304 * @brief Reference to the photon handler used during the ray-tracing simulation
1305 *
1306 * This handler manages the photons being traced through the domain.
1307 */
1308 Particles::ParticleHandler<3> &photon_handler;
1309};
1310
1311#endif
Vector< double > calculate_bdf_coefficients(Parameters::SimulationControl::TimeSteppingMethod method, const std::vector< double > &time_steps)
Calculate the coefficients required for backward differentiation formula (BDF) integration of order .
Definition bdf.cc:42
unsigned int number_of_previous_solutions(const Parameters::SimulationControl::TimeSteppingMethod method)
Get the number of previous time steps for a specific BDF scheme.
Definition bdf.h:97
SimulationControlAdjointSteady(const Parameters::SimulationControl &param)
Construct an adjoint steady-state simulation control object.
virtual bool is_at_end() override
End the simulation when the desired residual tolerance is reached.
virtual void print_progression(const ConditionalOStream &pcout) override
Print the current progress status of the adjoint simulation.
void print_progression(const ConditionalOStream &pcout) override
Print the current progress status of the ray tracing simulation.
Particles::ParticleHandler< 3 > & photon_handler
Reference to the photon handler used during the ray-tracing simulation.
bool is_at_end() override
End the simulation when there are no longer any photons in the triangulation.
bool is_adaptive_time_stepping() const override
Indicate if the simulation uses adaptive time stepping.
virtual bool integrate() override
Proceed with the simulation until the end condition is reached.
SimulationControlRayTracing(const Parameters::SimulationControl &param, Particles::ParticleHandler< 3 > &input_photon_handler)
Construct a ray tracing simulation control object.
virtual bool integrate() override
Proceed with the simulation until the end condition is reached.
SimulationControlSteady(const Parameters::SimulationControl &param)
Construct a steady-state simulation control object.
bool is_adaptive_time_stepping() const override
Indicate if the simulation uses adaptive time stepping.
virtual bool is_at_end() override
End the simulation when the number of mesh adaptations is reached.
virtual void print_progression(const ConditionalOStream &pcout) override
Print the current progress status of the steady-state simulation.
SimulationControlTransientDEM(const Parameters::SimulationControl &param)
Construct a DEM transient simulation control object.
virtual void print_progression(const ConditionalOStream &pcout) override
Print the current progress status of the DEM simulation.
bool is_adaptive_time_stepping() const override
Indicate if the simulation uses adaptive time stepping or not.
bool override_time_step_on_restart
Flag to override the time step with the set value upon restart.
SimulationControlTransient(const Parameters::SimulationControl &param)
Construct a transient simulation control object.
void read(const std::string &prefix) override
Read the simulation control information from a checkpoint file.
std::vector< double > output_time_interval
Time interval for output of transient iterations.
virtual void print_progression(const ConditionalOStream &pcout) override
Print the current progress status of the simulation.
virtual double calculate_time_step() override
Calculate the next value of the time step.
std::vector< double > output_times_vector
Specific output times for time output control.
static constexpr double output_time_tolerance
Relative tolerance used to decide whether an output time has been reached.
virtual bool integrate() override
Proceed with the simulation until the end condition is reached.
virtual bool is_at_end() override
End the simulation when the end condition is reached.
virtual bool is_output_iteration() override
Check if the current iteration is an output iteration.
double max_dt
Maximum allowed time step.
Parameters::SimulationControl::EndControl end_control
End control type: iteration-based or time-based.
double adaptative_time_step_scaling
Time step scaling factor for adaptive time stepping.
Parameters::SimulationControl::OutputControl output_control
Output control type: iteration-based or time-based.
double output_time_frequency
Output frequency for time-based output control.
virtual bool is_output_iteration()
Check if the present iteration is an output iteration.
virtual bool is_adaptive_time_stepping() const =0
Indicate if the simulation uses adaptive time stepping or not.
virtual double calculate_time_step()
Calculate the next value of the time step.
double startup_timestep_scaling
The time scaling used for small time steps at the startup of the simulation.
bool output_boundaries
Output boundaries flag.
virtual bool is_verbose_iteration()
Check if the present iteration is a verbose iteration.
bool is_sdirk() const
Establish if the method is an SDIRK method.
virtual bool is_first_assembly()
Check if this is the first assembly of the present iteration.
void set_CFL(const double p_CFL)
Set the value of the CFL condition.
Vector< double > bdf_coefs
BDF coefficients used for time-stepping methods.
double current_time
Time of the current iteration being solved for.
double current_capillary_time_step_ratio
Computed ratio between the current time step and the capillary time-step constraint (Δt/Δt_σ).
unsigned int get_group_files() const
Get number of parallel files to generate for output.
bool is_refinement_step(const Parameters::MeshAdaptation &mesh_adaptation)
Check if the current step is a refinement step.
unsigned int get_iteration_number() const
Get current iteration number.
bool output_enabled() const
Check if VTU/PVTU/PVD outputs are disabled.
double stop_tolerance
Residual tolerance at which the simulation stops.
double get_current_time() const
Get current simulation time.
double CFL
Courant-Friedrich-Levy (CFL) condition value.
double initial_time_step
Initial time step given in the parameter file.
virtual void read(const std::string &prefix)
Read the simulation control information from a checkpoint file.
unsigned int group_files
Number of parallel files to generate for output.
void add_time_step(double p_timestep)
Add a time step and store the previous one in the history.
bool is_steady() const
Establish if the simulation is a steady-state simulation.
unsigned int output_iteration_frequency
Output iteration frequency.
unsigned int iteration_number
Iteration number.
unsigned int get_number_subdivision() const
Get number of mesh subdivisions for output.
static unsigned int get_number_of_stages(const Parameters::SimulationControl::TimeSteppingMethod &method)
Return the number of stages associated with the time-stepping method. For SDIRK methods,...
double capillary_time_step_constraint
Capillary time-step constraint for simulation time-stepping.
std::string output_path
Output directory path.
unsigned int number_mesh_adapt
Number of mesh adaptation iterations performed.
void limit_initial_time_step_with_capillary_time_step_constraint()
Update initial time step to respect the capillary time-step constraint. If the initial time step is a...
void update_assembly_method()
Define the assembly method to use while integrating.
Parameters::SimulationControl::TimeSteppingMethod get_assembly_method() const
Get current assembly method.
unsigned int get_log_precision() const
Get log precision.
virtual bool integrate()=0
Pure virtual function to control the progression of the simulation.
void provide_residual(const double new_residual)
Provide the value of the residual at the beginning of the iteration to the simulation controller.
double previous_time
Time of the previous iteration.
double max_CFL
Maximal CFL condition for adaptive time stepping.
unsigned int get_log_frequency() const
Get log frequency.
void set_assembly_method(const Parameters::SimulationControl::TimeSteppingMethod a_method)
Set the assembly method.
std::string output_name
Output file name prefix.
bool time_step_independent_of_end_time
Boolean to keep the time step for the last iteration regardless of the end time.
std::vector< double > get_time_steps_vector() const
Get time step history vector.
std::vector< double > get_checkpointed_simulation_control_info(const std::string &prefix)
Read and return simulation control information from checkpoint without updating.
double get_time_step() const
Get current time step.
void end_stages()
Restore the current time to after all the stages of a multi-stage method have been solved....
virtual void save(const std::string &prefix)
Save the simulation control information to a checkpoint file.
double residual
Current value of the norm of the right-hand side residual.
Vector< double > const & get_bdf_coefficients()
Get BDF coefficients.
unsigned int get_number_of_previous_solution_in_assembly() const
Get number of previous solutions required in assembly.
void set_current_time_step(const double new_time_step)
Manually force the value of the time step for the present iteration.
SimulationControl(const Parameters::SimulationControl &param)
Construct a SimulationControl object from parameter structure.
unsigned int log_precision
Log precision.
bool adapt_with_capillary_time_step_ratio
Enable adaptive time-stepping that respects the capillary time-step constraint.
std::string get_output_name() const
Get output file name prefix.
bool get_output_boundaries() const
Check if the boundaries of the domain should be outputted when writing results.
virtual void print_progression(const ConditionalOStream &pcout)=0
Print the current progress status of the simulation.
double max_capillary_time_step_ratio
The user inputted ratio between the time step and the capillary time-step constraint (Δt/Δt_σ).
void set_stage_time(const double c_i)
Move the current time to an intermediate stage of a multi-stage (SDIRK) method, , so that time-depend...
void set_current_capillary_time_step_ratio()
Set the current capillary time-step ratio (Δt/Δt_σ).
virtual ~SimulationControl()=default
Default destructor.
double time_step
Time step linking the previous iteration and the current time.
void update_bdf_coefficients()
Update the BDF coefficients.
Parameters::SimulationControl::BDFStartupMethods bdf_start_method
The method used to start high-order BDF schemes.
double end_time
Simulation end time.
virtual bool is_at_end()=0
Establishes if a simulation has reached its end.
bool first_assembly
Indicator to tell if this is the first assembly of a time step.
bool is_bdf() const
Establish if the method is a BDF method.
std::vector< double > get_simulation_times() const
Get simulation times for current and previous time steps.
unsigned int subdivision
Number of mesh subdivisions to be used when outputting the results.
double get_previous_time() const
Get previous simulation time.
void set_capillary_time_step_constraint(const double p_capillary_time_step_constraint)
Set the value of the current capillary time-step constraint.
bool is_at_start() const
Establish if the iteration is the first iteration or if the simulation has not begun.
static constexpr unsigned int n_previous_time_steps
Number of time steps stored.
unsigned int end_iteration
Simulation end iteration.
unsigned int log_frequency
Log iteration frequency.
std::string get_output_path() const
Get output directory path.
Parameters::SimulationControl::TimeSteppingMethod method
Time stepping method used for the simulation (BDF, SDIRK, steady, etc.).
double get_current_capillary_time_step_ratio() const
Get current capillary time-step ratio (Δt/Δt_σ).
double get_CFL() const
Get current CFL number.
std::vector< double > time_step_vector
Time step vector storing previous time steps.
Parameters::SimulationControl::TimeSteppingMethod assembly_method
Current method used for the present assembly.
MeshAdaption - Parameters that control dynamic mesh adaptation. Dynamic mesh adaptation in Lethe is v...
SimulationControl - Defines the parameter that control the flow of the simulation as well as the freq...
Definition parameters.h:87