DomainAction

Set up the domain and compute devices.

Overview

DomainAction configures the FFT simulation domain and compute devices, and wires up the minimal runtime needed for Marlin problems:

Sets problem dimension and grid resolution ("dim", "nx", "ny", "nz") and computes grid spacing from "xmin"/"xmax", "ymin"/"ymax", "zmin"/"zmax".
Builds real-space axes (cell-centered) and reciprocal-space axes (via fftfreq/rfftfreq, scaled by 2π) and exposes helper accessors used throughout Marlin.
Partitions the domain for parallel execution based on "parallel_mode" and optional "device_names"/"device_weights".
Creates a matching mesh automatically (optional) using "mesh_mode" and adds a DomainMeshGenerator.
Creates a TensorProblem by default if one is not provided, enabling all Marlin objects to run.

Key concepts and behavior

Dimension and grids: The domain is a structured grid. Grid spacing is (max-min)/n per axis; axes are built at cell centers. The reciprocal axes use Torch FFT frequency helpers and represent angular wavenumbers.
Shapes and sizes: Methods such as getShape(), getReciprocalShape(), getGridSize(), getReciprocalGridSize() provide local/global extents used by tensor computes and outputs.
On-demand tensors: getXGrid(), getKGrid(), and getKSquare() lazily build coordinate arrays for the local partition when first requested.
FFT helpers: fft()/ifft() dispatch to serial or parallel implementations depending on parallel_mode. In serial, 1D/2D/3D transforms call torch::fft::rfft{,2,n} and inverse irfft{,2,n} with appropriate dimension lists. Slab/pencil modes target distributed FFTs (pencil not yet implemented).
Reductions: sum() and average() reduce over the spatial dimensions. Note: reductions are implemented in serial; MPI reduction is not yet provided.
Device and precision: If "device_names" are given, Marlin assigns a device per local host-rank and sets Torch floating precision with "floating_precision".

Mesh generation and problem creation

"mesh_mode" = DOMAIN generates a mesh with one element per grid cell; DUMMY creates a single-element mesh spanning the domain; MANUAL disables automatic mesh creation (user supplies [Mesh]). When mesh creation is enabled, DomainAction injects SetupMeshAction and adds a DomainMeshGenerator with consistent domain bounds and resolution.
If no Problem is provided, DomainAction creates a TensorProblem during create_problem_custom to ensure Marlin components can run.

Parallel partitioning modes

note:Work in progress

Parallel decomposition is a work in progress and not ready for production use!

NONE: No decomposition; requires running in serial (comm.size() == 1).
FFT_SLAB: Slab decomposition for 2D/3D. Real space is partitioned into X–Z slabs stacked along Y; in Fourier space Y–Z slabs stacked along X. Requires one all-to-all per FFT.
FFT_PENCIL: Intended for 3D pencil decomposition with two many-to-many communications per FFT. Not implemented yet.

Device assignment and weights

"device_names": Names in Torch syntax (e.g., "cuda:0", "cuda:1", "cpu"). For MPI runs, each process determines its local host-rank and picks a device by index (modulo the list length).
"device_weights": Optional relative speeds to influence partitioning balance across local ranks. If omitted, weights default proportionally to the number of devices.
"floating_precision": Selects DEVICE_DEFAULT, SINGLE, or DOUBLE precision for Torch tensors on the chosen device.

Example Input File Syntax

Basic 2D domain with a dummy mesh and serial execution

[Domain<<<{"href": "../../syntax/Domain/index.html"}>>>]
  dim<<<{"description": "Problem dimension"}>>> = 2
  nx<<<{"description": "Number of elements in the X direction"}>>> = 10
  ny<<<{"description": "Number of elements in the Y direction"}>>> = 10
  mesh_mode<<<{"description": "Mesh generation mode."}>>> = DUMMY
  parallel_mode<<<{"description": "Parallelization mode."}>>> = REAL_SPACE
  periodic_directions<<<{"description": "Periodic directions of the simulation cell (controls halo exchange wrap-around)."}>>> = 'X Y'
[]

3D domain with a dummy mesh

