Merge pull request #32701 from lindsayad/mfem-object-refactor-31434

Refactor MFEM objects away from MFEMGeneralUserObject

Author: nmnobre

framework/doc/content/source/mfem/auxkernels/MFEMAuxKernel.md

@@ -8,12 +8,12 @@ Base class for MFEM auxkernels used to evaluate real auxiliary variables to the
 
 ## Overview
 
-MFEM auxkernels are responsible for updating real auxiliary variables in the system, during pre- or
-post-processing steps.
+MFEM auxkernels are responsible for updating real auxiliary variables in the system during MFEM
+execution passes.
 
-An `MFEMAuxKernel` is derived from `MFEMGeneralUserObject`, and thus the order of their execution
-can be controlled similar to other MOOSE UserObjects using the `execution_order_group` input
-parameter.
+An `MFEMAuxKernel` is derived from `MFEMExecutedObject`. Its ordering relative to other MFEM
+executed objects is determined automatically from detected data dependencies rather than by manual
+execution groups.
 
 `MFEMAuxKernel` is a base class. Derived classes should override the `execute`
  method to update the `_result_var` during execution.

framework/doc/content/source/mfem/auxkernels/MFEMComplexAuxKernel.md

@@ -8,12 +8,12 @@ Base class for MFEM auxkernels used to evaluate complex auxiliary variables to t
 
 ## Overview
 
-Complex MFEM auxkernels are responsible for updating complex auxiliary variables in the system, during pre- or
-post-processing steps.
+Complex MFEM auxkernels are responsible for updating complex auxiliary variables in the system
+during MFEM execution passes.
 
-An `MFEMComplexAuxKernel` is derived from `MFEMGeneralUserObject`, and thus the order of their execution
-can be controlled similar to other MOOSE UserObjects using the `execution_order_group` input
-parameter.
+An `MFEMComplexAuxKernel` is derived from `MFEMExecutedObject`. Its ordering relative to other MFEM
+executed objects is determined automatically from detected data dependencies rather than by manual
+execution groups.
 
 `MFEMComplexAuxKernel` is a base class. Derived classes should override the `execute`
  method to update the `_result_var` during execution.

framework/doc/content/source/mfem/base/MFEMExecutedObject.md

@@ -0,0 +1,63 @@
+# MFEMExecutedObject
+
+!if! function=hasCapability('mfem')
+
+## Overview
+
+`MFEMExecutedObject` is the base class for MFEM objects that are scheduled and executed by
+[MFEMProblem](problem/MFEMProblem.md) during a solve. It derives from
+[MFEMObject](base/MFEMObject.md), `SetupInterface`, and `DependencyResolverInterface`.
+
+## Execution ordering
+
+Execution order among `MFEMExecutedObject` instances is determined automatically by
+`DependencyResolverInterface`: the MFEM scheduler builds a dependency graph from the variable,
+postprocessor, and vector postprocessor names that each object declares it consumes or produces,
+then performs a topological sort.
+
+Derived class authors register dependency-bearing parameters at `validParams` time using the
+provided helpers:
+
+- `addDependencyParam<T>` — adds an optional parameter whose value names a consumed resource.
+- `addRequiredDependencyParam<T>` — adds a required parameter whose value names a consumed resource.
+
+The template parameter `T` must be one of `VariableName`, `std::vector<VariableName>`,
+`PostprocessorName`, `std::vector<PostprocessorName>`, `VectorPostprocessorName`, or
+`std::vector<VectorPostprocessorName>`. The scheduler infers the resource category from the type.
+
+The resource supplied by this object is declared by overriding one of:
+
+- `suppliedVariableName()` — name of the MFEM variable written by this object.
+- `suppliedPostprocessorName()` — name of the postprocessor written by this object.
+- `suppliedVectorPostprocessorName()` — name of the vector postprocessor written by this object.
+
+Each returns `std::optional<std::string>`; return `std::nullopt` (the default) if the object supplies no resource in that category.
+
+## Lifecycle methods
+
+Each `MFEMExecutedObject` has three lifecycle methods that `MFEMProblem` calls in order for every
+execution pass:
+
+| Method | Purpose |
+| - | - |
+| `initialize()` | Pre-execution setup (zero accumulators, clear state, etc.). |
+| `execute()` | Main work: read variables/coefficients, write results. |
+| `finalize()` | Post-execution cleanup or reduction (e.g., parallel reduction for postprocessors). |
+
+All three have empty default implementations. Derived classes override whichever they need.
+
+## Derived classes
+
+The following MFEM object types derive from `MFEMExecutedObject`:
+
+- [MFEMAuxKernel](auxkernels/MFEMAuxKernel.md) — updates real auxiliary variables.
+- [MFEMComplexAuxKernel](auxkernels/MFEMComplexAuxKernel.md) — updates complex auxiliary variables.
+- [MFEMPostprocessor](postprocessors/MFEMPostprocessor.md) — computes a scalar quantity.
+- [MFEMVectorPostprocessor](vectorpostprocessors/MFEMVectorPostprocessor.md) — computes an array of values.
+- [MFEMSubMeshTransfer](transfers/MFEMSubMeshTransfer.md) — transfers variable data between a mesh and a submesh.
+- `MFEMInitialCondition` — sets the initial value on an MFEM variable.
+
+!if-end!
+
+!else
+!include mfem/mfem_warning.md

