Controls System
The Controls system in MOOSE has one primary purpose: to modify input parameters during runtime of a MOOSE-based simulation.
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 object.
[Kernels]
[./diff]
type = CoefDiffusion
variable = u
coef = 0.1
[../]
[./time]
type = TimeDerivative
variable = u
[../]
[]
[Controls]
[./func_control]
type = RealFunctionControl
parameter = '*/*/coef'
function = 'func_coef'
execute_on = 'initial timestep_begin'
[../]
[]
(moose/test/tests/controls/real_function_control/real_function_control.i)Here, func_control
controls the coef
parameter of the diff
object. See Object and Parameter Names for the allowable syntax to specify controlled parameters.
Making a Parameter Controllable
The input parameters of objects you wish to be controlled must:
Be marked as "controllable". In the
validParams()
method for the class, theInputParameters::declareControllable(param_names)
method is used as shown in Listing 6. Note thatparam_names
may be a list of parameter names separated by spaces, e.g.,"param1 param2 param3"
.
(moose/framework/src/bcs/DirichletBC.C)InputParameters DirichletBC::validParams() { InputParameters params = DirichletBCBase::validParams(); params.addRequiredParam<Real>("value", "Value of the BC"); params.declareControllable("value"); params.addClassDescription("Imposes the essential boundary condition $u=g$, where $g$ " "is a constant, controllable value."); return params; }
Be stored as
const
references; for example, in the.h
file,
(moose/framework/include/bcs/DirichletBC.h)const Real & _value;
which is initialized in the
.C
file usinggetParam<T>(param)
, as usual:
(moose/framework/src/bcs/DirichletBC.C): DirichletBCBase(parameters), _value(getParam<Real>("value"))
Each class documentation page lists whether each of its input parameters are controllable. For example, see the DirichletBC page.
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
method in your custom object. Within this method the following methods are generally used to get or set controllable parameters:
getControllableValue
<br> This method returns the current controllable parameter, in the case that multiple parameters are being controlled, only the first value will be returned and a warning will be produced if the values are differ (this warning may be disabled).setControllableValue
<br> This method allows for a controllable parameter to be changed, in the case that multiple parameters are being controlled, all of the values will be set.
These methods operator in a similar fashion as other systems in MOOSE (e.g., getPostprocessorValue
in the Postprocessors system), each expects an input parameter name (std::string
) that is prescribed in the validParams
method.
There are additional overloaded methods that allow for the setting and getting of controllable values 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.
Object and Parameter Names
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
. Listing 1 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
). 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. For example, Kernel::diff/coef
. All MOOSE "bases" are listed bellow:
ArrayAuxKernel,
ArrayKernel,
AuxKernel,
AuxScalarKernel,
BoundaryCondition,
Constraint,
Damper,
DGKernel,
DiracKernel,
Distribution,
EigenKernel,
Executioner,
Executor,
Function,
FVBoundaryCondition,
FVInterfaceKernel,
FVKernel,
Indicator,
InitialCondition,
InterfaceKernel,
Kernel,
LineSearch,
Marker,
MaterialBase,
MeshGenerator,
MooseMesh,
MoosePartitioner,
MoosePreconditioner,
MooseVariableBase,
MultiApp,
NodalKernel,
Output,
Postprocessor,
Predictor,
Problem,
RelationshipManager.,
Reporter,
Sampler,
ScalarInitialCondition,
ScalarKernel,
Split,
TimeIntegrator,
TimeStepper,
Transfer,
UserObject,
VectorAuxKernel,
VectorInterfaceKernel,
VectorKernel,
VectorPostprocessor,
MOOSE allows objects to define a tag
name to access its controllable parameters with their control_tags
parameter.
[Postprocessors]
[./test_object]
type = TestControlPointPP
function = '2*(x+y)'
point = '0.5 0.5 0'
control_tags = 'tag'
[../]
[./other_point_test_object]
type = TestControlPointPP
function = '3*(x+y)'
point = '0.5 0.5 0'
control_tags = 'tag'
[../]
[]
(moose/test/tests/controls/tag_based_naming_access/param.i)The two postprocessors in Listing 2 declare the same control tag tag
. Thus their controllable parameter point
can be set by controls simultaneously with tag/*/point
as in Listing 3.
[Controls]
[./point_control]
type = TestControl
test_type = 'point'
parameter = 'tag/*/point'
execute_on = 'initial'
[../]
[]
(moose/test/tests/controls/tag_based_naming_access/param.i)The tag name does not include the object name although the tag name is added by an object. To access a controllable parameter, the syntax is tag/object/name
. Internally, MOOSE adds the input block name as a special tag name.
Controllable Parameters Added by Actions
MOOSE also allows parameters in Actions to be controllable. The procedure for making a parameter in an Action controllable is the same as documented in Making a Parameter Controllable. It is important that this controllable parameter must be directly connected with the parameters of MOOSE objects, such as kernels, materials, etc., using this parameter.
auto params = _factory.getValidParams("GenericConstantArray");
params.set<std::string>("prop_name") = "dc";
params.set<RealEigenVector>("prop_value") =
getParam<RealEigenVector>("diffusion_coefficients");
_problem->addMaterial("GenericConstantArray", "dc", params);
// pass the control to the material by connecting them
(moose/test/src/actions/AddLotsOfDiffusion.C)The action controllable parameter can be referred as usual in an input file. For example,
[Controls]
[setdc]
type = RealVectorFunctionControl
function = dc
parameter = Testing/LotsOfDiffusion/lots/diffusion_coefficients
execute_on = timestep_begin
[]
[]
(moose/test/tests/controls/action_control/action_control_test.i)Child Objects
Available Objects
- Moose App
- BoolFunctionControlSets the value of a 'bool' input parameters to the value of a provided function.
- ConditionalFunctionEnableControlControl for enabling/disabling objects when a function value is true
- PIDTransientControlSets the value of a 'Real' input parameter (or postprocessor) based on a Proportional Integral Derivative control of a postprocessor to match a target a target value.
- RealFunctionControlSets the value of a 'Real' input parameters to the value of a provided function.
- TimePeriodControl the enabled/disabled state of objects with time.
- TimesEnableControlControl for enabling/disabling objects when a certain time is reached.
- WebServerControlStarts a webserver for sending/receiving JSON messages to get data and control a running MOOSE calculation
- Solid Mechanics App
- StepPeriodControl the enabled/disabled state of objects with user-provided simulation steps.
Associated Actions
Available Actions
- Moose App
- AddControlActionAdd a Control object to the simulation.