MOOSE (idaholab/moose)

MOOSE

https://github.com/idaholab/moose
Admin
MOOSE is a finite-element, multiphysics framework providing a high-level interface to nonlinear...

Tokens:1,894,622
Snippets:23,905
Trust Score:8.6
Update:1 day ago
Show doc for...
Context Summary (auto-generated)
Raw
# MOOSE - Multiphysics Object-Oriented Simulation Environment

MOOSE (Multiphysics Object-Oriented Simulation Environment) is a finite-element, multiphysics framework developed by Idaho National Laboratory. It provides a high-level interface to sophisticated nonlinear solver technology (PETSc), enabling scientists and engineers to tackle complex simulation problems. MOOSE features automatic parallelization (supporting over 100,000 CPU cores), built-in mesh adaptivity, both continuous and discontinuous Galerkin methods, and intuitive parallel multiscale solves through its MultiApp system.

The framework follows a modular plug-and-play architecture where users define simulations through input files using a hierarchical block syntax. MOOSE provides approximately 30 pluggable interfaces for specialization, including Kernels (governing equations), BCs (boundary conditions), Materials (material properties), and MultiApps (multiscale coupling). Users can extend the framework by creating custom C++ objects that inherit from base classes and register them with the application system.

---

## Input File Structure

Basic MOOSE input files use a hierarchical block-based syntax with required sections for Mesh, Variables, Kernels, BCs, Executioner, and Outputs.

```ini
# Basic diffusion problem demonstrating core MOOSE input file structure
[Mesh]
  # Generate a 2D mesh programmatically
  type = GeneratedMesh
  dim = 2
  nx = 10
  ny = 10
  xmax = 2
  ymax = 1
[]

[Variables]
  [u]
    order = FIRST
    family = LAGRANGE
  []
[]

[Kernels]
  [diff]
    type = Diffusion
    variable = u
  []
[]

[BCs]
  [left]
    type = DirichletBC
    variable = u
    boundary = 'left'
    value = 0
  []
  [right]
    type = DirichletBC
    variable = u
    boundary = 'right'
    value = 1
  []
[]

[Executioner]
  type = Steady
  solve_type = 'PJFNK'
[]

[Outputs]
  exodus = true
[]
```

---

## Mesh Generation

MOOSE supports both file-based meshes (Exodus format) and programmatic mesh generation through MeshGenerators.

```ini
# Using GeneratedMeshGenerator for simple geometries
[Mesh]
  [generated]
    type = GeneratedMeshGenerator
    dim = 2
    nx = 100
    ny = 100
    xmin = 0.0
    xmax = 1.0
    ymin = 0.0
    ymax = 1.0
  []
[]

# Using file-based mesh with refinement
[Mesh]
  file = reactor.e
  uniform_refine = 4
  # Assign human-readable names to blocks
  block_id = '1 2'
  block_name = 'fuel deflector'
  boundary_id = '4 5'
  boundary_name = 'bottom top'
[]

# Create subdomains using bounding boxes
[Mesh]
  [generated]
    type = GeneratedMeshGenerator
    dim = 2
    nx = 40
    ny = 20
    xmax = 2
    ymax = 1
  []
  [block1]
    type = SubdomainBoundingBoxGenerator
    input = generated
    block_id = 1
    bottom_left = '0 0 0'
    top_right = '1 1 0'
  []
  [block2]
    type = SubdomainBoundingBoxGenerator
    input = block1
    block_id = 2
    bottom_left = '1 0 0'
    top_right = '2 1 0'
  []
[]
```

---

## Variables and Initial Conditions

Variables represent the unknowns being solved for. Initial conditions can be set inline or through dedicated IC blocks.

```ini
[Variables]
  [diffused]
    order = FIRST
    family = LAGRANGE
    # Inline initial condition for simple constant values
    initial_condition = 0.5
  []

  [convected]
    order = FIRST
    family = LAGRANGE
    # Nested initial condition block for complex ICs
    [InitialCondition]
      type = ExampleIC
      coefficient = 2.0
    []
  []
[]

# Alternative: Separate ICs block
[ICs]
  [temperature_ic]
    type = ConstantIC
    variable = T
    value = 300.0
  []
  [gaussian_ic]
    type = FunctionIC
    variable = concentration
    function = 'exp(-((x-0.5)^2+(y-0.5)^2)/0.1)'
  []
[]
```

---

## Kernels - Governing Equations

Kernels implement the weak form of PDEs. MOOSE provides many built-in kernels and supports custom implementations.

```ini
[Kernels]
  # Laplacian operator: -nabla^2(u)
  [diff]
    type = Diffusion
    variable = u
  []

  # Time derivative: du/dt
  [time_derivative]
    type = TimeDerivative
    variable = u
  []

  # Body force / source term
  [source]
    type = BodyForce
    variable = u
    function = forcing_func
    value = 1.0
  []

  # Convection with specified velocity
  [convection]
    type = ExampleConvection
    variable = convected
    velocity = '0.0 0.0 1.0'
  []

  # AD (Automatic Differentiation) versions for exact Jacobians
  [ad_diff]
    type = ADDiffusion
    variable = u
  []
[]
```

---

## Boundary Conditions

MOOSE supports Dirichlet (fixed value), Neumann (flux), and Robin (mixed) boundary conditions.

```ini
[BCs]
  # Fixed value (Dirichlet)
  [fixed_temp]
    type = DirichletBC
    variable = T
    boundary = 'left'
    value = 300
  []

  # Time-dependent boundary using function
  [varying_temp]
    type = FunctionDirichletBC
    variable = T
    boundary = 'right'
    function = '300 + 5*t'
  []

  # Flux boundary (Neumann)
  [heat_flux]
    type = NeumannBC
    variable = T
    boundary = 'top'
    value = 100  # W/m^2
  []

  # Coupled boundary condition
  [coupled_bc]
    type = CoupledDirichletBC
    variable = convected
    boundary = 'right'
    alpha = 2
    some_var = diffused
  []

  # Pressure boundary for mechanics
  [Pressure]
    [top_pressure]
      boundary = top
      function = 1e7*t
    []
  []
[]

# Periodic boundary conditions
[BCs]
  [Periodic]
    [all]
      variable = u
      auto_direction = 'x y'
    []
  []
[]
```

---

## Materials System

Materials provide spatially-varying properties that can be coupled to variables.

```ini
[Materials]
  # Constant thermal conductivity
  [thermal]
    type = HeatConductionMaterial
    thermal_conductivity = 45.0
    specific_heat = 0.5
  []

  # Generic constant material
  [density]
    type = GenericConstantMaterial
    prop_names = 'density'
    prop_values = 8000.0
  []

  # Block-specific properties
  [elasticity_block1]
    type = ComputeIsotropicElasticityTensor
    youngs_modulus = 1e9
    poissons_ratio = 0.3
    block = 1
  []
  [elasticity_block2]
    type = ComputeIsotropicElasticityTensor
    youngs_modulus = 5e8
    poissons_ratio = 0.3
    block = 2
  []

  # Stress computation
  [stress]
    type = ComputeLinearElasticStress
  []

  # Variable-dependent material with interpolation
  [example_material]
    type = ExampleMaterial
    block = 'fuel'
    diffusion_gradient = 'diffused'
    independent_vals = '0 0.25 0.5 0.75 1.0'
    dependent_vals = '1e-2 5e-3 1e-3 5e-3 1e-2'
  []
[]
```

---

## Functions

Functions define spatially and temporally varying quantities for use in BCs, ICs, and kernels.

```ini
[Functions]
  # Parsed mathematical expression
  [bc_func]
    type = ParsedFunction
    expression = 'sin(alpha*pi*x)'
    symbol_names = 'alpha'
    symbol_values = '16'
  []

  # Time-dependent parsed function
  [ramp_function]
    type = ParsedFunction
    expression = '300 + 5*t'
  []

  # Piecewise linear function
  [piecewise]
    type = PiecewiseLinear
    x = '0 1 2 3'
    y = '0 1 1 0'
  []

  # Custom compiled function
  [custom_forcing]
    type = ExampleFunction
    alpha = 16
  []
[]
```

---

## Executioners and Time Stepping

Executioners control the solution strategy - steady-state or transient.

```ini
# Steady-state solve
[Executioner]
  type = Steady
  solve_type = 'PJFNK'  # Preconditioned Jacobian-Free Newton Krylov

  petsc_options_iname = '-pc_type -pc_hypre_type'
  petsc_options_value = 'hypre boomeramg'

  l_tol = 1e-3           # Linear solver tolerance
  nl_rel_tol = 1e-12     # Nonlinear relative tolerance
[]

# Transient solve
[Executioner]
  type = Transient
  scheme = bdf2          # Second-order backward differentiation
  solve_type = NEWTON

  # Time stepping
  start_time = 0
  end_time = 5
  dt = 0.1
  num_steps = 50

  # Solver settings
  petsc_options_iname = '-pc_type -pc_hypre_type -ksp_gmres_restart'
  petsc_options_value = 'hypre boomeramg 101'

  l_max_its = 30
  nl_max_its = 10
  nl_abs_tol = 1e-9
  l_tol = 1e-04
[]
```

---

## Adaptive Mesh Refinement

MOOSE supports h-adaptivity through indicators and markers.

```ini
[Adaptivity]
  marker = errorfrac
  steps = 2  # Refinement cycles per solve

  [Indicators]
    [error]
      type = GradientJumpIndicator
      variable = convected
      outputs = none
    []
  []

  [Markers]
    [errorfrac]
      type = ErrorFractionMarker
      indicator = error
      refine = 0.5    # Refine top 50% by error
      coarsen = 0.1   # Coarsen bottom 10%
      outputs = none
    []
  []
[]
```

---

## Heat Transfer Module

Provides kernels and materials for heat conduction problems.

```ini
# Complete heat conduction problem with transient term
[Variables]
  [T]
    initial_condition = 300.0
  []
[]

[Kernels]
  [heat_conduction]
    type = HeatConduction
    variable = T
  []
  [time_derivative]
    type = HeatConductionTimeDerivative
    variable = T
  []
[]

[Materials]
  [thermal]
    type = HeatConductionMaterial
    thermal_conductivity = 45.0  # W/(m*K)
    specific_heat = 0.5          # J/(kg*K)
  []
  [density]
    type = GenericConstantMaterial
    prop_names = 'density'
    prop_values = 8000.0         # kg/m^3
  []
[]

[BCs]
  [fixed_temp]
    type = DirichletBC
    variable = T
    value = 300
    boundary = 'left'
  []
  [varying_temp]
    type = FunctionDirichletBC
    variable = T
    function = '300+5*t'
    boundary = 'right'
  []
[]
```

---

## Solid Mechanics Module

Provides a physics-based system for structural analysis using the QuasiStatic action.

```ini
[GlobalParams]
  displacements = 'disp_x disp_y'
[]

[Mesh]
  [generated]
    type = GeneratedMeshGenerator
    dim = 2
    nx = 10
    ny = 10
    xmax = 2
    ymax = 1
  []
[]

# QuasiStatic action automatically creates strain and stress variables
[Physics/SolidMechanics/QuasiStatic]
  [all]
    add_variables = true
    strain = SMALL          # or FINITE for large deformation
    generate_output = 'stress_xx stress_yy vonmises_stress'
  []
[]

[Materials]
  [elasticity]
    type = ComputeIsotropicElasticityTensor
    youngs_modulus = 1e9    # Pa
    poissons_ratio = 0.3
  []
  [stress]
    type = ComputeLinearElasticStress
  []
[]

[BCs]
  [bottom_x]
    type = DirichletBC
    variable = disp_x
    boundary = bottom
    value = 0
  []
  [bottom_y]
    type = DirichletBC
    variable = disp_y
    boundary = bottom
    value = 0
  []
  [Pressure]
    [top]
      boundary = top
      function = 1e7*t
    []
  []
[]
```

