Simulation Control

This subsection is the most important in a simulation and therefore, the most commonly modified in a parameter file. It controls the general parameters of the simulation, such as, the time integration method, end time of a simulation and output settings for paraview files.

Tip

A standard convention in Lethe is to keep this section at the top of the parameter file, since it is generally the most accessed one.

subsection simulation control
  # Type of solver or time-stepping scheme
  set method = steady

  #---------------------------------------------------
  # Steady-state simulation parameters
  #---------------------------------------------------
  # Number of mesh adaptation
  set number mesh adapt = 0

  # Tolerance at which the simulation is stopped
  set stop tolerance = 1e-10

  #---------------------------------------------------
  # BDF scheme parameters
  #---------------------------------------------------
  # Method used to startup high order BDF methods
  set bdf startup method = multiple step bdf

  # Scaling factor used in the iterations necessary to startup the BDF schemes
  set startup time scaling = 0.4

  #---------------------------------------------------
  # Transient simulations parameters
  #---------------------------------------------------
  # End time value of the simulation
  set time end = 1

  # Time step value
  set time step = 1

  # Adaptive time-stepping with an imposed max CFL
  set adapt time step to respect CFL = false

  # True if the time step should be overridden upon restart
  set override time step on restart = false

  # Maximum CFL value
  set max cfl = 1

  # Maximum time step value
  set max time step = 1e6

  # Adaptative time step scaling
  set adaptative time step scaling = 1.1

  # Time step independent of end time
  set time step independent of end time = true

  #---------------------------------------------------
  # Log file parameters
  #---------------------------------------------------
  # Log frequency
  set log frequency = 1

  # Display precision when writing to log
  set log precision = 6

  #---------------------------------------------------
  # Output file parameters
  #---------------------------------------------------
  # File output path
  set output path = ./

  # File output prefix
  set output name = out

  # The control for the output of the simulation results
  set output control = iteration

  # Output iteration frequency
  set output frequency = 1

  # Output time frequency
  set output time frequency = -1

  # List of specific output times
  set output times = -1

  # Output time interval
  set output time interval = 0, 1.7e308

  # Maximum number of vtu output files
  set group files = 1

  # Output the boundaries of the domain along with their ID
  set output boundaries = false

  # Subdivision of mesh cell in postprocessing
  set subdivision = 1

  #---------------------------------------------------
  # Explicit coupling constraint parameters
  #---------------------------------------------------
  # Set time step to respect the imposed capillary time-step ratio
  set adapt time step to respect CTR = false

  # Set targeted maximum capillary time-step ratio (Δt/Δt_σ)
  set max capillary time-step ratio = 1.0
end

• method: time-stepping method used. The available options are:

  • steady: steady-state simulation

  • steady_bdf: steady-state simulation using adjoint time stepping with a bdf1 scheme

  • bdf1: 1st order backward differentiation

  • bdf2: 2nd order backward differentiation

  • bdf3: 3rd order backward differentiation

  • sdirk22: 2nd order 2 stages singly diagonally implicit Runge-Kutta

  • sdirk33: 3rd order 3 stages singly diagonally implicit Runge-Kutta

Warning

For now, the SDIRK schemes are not supported by any physics other than Fluid Dynamics.

Steady-state simulation parameters

• number mesh adapt: number of mesh adaptations during the steady-state simulation.

• stop tolerance: tolerance at which the adjoint time stepping steady-state simulation (method = steady_bdf) stops. The adjoint time stepping will stop when the \(\mathcal{L}_2\) norm of the initial residual is lower than stop tolerance at the beginning of a time step.

BDF scheme parameters

• bdf startup method: scheme used to start a high order BDF scheme (2nd order and above). The available options are:

  • multiple step bdf: A lower order BDF scheme is used to start the simulation. For example, in the case of bdf3, the first step is done using bdf1, the second with bdf2 and the third and onward are done with bdf3.

  • initial solution: In this case, a time-dependent initial solution is provided and that initial solution is used to start the time stepping. This is mostly useful when using the method of manufactured solutions to establish the formal accuracy of the BDF time stepping schemes.

• startup time scaling: scaling factor used in the iterations necessary to startup the BDF schemes.

Note

SDIRK schemes are self-starting and do not require any additional parameter.

Transient simulations parameters

• time end: value of the time at which the simulation ends.

• time step: value of the time step.

• adapt time step to respect CFL: If set to true, the time step will evolve to ensure that the max cfl value is respected. The time step is updated with the minimum value between time step, max time step and the computed time step with max cfl.

• override time step on restart: controls if the time step should be overridden by the set value upon restart. If set to true, the time step will be set to the value of time step and the time-step value recorded at the last checkpoint will be overridden at the start of the simulation.

• max cfl: maximum value of the \(\text{CFL}\) condition number that can be reached during the simulation. This parameter is only used when set adapt time step to respect CFL = true. The \(N_{\mathrm{CFL}}\) is calculated as:

  \[N_{\mathrm{CFL}} = \max_q \frac{|\mathbf{u}_q| \Delta t} {h}\]

  where \(q\) the Gauss points and \(|\mathbf{u}_q|\) is the velocity at the Gauss points. Essentially, the maximum CFL is the max of the CFL evaluated at every Gauss point in the mesh.

• max time step: maximum time step value that can be reached during the simulation. It is useful when the problem of interest has an additional time-step constraint.

• adaptative time step scaling: rate of increase of the time step value. The new time step value is fixed by adaptative time step scaling * previous value of the time step.

Warning

