MOOSE Framework
Theory: writing physics as residuals
Overview
How does MOOSE differ from other open-source finite element codes?
It is a framework for building analysis codes rather than an analysis code itself. MOOSE (Multiphysics Object Oriented Simulation Environment) is developed at Idaho National Laboratory; it delegates meshing to libMesh and linear and nonlinear solvers to PETSc, and the user writes only the residual of each governing equation. For heat conduction you write the diffusion term and the source term as separate Kernels and list them in an input file; MOOSE sums and solves them. Adding physics means adding Kernels: all unknowns — thermal, mechanical, chemical — are assembled into one nonlinear system and solved together by Newton's method. BISON, which models nuclear fuel behaviour, and many other research codes are built on it.
Residuals and Newton's method
ψᵢ are test functions, k(u) a solution-dependent coefficient, f the source and J the Jacobian. MOOSE either builds J (possibly approximately) or uses JFNK (Jacobian-Free Newton-Krylov), computing J·v from residual differences without forming the matrix.
Verification by manufactured solutions
Choose the solution first and back out the source f that it satisfies. The convergence order p comes from the error ratio when the element count N doubles, compared with theory (for linear elements, 2 for values and 1 for gradients).
A framework born for nuclear fuel
MOOSE development began around 2008 at Idaho National Laboratory to model nuclear fuel. Inside a fuel pellet, heat, deformation, fission gas release and material changes all affect one another, and running separate codes in sequence could not handle the strong coupling. The chosen design — physics written as residuals, with coupling and solvers handled by the framework — was released as open source in 2014.
Worked examples
Example 1: checking convergence order with sin(πx)
Solve −u″ = f on [0, 1] with linear elements, u = 0 at both ends; the exact solution is sin(πx).
| Elements N | L2 error | Gradient error | L2 order | Gradient order |
|---|---|---|---|---|
| 4 | 3.93×10⁻² | 0.499 | — | — |
| 8 | 9.92×10⁻³ | 0.251 | 1.99 | 0.99 |
| 16 | 2.49×10⁻³ | 0.126 | 2.00 | 1.00 |
| 32 | 6.22×10⁻⁴ | 0.0630 | 2.00 | 1.00 |
Each halving of element size cuts the L2 error by 4 and the gradient error by 2, matching theory.
Comparing nodal values with the exact solution, the error was below 10⁻⁷ even with 4 elements. Is that already accurate enough?
That is a quirk of linear elements in 1D, and it misleads easily. In this problem the nodal values alone almost match the exact solution (superconvergence), yet between nodes and in the gradient the table shows an L2 error of 4×10⁻² and a gradient error of 0.5 with 4 elements. Looking only at nodes can hide a wrong element implementation. In MOOSE the standard is to measure error with integral norms such as L2 and the H1 seminorm and to judge by the order as elements are refined two and four times. If the order departs from theory, suspect a Kernel sign, quadrature, or how boundary conditions are applied.
Example 2: Newton vs Picard on nonlinear diffusion
−(k(u)u′)′ = 10 with k = 1 + u², u = 0 at both ends, 32 elements. Compare iterations until the residual norm drops below 10⁻¹⁰.
| Method | Iterations | Max u |
|---|---|---|
| Newton (consistent Jacobian) | 5 | 0.957 |
| Picard (k frozen at previous iterate) | 12 | 0.957 |
| For reference: k = 1 (linear) | 1 | 1.250 |
Near convergence Newton's residual falls quadratically (7×10⁻³ → 4×10⁻⁶), while Picard reduces it only about tenfold per iteration. Because k grows with u, the maximum drops from 1.25 in the linear case to 0.957.
If Newton is always better, why are segregated, one-after-another schemes still used?
Newton's weaknesses are the effort of building a correct Jacobian and its tendency to diverge from a poor initial guess. When you want to reuse existing codes per physics, or the coupling is weak enough to converge in a few exchanges, segregated schemes are simpler and faster. MOOSE supports both: strongly coupled variables go into one Newton system, while weakly coupled physics or those on different time scales can be solved separately as MultiApps that exchange data. An inaccurate Jacobian loses quadratic convergence and the iteration count climbs toward Picard's, so MOOSE also offers a check that compares Kernel derivatives against a finite-difference Jacobian.
Getting started
- Set up an environment (e.g. conda), build MOOSE and run its tests once.
- Run a bundled example such as heat conduction from its input file and learn how Kernels, boundary conditions and the Executioner are written.
- After writing your own Kernel, verify its convergence order with a manufactured solution.
- For nonlinear problems, watch Newton iteration counts to confirm the Jacobian is right.
- Register verified cases as tests and run them automatically on every change.
“The order stalled at 1.5”
When you implement a new boundary condition as a Kernel and check it with a manufactured solution, the L2 order often stalls near 1.5 instead of 2. The cause is usually a small inconsistency: boundary terms not evaluated at the same quadrature as the interior, or a source approximated by nodal values. The plotted results look plausible, so such errors are found only by measuring the order. That is why verification tests carry so much weight in MOOSE development.
Common mistakes
Mistakes and fixes
| Mistake | Effect | Fix |
|---|---|---|
| Verifying with nodal values only | Implementation errors missed | Check order in L2/H1 norms |
| Wrong Jacobian | Newton iterations grow | Compare with a finite-difference Jacobian |
| Sign error in a Kernel | Divergence or reversed solution | Check with MMS |
| Initial guess far from the solution | Newton diverges | Approach by load stepping or time marching |
| Lumping weak couplings into one system | Expensive solves | Separate with MultiApps |
I'd like to learn related topics.
Related pages include the method of manufactured solutions, MMS convergence rate calculation, the FEniCS Project, Elmer Multiphysics and introduction to Code_Aster.
Related Topics
Experience the theory firsthand with the interactive simulator for this field
All Simulators