---

## Coupled Thermomechanics

Demonstrates coupling heat transfer with solid mechanics for thermal expansion analysis.

```ini
[Variables]
  [T]
    initial_condition = 800
    scaling = 1e7
  []
  [disp_x]
  []
  [disp_y]
  []
[]

[Kernels]
  [heat_conduction]
    type = HeatConduction
    variable = T
  []
  [TensorMechanics]
    displacements = 'disp_x disp_y'
  []
  [heat_source]
    type = BodyForce
    variable = T
    value = 1
    function = 0.8e-9*t
  []
[]

[Materials]
  [thermal_conductivity]
    type = GenericConstantMaterial
    prop_names = 'thermal_conductivity'
    prop_values = '5e-6'
  []
  [elasticity_tensor]
    type = ComputeElasticityTensor
    fill_method = symmetric_isotropic
    C_ijkl = '2.15e5 0.74e5'
  []
  [strain]
    type = ComputeSmallStrain
    displacements = 'disp_x disp_y'
    eigenstrain_names = eigenstrain
  []
  [stress]
    type = ComputeLinearElasticStress
  []
  [thermal_expansion]
    type = ComputeThermalExpansionEigenstrain
    thermal_expansion_coeff = 1e-6
    temperature = T
    stress_free_temperature = 273
    eigenstrain_name = eigenstrain
  []
[]
```

---

## AuxVariables and AuxKernels

Auxiliary variables store computed quantities for visualization or coupling.

```ini
[AuxVariables]
  [radial_stress]
    order = CONSTANT
    family = MONOMIAL
  []
  [hoop_stress]
    order = CONSTANT
    family = MONOMIAL
  []
  [temperature_gradient]
    order = FIRST
    family = LAGRANGE
  []
[]

[AuxKernels]
  [radial_stress_calc]
    type = CylindricalRankTwoAux
    variable = radial_stress
    rank_two_tensor = stress
    index_i = 0
    index_j = 0
    center_point = '0 0 0'
  []
  [hoop_stress_calc]
    type = CylindricalRankTwoAux
    variable = hoop_stress
    rank_two_tensor = stress
    index_i = 1
    index_j = 1
    center_point = '0 0 0'
  []
[]
```

---

## Postprocessors

Compute scalar quantities from the solution for output and monitoring.

```ini
[Postprocessors]
  [average_element_size]
    type = AverageElementSize
  []
  [l2_error]
    type = ElementL2Error
    variable = forced
    function = exact_solution
  []
  [max_temperature]
    type = NodalExtremeValue
    variable = T
    value_type = max
  []
  [total_heat_flux]
    type = SideDiffusiveFluxIntegral
    variable = T
    boundary = 'right'
    diffusivity = thermal_conductivity
  []
[]

[VectorPostprocessors]
  [line_sample]
    type = LineValueSampler
    variable = T
    start_point = '0 0.5 0'
    end_point = '2 0.5 0'
    num_points = 20
    sort_by = x
  []
[]
```

---

## MultiApp System

MultiApps enable hierarchical multiscale and multiphysics coupling.

```ini
# Parent application
[MultiApps]
  [sub_app]
    type = TransientMultiApp
    app_type = MooseTestApp
    input_files = 'sub_application.i'
    # Multiple sub-applications at different positions
    positions = '0   0   0
                 0.5 0.5 0
                 0.6 0.6 0
                 0.7 0.7 0'
    execute_on = 'timestep_end'
  []
[]

# Data transfer between applications
[Transfers]
  [temperature_to_sub]
    type = MultiAppNearestNodeTransfer
    to_multi_app = sub_app
    source_variable = T
    variable = T_from_parent
  []
  [stress_from_sub]
    type = MultiAppNearestNodeTransfer
    from_multi_app = sub_app
    source_variable = stress_xx
    variable = stress_from_sub
  []
[]
```