[Domain<<<{"href": "../../syntax/Domain/index.html"}>>>]
  dim<<<{"description": "Problem dimension"}>>> = 3
  nx<<<{"description": "Number of elements in the X direction"}>>> = 10
  ny<<<{"description": "Number of elements in the Y direction"}>>> = 10
  nz<<<{"description": "Number of elements in the Z direction"}>>> = 10
  mesh_mode<<<{"description": "Mesh generation mode."}>>> = DUMMY
  parallel_mode<<<{"description": "Parallelization mode."}>>> = REAL_SPACE
  periodic_directions<<<{"description": "Periodic directions of the simulation cell (controls halo exchange wrap-around)."}>>> = 'X Y Z'
[]

Parallel slab decomposition with explicit device selection and weights

[Domain<<<{"href": "../../syntax/Domain/index.html"}>>>]
  device_names<<<{"description": "Compute devices to run on."}>>> = "cuda:1 cuda:0 cpu"
  device_weights<<<{"description": "Device weights (or speeds) to influence the partitioning."}>>> = "10 10 1"

  parallel_mode<<<{"description": "Parallelization mode."}>>> = FFT_SLAB

  dim<<<{"description": "Problem dimension"}>>> = 2
  nx<<<{"description": "Number of elements in the X direction"}>>> = 400
  ny<<<{"description": "Number of elements in the Y direction"}>>> = 400
  xmax<<<{"description": "Upper X Coordinate of the generated mesh"}>>> = '${fparse pi*2*30}'
  ymax<<<{"description": "Upper Y Coordinate of the generated mesh"}>>> = '${fparse pi*2*30}'
[]

Set up the domain and compute devices.

Input Parameters

dimProblem dimension
C++ Type:MooseEnum
Options:1, 2, 3
Controllable:No
Description:Problem dimension

Required Parameters

active__all__ If specified only the blocks named will be visited and made active
Default:__all__
C++ Type:std::vector<std::string>
Controllable:No
Description:If specified only the blocks named will be visited and made active
debugFalseEnable additional debugging and diagnostics, such a checking for initialized tensors.
Default:False
C++ Type:bool
Controllable:No
Description:Enable additional debugging and diagnostics, such a checking for initialized tensors.
device_namesCompute devices to run on.
C++ Type:std::vector<std::string>
Controllable:No
Description:Compute devices to run on.
device_weightsDevice weights (or speeds) to influence the partitioning.
C++ Type:std::vector<unsigned int>
Controllable:No
Description:Device weights (or speeds) to influence the partitioning.
floating_precisionDEVICE_DEFAULTFloating point precision.
Default:DEVICE_DEFAULT
C++ Type:MooseEnum
Options:DEVICE_DEFAULT, SINGLE, DOUBLE
Controllable:No
Description:Floating point precision.
gpu_aware_mpiFalseEnable GPU-aware MPI. If true, tensors will not be copied to the CPU before MPI communication. Requires a CUDA-aware MPI implementation.
Default:False
C++ Type:bool
Controllable:No
Description:Enable GPU-aware MPI. If true, tensors will not be copied to the CPU before MPI communication. Requires a CUDA-aware MPI implementation.
inactiveIf specified blocks matching these identifiers will be skipped.
C++ Type:std::vector<std::string>
Controllable:No
Description:If specified blocks matching these identifiers will be skipped.
mesh_modeDUMMYMesh generation mode.
Default:DUMMY
C++ Type:MooseEnum
Options:DUMMY, DOMAIN, MANUAL
Controllable:No
Description:Mesh generation mode.
nx1Number of elements in the X direction
Default:1
C++ Type:unsigned int
Controllable:No
Description:Number of elements in the X direction
ny1Number of elements in the Y direction
Default:1
C++ Type:unsigned int
Controllable:No
Description:Number of elements in the Y direction
nz1Number of elements in the Z direction
Default:1
C++ Type:unsigned int
Controllable:No
Description:Number of elements in the Z direction
parallel_modeFFT_AUTOParallelization mode.
Default:FFT_AUTO
C++ Type:MooseEnum
Options:NONE, REAL_SPACE, FFT_SLAB, FFT_PENCIL, FFT_AUTO
Controllable:No
Description:Parallelization mode.
periodic_directionsPeriodic directions of the simulation cell (controls halo exchange wrap-around).
C++ Type:MultiMooseEnum
Options:X, Y, Z
Controllable:No
Description:Periodic directions of the simulation cell (controls halo exchange wrap-around).
xmax1Upper X Coordinate of the generated mesh
Default:1
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Upper X Coordinate of the generated mesh
xmin0Lower X Coordinate of the generated mesh
Default:0
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Lower X Coordinate of the generated mesh
ymax1Upper Y Coordinate of the generated mesh
Default:1
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Upper Y Coordinate of the generated mesh
ymin0Lower Y Coordinate of the generated mesh
Default:0
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Lower Y Coordinate of the generated mesh
zmax1Upper Z Coordinate of the generated mesh
Default:1
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Upper Z Coordinate of the generated mesh
zmin0Lower Z Coordinate of the generated mesh
Default:0
C++ Type:double
Unit:(no unit assumed)
Controllable:No
Description:Lower Z Coordinate of the generated mesh

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

