Merge pull request idaholab#28964 from joshuahansel/chain-controls

Added the ChainControl system

framework/doc/content/source/actions/AddChainControlAction.md

@@ -0,0 +1,5 @@
+# AddChainControlAction
+
+This action adds a [ChainControl](syntax/ChainControls/index.md) to the `ControlWarehouse`.
+
+!syntax parameters /ChainControls/AddChainControlAction

framework/doc/content/source/actions/ChainControlSetupAction.md

@@ -0,0 +1,12 @@
+# ChainControlSetupAction
+
+This [Action.md] is responsible for setup and checks that should occur after
+all [ChainControls](syntax/ChainControls/index.md) have been added. It does
+the following:
+
+- Checks that all requested [/ChainControlData.md] has been declared and throws
+  an error if not.
+- Calls `init()` on all `ChainControls`.
+- Adds dependencies for each `ChainControl` on other `ChainControls` based on
+  the dependencies of the `ChainControlData`; if the `ChainControl` depends on
+  a `ChainControlData`, then it depends on the `ChainControl` that declared that data.

framework/doc/content/source/base/ChainControlDataSystem.md

@@ -0,0 +1,11 @@
+# ChainControlDataSystem
+
+The `ChainControlDataSystem` manages [/ChainControlData.md] objects and provides
+interfaces to do the following:
+
+- Check if control data exists (and if it has a certain type).
+- Get control data
+- Declare control data
+
+This object is owned by [/MooseApp.md], which provides a `getChainControlDataSystem()`
+method to get it.

framework/doc/content/source/chaincontrols/ChainControlData.md

@@ -0,0 +1,4 @@
+# ChainControlData
+
+`ChainControlData` is used in the [ChainControls system](syntax/ChainControls/index.md).
+Each `ChainControlData` has a unique name and some type.

framework/doc/content/source/chaincontrols/GetFunctionValueChainControl.md

@@ -0,0 +1,12 @@
+# GetFunctionValueChainControl
+
+This [ChainControl](syntax/ChainControls/index.md) creates a new [/ChainControlData.md]
+named `<control>:value`, where `<control>` is the name of the `ChainControl`
+object, and it computes its value by evaluating a given [Function](syntax/Functions/index.md)
+at the current time and a given point in space.
+
+!syntax parameters /ChainControls/GetFunctionValueChainControl
+
+!syntax inputs /ChainControls/GetFunctionValueChainControl
+
+!syntax children /ChainControls/GetFunctionValueChainControl

framework/doc/content/source/chaincontrols/GetPostprocessorChainControl.md

@@ -0,0 +1,17 @@
+# GetPostprocessorChainControl
+
+This [ChainControl](syntax/ChainControls/index.md) copies the current value of a
+[Postprocessor](syntax/Postprocessors/index.md) into a [/ChainControlData.md] of
+type `Real`. This data will be named as `<control>:value`, where `<control>`
+is the user-given name of the control, unless
+[!param](/ChainControls/GetPostprocessorChainControl/name_data_same_as_postprocessor)
+is set to `true`, in which case the data is named the same as the post-processor.
+
+Note that modification
+of this `ChainControlData` does not modify the value of the original post-processor.
+
+!syntax parameters /ChainControls/GetPostprocessorChainControl
+
+!syntax inputs /ChainControls/GetPostprocessorChainControl
+
+!syntax children /ChainControls/GetPostprocessorChainControl

framework/doc/content/source/chaincontrols/ParsedChainControl.md

@@ -0,0 +1,15 @@
+# ParsedChainControl
+
+This [ChainControl](syntax/ChainControls/index.md) allows the user to specify
+a function expression to be parsed and evaluated to populate a new [/ChainControlData.md]
+named `<control>:value`, where `<control>` is the user-given name of the control.
+
+See [ChainControlParsedFunctionWrapper.md] for a list of acceptable types of
+values for the entries in [!param](/ChainControls/ParsedChainControl/symbol_values)
+and acceptable syntax for [!param](/ChainControls/ParsedChainControl/expression).
+
+!syntax parameters /ChainControls/ParsedChainControl
+
+!syntax inputs /ChainControls/ParsedChainControl
+
+!syntax children /ChainControls/ParsedChainControl

framework/doc/content/source/chaincontrols/SetValueChainControl.md

@@ -0,0 +1,23 @@
+# SetValueChainControl
+
+## SetRealValueChainControl
+
+This [ChainControl](syntax/ChainControls/index.md) sets the value of one or
+more parameters of type `Real` from a `Real`-valued [/ChainControlData.md].
+
+!syntax parameters /ChainControls/SetRealValueChainControl
+
+!syntax inputs /ChainControls/SetRealValueChainControl
+
+!syntax children /ChainControls/SetRealValueChainControl
+
+## SetBoolValueChainControl
+
+This [ChainControl](syntax/ChainControls/index.md) sets the value of one or
+more parameters of type `bool` from a `bool`-valued [/ChainControlData.md].
+
+!syntax parameters /ChainControls/SetBoolValueChainControl
+
+!syntax inputs /ChainControls/SetBoolValueChainControl
+
+!syntax children /ChainControls/SetBoolValueChainControl