---

## Custom Kernel Development (C++)

Creating custom physics requires implementing a C++ class that inherits from Kernel.

```cpp
// ExampleConvection.h
#pragma once
#include "Kernel.h"

class ExampleConvection : public Kernel
{
public:
  ExampleConvection(const InputParameters & parameters);
  static InputParameters validParams();

protected:
  virtual Real computeQpResidual() override;
  virtual Real computeQpJacobian() override;

private:
  RealVectorValue _velocity;
};

// ExampleConvection.C
#include "ExampleConvection.h"

registerMooseObject("ExampleApp", ExampleConvection);

InputParameters
ExampleConvection::validParams()
{
  InputParameters params = Kernel::validParams();
  params.addRequiredParam<RealVectorValue>("velocity", "Velocity Vector");
  return params;
}

ExampleConvection::ExampleConvection(const InputParameters & parameters)
  : Kernel(parameters),
    _velocity(getParam<RealVectorValue>("velocity"))
{
}

Real
ExampleConvection::computeQpResidual()
{
  // (V . grad(u), test)
  return _test[_i][_qp] * (_velocity * _grad_u[_qp]);
}

Real
ExampleConvection::computeQpJacobian()
{
  // Derivative of residual with respect to u_j
  return _test[_i][_qp] * (_velocity * _grad_phi[_j][_qp]);
}
```

---

## Output Configuration

MOOSE supports multiple output formats including Exodus, CSV, and console output.

```ini
[Outputs]
  execute_on = 'timestep_end'

  # Exodus format for visualization
  exodus = true

  # Performance logging
  perf_graph = true

  # CSV output for postprocessors
  [csv]
    type = CSV
    file_base = simulation_results
    execute_on = 'final'
  []

  # Console output settings
  [console]
    type = Console
    output_linear = true
    output_nonlinear = true
  []

  # Checkpoint for restart
  [checkpoint]
    type = Checkpoint
    num_files = 2
    interval = 10
  []
[]
```

---

## Running MOOSE Applications

Execute simulations from the command line with various options.

```bash
# Basic execution
./myapp-opt -i input_file.i

# Parallel execution with MPI
mpiexec -n 4 ./myapp-opt -i input_file.i

# Generate mesh only (no solve)
./myapp-opt -i input_file.i --mesh-only output_mesh.e

# Override input file parameters
./myapp-opt -i input_file.i Mesh/uniform_refine=2 Executioner/num_steps=100

# Use split mesh for large parallel runs
mpiexec -n 1000 ./myapp-opt -i input_file.i --use-split
```

---

## Summary

MOOSE excels at solving tightly-coupled multiphysics problems through its unified finite element framework. The primary use cases include nuclear fuel performance analysis, thermomechanical stress analysis, fluid-structure interaction, phase-field modeling, porous flow simulations, and general PDE-based engineering problems. The modular architecture enables combining physics modules (Heat Transfer, Solid Mechanics, Navier-Stokes, Phase Field, Porous Flow, etc.) to model complex real-world phenomena with automatic parallel execution.

Integration patterns typically involve: (1) defining meshes through files or generators, (2) specifying variables and their governing equations via Kernels, (3) applying boundary and initial conditions, (4) defining material properties, (5) configuring the solver through Executioner settings, and (6) coupling multiple physics through shared variables or the MultiApp system. Users can extend MOOSE by creating custom Kernels, Materials, BCs, and other objects in C++, registering them with the application system, and using them in input files like built-in objects. The framework handles parallel decomposition, assembly, and solve automatically.