Run MOOSE finite-element simulations on Windows via Docker. Use when creating, running, debugging, or visualizing MOOSE input files (.i). Covers the full lifecycle: prerequisites check, input file authoring, Docker execution, output validation, plot generation, and README documentation. Applies to heat transfer, solid mechanics, fluid dynamics, phase field, porous flow, electromagnetics, and any MOOSE module.
Run MOOSE finite-element simulations on Windows via Docker. Use when creating, running, debugging, or visualizing MOOSE input files (.i). Covers the full lifecycle: prerequisites check, input file authoring, Docker execution, output validation, plot generation, and README documentation. Applies to heat transfer, solid mechanics, fluid dynamics, phase field, porous flow, electromagnetics, and any MOOSE module.
allowed-tools
Read, Grep, Glob, Bash, Write, Edit
MOOSE Simulation on Windows (Git Bash + Docker)
This skill governs the complete lifecycle of running MOOSE simulations on a
Windows machine using Docker. Follow every section as a checklist.
1. Prerequisites Checklist
Before running ANY simulation, verify all prerequisites. Do not skip any step.
Always include exodus = true and csv = true in [Outputs]
2.2 Header Comment Block
Every .i file must start with a descriptive header:
# ============================================================
# Case NN: Title — Subtitle
# Brief description of the physics being solved.
#
# Governing equations (in readable math notation)
# Boundary conditions summary
# Domain dimensions and mesh size
# ============================================================
2.3 Inline Comments
Add comments explaining:
Why each kernel/BC/material is needed (not just what it does)
Physical meaning of parameter values (units, typical ranges)
Relationships between coupled variables
Solver/preconditioner choices and why they suit this problem
2.4 Required Output Blocks
Every simulation must produce both spatial and scalar outputs:
[Outputs]
exodus = true # spatial fields for visualization
csv = true # postprocessor time histories
[]
For transient problems, also include relevant [Postprocessors]:
At least one domain-averaged quantity (conservation check)
Extreme values (min/max of primary variable)
Boundary fluxes or integrals where physically meaningful
2.5 Mesh Sizing for Quick Runs
Keep meshes small enough to converge in under 2 minutes on a laptop:
Problem Type
Recommended Mesh
2D steady state
20x20 to 40x40
2D transient
20x20 to 40x40
2D FV (Navier-Stokes)
30x30
Quasi-1D (thin strip)
100x5
Phase field
40x40
2.6 Docker Portability Rules
These rules prevent failures inside the idaholab/moose:latest container:
Rule
Reason
Add disable_fpoptimizer = true and enable_jit = false to ALL DerivativeParsedMaterial blocks
The container lacks mpicxx, so JIT compilation fails. The fpoptimizer can also cause issues.
Use time_step_interval not interval in [Outputs] sub-blocks
MOOSE renamed this parameter; interval triggers an unused-parameter error
Use NEWTON or PJFNK solve types with lu or hypre/boomeramg preconditioner
These are the most robust choices for small educational meshes
Avoid type = FileMesh unless the mesh file is in the same directory
The exodus file will be named caseNN_name_exodus.e (NOT caseNN_name_out.e).
The CSV always gets the _out.csv suffix from the top-level csv = true.
5. Visualization Requirements
Every case needs Python-generated PNG plots. The visualization script is at
quickstart-runs/visualize_all.py.
5.1 Plot Function Requirements
Each case needs a plot_caseNN() function that produces at least one PNG.
For steady-state problems: 2D contour of the primary variable(s)
For transient problems: Snapshots at multiple times + time-history from CSV
For multi-physics: Side-by-side panels showing each coupled field
5.2 Reading Exodus Files
MOOSE outputs two types of variables:
Type
Where to Find
How to Read
Typical Variables
Nodal (name_nod_var)
vals_nod_var{N}
get_nod_var(ds, idx, timestep) with node coordinates coordx, coordy
T, u, disp_x, disp_y, c, w, V, porepressure, temperature
Element (name_elem_var)
vals_elem_var{N}eb{block}
get_elem_var(ds, idx, block, timestep) with element centroids
vonmises_stress, stress_xx, stress_yy
FV (Finite Volume) variables (Navier-Stokes, etc.) are ALL element variables
with NO nodal variables. Use element centroids for plotting.
Multi-block meshes (e.g., bimetallic strip with two materials) have separate
element variable arrays per block: vals_elem_var1eb1, vals_elem_var1eb2, etc.
Concatenate them for full-domain plots.
5.3 Plot Naming Convention
caseNN_descriptive_name.png # primary multi-panel plot
caseNN_variable_name.png # single-variable plot
caseNN_time_history.png # CSV-based time series
6. README Documentation Requirements
Every case directory MUST contain a README.md explaining the simulation.
Follow this structure:
# Case NN: Title — Subtitle## Overview
2-3 paragraphs explaining:
- What physics is being modeled and why it matters
- What MOOSE modules/objects are used (with object names)
- What new concepts this case introduces vs. previous cases
---
## The Physics- Governing equation(s) in readable form
- Boundary conditions and their physical meaning
- Material properties and their values (with units)
- Domain geometry and mesh
## Input File Walkthrough
Block-by-block explanation of the `.i` file:
- [Mesh]: domain and discretization
- [Variables]: what is being solved for
- [Kernels] or [Modules/...]: weak form terms
- [BCs]: boundary conditions
- [Materials]: constitutive relations
- [Executioner]: solver strategy and time stepping
- [Postprocessors]: quantities of interest
- [Outputs]: what files are produced
## Running the Simulation
Docker command (copy-paste ready):
```bash
MSYS_NO_PATHCONV=1 docker run --rm \
-v "C:/Users/simon/Downloads/moose-next/quickstart-runs:/work" \
-w /work/caseNN-directory-name \
--entrypoint /bin/bash \
idaholab/moose:latest \
-c '/opt/moose/bin/combined-opt -i caseNN_name.i 2>&1 | tail -30'
Expected Results
What the solver output should look like (converged in N steps)
Physical interpretation of the results
What the plots show and how to read them
Key Takeaways
Bullet list of what the learner should take away from this case.
---
## 7. Common Failure Patterns and Fixes
These are real failures encountered across 21 cases. Check for these FIRST
when debugging a failed run.
### 7.1 MINGW Path Mangling (Silent Failure)
**Symptom**: Docker starts but produces no output files, or output is empty.
**Cause**: Missing `MSYS_NO_PATHCONV=1`.
**Fix**: Always prefix Docker commands with `MSYS_NO_PATHCONV=1`.
### 7.2 JIT Compilation Failure
**Symptom**: `sh: mpicxx: command not found` / `JIT compile failed`
**Cause**: `DerivativeParsedMaterial` tries to JIT-compile expressions using
`mpicxx`, which is not on PATH in the Docker container.
**Fix**: Add to every `DerivativeParsedMaterial`:
disable_fpoptimizer = true
enable_jit = false
### 7.3 Missing Material Properties (PorousFlow)
**Symptom**: `Material property 'PorousFlow_constant_biot_modulus_qp' not defined on block 0`
**Cause**: `PorousFlowBasicTHM` action does NOT auto-create these materials.
**Fix**: Add explicit material blocks:
### 7.4 Renamed Parameters
**Symptom**: `unused parameter 'Outputs/exodus/interval'`
**Cause**: MOOSE renamed `interval` to `time_step_interval`.
**Fix**: Use `time_step_interval` in all `[Outputs]` sub-blocks.
### 7.5 FV Navier-Stokes Parameter Names
**Symptom**: Vector parameter size mismatch errors in NavierStokesFV.
**Cause**: `momentum_inlet_function` was renamed to `momentum_inlet_functors`.
**Fix**: Use `momentum_inlet_functors` (plural, with "functors").
### 7.6 Solver Divergence
**Symptom**: `Solve failed and timestep already at dtmin, cannot continue!`
**Cause**: Newton iterations not converging — usually dt too large, bad
preconditioner, or ill-conditioned system.
**Fix** (try in order):
1. Reduce initial `dt` (e.g., from 0.5 to 0.1)
2. Switch preconditioner to LU: `-pc_type lu -pc_factor_mat_solver_type mumps`
3. Increase `nl_max_its` (e.g., from 20 to 30)
4. Add `nl_abs_tol` (e.g., 1e-11) alongside `nl_rel_tol`
5. Reduce `growth_factor` in `IterationAdaptiveDT` (e.g., from 1.5 to 1.2)
### 7.7 Porosity Material Type
**Symptom**: Errors about missing porosity derivatives or qp materials.
**Cause**: `PorousFlowPorosityConst` may not provide all derivatives that
`PorousFlowBasicTHM` expects.
**Fix**: Use `PorousFlowPorosity` with `porosity_zero` instead:
