MOOSE: a multiphysics framework where the solver is the easy part

A framework from a national laboratory, not a startup

MOOSE stands for Multiphysics Object-Oriented Simulation Environment, and the README names who builds it: it is primarily developed by Idaho National Laboratory. That provenance explains most of what is unusual about the project, starting with the fact that the repository is not the documentation and the documentation is not in the repository.

The README is short. It describes the framework as a finite element, multiphysics framework, explains that it provides a high-level interface to what it calls some of the most sophisticated nonlinear solver technology on the planet, linking that claim to PETSc, and then hands off. Installation instructions, the contributing guide and everything else live on the project website at mooseframework.inl.gov. For a project of this size that is a deliberate division of labour rather than an omission.

The repository itself is in C++, licensed under LGPL 2.1, and its default branch is named next. There are no GitHub releases published at all. For a laboratory framework consumed by researchers who build from source against a pinned commit, that is unremarkable, but it does mean there is no version number to cite and no changelog to read. The last push was on 2026-09-28.

The capability list is unusually specific

Most framework READMEs list features in the passive voice. This one lists concrete engineering properties, and several of them are worth reading twice because they describe hard-won experience.

A fully-coupled, fully-implicit multiphysics solver means no operator splitting and no staggered iteration to converge, which is expensive per step and much better conditioned. Dimension independent physics means you can change from two dimensions to three without rewriting the formulation layer. Built-in mesh adaptivity is listed as a feature rather than a bolt-on. Continuous and Discontinuous Galerkin at the same time is the entry that stands out, since mixing the two discretisations in one formulation is a research-grade capability rather than a checkbox.

Three entries describe scale and performance. Automatic parallelism with largest runs above 100,000 CPU cores. Intuitive parallel multiscale solves, which means solving a coarse problem and refining rather than refining everything at once. And dimension agnostic, parallel geometric search for contact related applications, which is the computationally nasty part of contact mechanics and is claimed as a solved problem.

The last two entries are about extensibility: a flexible, pluggable graphical user interface, and around thirty pluggable interfaces that allow specialization of every part of the solve. The README also mentions modular development simplifying code reuse, which is the least interesting item on the list and the one you will notice most if it is missing.

Twenty-one examples arranged as a curriculum

The most useful thing in the repository is the examples directory, and it is laid out as a numbered teaching sequence rather than a set of unrelated demos. Each one isolates a single concept.

The first three are the foundation: ex01_inputfile for driving a run from an input deck, ex02_kernel for the object you actually write, and ex03_coupling for connecting two physics. After that the sequence walks the boundary conditions in ex04, adaptive mesh refinement in ex05, transient problems in ex06, initial conditions in ex07, materials in ex08 and stateful materials in ex09, where material state carries history.

The back half of the sequence is the part that reflects real research work. ex10_aux is auxiliary variables, ex11_prec is preconditioners, ex12_pbp and ex14_pps are two different partitioned block preconditioning strategies, ex13_functions is function support, ex15_actions is a post-processing hook system, and ex16_timestepper is custom time integrators. The last five go furthest out: ex17 is Dirac sources, ex18 scalar kernels, ex19 dampers, ex20 user objects for extending the framework itself, and ex21 is a debugging example.

The order is the argument. Each directory adds one idea to what came before, so a reader can work through them in sequence and end up with a working mental model rather than a pile of snippets. There is also a Makefile and test.mk alongside them, which suggests they are wired into a build rather than being loose files.

Submodules for the mesh and the solver stack

Two entries at the root of the tree explain a great deal about the build. libmesh and petsc sit there as top-level directories, and a .gitmodules file is present, which means both are checked in as submodules rather than vendored copies.

That matters for anyone trying to build MOOSE from a source archive. The mesh handling and the nonlinear solver stack are external projects with their own build systems, and MOOSE is coordinating them rather than implementing them. The README's claim of a high-level interface to sophisticated nonlinear solver technology is, concretely, an interface to PETSc.