Advanced Parameters

Notes and Limitations

"parallel_mode" = NONE requires a single-process run.
FFT_PENCIL is declared but not implemented; prefer FFT_SLAB for distributed runs.
sum()/average() use local reductions only; parallel reductions are not yet available.
When "device_names" are omitted in MPI runs, the action aborts with an error to avoid ambiguous device assignment.

DomainMeshGenerator: Mesh generator added automatically when mesh_mode != MANUAL.
TensorProblem: Created by default if the user does not provide a [Problem] compatible with Marlin.

(test/tests/lbm/channel2D.i)

[Domain]
  dim = 2
  nx = 10
  ny = 10
  mesh_mode = DUMMY
  parallel_mode = REAL_SPACE
  periodic_directions = 'X Y'
[]

[Stencil]
  [d2q9]
    type = LBMD2Q9
  []
[]

[TensorBuffers]
  [f]
    type = LBMTensorBuffer
    buffer_type = df
  []
  [feq]
    type = LBMTensorBuffer
    buffer_type = df
  []
  [fpc]
    type = LBMTensorBuffer
    buffer_type = df
  []
  [velocity]
    type=LBMTensorBuffer
    buffer_type = mv
  []
  [density]
    type=LBMTensorBuffer
    buffer_type = ms
  []
  [speed]
    type=LBMTensorBuffer
    buffer_type = ms
  []
[]

[TensorComputes]
  [Initialize]
    [initial_density]
      type = LBMConstantTensor
      buffer = density
      constants = 1.0
    []
    [initial_velocity]
      type = LBMConstantTensor
      buffer = velocity
      constants = '0.0 0.0'
    []
    [initial_equilibrium]
      type = LBMEquilibrium
      buffer = feq
      bulk = density
      velocity = velocity
    []
    [initial_distribution]
      type = LBMEquilibrium
      buffer = f
      bulk = density
      velocity = velocity
    []
    [initial_distribution_pc]
      type = LBMEquilibrium
      buffer = fpc
      bulk = density
      velocity = velocity
    []
  []
  [Solve]
    [equilibrium]
      type=LBMEquilibrium
      buffer = feq
      bulk = density
      velocity = velocity
    []
    [collision]
      type=LBMBGKCollision
      buffer = fpc
      f = f
      feq = feq
      tau0 = 1.0
    []
    [density]
      type = LBMComputeDensity
      buffer = density
      f = f
    []
    [velocity]
      type = LBMComputeVelocity
      buffer = velocity
      f = f
      rho = density
      add_body_force = true
      body_force_x = 0.0001
    []
    [speed]
      type = LBMComputeVelocityMagnitude
      buffer = speed
      velocity = velocity
    []
    [residual]
      type = LBMComputeResidual
      buffer = speed
      speed = speed
    []
  []
  [Boundary]
    [top]
      type = LBMBounceBack
      buffer = f
      f_old = fpc
      boundary = top
    []
    [bottom]
      type = LBMBounceBack
      buffer = f
      f_old = fpc
      boundary = bottom
    []
  []
[]

[TensorSolver]
  type = LBMStream
  buffer = f
  f_old = fpc
[]