max time step and adaptative time step scaling are only used when either adapt time step to respect CFL or adapt time step to respect CTR is set to true (adaptive time-stepping enabled). max time step enforces a strict upper bound to the time step, while adaptative time step scaling controls the adaptive time-stepping, by limiting the time-step variation from one time iteration to the following.

• time step independent of end time: this variable ensures that the time step of the simulation is always consistent at the end of the simulation. If one uses a time step that eventually leads exactly to the end time of the simulation this variable does not do anything. However, if adaptive time stepping is used or the end time is not exactly reached when using certain fixed time step, this flag ensures that the simulation does not change the last time step to reach the end time. For example, if your end time is 20, and you have a time step that leads to a last iteration until 20.1, all your results will be outputted until 20.1. If you wish to have exactly 20, you need to set this flag to false.

Log file parameters

• log frequency: frequency at which information is written in the terminal.

• log precision: number of significant digits used when writting in the terminal.

Paraview output file parameters

• output path: directory for the output files.

• output name: prefix for the Paraview output files (.pvd / .vtu / .pvtu)

  Important

  Lethe saves the simulation results in the Paraview format. For every iteration, one or more .vtu are produced, which are indexed by a single .pvtu file. A single .pvd file linking all iterations together is also generated. Use the open-source software Paraview to visualize them.

• output control: control for the output of the simulation results. The available options are:

  • iteration: results will be outputted at constant iteration frequency.

  • time : results will be outputted based on time parameters (specific times or time frequency). The results can also be outputted for certain time interval.

• output frequency: controls after which number of iterations the results are written. This parameter is only used when set output control = iteration.

  Tip

  If set output frequency = 0, no output file will be generated. This is the only way to prevent the generation of output files.

• output time frequency: controls the time frequency when the results are written, e.g., if set to 1, paraview files will be outputted every unit of time. This parameter is only used when set output control = time.

• output times: allows to specify specific times for the output of .pvd / .vtu files. This parameter is only used when set output control = time. As an example, one can output files only at 5 seconds, by setting set output times = 5 or at multiple specific times separating the values with commas: set output times = 5, 14.

  Warning

  Since it is possible that the times specified in the interval or in specific output times do not correspond to the time of specific iterations, Lethe will always write the Paraview files before and after the time specified. Furthermore, it is not possible to use both output times and output time frequency at the same time. For the output times to work, the value of output time frequency must be set to -1, which is the default value for the parameter.

• output time interval: Only writes the .pvd / .vtu files when the simulation time is within the closed interval defined by the output time interval. Default values are 0s and 1.7e308s. Used for both iteration and time output control.

• group files: number of .vtu files generated in a parallel simulation.

  Tip

  This parameter reduces the number of files generated when the simulation is run with a large number of processors. set group files = 1 ensures that a single .vtu file will be generated. In this case, the file is written using MPI IO functionalities.

  The value for this parameter should always be a compromise between keeping a low number of files but preventing excessive MPI communications. We have found that the default value of 1 does not have a significant impact except in very large simulations.

  Warning

  As soon as the size of the output .vtu files reaches 3 Gb, it is preferable to start splitting them into multiple smaller files as this may lead to corrupted files on some file systems.

• output boundaries: controls if the boundaries of the domain are written to a file. This will write additional .vtu files made of the contour of the domain.

  Tip

  This is particularly useful for the visualisation of 3D flows with obstacles or objects.

• subdivision: sub-division of the mesh cells to enable visualisation of high-order elements with Paraview.

  Tip

  Generally, we advise to use a subdivision level of \((n)\) for interpolation order of \(n\). For example, a Q2-Q1 interpolation could be visualized with set subdivision = 2.

Explicit coupling constraint parameters

• adapt time step to respect CTR: computes the capillary time-step constraint [1]:

  \[\Delta t_\sigma = \min_{x \in \Omega}\left(\sqrt{\frac{(\rho_0 + \rho_1) h^3}{2 \pi \sigma}}\right)\]

  where

  • \(\sigma\) is the surface tension coefficient;

  • \(\rho_0\) and \(\rho_1\) are respectively the densities of fluid \(0\) and \(1\), and;

  • \(h\) is the cell size.

  Note

  Here, we define the cell size \((h)\) as being the diameter of:

  • a disk with equivalent area in 2D, and;

  • a sphere with equivalent volume in 3D.

  and replaces the time step with the capillary time step \(\left(\Delta t_\text{CTR} = N_\text{CTR, max} \times \Delta t_\sigma\right)\) if the later is smaller than the current time step and max time step. \(N_\text{CTR, max}\) is the user-defined max capillary time-step ratio.

  This is used in the coupling of the Navier-Stokes equations with the VOF method to simulate multiphase flows with surface tension.

  Note

  When adapt time step to respect CFL is also enabled, the simulation time step takes the minimum value between time step, max time step, the time step computed with max cfl (\(\Delta t_\text{CFL}\)) and the imposed capillary time step.

  \[\Delta t_\text{new} = \min{\left(\Delta t, \Delta t_\text{max}, \Delta t_\text{CTR}, \Delta t_\text{CFL}\right)}\]

• max capillary time-step ratio: corresponds to the aimed ratio of the simulation time step over the capillary time-step constraint \(\left(\frac{\Delta t}{\Delta t_\sigma} \right)\). The time step is updated such that:

  \[\Delta t_\text{new} \leq N_\text{CTR, max} \, \Delta t_\sigma\]

  where \(N_\text{CTR, max}\) is the maximum capillary time-step ratio.

---

References

[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.