The rest of the tree describes a serious software project. framework/ and modules/ separate the core from the physics applications, python/ holds a Python layer, conda/ and apptainer/ cover two forms of environment packaging, docker_ci/ covers continuous integration, and unit/ and test/ cover testing. There is a gui directory for the graphical interface the README mentions, a stork directory whose purpose the README does not explain, and tools/ and scripts/ for utilities.

One entry is worth flagging for what it says about how the project now works. Alongside CODEOWNERS and a codegraph.json, the root contains AGENTS.md and CLAUDE.md, plus .agents/ and .claude/ directories, and AGENTS.md has its own LICENSE file. A large scientific codebase now carries instructions aimed at automated coding assistants, which is a reasonable response to a contributor pool that has changed.

Python tooling is pinned hard and maintained deliberately

The requirements file is unusual for a C++ project because it is almost entirely about tooling rather than runtime. Its own header explains that it should mirror the conda build configuration as closely as reasonably possible, and that it is currently only used inside the development containers.

Several tools are pinned to exact versions: black at 26.5.1, clang-format at 19.1.7, coverage at 7.13.2 and ruff at 0.15.15. One entry has an upper bound rather than a pin, xmltodict at less than 0.14, which is the kind of constraint you add after an upstream release changes behaviour. Others carry inline comments explaining why they are not in the conda package, such as fastcov, lcov-cobertura and psycopg2-binary.

The rest of the file is a scientific Python stack: numpy, scipy through scikit-image, sympy for symbolic work, h5py, pyarrow and pandas for data, matplotlib and plotly for output, and pytest with pytest-cov for testing. paramiko and pymongo suggest remote execution and results storage, and pymongo in particular hints at a workflow where simulations write results to a database.

The linting configuration in pyproject.toml is similarly opinionated, enabling a broad rule set that includes NumPy docstring conventions, import sorting, class naming and code simplification, with two docstring rules explicitly disabled.

[tool.ruff.lint]
select = ["D", "E", "F", "I", "N801", "SIM", "TID"]
ignore = ["D203", "D212"]

Enforcing NumPy style docstrings by default across a scientific codebase is a real editorial position, and the black configuration targets Python 3.10 through 3.13, which tells you the supported interpreter range.

Who this is for, and what to check first

MOOSE is aimed at scientists and engineers with a hard simulation problem, which is a narrower audience than the topic tags might suggest. The framework is free software and the source is public, but the cost of entry is a build of PETSc, libMesh and a C++ application, plus learning an object oriented API where every part of the solve is a class you can specialise.

The repository has a substantial open issue count and a large contributor base, which is consistent with an actively developed laboratory project rather than a finished product. It was last pushed to on 2026-09-28, on a branch named next, which suggests the main line of development is where new work lands.

Before writing any code, the practical question is whether you can build it. Installation is documented on the website and not in the README, the container route through apptainer and conda is the path the requirements file describes itself as serving, and there is no released version to download. If the website's installation page does not give you a working build for your platform, nothing else in the repository will help you, because there is no smaller entry point than the framework itself.

Editorial conclusion

MOOSE is one of those frameworks whose difficulty is not the physics but the packaging. The physics is genuinely ambitious, with fully coupled implicit multiphysics, dimension independent formulations, adaptive refinement and simultaneous continuous and discontinuous Galerkin, and the claim of runs above 100,000 CPU cores is the kind of thing you only make when a national laboratory has tested it. The obstacle for an outside user is everything around the physics: installation instructions live entirely on the website, the repository publishes no GitHub releases, and the default branch is called next. Go to mooseframework.inl.gov first and find out how the build works before you read any code. If that page answers your questions, the twenty-one examples in the repository are an unusually good curriculum, numbered from input file to user objects and arranged so each one adds a single concept.

Frequently asked questions

Official sources

1. idaholab/moose on GitHub
2. Issues
3. License: LGPL-2.1
4. Project website
5. README