Add Physics base class and a heat conduction example

framework/doc/content/source/physics/DiffusionCG.md

@@ -0,0 +1,49 @@
+# DiffusionCG
+
+!syntax description /Physics/DiffusionCG/DiffusionCG
+
+See the [DiffusionPhysicsBase.md] documentation for the diffusion equation solved.
+
+## Continuous Galerkin Discretization
+
+The volumetric discretization of the time derivative uses the [TimeDerivative.md] kernel.
+The diffusion term $\nabla \cdot D \nabla u(\vec{x})$ is integrated by parts and represented using:
+- a [Diffusion.md] kernel if no diffusion coefficient is passed
+- a [MatDiffusion.md] kernel if a diffusion coefficient is passed, usually as a [material property](syntax/Materials/index.md)
+
+
+The source term $f$ is added using:
+- a [BodyForce.md] if the source is a constant, a [Postprocessor](syntax/Postprocessors/index.md) or a [Function](syntax/Functions/index.md)
+- a [MatCoupledForce.md] if the force is specified using a material property
+- a [CoupledForce.md] if the source is another type of [functor](syntax/Functors/index.md)
+
+
+The Dirichlet boundary conditions are created using:
+- a [DirichletBC.md] if the boundary value is set to a number
+- a [FunctionDirichletBC.md] if set to a [Function](syntax/Functions/index.md)
+- a [PostprocessorDirichletBC.md] if set to a [Postprocessor](syntax/Postprocessors/index.md)
+- a [FunctorDirichletBC.md] for any other kind of [functor](syntax/Functors/index.md) for the boundary value
+
+
+The Neumann boundary conditions are created using:
+- a [NeumannBC.md] if the flux is set to a number
+- a [FunctionNeumannBC.md] if set to a [Function](syntax/Functions/index.md)
+- a [PostprocessorNeumannBC.md] if set to a [Postprocessor](syntax/Postprocessors/index.md)
+- a [FunctorNeumannBC.md] for any other kind of [functor](syntax/Functors/index.md) for the flux value
+
+
+!alert note
+We could use a [Functor](syntax/Functors/index.md) object to cover every need, but the specialized objects
+are a few percent faster, depending on the case.
+
+!alert note
+The user may switch between using / not using automatic differentiation for the kernel and boundary
+conditions using the [!param](/Physics/DiffusionCG/automatic_differentiation). This parameter is only
+obeyed if the AD/non-AD object exists for the requested diffusivity / source / boundary value functor etc.
+
+
+!syntax parameters /Physics/DiffusionCG/DiffusionCG
+
+!syntax inputs /Physics/DiffusionCG/DiffusionCG
+
+!syntax children /Physics/DiffusionCG/DiffusionCG

framework/doc/content/source/physics/DiffusionFV.md

@@ -0,0 +1,37 @@
+# DiffusionFV
+
+!syntax description /Physics/DiffusionFV/DiffusionFV
+
+See the [DiffusionPhysicsBase.md] documentation for the diffusion equation solved.
+
+## Finite Volume Discretization
+
+The volumetric discretization of the time derivative uses the [FVTimeKernel.md] kernel.
+The diffusion term $\nabla \cdot D \nabla u(\vec{x})$ is integrated by parts and represented using a [FVDiffusion.md] kernel.
+The source term $f$ is added using:
+
+- a [FVBodyForce.md] if the source is a constant, a [Postprocessor](syntax/Postprocessors/index.md) or a [Function](syntax/Functions/index.md)
+- a [FVCoupledForce.md] if the source is another type of [functor](syntax/Functors/index.md)
+
+
+The Dirichlet boundary conditions are created using:
+- a [FVDirichletBC.md] if the boundary value is set to a number
+- a [FVFunctionDirichletBC.md] if set to a [Function](syntax/Functions/index.md)
+- a [FVFunctorDirichletBC.md] for any other kind of [functor](syntax/Functors/index.md) for the boundary value
+
+
+The Neumann boundary conditions are created using:
+- a [FVNeumannBC.md] if the flux is set to a number
+- a [FVFunctionNeumannBC.md] if set to a [Function](syntax/Functions/index.md)
+- a [FVFunctorNeumannBC.md] for any other kind of [functor](syntax/Functors/index.md) for the flux value
+
+
+!alert note
+We could use a [Functor](syntax/Functors/index.md) object to cover every need, but the specialized objects
+are a few percent faster, depending on the case.
+
+!syntax parameters /Physics/DiffusionFV/DiffusionFV
+
+!syntax inputs /Physics/DiffusionFV/DiffusionFV
+
+!syntax children /Physics/DiffusionFV/DiffusionFV

