LatticeBoltzmannProblem

Problem object to enable solving lattice Boltzmann problems

The problem object derived from TensorProblem (/TensorProblem.md) is used to solve Lattice Boltzmann simulations. It works in the same way as TensorProblem, with a few extra features. It adds stencil and boundary condition object and modifies the initialization and execution order in favor of LBM.

Overview

Problem driver specialized for Lattice Boltzmann simulations: manages stencils, distribution buffers, macroscopic fields, and substepping between collision and streaming. Provides access to LBM constants like c_s and time step for objects that require them.

Binary Media for Complex Geometries

The binary_media parameter enables simulation of flow through complex solid geometries (porous media, obstacles, etc.). It accepts an integer tensor buffer where:

  • Value 0**: Solid cell (closed cell) - no flow allowed, acts as a wall

  • Value 1**: Fluid cell (open cell) - normal flow

  • Value 2**: (Internal use) Fluid cell adjacent to solid boundary - automatically computed

Important Usage Notes

When using binary_media, boundary conditions must be specified for TWO distinct types of boundaries:

  1. Domain Edge Boundaries**: Use standard boundary specifiers (top, bottom, left, right, front, back) for the computational domain edges

  2. Internal Solid Boundaries**: Use boundary = wall for the solid obstacles/structures defined by binary_media

Example with Binary Media


[TensorComputes]
  [Initialize]
    [binary_media]
        type = ParsedCompute
        buffer = binary_media
        expression = '...' # expression that defined the media
        extra_symbols = true
        is_integer = true
    []
  []

  [Boundary]
    # Domain edge boundary (top wall of domain)
    [top]
      type = LBMBounceBack
      buffer = f
      f_old = fpc
      boundary = top
    []

    # Internal solid boundary (obstacle surface)
    [obstacle_wall]
      type = LBMBounceBack
      buffer = f
      f_old = fpc
      boundary = wall  # Critical: use 'wall' for binary media obstacles
    []
  []
[]

[Problem]
  type = LatticeBoltzmannProblem
  binary_media = binary_media
  substeps = 100
[]

Without binary_media, all cells default to value 1 (fluid), and only domain edge boundaries need to be specified.

Example Input File Syntax

[Problem<<<{"href": "../../syntax/Problem/index.html"}>>>]
  type = LatticeBoltzmannProblem
  substeps = 10
[]
(test/tests/lbm/channel2D.i)

Input Parameters

  • binary_mediaInteger tensor buffer defining solid/fluid regions for complex geometries. Values: 0 = solid (closed cell, no flow), 1 = fluid (open cell, flow allowed). Internal solid boundaries must use 'boundary = wall' in boundary conditions. Domain edge boundaries (top/bottom/left/right/front/back) are specified separately.

    C++ Type:std::string

    Controllable:No

    Description:Integer tensor buffer defining solid/fluid regions for complex geometries. Values: 0 = solid (closed cell, no flow), 1 = fluid (open cell, flow allowed). Internal solid boundaries must use 'boundary = wall' in boundary conditions. Domain edge boundaries (top/bottom/left/right/front/back) are specified separately.

  • blockANY_BLOCK_ID List of subdomains for kernel coverage and material coverage checks. Setting this parameter is equivalent to setting 'kernel_coverage_block_list' and 'material_coverage_block_list' as well as using 'ONLY_LIST' as the coverage check mode.

    Default:ANY_BLOCK_ID

    C++ Type:std::vector<SubdomainName>

    Controllable:No

    Description:List of subdomains for kernel coverage and material coverage checks. Setting this parameter is equivalent to setting 'kernel_coverage_block_list' and 'material_coverage_block_list' as well as using 'ONLY_LIST' as the coverage check mode.

  • linear_sys_namesThe linear system names

    C++ Type:std::vector<LinearSystemName>

    Controllable:No

    Description:The linear system names

  • log_interval1Interval for logging LBM substep information

    Default:1

    C++ Type:unsigned int

    Controllable:No

    Description:Interval for logging LBM substep information

  • print_debug_outputFalseShow Tensor specific debug outputs

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Show Tensor specific debug outputs

  • regard_general_exceptions_as_errorsFalseIf we catch an exception during residual/Jacobian evaluaton for which we don't have specific handling, immediately error instead of allowing the time step to be cut

    Default:False

    C++ Type:bool

    Controllable:No

    Description:If we catch an exception during residual/Jacobian evaluaton for which we don't have specific handling, immediately error instead of allowing the time step to be cut

  • scalar_constant_namesScalar constant names

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:Scalar constant names

  • scalar_constant_valuesScalar constant values

    C++ Type:std::vector<double>

    Unit:(no unit assumed)

    Controllable:No

    Description:Scalar constant values

  • solveTrueWhether or not to actually solve the Nonlinear system. This is handy in the case that all you want to do is execute AuxKernels, Transfers, etc. without actually solving anything

    Default:True

    C++ Type:bool

    Controllable:Yes

    Description:Whether or not to actually solve the Nonlinear system. This is handy in the case that all you want to do is execute AuxKernels, Transfers, etc. without actually solving anything

  • spectral_solve_substeps1How many substeps to divide the spectral solve for each MOOSE timestep into.

    Default:1

    C++ Type:unsigned int

    Controllable:No

    Description:How many substeps to divide the spectral solve for each MOOSE timestep into.

  • substeps1Number of LBM iterations for every MOOSE timestep

    Default:1

    C++ Type:unsigned int

    Controllable:No

    Description:Number of LBM iterations for every MOOSE timestep

  • tolerance1e-10LBM convergence tolerance

    Default:1e-10

    C++ Type:double

    Unit:(no unit assumed)

    Controllable:No

    Description:LBM convergence tolerance

