Namespace all of MOOSE-MFEM

.gitignore

@@ -229,6 +229,7 @@ framework/contrib/asio/
 *.cpr
 *.cpa.gz-*
 *.cpr-*
+*_cp/
 
 # Ignore petsc arch
 petsc/arch-*/*

framework/doc/content/source/mfem/actions/AddMFEMPreconditionerAction.md

@@ -5,7 +5,7 @@
 ## Overview
 
 Action called to add a linear preconditioner to an MFEM problem, parsing content inside a
-[`Preconditioner`](source/mfem/solvers/MFEMSolverBase.md) block in the user input. Only has an effect if
+[`Preconditioner`](syntax/Preconditioner/index.md) block in the user input. Only has an effect if
 the `Problem` type is set to [`MFEMProblem`](source/mfem/problem/MFEMProblem.md).
 
 ## Example Input File Syntax

framework/doc/content/source/mfem/actions/AddMFEMSolverAction.md

@@ -4,15 +4,15 @@
 
 ## Overview
 
-Action called to add a linear solver to an MFEM problem, parsing content inside a
-[`Solver`](source/mfem/solvers/MFEMSolverBase.md) block in the user input. Only has an effect if the
+Action called to add an MFEM solver object to an MFEM problem, parsing content inside a
+[`Solvers`](syntax/Solvers/index.md) block in the user input. Only has an effect if the
 `Problem` type is set to [`MFEMProblem`](source/mfem/problem/MFEMProblem.md).
 
 ## Example Input File Syntax
 
-!listing test/tests/mfem/kernels/curlcurl.i block=Problem FESpaces Preconditioner Solver
+!listing test/tests/mfem/kernels/curlcurl.i block=Problem FESpaces Preconditioner Solvers
 
-!syntax parameters /Solver/AddMFEMSolverAction
+!syntax parameters /Solvers/AddMFEMSolverAction
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMCGSolver.md

@@ -8,14 +8,14 @@ Defines and builds an `mfem::CGSolver` solver to use as an iterative solver to s
 equation system. Compatible with use on partially assembled equation systems.
 
 A Low-Order-Refined (LOR) version of this solver may be used instead by setting the parameter
-[!param](/Solver/MFEMCGSolver/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
+[!param](/Solvers/MFEMCGSolver/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
 order systems.
 
-!syntax parameters /Solver/MFEMCGSolver
+!syntax parameters /Solvers/MFEMCGSolver
 
-!syntax inputs /Solver/MFEMCGSolver
+!syntax inputs /Solvers/MFEMCGSolver
 
-!syntax children /Solver/MFEMCGSolver
+!syntax children /Solvers/MFEMCGSolver
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMGMRESSolver.md

@@ -8,14 +8,14 @@ Defines and builds an `mfem::GMRESSolver` solver to use as an iterative solver t
 equation system. Compatible with use on partially assembled equation systems.
 
 A Low-Order-Refined (LOR) version of this solver may be used instead by setting the parameter
-[!param](/Solver/MFEMGMRESSolver/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
+[!param](/Solvers/MFEMGMRESSolver/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
 order systems.
 
-!syntax parameters /Solver/MFEMGMRESSolver
+!syntax parameters /Solvers/MFEMGMRESSolver
 
-!syntax inputs /Solver/MFEMGMRESSolver
+!syntax inputs /Solvers/MFEMGMRESSolver
 
-!syntax children /Solver/MFEMGMRESSolver
+!syntax children /Solvers/MFEMGMRESSolver
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMHypreADS.md

@@ -10,18 +10,18 @@ Raviart-Thomas elements, in which case the $H(\mathrm{div})$ FE space should be
 `mfem::HypreADS` solver during construction.
 
 A Low-Order-Refined (LOR) version of this solver may be used instead by setting the parameter
-[!param](/Solver/MFEMHypreADS/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
+[!param](/Solvers/MFEMHypreADS/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
 order systems.
 
 ## Example Input File Syntax
 
-!listing test/tests/mfem/kernels/graddiv.i block=FESpace Preconditioner Solver
+!listing test/tests/mfem/kernels/graddiv.i block=FESpace Preconditioner Solvers
 
-!syntax parameters /Solver/MFEMHypreADS
+!syntax parameters /Solvers/MFEMHypreADS
 
-!syntax inputs /Solver/MFEMHypreADS
+!syntax inputs /Solvers/MFEMHypreADS
 
-!syntax children /Solver/MFEMHypreADS
+!syntax children /Solvers/MFEMHypreADS
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMHypreAMS.md

@@ -14,18 +14,18 @@ magnetic vector potential in magnetostatic systems in the steady state - users s
 `singular` parameter to `true` to add a small mass term to ensure solvability.
 
 A Low-Order-Refined (LOR) version of this solver may be used instead by setting the parameter
-[!param](/Solver/MFEMHypreAMS/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
+[!param](/Solvers/MFEMHypreAMS/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
 order systems.
 
 ## Example Input File Syntax
 
-!listing test/tests/mfem/kernels/curlcurl.i block=FESpace Preconditioner Solver
+!listing test/tests/mfem/kernels/curlcurl.i block=FESpace Preconditioner Solvers
 
-!syntax parameters /Solver/MFEMHypreAMS
+!syntax parameters /Solvers/MFEMHypreAMS
 
-!syntax inputs /Solver/MFEMHypreAMS
+!syntax inputs /Solvers/MFEMHypreAMS
 
-!syntax children /Solver/MFEMHypreAMS
+!syntax children /Solvers/MFEMHypreAMS
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMHypreBoomerAMG.md

@@ -7,18 +7,18 @@
 Defines and builds an `mfem::HypreBoomerAMG` solver to use as a preconditioner or solver to solve the MFEM equation system.
 
 A Low-Order-Refined (LOR) version of this solver may be used instead by setting the parameter
-[!param](/Solver/MFEMHypreBoomerAMG/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
+[!param](/Solvers/MFEMHypreBoomerAMG/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
 order systems.
 
 ## Example Input File Syntax
 
-!listing test/tests/mfem/kernels/diffusion.i block=Preconditioner Solver
+!listing test/tests/mfem/kernels/diffusion.i block=Preconditioner Solvers
 
-!syntax parameters /Solver/MFEMHypreBoomerAMG
+!syntax parameters /Solvers/MFEMHypreBoomerAMG
 
-!syntax inputs /Solver/MFEMHypreBoomerAMG
+!syntax inputs /Solvers/MFEMHypreBoomerAMG
 
-!syntax children /Solver/MFEMHypreBoomerAMG
+!syntax children /Solvers/MFEMHypreBoomerAMG
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMHypreFGMRES.md

@@ -9,14 +9,14 @@ Defines and builds an `mfem::HypreFGMRES` solver to use as an iterative solver t
 Not compatible with use on partially assembled equation systems.
 
 A Low-Order-Refined (LOR) version of this solver may be used instead by setting the parameter
-[!param](/Solver/MFEMHypreFGMRES/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
+[!param](/Solvers/MFEMHypreFGMRES/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
 order systems.
 
-!syntax parameters /Solver/MFEMHypreFGMRES
+!syntax parameters /Solvers/MFEMHypreFGMRES
 
-!syntax inputs /Solver/MFEMHypreFGMRES
+!syntax inputs /Solvers/MFEMHypreFGMRES
 
-!syntax children /Solver/MFEMHypreFGMRES
+!syntax children /Solvers/MFEMHypreFGMRES
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMHypreGMRES.md

@@ -10,14 +10,14 @@ equation system.
 Not compatible with use on partially assembled equation systems.
 
 A Low-Order-Refined (LOR) version of this solver may be used instead by setting the parameter
-[!param](/Solver/MFEMHypreGMRES/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
+[!param](/Solvers/MFEMHypreGMRES/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
 order systems.
 
-!syntax parameters /Solver/MFEMHypreGMRES
+!syntax parameters /Solvers/MFEMHypreGMRES
 
-!syntax inputs /Solver/MFEMHypreGMRES
+!syntax inputs /Solvers/MFEMHypreGMRES
 
-!syntax children /Solver/MFEMHypreGMRES
+!syntax children /Solvers/MFEMHypreGMRES
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMHyprePCG.md

@@ -9,14 +9,14 @@ Defines and builds an `mfem::HyprePCG` solver to use as an iterative solver to s
 Not compatible with use on partially assembled equation systems.
 
 A Low-Order-Refined (LOR) version of this solver may be used instead by setting the parameter
-[!param](/Solver/MFEMHyprePCG/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
+[!param](/Solvers/MFEMHyprePCG/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
 order systems.
 
-!syntax parameters /Solver/MFEMHyprePCG
+!syntax parameters /Solvers/MFEMHyprePCG
 
-!syntax inputs /Solver/MFEMHyprePCG
+!syntax inputs /Solvers/MFEMHyprePCG
 
-!syntax children /Solver/MFEMHyprePCG
+!syntax children /Solvers/MFEMHyprePCG
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMMUMPS.md

@@ -6,11 +6,11 @@
 
 Defines and builds an `mfem::MUMPSSolver` to use as a direct solver to solve the MFEM equation system.
 
-!syntax parameters /Solver/MFEMMUMPS
+!syntax parameters /Solvers/MFEMMUMPS
 
-!syntax inputs /Solver/MFEMMUMPS
+!syntax inputs /Solvers/MFEMMUMPS
 
-!syntax children /Solver/MFEMMUMPS
+!syntax children /Solvers/MFEMMUMPS
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMNewtonNonlinearSolver.md

@@ -0,0 +1,23 @@
+# MFEMNewtonNonlinearSolver
+
+!if! function=hasCapability('mfem')
+
+## Overview
+
+Defines and builds an `mfem::NewtonSolver` to solve nonlinear MFEM equation systems.
+
+This solver requires Jacobian information from the MFEM operator and uses the externally configured
+MFEM linear solver for the inner linear solves.
+
+Define this object in the [`Solvers`](syntax/Solvers/index.md) block.
+
+!syntax parameters /Solvers/MFEMNewtonNonlinearSolver
+
+!syntax inputs /Solvers/MFEMNewtonNonlinearSolver
+
+!syntax children /Solvers/MFEMNewtonNonlinearSolver
+
+!if-end!
+
+!else
+!include mfem/mfem_warning.md

framework/doc/content/source/mfem/solvers/MFEMOperatorJacobiSmoother.md

@@ -8,14 +8,14 @@ Defines and builds an `mfem::OperatorJacobiSmoother` solver to use to perform Ja
 the MFEM equation system. Most often used as a preconditioner, compatible with partial assembly.
 
 A Low-Order-Refined (LOR) version of this solver may be used instead by setting the parameter
-[!param](/Solver/MFEMOperatorJacobiSmoother/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
+[!param](/Solvers/MFEMOperatorJacobiSmoother/low_order_refined) to `true`. Using an LOR solver improves performance for high polynomial
 order systems.
 
-!syntax parameters /Solver/MFEMOperatorJacobiSmoother
+!syntax parameters /Solvers/MFEMOperatorJacobiSmoother
 
-!syntax inputs /Solver/MFEMOperatorJacobiSmoother
+!syntax inputs /Solvers/MFEMOperatorJacobiSmoother
 
-!syntax children /Solver/MFEMOperatorJacobiSmoother
+!syntax children /Solvers/MFEMOperatorJacobiSmoother
 
 !if-end!
 

framework/doc/content/source/mfem/solvers/MFEMPetscNonlinearSolver.md

@@ -0,0 +1,27 @@
+# MFEMPetscNonlinearSolver
+
+!if! function=hasCapability('mfem')
+
+## Overview
+
+Defines and builds an `mfem::PetscNonlinearSolver` to solve nonlinear MFEM equation systems
+through PETSc SNES.
+
+This solver currently requires Jacobian information from the MFEM operator and manages its own
+internal PETSc KSP/PC stack rather than using an external MFEM linear solver.
+
+PETSc options may be supplied through the object parameters, and `petsc_options_prefix` controls
+the prefix applied to the owned SNES object and its sub-objects.
+
+Define this object in the [`Solvers`](syntax/Solvers/index.md) block.
+
+!syntax parameters /Solvers/MFEMPetscNonlinearSolver
+
+!syntax inputs /Solvers/MFEMPetscNonlinearSolver
+
+!syntax children /Solvers/MFEMPetscNonlinearSolver
+
+!if-end!
+
+!else
+!include mfem/mfem_warning.md

framework/doc/content/source/mfem/solvers/MFEMSuperLU.md

@@ -6,11 +6,11 @@
 
 Defines and builds an `mfem::SuperLUSolver` to use as a direct solver to solve the MFEM equation system.
 
-!syntax parameters /Solver/MFEMSuperLU
+!syntax parameters /Solvers/MFEMSuperLU
 
-!syntax inputs /Solver/MFEMSuperLU
+!syntax inputs /Solvers/MFEMSuperLU
 
-!syntax children /Solver/MFEMSuperLU
+!syntax children /Solvers/MFEMSuperLU
 
 !if-end!
 

framework/doc/content/syntax/MFEM/index.md

@@ -69,11 +69,11 @@ Now we set up boundary conditions. Here, we choose scalar Dirichlet boundary con
 
 ### Solver and Executioner
 
-With the equation system set up, we specify how it is to be solved. Firstly, we choose a preconditioner and solver. For problems with high polynomial order, setting [!param](/Solver/MFEMHypreGMRES/low_order_refined) to `true` may greatly increase performance, as explained [here](MFEMSolverBase.md).
+With the equation system set up, we specify how it is to be solved. Firstly, we choose a preconditioner and solver. For problems with high polynomial order, setting [!param](/Solvers/MFEMHypreGMRES/low_order_refined) to `true` may greatly increase performance, as explained [here](MFEMSolverBase.md).
 
 While in principle any solver may be used as the main solver or preconditioner, the main limitation to keep in mind is that Hypre solvers may only be preconditioned by other Hypre solvers. Furthermore, when a Hypre solver has its `low_order_refined` parameter set to `true`, it ceases to be considered a Hypre solver for preconditioning purposes.
 
-!listing test/tests/mfem/kernels/diffusion.i block=/Preconditioner Solver remove=jacobi
+!listing test/tests/mfem/kernels/diffusion.i block=/Preconditioner Solvers remove=jacobi
 
 Static and time-dependent executioners may be implemented respectively with the [MFEMSteady.md] and [MFEMTransient.md] types. If MFEM-MOOSE has been built with GPU offloading capabilities, it is possible to set [!param](/Executioner/MFEMSteady/device) to `cuda` or `hip` to make use of GPU acceleration. For GPU runs, it is advisable to choose an [!param](/Executioner/MFEMSteady/assembly_level) other than `legacy`, otherwise the matrix assembly step will not be offloaded. The options for [!param](/Executioner/MFEMSteady/assembly_level) are `legacy`, `full`, `element`, `partial`, and `none` (the latter is only available if MFEM-MOOSE has been built with libCEED support).
 

framework/doc/content/syntax/Solvers/index.md

@@ -0,0 +1,71 @@
+# Solvers
+
+The `Solvers` syntax defines named solver objects for a simulation.
+Each sub-block under `Solvers` constructs one solver MooseObject and
+adds it to the problem during action setup.
+
+For MFEM-based problems, solver objects are used to configure both:
+
+- linear solves, such as Krylov methods
+- nonlinear solves, such as Newton and PETSc SNES-backed solvers
+
+This syntax replaces the older singular `Solver` block. The plural
+form is more flexible because a problem may need more than one solver
+object at a time. Common examples include:
+
+- a linear solver together with a preconditioner
+- a nonlinear solver that drives the global solve and a separate linear
+  solver used for Jacobian solves
+
+## Structure
+
+Each child block under `Solvers` names one solver object:
+
+```text
+[Solvers]
+  [linear]
+    type = MFEMHypreGMRES
+    preconditioner = amg
+    l_tol = 1e-12
+  []
+  [nonlinear]
+    type = MFEMNewtonNonlinearSolver
+    rel_tol = 1e-8
+    abs_tol = 1e-10
+  []
+[]
+```
+
+The child block name is the object name. The `type` selects the solver
+class and therefore the valid parameters for that block.
+
+## MFEM Usage
+
+For MFEM problems, solver objects are created through
+`AddMFEMSolverAction` and stored directly on the `MFEMProblem`. Linear
+and nonlinear solver objects share the same top-level syntax, but they
+play different roles at solve time:
+
+- linear solver objects wrap `mfem::Solver` implementations used for
+  assembled linear systems
+- nonlinear solver objects wrap nonlinear MFEM solve strategies, such
+  as `mfem::NewtonSolver` or `mfem::PetscNonlinearSolver`
+
+Some nonlinear solvers also depend on a separate linear solver. For
+example, Newton requires a Jacobian solve. Others, such as the current
+PETSc nonlinear wrapper, manage their own internal linear solver stack.
+
+## Why This Exists
+
+The old singular `Solver` syntax encoded the assumption that an MFEM
+input would have one distinguished solver block. That stopped scaling
+once MFEM nonlinear solver objects were added, because the problem
+could legitimately require multiple solver objects at once. Moving to
+`Solvers` makes the syntax consistent with that reality and keeps the
+solver configuration extensible.
+
+## See Also
+
+- [MFEM solver base class](source/mfem/solvers/MFEMSolverBase.md)
+- [MFEM Newton nonlinear solver](source/mfem/solvers/MFEMNewtonNonlinearSolver.md)
+- [MFEM PETSc nonlinear solver](source/mfem/solvers/MFEMPetscNonlinearSolver.md)