framework/doc/content/source/physics/DiffusionPhysicsBase.md

@@ -0,0 +1,26 @@
+# DiffusionPhysicsBase
+
+This is a base class for the derived [Physics](syntax/Physics/index.md) actions setting up objects
+to solve the diffusion equation with a particular discretization.
+
+The diffusion equation solved is:
+
+!equation
+\dfrac{\partial u}{\partial t} - \nabla \cdot D \nabla u(\vec{x}) - f(\vec{x}) = 0
+
+with Dirichlet boundary conditions:
+
+!equation
+u(\vec{x}) = g
+
+and / or Neumann boundary conditions:
+
+!equation
+D\dfrac{\partial u}{\partial n} = h
+
+over the boundaries specified by the [!param](/Physics/DiffusionFV/dirichlet_boundaries) and
+[!param](/Physics/DiffusionFV/neumann_boundaries) parameters respectively.
+
+The values set at the Dirichlet boundary conditions, $g$, and Neumann boundary conditions, $h$,
+are set by the [!param](/Physics/DiffusionFV/boundary_values) and
+[!param](/Physics/DiffusionFV/boundary_fluxes) respectively.

framework/doc/content/syntax/Physics/DiffusionCG/index.md

@@ -0,0 +1 @@
+../../../source/physics/DiffusionCG.md

framework/doc/content/syntax/Physics/DiffusionFV/index.md

@@ -0,0 +1 @@
+../../../source/physics/DiffusionFV.md

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