framework/doc/content/source/mfem/base/MFEMObject.md

@@ -0,0 +1,49 @@
+# MFEMObject
+
+!if! function=hasCapability('mfem')
+
+## Overview
+
+`MFEMObject` is the common base class for all MFEM objects. It provides every MFEM object with a
+typed reference to the owning [MFEMProblem](problem/MFEMProblem.md) and a set of helpers for
+retrieving MFEM coefficients by name.
+
+`MFEMObject` also mixes in `FunctionInterface`, `PostprocessorInterface`,
+`VectorPostprocessorInterface`, and `ReporterInterface` so that derived classes can consume MOOSE
+functions, postprocessors, vector postprocessors, and reporters in the normal way.
+
+## Problem access
+
+The `getMFEMProblem()` method returns a typed reference to the owning `MFEMProblem`.
+
+## Coefficient access
+
+MFEM coefficients declared through [MFEMFunctorMaterial](functormaterials/MFEMFunctorMaterial.md)
+objects are stored in the `CoefficientManager` owned by `MFEMProblem`. `MFEMObject` exposes two
+families of accessor methods for them:
+
+| Method | Looks up by |
+| - | - |
+| `getScalarCoefficient(param_name)` | Value of an `MFEMScalarCoefficientName` input parameter |
+| `getVectorCoefficient(param_name)` | Value of an `MFEMVectorCoefficientName` input parameter |
+| `getMatrixCoefficient(param_name)` | Value of an `MFEMMatrixCoefficientName` input parameter |
+| `getScalarCoefficientByName(name)` | Declared coefficient name directly |
+| `getVectorCoefficientByName(name)` | Declared coefficient name directly |
+| `getMatrixCoefficientByName(name)` | Declared coefficient name directly |
+
+The `param_name` variants are the most common: they read the coefficient name from an input
+parameter, so the caller does not need to extract the string itself.
+
+## Derived classes
+
+`MFEMObject` is the root of the MFEM object hierarchy. Direct subclasses include:
+
+- [MFEMExecutedObject](base/MFEMExecutedObject.md) — objects that are scheduled and executed by `MFEMProblem` (aux kernels, postprocessors, transfers, initial conditions, etc.).
+- `MFEMSolverBase` — MFEM linear solver and preconditioner objects.
+- `MFEMKernel` / `MFEMComplexKernel` — weak-form contributions to the equation system.
+- `MFEMBoundaryCondition` — boundary conditions applied to the equation system.
+
+!if-end!
+
+!else
+!include mfem/mfem_warning.md

framework/doc/content/source/mfem/postprocessors/MFEMPostprocessor.md

@@ -8,17 +8,12 @@ Base class for MFEM postprocessors used to evaluate a single scalar.
 
 ## Overview
 
-MFEM postprocessors calculate scalar quantities from the
-(aux)variables, typically after each timestep.
+MFEM postprocessors calculate scalar quantities from the (aux)variables, typically after each
+timestep.
 
-An `MFEMPostprocessor` is derived from `MFEMGeneralUserObject`.
-Therefore, the order of their execution can be controlled similar to other
-MOOSE UserObjects using the `execution_order_group` input parameter, e.g.,
-to require the execution of a postprocessor computing on an [AuxVariable.md]
-strictly after the execution of the [MFEMAuxKernel.md] computing the variable
-field itself. For example:
-
-!listing mfem/kernels/irrotational.i block=AuxKernels Postprocessors/velocity_error
+An `MFEMPostprocessor` is derived from `MFEMExecutedObject`. Its ordering relative to MFEM initial
+conditions, aux kernels, transfers, and other MFEM postprocessors is determined automatically from
+detected data dependencies instead of manual execution groups.
 
 `MFEMPostprocessor` is a purely virtual base class. Derived classes
 should override the `execute` and `getValue` methods.

framework/doc/content/source/mfem/userobjects/MFEMGeneralUserObject.md

@@ -8,15 +8,12 @@ Base class for MFEM vectorpostprocessors used to evaluate an array of values.
 
 ## Overview
 