[Problem]
  type = LatticeBoltzmannProblem
  substeps = 10
[]

[Postprocessors]
  [velocity_min]
    type = TensorExtremeValuePostprocessor
    buffer = velocity
    value_type = MIN
  []
  [velocity_max]
    type = TensorExtremeValuePostprocessor
    buffer = velocity
    value_type = MAX
  []
  [speed_min]
    type = TensorExtremeValuePostprocessor
    buffer = speed
    value_type = MIN
  []
  [speed_max]
    type = TensorExtremeValuePostprocessor
    buffer = speed
    value_type = MAX
  []
  [density_min]
    type = TensorExtremeValuePostprocessor
    buffer = density
    value_type = MIN
  []
  [densty_max]
    type = TensorExtremeValuePostprocessor
    buffer = density
    value_type = MAX
  []
[]

[Executioner]
  type = Transient
  num_steps = 11
[]

[Outputs]
  file_base = channel2D
  csv = true
[]

(test/tests/lbm/channel3D.i)

[Domain]
  dim = 3
  nx = 10
  ny = 10
  nz = 10
  mesh_mode = DUMMY
  parallel_mode = REAL_SPACE
  periodic_directions = 'X Y Z'
[]

[Stencil]
  [d3q19]
    type = LBMD3Q19
  []
[]

[TensorBuffers]
  [f]
    type = LBMTensorBuffer
    buffer_type = df
  []
  [feq]
    type = LBMTensorBuffer
    buffer_type = df
  []
  [fpc]
    type = LBMTensorBuffer
    buffer_type = df
  []
  [velocity]
    type=LBMTensorBuffer
    buffer_type = mv
  []
  [density]
    type=LBMTensorBuffer
    buffer_type = ms
  []
  [speed]
    type=LBMTensorBuffer
    buffer_type = ms
  []
[]

[TensorComputes]
  [Initialize]
    [initial_density]
      type = LBMConstantTensor
      buffer = density
      constants = 1.0
    []
    [initial_velocity]
      type = LBMConstantTensor
      buffer = velocity
      constants = '0.0 0.0 0.0'
    []
    [initial_equilibrium]
      type = LBMEquilibrium
      buffer = feq
      bulk = density
      velocity = velocity
    []
    [initial_distribution]
      type = LBMEquilibrium
      buffer = f
      bulk = density
      velocity = velocity
    []
    [initial_distribution_pc]
      type = LBMEquilibrium
      buffer = fpc
      bulk = density
      velocity = velocity
    []
  []
  [Solve]
    [equilibrium]
      type=LBMEquilibrium
      buffer = feq
      bulk = density
      velocity = velocity
    []
    [collision]
      type=LBMBGKCollision
      buffer = fpc
      f = f
      feq = feq
      tau0 = 1.0
    []
    [density]
      type = LBMComputeDensity
      buffer = density
      f = f
    []
    [velocity]
      type = LBMComputeVelocity
      buffer = velocity
      f = f
      rho = density
      add_body_force = true
      body_force_x = 0.0001
    []
    [speed]
      type = LBMComputeVelocityMagnitude
      buffer = speed
      velocity = velocity
    []
    [residual]
      type = LBMComputeResidual
      buffer = speed
      speed = speed
    []
  []
  [Boundary]
    [top]
      type = LBMBounceBack
      buffer = f
      f_old = fpc
      boundary = top
    []
    [bottom]
      type = LBMBounceBack
      buffer = f
      f_old = fpc
      boundary = bottom
    []
  []
[]

[TensorSolver]
  type = LBMStream
  buffer = f
  f_old = fpc
[]

[Problem]
  type = LatticeBoltzmannProblem
  substeps = 10
[]

[Postprocessors]
  [velocity_min]
    type = TensorExtremeValuePostprocessor
    buffer = velocity
    value_type = MIN
  []
  [velocity_max]
    type = TensorExtremeValuePostprocessor
    buffer = velocity
    value_type = MAX
  []
  [speed_min]
    type = TensorExtremeValuePostprocessor
    buffer = speed
    value_type = MIN
  []
  [speed_max]
    type = TensorExtremeValuePostprocessor
    buffer = speed
    value_type = MAX
  []
  [density_min]
    type = TensorExtremeValuePostprocessor
    buffer = density
    value_type = MIN
  []
  [densty_max]
    type = TensorExtremeValuePostprocessor
    buffer = density
    value_type = MAX
  []