@@ -0,0 +1,75 @@
+# Physics system
+
+The `Physics` system is meant to standardize the process of adding an equation and its discretization
+to a simulation. It is based on the [Action system](source/actions/Action.md), with additional APIs
+defined to support the definition of an equation.
+
+## Interaction with Components
+
+The interaction with Components is one of the main goals of the Physics system. Stay tuned for future developments.
+
+## Implementing your own Physics
+
+If you have *not* created the kernels, boundary conditions, and so on, the `Physics` system is not a good place
+to start. You must start with a working implementation of your equations before attempting to create a `Physics` object.
+
+If you do have a working set of kernels, boundary conditions, and other MOOSE objects, that let you solve an equation in MOOSE, you should consider the following before implementing a `Physics`:
+
+- is user-friendliness a priority for the expansion of my work?
+- is the current workflow unsatisfactory in that regard?
+- would creating objects programmatically reduce the potential for user-error while allowing sufficient flexibility?
+
+If the answer is yes to all three, then you may start implementing a `Physics` object for your equation.
+The simple concepts behind the simulation setup in a `Physics` is that the `add<various MOOSE object>` routines
+are all called on the `Physics` and they are all called at the same time in the setup as with a regular input file.
+
+So for example, to make a `DiffusionPhysics` create a finite element diffusion kernel, one can override `addFEKernels` like this:
+
+```
+void
+DiffusionPhysics::addFEKernels()
+{
+  {
+    const std::string kernel_type = "ADDiffusion";
+    InputParameters params = getFactory().getValidParams(kernel_type);
+    params.set<NonlinearVariableName>("variable") = _temperature_name;  // we saved the name of the variable as a class attribute
+    getProblem().addKernel(kernel_type, name() + "_diffusion", params);
+  }
+}
+```
+
+Notice how we use the `PhysicsBase::getFactory()` routine to get access to the `Factory` that will get the parameters we
+need to fill, and the `PhysicsBase::getProblem()` to get access to the `Problem` which stores the objects created.
+
+If you already have an `Action` defined for your physics, converting it to a `Physics` should be fairly straightforward. The principal advantages of doing so are:
+
+- benefit from new APIs implemented in the `Physics` system
+- future ability to leverage the `Components` system to define a complex system
+
+### Advice on implementation
+
+#### Add a lot of checks
+
+Do as much parameter checking as you can. The `PhysicsBase` class defines utilities such as the ones below
+that let you check that the user inputs to your physics are correct.
+
+```
+  void checkParamsBothSetOrNotSet(const std::string & param1, const std::string & param2) const;
+  template <typename T, typename S>
+  void checkVectorParamsSameLength(const std::string & param1, const std::string & param2) const;
+  template <typename T>
+  void checkVectorParamsNoOverlap(const std::vector<std::string> & param_vec) const;
+```
+
+#### Separate the definition of the equation from its discretization
+
+The Physics base class you will create will hold the parameters that are shared between all the
+discretized versions of it.
+
+Physics and spatial discretizations are as separated as we could make them, but they are still very much intertwined. So
+when you are adding a parameter you need to think about:
+
+- is this more tied to the strong form of the equation? If so then it likely belongs in a `XYZPhysicsBase` base class
+- is this more tied to the discretization of the equation? If so then it likely belong in the derived, user-instantiated,
+  `XYZPhysics` class.
+

framework/doc/globals.yml

@@ -12,6 +12,7 @@ Kernels: /Kernels/index.md
 Functions: /Functions/index.md
 Postprocessors: /Postprocessors/index.md
 VectorPostprocessors: /VectorPostprocessors/index.md
+Physics: /Physics/index.md
 Positions: /Positions/index.md
 MultiApps: /MultiApps/index.md
 Samplers: /Samplers/index.md
@@ -21,6 +22,7 @@ Transfers: /Transfers/index.md
 Controls: /Controls/index.md
 Distributions: /Distributions/index.md
 Mesh: /Mesh/index.md
+MeshDivisions: /MeshDivisions/index.md
 Outputs: /syntax/Outputs/index.md
 ScalarKernels: /ScalarKernels/index.md
 FVKernels: /FVKernels/index.md

framework/include/base/Factory.h

@@ -59,7 +59,7 @@ class Factory
    * @param name Name of the object whose parameter we are requesting
    * @return Parameters of the object
    */
-  InputParameters getValidParams(const std::string & name);
+  InputParameters getValidParams(const std::string & name) const;
 
   /**
    * Build an object (must be registered) - THIS METHOD IS DEPRECATED (Use create<T>())
@@ -146,7 +146,7 @@ class Factory
    * Show the appropriate message for deprecated objects
    * @param obj_name Name of the deprecated object
    */
-  void deprecatedMessage(const std::string obj_name);
+  void deprecatedMessage(const std::string obj_name) const;
 
   /**
    * Prints error information when an object is not registered
@@ -177,7 +177,7 @@ class Factory
   std::set<std::string> _constructed_types;
 
   /// Set of deprecated object types that have been printed
-  std::set<std::string> _deprecated_types;
+  mutable std::set<std::string> _deprecated_types;
 
   /// set<label/appname, objectname> used to track if an object previously added is being added
   /// again - which is okay/allowed, while still allowing us to detect/reject cases of duplicate

framework/include/executioners/Executioner.h

@@ -111,7 +111,7 @@ class Executioner : public MooseObject,
   virtual std::string getTimeIntegratorName() const { return std::string(); }
 
   /**
-   * Can be used by subsclasses to call parentOutputPositionChanged()
+   * Can be used by subclasses to call parentOutputPositionChanged()
    * on the underlying FEProblemBase.
    */
   virtual void parentOutputPositionChanged() {}