-MFEM vectorpostprocessors calculate an array of values from the (aux)variables,
-typically after each timestep.
-
-An `MFEMVectorPostprocessor` is derived from `MFEMGeneralUserObject`.
-Therefore, the order of their execution can be controlled similar to other
-MOOSE UserObjects using the `execution_order_group` input parameter, e.g., to
-require the execution of a vectorpostprocessor computing on an [AuxVariable.md]
-strictly after the execution of the [MFEMAuxKernel.md] computing the variable
-field itself.
+MFEM vectorpostprocessors calculate an array of values from the (aux)variables, typically after
+each timestep.
+
+An `MFEMVectorPostprocessor` is derived from `MFEMExecutedObject`. Its ordering relative to other
+MFEM executed objects is determined automatically from detected data dependencies instead of manual
+execution groups.
 
 `MFEMVectorPostprocessor` is a virtual base class. Derived classes should use
 the `VectorPostprocessor::declareVector` method to get a reference to a vector

framework/doc/content/source/mfem/vectorpostprocessors/MFEMVectorPostprocessor.md

@@ -157,8 +157,8 @@ class MooseBase : public ConsoleStreamInterface
   /**
    * Query a parameter for the object
    *
-   * If the parameter is not valid, nullptr will be returned
-   *
+   * If a parameter of the given name and type does not exist or if the
+   * parameter is not valid, nullptr will be returned
    * @param name The name of the parameter
    * @return A pointer to the parameter value, if it exists
    */
@@ -192,6 +192,16 @@ class MooseBase : public ConsoleStreamInterface
   template <typename T>
   T getCheckedPointerParam(const std::string & name, const std::string & error_string = "") const;
 
+  /**
+   * Test if a parameter of the given name and type exists
+   * @param name The name of the parameter to test
+   */
+  template <typename T>
+  inline bool haveParameter(const std::string & name) const
+  {
+    return _pars.have_parameter<T>(name);
+  }
+
   /**
    * Test if the supplied parameter is valid
    * @param name The name of the parameter to test
@@ -412,7 +422,7 @@ template <typename T>
 const T *
 MooseBase::queryParam(const std::string & name) const
 {
-  return isParamValid(name) ? &getParam<T>(name) : nullptr;
+  return haveParameter<T>(name) && isParamValid(name) ? &getParam<T>(name) : nullptr;
 }
 
 template <typename T>

framework/include/base/MooseBase.h

@@ -65,6 +65,11 @@ class DependencyResolverInterface
   /**
    * A helper method for cyclic errors.
    */
+  template <typename T, typename T2, typename NameFunc>
+  static void cyclicDependencyError(CyclicDependencyException<T2> & e,
+                                    const std::string & header,
+                                    NameFunc && name_func);
+
   template <typename T, typename T2>
   static void cyclicDependencyError(CyclicDependencyException<T2> & e, const std::string & header);
 };
@@ -124,18 +129,27 @@ DependencyResolverInterface::sortDFS(typename std::vector<T> & vector)
   vector = sorted;
 }
 
-template <typename T, typename T2>
+template <typename T, typename T2, typename NameFunc>
 void
 DependencyResolverInterface::cyclicDependencyError(CyclicDependencyException<T2> & e,
-                                                   const std::string & header)
+                                                   const std::string & header,
+                                                   NameFunc && name_func)
 {
   std::ostringstream oss;
 
   oss << header << ":\n";
   const auto cycle = e.getCyclicDependencies();
   std::vector<std::string> names(cycle.size());
   for (const auto i : index_range(cycle))
-    names[i] = static_cast<T>(cycle[i])->name();
+    names[i] = name_func(cycle[i]);
   oss << MooseUtils::join(names, " <- ");
   mooseError(oss.str());
 }
+
+template <typename T, typename T2>
+void
+DependencyResolverInterface::cyclicDependencyError(CyclicDependencyException<T2> & e,
+                                                   const std::string & header)
+{
+  cyclicDependencyError<T>(e, header, [](const auto & obj) { return static_cast<T>(obj)->name(); });
+}

framework/include/interfaces/DependencyResolverInterface.h

@@ -11,13 +11,13 @@
 
 #pragma once
 
-#include "MFEMGeneralUserObject.h"
+#include "MFEMExecutedObject.h"
 #include "MFEMContainers.h"
 
 /**
  * Class to construct an auxiliary solver used to update a real auxvariable.
  */
-class MFEMAuxKernel : public MFEMGeneralUserObject
+class MFEMAuxKernel : public MFEMExecutedObject
 {
 public:
   static InputParameters validParams();
@@ -26,7 +26,9 @@ class MFEMAuxKernel : public MFEMGeneralUserObject
   virtual ~MFEMAuxKernel() = default;
 
   /// Method called to update any owned objects upon an FE space update
-  virtual void update() {};
+  virtual void update() {}
+
+  virtual std::optional<std::string> suppliedVariableName() const override;
 
 protected:
   /// Name of auxvariable to store the result of the auxkernel in.