Optional Parameters

  • allow_initial_conditions_with_restartFalseTrue to allow the user to specify initial conditions when restarting. Initial conditions can override any restarted field

    Default:False

    C++ Type:bool

    Controllable:No

    Description:True to allow the user to specify initial conditions when restarting. Initial conditions can override any restarted field

  • force_restartFalseEXPERIMENTAL: If true, a sub_app may use a restart file instead of using of using the master backup file

    Default:False

    C++ Type:bool

    Controllable:No

    Description:EXPERIMENTAL: If true, a sub_app may use a restart file instead of using of using the master backup file

  • restart_file_baseFile base name used for restart (e.g. / or /LATEST to grab the latest file available)

    C++ Type:FileNameNoExtension

    Controllable:No

    Description:File base name used for restart (e.g. / or /LATEST to grab the latest file available)

Restart Parameters

  • allow_invalid_solutionFalseSet to true to allow convergence even though the solution has been marked as 'invalid'

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Set to true to allow convergence even though the solution has been marked as 'invalid'

  • immediately_print_invalid_solutionFalseWhether or not to report invalid solution warnings at the time the warning is produced instead of after the calculation

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Whether or not to report invalid solution warnings at the time the warning is produced instead of after the calculation

  • show_invalid_solution_consoleTrueSet to true to show the invalid solution occurrence summary in console

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Set to true to show the invalid solution occurrence summary in console