framework/include/physics/DiffusionCG.h

@@ -0,0 +1,32 @@
+//* This file is part of the MOOSE framework
+//* https://www.mooseframework.org
+//*
+//* All rights reserved, see COPYRIGHT for full restrictions
+//* https://github.com/idaholab/moose/blob/master/COPYRIGHT
+//*
+//* Licensed under LGPL 2.1, please see LICENSE for details
+//* https://www.gnu.org/licenses/lgpl-2.1.html
+
+#pragma once
+
+#include "DiffusionPhysicsBase.h"
+
+/**
+ * Creates all the objects needed to solve a diffusion equation with a continuous Galerkin finite
+ * element discretization
+ */
+class DiffusionCG : public DiffusionPhysicsBase
+{
+public:
+  static InputParameters validParams();
+
+  DiffusionCG(const InputParameters & parameters);
+
+private:
+  virtual void addNonlinearVariables() override;
+  virtual void addFEKernels() override;
+  virtual void addFEBCs() override;
+
+  /// Whether to use automatic differentiation or not
+  const bool _use_ad;
+};

framework/include/physics/DiffusionFV.h

@@ -0,0 +1,30 @@
+//* This file is part of the MOOSE framework
+//* https://www.mooseframework.org
+//*
+//* All rights reserved, see COPYRIGHT for full restrictions
+//* https://github.com/idaholab/moose/blob/master/COPYRIGHT
+//*
+//* Licensed under LGPL 2.1, please see LICENSE for details
+//* https://www.gnu.org/licenses/lgpl-2.1.html
+
+#pragma once
+
+#include "DiffusionPhysicsBase.h"
+
+/**
+ * Creates all the objects needed to solve a diffusion equation with a cell-centered finite
+ * volume discretization
+ */
+class DiffusionFV : public DiffusionPhysicsBase
+{
+public:
+  static InputParameters validParams();
+
+  DiffusionFV(const InputParameters & parameters);
+
+private:
+  virtual void addNonlinearVariables() override;
+  virtual void addFVKernels() override;
+  virtual void addFVBCs() override;
+  virtual InputParameters getAdditionalRMParams() const override;
+};

framework/include/physics/DiffusionPhysicsBase.h

@@ -0,0 +1,40 @@
+//* This file is part of the MOOSE framework
+//* https://www.mooseframework.org
+//*
+//* All rights reserved, see COPYRIGHT for full restrictions
+//* https://github.com/idaholab/moose/blob/master/COPYRIGHT
+//*
+//* Licensed under LGPL 2.1, please see LICENSE for details
+//* https://www.gnu.org/licenses/lgpl-2.1.html
+
+#pragma once
+
+#include "PhysicsBase.h"
+
+#define registerDiffusionPhysicsBaseTasks(app_name, derived_name)                                  \
+  registerPhysicsBaseTasks(app_name, derived_name);                                                \
+  registerMooseAction(app_name, derived_name, "add_preconditioning")
+
+/**
+ * Base class to host all common parameters and attributes of Physics actions to solve the diffusion
+ * equation
+ */
+class DiffusionPhysicsBase : public PhysicsBase
+{
+public:
+  static InputParameters validParams();
+
+  DiffusionPhysicsBase(const InputParameters & parameters);
+
+protected:
+  /// Name of the diffused variable
+  const VariableName & _var_name;
+  /// Boundaries on which a Neumann boundary condition is applied
+  const std::vector<BoundaryName> & _neumann_boundaries;
+  /// Boundaries on which a Dirichlet boundary condition is applied
+  const std::vector<BoundaryName> & _dirichlet_boundaries;
+
+private:
+  /// Add default preconditioning options
+  void addPreconditioning() override;
+};