[]

[Executioner]
  type = Transient
  num_steps = 11
[]

[Outputs]
  file_base = channel3D
  csv = true
[]

(test/tests/tensor_compute/parallel.i)

[Domain]
  device_names = "cuda:1 cuda:0 cpu"
  device_weights = "10 10 1"

  parallel_mode = FFT_SLAB

  dim = 2
  nx = 400
  ny = 400
  xmax = ${fparse pi*2*30}
  ymax = ${fparse pi*2*30}
[]


# [Mesh]
#   type = GeneratedMesh
#   dim =1
# []


[TensorBuffers]
  [psi]
    # map_to_aux_variable = psi
  []
  [psibar]
  []
  [psi3]
  []
  [psi3bar]
  []
  # constant tensors
  [linear]
  []

  # output
  [filter]
    # map_to_aux_variable = filter
  []
  [filterbar]
  []
[]

[AuxVariables]
  [psi]
  []
  [filter]
  []
[]

[TensorComputes]
  [Initialize]
    [psi]
      type = RandomTensor
      buffer = psi
      min = 0
      max = 0.07
    []
    [linear]
      type = SwiftHohenbergLinear
      buffer = linear
      alpha = 1
      r = 0.025
    []
  []

  [Solve]
    [psi3]
      type = ParsedCompute
      buffer = psi3
      expression = "0.20*psi^2-psi^3"
      inputs = psi
    []
    [psibar]
      type = ForwardFFT
      buffer = psibar
      input = psi
    []
    [psi3bar]
      type = ForwardFFT
      buffer = psi3bar
      input = psi3
    []
  []

  [Postprocess]
    [low_pass]
      type = ParsedCompute
      buffer = filterbar
      extra_symbols = true
      expression = 'psibar * exp(-k2*10)'
      inputs = psibar
    []
    [filter]
      type = InverseFFT
      buffer = filter
      input = filterbar
    []
  []
[]

[TensorTimeIntegrators]
  [c]
    type = FFTSemiImplicit
    buffer = psi
    reciprocal_buffer = psibar
    linear_reciprocal = linear
    nonlinear_reciprocal = psi3bar
  []
[]

[Problem]
  type = TensorProblem
  spectral_solve_substeps = 1000
[]

[Executioner]
  type = Transient
  num_steps = 300
  [TimeStepper]
    type = IterationAdaptiveDT
    growth_factor = 1.2
    dt = 10
  []
  dtmax = 1000
[]

[Postprocessors]
  [min_psi]
    type = TensorExtremeValuePostprocessor
    buffer = psi
    value_type = MIN
    execute_on = 'TIMESTEP_END'
  []
  [max_psi]
    type = TensorExtremeValuePostprocessor
    buffer = psi
    value_type = MAX
    execute_on = 'TIMESTEP_END'
  []
  [Psi]
    type = TensorIntegralPostprocessor
    buffer = psi
  []
[]

# [TensorOutputs]
#   [xdmf]
#     type = XDMFTensorOutput
#     buffer = 'psi'
#     output_mode = 'Node'
#     enable_hdf5 = true
#   []
# []

[Outputs]
  exodus = true
  perf_graph = true
  execute_on = 'TIMESTEP_END'
[]

Overview
Example Input File Syntax
Input Parameters
Notes and Limitations
Related

DomainAction

Overview

Key concepts and behavior

Mesh generation and problem creation

Parallel partitioning modes

Device assignment and weights

Example Input File Syntax

Input Parameters

Required Parameters

Optional Parameters

Advanced Parameters

Notes and Limitations

Related

dim

nx

ny

nz

xmin

xmax

ymin

ymax

zmin

zmax

parallel_mode

device_names

device_weights

mesh_mode

device_names

floating_precision

mesh_mode

device_names

device_weights

floating_precision

(test/tests/lbm/channel2D.i)

(test/tests/lbm/channel3D.i)

(test/tests/tensor_compute/parallel.i)

parallel_mode

device_names