Solution Validity Control Parameters

  • boundary_restricted_elem_integrity_checkTrueSet to false to disable checking of boundary restricted elemental object variable dependencies, e.g. are the variable dependencies defined on the selected boundaries?

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Set to false to disable checking of boundary restricted elemental object variable dependencies, e.g. are the variable dependencies defined on the selected boundaries?

  • boundary_restricted_node_integrity_checkTrueSet to false to disable checking of boundary restricted nodal object variable dependencies, e.g. are the variable dependencies defined on the selected boundaries?

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Set to false to disable checking of boundary restricted nodal object variable dependencies, e.g. are the variable dependencies defined on the selected boundaries?

  • check_uo_aux_stateFalseTrue to turn on a check that no state presents during the evaluation of user objects and aux kernels

    Default:False

    C++ Type:bool

    Controllable:No

    Description:True to turn on a check that no state presents during the evaluation of user objects and aux kernels

  • error_on_jacobian_nonzero_reallocationFalseThis causes PETSc to error if it had to reallocate memory in the Jacobian matrix due to not having enough nonzeros

    Default:False

    C++ Type:bool

    Controllable:No

    Description:This causes PETSc to error if it had to reallocate memory in the Jacobian matrix due to not having enough nonzeros

  • fv_bcs_integrity_checkTrueSet to false to disable checking of overlapping Dirichlet and Flux BCs and/or multiple DirichletBCs per sideset

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Set to false to disable checking of overlapping Dirichlet and Flux BCs and/or multiple DirichletBCs per sideset

  • kernel_coverage_block_listList of subdomains for kernel coverage check. The meaning of this list is controlled by the parameter 'kernel_coverage_check' (whether this is the list of subdomains to be checked, not to be checked or not taken into account).

    C++ Type:std::vector<SubdomainName>

    Controllable:No

    Description:List of subdomains for kernel coverage check. The meaning of this list is controlled by the parameter 'kernel_coverage_check' (whether this is the list of subdomains to be checked, not to be checked or not taken into account).

  • kernel_coverage_checkTRUEControls, if and how a kernel subdomain coverage check is performed. With 'TRUE' or 'ON' all subdomains are checked (the default). Setting 'FALSE' or 'OFF' will disable the check for all subdomains. To exclude a predefined set of subdomains 'SKIP_LIST' is to be used, while the subdomains to skip are to be defined in the parameter 'kernel_coverage_block_list'. To limit the check to a list of subdomains, 'ONLY_LIST' is to be used (again, using the parameter 'kernel_coverage_block_list').

    Default:TRUE

    C++ Type:MooseEnum

    Options:FALSE, TRUE, OFF, ON, SKIP_LIST, ONLY_LIST

    Controllable:No

    Description:Controls, if and how a kernel subdomain coverage check is performed. With 'TRUE' or 'ON' all subdomains are checked (the default). Setting 'FALSE' or 'OFF' will disable the check for all subdomains. To exclude a predefined set of subdomains 'SKIP_LIST' is to be used, while the subdomains to skip are to be defined in the parameter 'kernel_coverage_block_list'. To limit the check to a list of subdomains, 'ONLY_LIST' is to be used (again, using the parameter 'kernel_coverage_block_list').

  • material_coverage_block_listList of subdomains for material coverage check. The meaning of this list is controlled by the parameter 'material_coverage_check' (whether this is the list of subdomains to be checked, not to be checked or not taken into account).

    C++ Type:std::vector<SubdomainName>

    Controllable:No

    Description:List of subdomains for material coverage check. The meaning of this list is controlled by the parameter 'material_coverage_check' (whether this is the list of subdomains to be checked, not to be checked or not taken into account).

  • material_coverage_checkTRUEControls, if and how a material subdomain coverage check is performed. With 'TRUE' or 'ON' all subdomains are checked (the default). Setting 'FALSE' or 'OFF' will disable the check for all subdomains. To exclude a predefined set of subdomains 'SKIP_LIST' is to be used, while the subdomains to skip are to be defined in the parameter 'material_coverage_block_list'. To limit the check to a list of subdomains, 'ONLY_LIST' is to be used (again, using the parameter 'material_coverage_block_list').

    Default:TRUE

    C++ Type:MooseEnum

    Options:FALSE, TRUE, OFF, ON, SKIP_LIST, ONLY_LIST

    Controllable:No

    Description:Controls, if and how a material subdomain coverage check is performed. With 'TRUE' or 'ON' all subdomains are checked (the default). Setting 'FALSE' or 'OFF' will disable the check for all subdomains. To exclude a predefined set of subdomains 'SKIP_LIST' is to be used, while the subdomains to skip are to be defined in the parameter 'material_coverage_block_list'. To limit the check to a list of subdomains, 'ONLY_LIST' is to be used (again, using the parameter 'material_coverage_block_list').

  • material_dependency_checkTrueSet to false to disable material dependency check

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Set to false to disable material dependency check

  • skip_nl_system_checkTrueTrue to skip the NonlinearSystem check for work to do (e.g. Make sure that there are variables to solve for).

    Default:True

    C++ Type:bool

    Controllable:No

    Description:True to skip the NonlinearSystem check for work to do (e.g. Make sure that there are variables to solve for).

Simulation Checks Parameters

  • control_tagsAdds user-defined labels for accessing object parameters via control logic.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:Adds user-defined labels for accessing object parameters via control logic.

  • default_ghostingFalseWhether or not to use libMesh's default amount of algebraic and geometric ghosting

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Whether or not to use libMesh's default amount of algebraic and geometric ghosting

  • enableTrueSet the enabled status of the MooseObject.

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Set the enabled status of the MooseObject.

