Understanding the Parameter file (.prm)

The documentation for the parameter files is currently under migration to the new Lethe documentation

1. Boundary conditions - Multiphysics
2. Mesh Adaptation Control
3. Restart
4. Non-Linear Solver Control
5. Linear Solver Control
6. Dynamic flow control
7. Interface Sharpening

Boundary conditions - Multiphysics

This subsection's purpose is defining the boundary conditions associated to multiphysic problems.

Heat Transfer

subsection boundary conditions heat transfer
  set number                  = 2
    subsection bc 0
	set type	      = temperature
        set value	      = 0
    end
    subsection bc 1
      set type		    = convection
      set h 		    = 10
      set Tinf	   	    = -13
    end
end

• number: This is the number of boundary conditions of the problem.

• type : This is the type of boundary condition been imposed. At the moment, choices are

  • temperature (Dirichlet BC), to impose a given temperature value at the boundary
  • convection (Robin BC) for cooling/heating, depending on the environment temperature at the boundary Tinf, with a given heat transfer coefficient h

• NB : by default, the boundary condition type is temperature with value = 0

Tracer

subsection boundary conditions tracer
  set number                  = 1
  subsection bc 0
        set type              = dirichlet
        subsection dirichlet
            set Function expression = x
        end
  end
end

• number: This is the number of boundary conditions of the problem.

• type : This is the type of boundary condition been imposed. At the moment, only dirichlet boundary conditions can be imposed for tracer.

Mesh Adaptation Control

This subsection controls the mesh adaptation method.

subsection mesh adaptation
  # Fraction of coarsened elements
  set fraction coarsening  = 0.05

  # Fraction of refined elements
  set fraction refinement  = 0.1

  # How the fraction of refinement/coarsening are interpreted
  # Choices are number or fraction 
  set fraction type        = number

  # Frequency of the mesh refinement
  set frequency            = 1

  # Maximum number of elements
  set max number elements  = 100000000

  # Maximum refinement level
  set max refinement level = 10

  # Minimum refinement level
  set min refinement level = 0

  # Type of mesh adaptation. Choices are  none, uniform or kelly.
  set type                 = none

  # Variable for kelly estimation. Choices are velocity, pressure or phase.
  set variable             = velocity
end

• Two type of mesh adaptation are available. The uniform mesh adaptation refines the mesh at every cell, whereas the kelly uses a kelly error estimator to decides which cell are refined.
• The fraction of cell that are refined and coarsened are controlled with the fraction refinement and fraction coarsening parameters. Note that a cell cannot be coarsened more than it's initial level. Consequently, adaptively refined simulations should start with a mesh as coarse as possible.
• The maximal and minimal refinement level reachable for a cell are controlled with the max refinement and min refinement parameters.
  • for deal.ii meshes, min refinement level should be equal to the initial refinement
  • for gmsh imported meshes, min refinement level = 0
  • for a good compromise between speed and precision, max refinement level should be set to 2 or 3 more than the min refinement level

If the option kelly is chosen, variables for use for the kelly estimation should be specified:

• velocity
• pressure
• phase (for multiphase flows)

Restart

This subsection controls the restart and checkpointing of the simulation.

subsection restart
  # Enable checkpointing
  set checkpoint = true

  # Enable restart from previous checkpoint
  set restart    = false

  # Prefix for the filename of checkpoints
  set filename   = restart

  # Frequency for checkpointing
  set frequency  = 1

end

• The checkpoint option enables (true) or disables (false) checkpointing.
• The restart option controls if the simulation will be restarted from a previous checkpoint. Turn to false for the first checkpoint creation. The simulation will start from the last checkpoint and will finish at the provided time end (see Simulation Control).
• The filename option fixes the prefix of all the checkpointing files. ⚠️ restart files are searched for in the output path specified in subsection simulation control
• The frequency controls the checkpointing frequency. Checkpointing is very intensive from an I/O point of view, consequently it should not be done at every iteration.

Non-Linear Solver Control

The Navier-Stokes equations (and other) are non-linear equation. This section controls the non-linear solver used within lethe.

subsection non-linear solver
  # Maximum number of Newton Iterations
  set max iterations     = 10

  # Non-linear solver that will be used. Choices is newton.
  set solver             = newton

  # Newton solver tolerance
  set tolerance          = 1e-6

  # Tolerance for the acceptation of the step
  set step tolerance     = 0.9

  # State whether from the non-linear solver should be printed Choices are
  # .
  set verbosity          = verbose
end

• Lethe currently has one solver for non-linear equations. The newton solver is a Newton-Raphson solver which recalculates the jacobian matrix at every iteration.
• The verbosity options enables the display of the residual at each non-linear iteration. This allow ones to monitor how the non-linear iterations are progressing.
• The step tolerance option controls how much the L2 norm of the residual must decrease for a non-linear step to be accepted. If the new_residual < old_residual * step tolerance, than a newton iteration is accepted. If this condition is not reached, then a theta weighting of the step is applied until this condition is reached.