framework/doc/content/source/functions/ChainControlParsedFunctionWrapper.md

@@ -0,0 +1,17 @@
+# ChainControlParsedFunctionWrapper
+
+This class wraps `libMesh::ParsedFunction` for use of various parsed
+[ChainControls](syntax/ChainControls/index.md).
+
+For valid syntax for the function expression, see the
+[function parser site](http://warp.povusers.org/FunctionParser/).
+
+The user-defined symbols may include the following:
+
+- `bool` or `Real` [/ChainControlData.md]
+- [Functions](syntax/Functions/index.md)
+- Scalar variables
+- Constant values
+
+Pre-defined symbols that may be used in the function expression are `x`, `y`, `z`, and `t`,
+representing the corresponding spatial coordinates and time value.

framework/doc/content/source/postprocessors/ChainControlDataPostprocessor.md

@@ -0,0 +1,16 @@
+# ChainControlDataPostprocessor
+
+This [Postprocessor](syntax/Postprocessors/index.md) gets the current value of a
+[/ChainControlData.md], which may be of type `Real` or `bool`. For `bool`,
+a value of `true` converts to "1.0", and a value of `bool` converts to "0.0".
+
+!alert warning title=A lag may be present
+Within an execution step, [Controls](syntax/Controls/index.md) are executed
+*before* post-processors, except for `INITIAL`, so depending on the sequence
+of executions, a lag may be present.
+
+!syntax parameters /Postprocessors/ChainControlDataPostprocessor
+
+!syntax inputs /Postprocessors/ChainControlDataPostprocessor
+
+!syntax children /Postprocessors/ChainControlDataPostprocessor

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

@@ -0,0 +1,25 @@
+# ChainControls System
+
+The `ChainControls` system is an extension of the [Controls system](syntax/Controls/index.md)
+that uses `ChainControl` objects, which instead of working directly with
+controllable parameters, work with an additional layer of "control data",
+[/ChainControlData.md]. `ChainControl` objects can do the following:
+
+- Declare new control data
+- Retrieve control data declared elsewhere
+- Change control data values
+- Set controllable parameters in MOOSE objects using control data
+
+The main advantage of this additional capability is to chain control operations together,
+which is useful for composing complex control systems.
+
+`ChainControlData` is managed by the [/ChainControlDataSystem.md].
+
+## Objects and Associated Actions
+
+!syntax list /ChainControls objects=True actions=False subsystems=False
+
+!syntax list /ChainControls objects=False actions=False subsystems=True
+
+!syntax list /ChainControls objects=False actions=True subsystems=False
+

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

@@ -1,36 +1,50 @@
 # Controls System
 
-The control system in MOOSE has one primary purpose: +to modify input parameters during runtime
+The Controls system in MOOSE has one primary purpose: +to modify input parameters during runtime
 of a MOOSE-based simulation+.
 
-## Creating a Controllable Parameter id=sec:control-param
+If a developer has marked a MOOSE object input parameter as *controllable*, that
+parameter may be controlled during a simulation using `Control` objects.
+`Control` objects are defined in the input file in the `Controls` block, similar to other systems
+in MOOSE. For example, the following input file snippet shows the use of the
+[RealFunctionControl](/RealFunctionControl.md) object.
 
-The input parameters of objects you which to be controlled must:
+!listing test/tests/controls/real_function_control/real_function_control.i
+         block=Kernels Controls
+         id=controls_example
+         caption=Example of a Control object used in a MOOSE input file.
 
-- Store parameter as a `const` reference; in your *.h files, declare storage for the parameters as
-  follows.
+Here, `func_control` controls the `coef` parameter of the `diff` object. See
+[#object-and-parameter-names] for the allowable syntax to specify controlled
+parameters.
 
-  !listing framework/include/bcs/DirichletBC.h line=_value
+## Making a Parameter Controllable id=sec:control-param
 
-- Initialize the reference in the *.C file as follows.
+The input parameters of objects you wish to be controlled must:
 
-  !listing framework/src/bcs/DirichletBC.C line=_value(getParam
+- Be marked as "controllable". In the `validParams()` method for the class,
+  the `InputParameters::declareControllable(param_names)` method is used as
+  shown in [declare_controllable_listing]. Note that `param_names` may be a
+  list of parameter names separated by spaces, e.g., `"param1 param2 param3"`.
 
-In order to "control" a parameter it must be communicated that the parameter is allowed to be
-controlled, this is done in the `validParams` function as in [declare_controllable]. The input can
-be a single value or a space separated list of parameters.
+  !listing framework/src/bcs/DirichletBC.C
+          start=InputParameters
+          end=DirichletBC::DirichletBC
+          id=declare_controllable_listing
+          caption=Example `validParams` method that declares a parameter as controllable.
+- Be stored as `const` references; for example, in the `.h` file,
 
-!listing framework/src/bcs/DirichletBC.C
-         start=InputParameters
-         end=DirichletBC::DirichletBC
-         id=declare_controllable
-         caption=Example `validParams` method that declares a parameter as controllable.
+  !listing framework/include/bcs/DirichletBC.h line=_value
+
+  which is initialized in the `.C` file using `getParam<T>(param)`, as usual:
+
+  !listing framework/src/bcs/DirichletBC.C line=_value(getParam
 
-!alert tip
-The documentation for a given parameter will indicate whether it is controllable. For example, see
-the [DirichletBC](source/bcs/DirichletBC.md#input-parameters) page.
+!alert tip title=Parameter controllability listed on documentation pages
+Each class documentation page lists whether each of its input parameters are controllable.
+For example, see the [DirichletBC](source/bcs/DirichletBC.md#input-parameters) page.
 
-## Create a Control object
+## Developing a New Control
 
 `Control` objects are similar to other systems in MOOSE. You create a control in your application
 by inheriting from the `Control` C++ class in MOOSE. It is required to override the `execute`
@@ -54,38 +68,20 @@ There are additional overloaded methods that allow for the setting and getting o
 with various inputs for prescribing the parameter name, but the two listed above are generally
 what is needed.  Please refer to the source code for a complete list.
 
-## Controls Block
-
-`Control` objects are defined in the input file in the Controls block, similar to other systems
-in MOOSE. For example, the following input file snippet shows the use of the
-[RealFunctionControl](/RealFunctionControl.md) object.
-
-!listing test/tests/controls/real_function_control/real_function_control.i
-         block=Controls
-         id=controls_example
-         caption=Example of a Control object used in a MOOSE input file.
-
 ## Object and Parameter Names id=object-and-parameter-names
 
-Notice that in [controls_example] the syntax for specifying a parameter is shown. In general,
-the syntax for a parameter name is specified as: `block/object/name`.
-
-- +`block`+: specifies the input file block name (e.g., "[Kernels]", "[BCs]").
-- +`object`+: specifies the input file sub-block name (e.g., "diff" in [controls_example2]).
-- +`name`+: specifies the parameter name (e.g., "coef" in [controls_example2]).
-
-!listing test/tests/controls/real_function_control/real_function_control.i
-         block=Kernels
-         id=controls_example2
-         caption=Example of a "Kernel" block that contains a parameter that is controlled via a
-                 MOOSE Control object.
-
-As shown in [controls_example] an asterisk ("*") can be substituted for any one of these three
-"names", doing so allows multiple parameters to match and be controlled simultaneously.
+The objective of a `Control` object is to control parameters of one or more other
+objects; these parameters to control are specified by input parameters of the `Control`.
+[controls_example] shows an example syntax for specifying input parameters in the
+`parameter` parameter. In this example, `*/*/coef` is specified, which would
+match any controllable parameter named `coef` at that nesting level. In the example, there
+is only one parameter that the pattern matches, so `Kernels/diff/coef` would
+be equivalent. The "/"-separated path preceding the parameter name corresponds
+to the syntax blocks under which the parameter is located, such as for the system name and object name.
 
 In similar fashion, object names can be requested by controls (e.g., as in the
-[`TimePeriod`](/TimePeriod.md)). In this case, the general name scheme is the same
-as above but the parameter name is not included.
+[`TimePeriod`](/TimePeriod.md)). In this case, the general naming scheme is the same
+as above but the parameter name is not included, e.g., `Kernels/diff`.
 
 In both cases there is an alternative form for defining an object and parameter names:
 `base::object/name`. In this case "base" is the MOOSE base system that the object is derived from.

framework/include/actions/AddChainControlAction.h

@@ -0,0 +1,23 @@
+//* 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 "AddControlAction.h"
+
+/**
+ * Adds a ChainControl to the control warehouse.
+ */
+class AddChainControlAction : public AddControlAction
+{
+public:
+  static InputParameters validParams();
+
+  AddChainControlAction(const InputParameters & parameters);
+};

framework/include/actions/ChainControlSetupAction.h

@@ -0,0 +1,25 @@
+//* 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 "Action.h"
+
+/**
+ * Performs various setup tasks and checks for ChainControls.
+ */
+class ChainControlSetupAction : public Action
+{
+public:
+  static InputParameters validParams();
+
+  ChainControlSetupAction(const InputParameters & parameters);
+
+  virtual void act() override;
+};