Advanced Parameters

  • extra_tag_matricesExtra matrices to add to the system that can be filled by objects which compute residuals and Jacobians (Kernels, BCs, etc.) by setting tags on them. The outer index is for which nonlinear system the extra tag vectors should be added for

    C++ Type:std::vector<std::vector<TagName>>

    Controllable:No

    Description:Extra matrices to add to the system that can be filled by objects which compute residuals and Jacobians (Kernels, BCs, etc.) by setting tags on them. The outer index is for which nonlinear system the extra tag vectors should be added for

  • extra_tag_solutionsExtra solution vectors to add to the system that can be used by objects for coupling variable values stored in them.

    C++ Type:std::vector<TagName>

    Controllable:No

    Description:Extra solution vectors to add to the system that can be used by objects for coupling variable values stored in them.

  • extra_tag_vectorsExtra vectors to add to the system that can be filled by objects which compute residuals and Jacobians (Kernels, BCs, etc.) by setting tags on them. The outer index is for which nonlinear system the extra tag vectors should be added for

    C++ Type:std::vector<std::vector<TagName>>

    Controllable:No

    Description:Extra vectors to add to the system that can be filled by objects which compute residuals and Jacobians (Kernels, BCs, etc.) by setting tags on them. The outer index is for which nonlinear system the extra tag vectors should be added for

  • not_zeroed_tag_vectorsExtra vector tags which the sytem will not zero when other vector tags are zeroed. The outer index is for which nonlinear system the extra tag vectors should be added for

    C++ Type:std::vector<std::vector<TagName>>

    Controllable:No

    Description:Extra vector tags which the sytem will not zero when other vector tags are zeroed. The outer index is for which nonlinear system the extra tag vectors should be added for

Contribution To Tagged Field Data Parameters

  • identify_variable_groups_in_nlTrueWhether to identify variable groups in nonlinear systems. This affects dof ordering

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Whether to identify variable groups in nonlinear systems. This affects dof ordering

  • ignore_zeros_in_jacobianFalseDo not explicitly store zero values in the Jacobian matrix if true

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Do not explicitly store zero values in the Jacobian matrix if true

  • nl_sys_namesnl0 The nonlinear system names

    Default:nl0

    C++ Type:std::vector<NonlinearSystemName>

    Controllable:No

    Description:The nonlinear system names

  • previous_nl_solution_requiredFalseTrue to indicate that this calculation requires a solution vector for storing the previous nonlinear iteration.

    Default:False

    C++ Type:bool

    Controllable:No

    Description:True to indicate that this calculation requires a solution vector for storing the previous nonlinear iteration.

  • restore_original_nonzero_patternFalseWhether we should reset matrix memory for every Jacobian evaluation. This option is useful if the sparsity pattern is constantly changing and you are using hash table assembly or if you wish to continually restore the matrix to the originally preallocated sparsity pattern computed by relationship managers.

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Whether we should reset matrix memory for every Jacobian evaluation. This option is useful if the sparsity pattern is constantly changing and you are using hash table assembly or if you wish to continually restore the matrix to the originally preallocated sparsity pattern computed by relationship managers.

  • use_hash_table_matrix_assemblyFalseWhether to assemble matrices using hash tables instead of preallocating matrix memory. This can be a good option if the sparsity pattern changes throughout the course of the simulation.

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Whether to assemble matrices using hash tables instead of preallocating matrix memory. This can be a good option if the sparsity pattern changes throughout the course of the simulation.

  • use_nonlinearTrueDetermines whether to use a Nonlinear vs a Eigenvalue system (Automatically determined based on executioner)

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Determines whether to use a Nonlinear vs a Eigenvalue system (Automatically determined based on executioner)

Nonlinear System(S) Parameters

  • near_null_space_dimension0The dimension of the near nullspace

    Default:0

    C++ Type:unsigned int

    Controllable:No

    Description:The dimension of the near nullspace

  • null_space_dimension0The dimension of the nullspace

    Default:0

    C++ Type:unsigned int

    Controllable:No

    Description:The dimension of the nullspace

  • transpose_null_space_dimension0The dimension of the transpose nullspace

    Default:0

    C++ Type:unsigned int

    Controllable:No

    Description:The dimension of the transpose nullspace

Null Space Removal Parameters

  • parallel_barrier_messagingFalseDisplays messaging from parallel barrier notifications when executing or transferring to/from Multiapps (default: false)

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Displays messaging from parallel barrier notifications when executing or transferring to/from Multiapps (default: false)

  • verbose_multiappsFalseSet to True to enable verbose screen printing related to MultiApps

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Set to True to enable verbose screen printing related to MultiApps

  • verbose_restoreFalseSet to True to enable verbose screen printing related to solution restoration

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Set to True to enable verbose screen printing related to solution restoration

  • verbose_setupfalseSet to 'true' to have the problem report on any object created. Set to 'extra' to also display all parameters.

    Default:false

    C++ Type:MooseEnum

    Options:false, true, extra

    Controllable:No

    Description:Set to 'true' to have the problem report on any object created. Set to 'extra' to also display all parameters.

Verbosity Parameters

Input Files