Linear Solver Control

In these subsections, the control options of linear solvers are specified. These control options may include solution method, maximum number of iterations, tolerance, residual precision and preconditioner information.

Lethe currently supports three core solution strategy or method :

• GMRES solver + ILU preconditioning. This is set by method = gmres
• GMRES solver + AMG preconditioning. This is set by method = amg
• BiCGStab solver + ILU preconditioning. This is set by method = bicgstab

For all methods, a number of parameters to control the preconditioner can be set.

On coarse meshes, the gmres/bicgstab solver with ILU preconditioning is more efficient. As the number of mesh elements increase, the amg solver is the most efficient. Generally, at 1M elements, the amg solver always outperforms the gmres or bicgstab for 2D steady-state problems.

subsection linear solver
  # amg aggregation threshold
  set amg aggregation threshold                 = 1e-14

  # amg number of cycles
  set amg n cycles                              = 1

  # amg preconditioner ilu smoother/coarsener absolute tolerance
  set amg preconditioner ilu absolute tolerance = 1e-12

  # amg preconditioner ilu smoother/coarsener fill
  set amg preconditioner ilu fill               = 1

  # amg preconditioner ilu smoother/coarsener relative tolerance
  set amg preconditioner ilu relative tolerance = 1.00

  # amg smoother overlap
  set amg smoother overlap                      = 1

  # amg smoother sweeps
  set amg smoother sweeps                       = 2

  # amg w cycling. If this is set to true, W cycling is used. Otherwise, V
  # cycling is used.
  set amg w cycles                              = false

  # Ilu preconditioner tolerance
  set ilu preconditioner absolute tolerance     = 1e-6

  # Ilu preconditioner fill
  set ilu preconditioner fill                   = 1

  # Ilu relative tolerance
  set ilu preconditioner relative tolerance     = 1.00

  # Maximum solver iterations
  set max iters                                 = 1000

  # Maximum number of krylov vectors for GMRES solver
  set max krylov vectors                        = 30

  # The iterative solver for the linear system of equations. Choices are
  # . gmres is a GMRES iterative solver with ILU
  # preconditioning. bicgstab is a BICGSTAB iterative solver with ILU
  # preconditioning. amg is GMRES + AMG preconditioning with an ILU coarsener
  # and smoother. On coarse meshes, the gmres/bicgstab solver with ILU
  # preconditioning is more efficient. As the number of mesh elements
  # increase, the amg solver is the most efficient. Generally, at 1M elements,
  # the amg solver always outperforms the gmres or bicgstab
  set method                                    = gmres

  # Linear solver minimum residual
  set minimum residual                          = 1e-8

  # Linear solver residual
  set relative residual                         = 1e-3

  # State whether output from solver runs should be printed. Choices are
  # .
  set verbosity                                 = verbose
end

Dynamic flow control

This subsection's purpose is to enable a dynamic flow control. When a periodic boundary condition is set, the flow must be controlled at inlet. It calculates a Beta coefficient at each time step and may be added to a source term. If the chosen wall boundary to force the flow is at inlet, the volumetric flow rate targeted must be negative since outward normal vector is used. Therefore, if the chosen wall boundary is at outlet, volumetric flow rate must be positive.

subsection flow control
 # Enable the dynamic flow control
 set enable = true

 # Volumetric flow rate targeted (negative if at inlet)
 set volumetric flow rate = -91.75
 
 # Wall boundary where the flow is adjusted
 set boundary id = 0

 # Flow direction
 set flow direction = 0

 # Initial Beta coefficient
 set initial beta = 100
 
end

• The volumetric flow rate parameter set a flow rate where the algorithm will target at each time step. Important : when there is a periodic boundary, the wall boundary should be at inlet only and if the chosen wall boundary is at inlet, flow rate must be negative and vice versa.
• The boundary id parameter is the wall boundary where the flow rate intended is controlled. (inlet or outlet).
• The flow direction parameter set the absolute direction. 0 = x, 1 = y and 2 = z.
• The initial beta parameter set a initial beta coefficient that may speed up the convergence of the flow rate targeted. Some tests should be done to find a good initial beta coefficient.

Interface Sharpening

This subsection includes parameters related to the interface sharpening in VOF simulations of Lethe.

subsection interface sharpening
   set sharpening threshold   = 0.5
   set interface sharpness    = 2
   set sharpening frequency   = 10
end

• The sharpening threshold parameter defines the interface sharpening threshold that represents the mass conservation level. This parameter must be larger than 1 for interface sharpening. Choosing values less than 1 leads to interface smoothing instead of sharpening.
• The interface sharpness parameter defines the sharpness of the moving interface (parameter alpha in the interface sharpening model).
• The sharpening frequency parameter defines the VOF interface sharpening frequency.