Controls System

The control system in MOOSE has one primary purpose: to modify input parameters during runtime of a MOOSE-based simulation.

Creating a Controllable Parameter

The input parameters of objects you which to be controlled must:

Store parameter as a const reference; in your *.h files, declare storage for the parameters as follows.
```
  const Real & _value;
```
(../moose/framework/include/bcs/DirichletBC.h)
Initialize the reference in the *.C file as follows.
```
  : DirichletBCBase(parameters), _value(getParam<Real>("value"))
```
(../moose/framework/src/bcs/DirichletBC.C)

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 Listing 1. The input can be a single value or a space separated list of parameters.

Listing 1: Example validParams method that declares a parameter as controllable.

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;
}

tip

The documentation for a given parameter will indicate whether it is controllable. For example, see the DirichletBC page.

Create a Control object

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 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 object.

Listing 2: Example of a Control object used in a MOOSE input file.

[Controls]
  [./func_control]
    type = RealFunctionControl
    parameter = '*/*/coef'
    function = 'func_coef'
    execute_on = 'initial timestep_begin'
  [../]
[]

Object and Parameter Names

Notice that in Listing 2 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 Listing 3).
name: specifies the parameter name (e.g., "coef" in Listing 3).

Listing 3: Example of a "Kernel" block that contains a parameter that is controlled via a MOOSE Control object.

[Kernels]
  [./diff]
    type = CoefDiffusion
    variable = u
    coef = 0.1
  [../]
  [./time]
    type = TimeDerivative
    variable = u
  [../]
[]

As shown in Listing 2 an asterisk ("*") can be substituted for any one of these three "names", doing so allows multiple parameters to match and be controlled simultaneously.

In similar fashion, object names can be requested by controls (e.g., as in the TimePeriod). In this case, the general name scheme is the same as above but the parameter name is not included.

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.

Listing 4: Example of the parameter control_tags.

[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'
  [../]
[]

The two postprocessors in Listing 4 declare the same control tag tag. Thus their controllable parameter point can be set by controls simultaneously with tag/*/point as in Listing 5.

Listing 5: Example of usinging the tagged controllable parameters.

[Controls]
  [./point_control]
    type = TestControl
    test_type = 'point'
    parameter = 'tag/*/point'
    execute_on = 'initial'
  [../]
[]

note

The tag name does not include the object name although the tag name is added by an object. To access a controllable parameter, the sytax 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 Creating a Controllable Parameter. 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.

Listing 6: Example of connecting controllable parameters in an action and the objects added by the action.

      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

The action controllable parameter can be referred as usual in an input file. For example,

Listing 7: Example of a "Action" block that contains a parameter that is controlled via a MOOSE Control object.

[Controls]
  [setdc]
    type = RealVectorFunctionControl
    function = dc
    parameter = Testing/LotsOfDiffusion/lots/diffusion_coefficients
    execute_on = timestep_begin
  []
[]

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.
Tensor 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.

(../moose/framework/include/bcs/DirichletBC.h)

// 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 "DirichletBCBase.h"

/**
 * Boundary condition of a Dirichlet type
 *
 * Sets the value in the node
 */
class DirichletBC : public DirichletBCBase
{
public:
  static InputParameters validParams();

  DirichletBC(const InputParameters & parameters);

protected:
  virtual Real computeQpValue() override;

  /// The value for this BC
  const Real & _value;
};

(../moose/framework/src/bcs/DirichletBC.C)

// 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

#include "DirichletBC.h"

registerMooseObject("MooseApp", DirichletBC);

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;
}

DirichletBC::DirichletBC(const InputParameters & parameters)
  : DirichletBCBase(parameters), _value(getParam<Real>("value"))
{
}

Real
DirichletBC::computeQpValue()
{
  return _value;
}

(../moose/framework/src/bcs/DirichletBC.C)

// 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

#include "DirichletBC.h"

registerMooseObject("MooseApp", DirichletBC);

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;
}

DirichletBC::DirichletBC(const InputParameters & parameters)
  : DirichletBCBase(parameters), _value(getParam<Real>("value"))
{
}

Real
DirichletBC::computeQpValue()
{
  return _value;
}

(../moose/test/tests/controls/real_function_control/real_function_control.i)

[Mesh]
  type = GeneratedMesh
  dim = 2
  nx = 10
  ny = 10
[]

[Variables]
  [./u]
  [../]
[]

[Kernels]
  [./diff]
    type = CoefDiffusion
    variable = u
    coef = 0.1
  [../]
  [./time]
    type = TimeDerivative
    variable = u
  [../]
[]

[BCs]
  [./left]
    type = DirichletBC
    variable = u
    boundary = left
    value = 0
  [../]
  [./right]
    type = DirichletBC
    variable = u
    boundary = right
    value = 1
  [../]
[]

[Executioner]
  type = Transient
  num_steps = 10
  dt = 0.1
  dtmin = 0.1
  solve_type = PJFNK
  petsc_options_iname = '-pc_type -pc_hypre_type'
  petsc_options_value = 'hypre boomeramg'
[]

[Outputs]
  csv = true
[]

[Functions]
  [./func_coef]
    type = ParsedFunction
    expression = '2*t + 0.1'
  [../]
[]

[Postprocessors]
  [./coef]
    type = RealControlParameterReporter
    parameter = 'Kernels/diff/coef'
  [../]
[]

[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)

[Mesh]
  type = GeneratedMesh
  dim = 2
  nx = 10
  ny = 10
[]

[Variables]
  [./u]
  [../]
[]

[Kernels]
  [./diff]
    type = CoefDiffusion
    variable = u
    coef = 0.1
  [../]
  [./time]
    type = TimeDerivative
    variable = u
  [../]
[]

[BCs]
  [./left]
    type = DirichletBC
    variable = u
    boundary = left
    value = 0
  [../]
  [./right]
    type = DirichletBC
    variable = u
    boundary = right
    value = 1
  [../]
[]

[Executioner]
  type = Transient
  num_steps = 10
  dt = 0.1
  dtmin = 0.1
  solve_type = PJFNK
  petsc_options_iname = '-pc_type -pc_hypre_type'
  petsc_options_value = 'hypre boomeramg'
[]

[Outputs]
  csv = true
[]

[Functions]
  [./func_coef]
    type = ParsedFunction
    expression = '2*t + 0.1'
  [../]
[]

[Postprocessors]
  [./coef]
    type = RealControlParameterReporter
    parameter = 'Kernels/diff/coef'
  [../]
[]

[Controls]
  [./func_control]
    type = RealFunctionControl
    parameter = '*/*/coef'
    function = 'func_coef'
    execute_on = 'initial timestep_begin'
  [../]
[]

(../moose/test/tests/controls/tag_based_naming_access/param.i)

[Mesh]
  type = GeneratedMesh
  dim = 2
  elem_type = QUAD4

  # use odd numbers so points do not fall on element boundaries
  nx = 31
  ny = 31
[]

[Variables]
  [./diffused]
    order = FIRST
    family = LAGRANGE
  [../]
[]

[Kernels]
  [./diff]
    type = Diffusion
    variable = diffused
  [../]
[]

[DiracKernels]
  [./test_object]
    type = MaterialPointSource
    point = '0.5 0.5 0'
    variable = diffused
    control_tags = 'tag'
  [../]
[]

[BCs]
  [./bottom_diffused]
    type = DirichletBC
    variable = diffused
    boundary = 'bottom'
    value = 2
  [../]

  [./top_diffused]
    type = DirichletBC
    variable = diffused
    boundary = 'top'
    value = 0
  [../]
[]

[Materials]
  [./mat]
    type = GenericConstantMaterial
    prop_names = 'matp'
    prop_values = '1'
    block = 0
  [../]
[]

[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'
  [../]
[]

[Executioner]
  type = Steady
  solve_type = 'PJFNK'
[]

[Outputs]
  execute_on = 'timestep_end'
  exodus = true
[]

[Controls]
  [./point_control]
    type = TestControl
    test_type = 'point'
    parameter = 'tag/*/point'
    execute_on = 'initial'
  [../]
[]

(../moose/test/tests/controls/tag_based_naming_access/param.i)

[Mesh]
  type = GeneratedMesh
  dim = 2
  elem_type = QUAD4

  # use odd numbers so points do not fall on element boundaries
  nx = 31
  ny = 31
[]

[Variables]
  [./diffused]
    order = FIRST
    family = LAGRANGE
  [../]
[]

[Kernels]
  [./diff]
    type = Diffusion
    variable = diffused
  [../]
[]

[DiracKernels]
  [./test_object]
    type = MaterialPointSource
    point = '0.5 0.5 0'
    variable = diffused
    control_tags = 'tag'
  [../]
[]

[BCs]
  [./bottom_diffused]
    type = DirichletBC
    variable = diffused
    boundary = 'bottom'
    value = 2
  [../]

  [./top_diffused]
    type = DirichletBC
    variable = diffused
    boundary = 'top'
    value = 0
  [../]
[]

[Materials]
  [./mat]
    type = GenericConstantMaterial
    prop_names = 'matp'
    prop_values = '1'
    block = 0
  [../]
[]

[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'
  [../]
[]

[Executioner]
  type = Steady
  solve_type = 'PJFNK'
[]

[Outputs]
  execute_on = 'timestep_end'
  exodus = true
[]

[Controls]
  [./point_control]
    type = TestControl
    test_type = 'point'
    parameter = 'tag/*/point'
    execute_on = 'initial'
  [../]
[]

(../moose/test/src/actions/AddLotsOfDiffusion.C)

// 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

#include "AddLotsOfDiffusion.h"
#include "Parser.h"
#include "FEProblem.h"
#include "Factory.h"
#include "MooseEnum.h"
#include "AddVariableAction.h"
#include "Conversion.h"
#include "DirichletBC.h"
#include "AddVariableAction.h"

#include <sstream>
#include <stdexcept>

#include "libmesh/libmesh.h"
#include "libmesh/exodusII_io.h"
#include "libmesh/equation_systems.h"
#include "libmesh/nonlinear_implicit_system.h"
#include "libmesh/explicit_system.h"
#include "libmesh/string_to_enum.h"
#include "libmesh/fe.h"

registerMooseAction("MooseTestApp", AddLotsOfDiffusion, "add_variable");
registerMooseAction("MooseTestApp", AddLotsOfDiffusion, "add_kernel");
registerMooseAction("MooseTestApp", AddLotsOfDiffusion, "add_bc");
registerMooseAction("MooseTestApp", AddLotsOfDiffusion, "add_material");

InputParameters
AddLotsOfDiffusion::validParams()
{
  InputParameters params = Action::validParams();

  MooseEnum order(
      "CONSTANT FIRST SECOND THIRD FOURTH FIFTH SIXTH SEVENTH EIGHTH NINTH", "FIRST", true);
  params.addParam<MooseEnum>("order",
                             order,
                             "Order of the FE shape function to use for this variable (additional "
                             "orders not listed here are allowed, depending on the family).");

  MooseEnum family("LAGRANGE MONOMIAL HERMITE SCALAR HIERARCHIC CLOUGH XYZ SZABAB BERNSTEIN "
                   "L2_LAGRANGE L2_HIERARCHIC NEDELEC_ONE LAGRANGE_VEC",
                   "LAGRANGE");
  params.addParam<MooseEnum>(
      "family", family, "Specifies the family of FE shape functions to use for this variable.");
  params.addParam<bool>("array", false, "Whether or not to use array variables");
  params.addRequiredParam<unsigned int>("number", "The number of variables to add");
  params.addParam<unsigned int>("n_components", 2, "The number of components of array variables");
  params.addParam<bool>("add_reaction", false, "True to add reaction kernels");

  params.addRequiredParam<RealEigenVector>("diffusion_coefficients",
                                           "Diffusion coefficient to be used by all variables");
  params.declareControllable("diffusion_coefficients");
  return params;
}

AddLotsOfDiffusion::AddLotsOfDiffusion(const InputParameters & params) : Action(params) {}

void
AddLotsOfDiffusion::act()
{
  unsigned int number = getParam<unsigned int>("number");
  unsigned int ncomp = getParam<unsigned int>("n_components");

  const auto array = getParam<bool>("array");

  if (_current_task == "add_variable")
  {
    auto fe_type = AddVariableAction::feType(_pars);
    auto type = AddVariableAction::variableType(fe_type, false, array);
    auto var_params = _factory.getValidParams(type);

    var_params.set<MooseEnum>("family") = getParam<MooseEnum>("family");
    var_params.set<MooseEnum>("order") = getParam<MooseEnum>("order");
    if (array)
      var_params.set<unsigned int>("components") = ncomp;
    for (unsigned int cur_num = 0; cur_num < number; cur_num++)
    {
      std::string var_name = name() + Moose::stringify(cur_num);
      _problem->addVariable(type, var_name, var_params);
    }
  }
  else if (_current_task == "add_kernel")
  {
    for (unsigned int cur_num = 0; cur_num < number; cur_num++)
    {
      std::string var_name = name() + Moose::stringify(cur_num);
      {
        const auto kernel_type = array ? "ArrayDiffusion" : "Diffusion";

        InputParameters params = _factory.getValidParams(kernel_type);
        params.set<NonlinearVariableName>("variable") = var_name;
        if (array)
          params.set<MaterialPropertyName>("diffusion_coefficient") = "dc";
        _problem->addKernel(kernel_type, var_name, params);
      }

      if (getParam<bool>("add_reaction"))
      {
        const auto kernel_type = array ? "ArrayReaction" : "Reaction";
        InputParameters params = _factory.getValidParams(kernel_type);
        params.set<NonlinearVariableName>("variable") = var_name;
        if (array)
          params.set<MaterialPropertyName>("reaction_coefficient") = "rc";
        _problem->addKernel(kernel_type, var_name + "_reaction", params);
      }
    }
  }
  else if (_current_task == "add_bc")
  {
    for (unsigned int cur_num = 0; cur_num < number; cur_num++)
    {
      std::string var_name = name() + Moose::stringify(cur_num);
      const auto bc_type = array ? "ArrayDirichletBC" : "DirichletBC";

      InputParameters params = _factory.getValidParams(bc_type);
      params.set<NonlinearVariableName>("variable") = var_name;
      params.set<std::vector<BoundaryName>>("boundary").push_back("left");
      if (array)
        params.set<RealEigenVector>("values") = RealEigenVector::Constant(ncomp, 0);
      else
        params.set<Real>("value") = 0;

      _problem->addBoundaryCondition(bc_type, var_name + "_left", params);

      params.set<std::vector<BoundaryName>>("boundary")[0] = "right";
      if (array)
        params.set<RealEigenVector>("values") = RealEigenVector::Constant(ncomp, 1);
      else
        params.set<Real>("value") = 1;

      _problem->addBoundaryCondition(bc_type, var_name + "_right", params);
    }
  }
  else if (_current_task == "add_material" && array)
  {
    {
      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
      connectControllableParams(
          "diffusion_coefficients", "GenericConstantArray", "dc", "prop_value");
    }

    if (getParam<bool>("add_reaction"))
    {
      auto params = _factory.getValidParams("GenericConstantArray");
      params.set<std::string>("prop_name") = "rc";
      params.set<RealEigenVector>("prop_value") = RealEigenVector::Constant(ncomp, 1);
      _problem->addMaterial("GenericConstantArray", "rc", params);
    }
  }
}

(../moose/test/tests/controls/action_control/action_control_test.i)

[Mesh]
  [gmg]
    type = GeneratedMeshGenerator
    dim = 2
    nx = 3
    ny = 3
  []
[]

[Testing/LotsOfDiffusion/lots]
  number = 10
  array = true
  n_components = 4
  diffusion_coefficients = '1 1 1 1'
  add_reaction = true
[]

[Functions]
  [dc]
    type = ParsedFunction
    expression = t+1
  []
[]

[Controls]
  [setdc]
    type = RealVectorFunctionControl
    function = dc
    parameter = Testing/LotsOfDiffusion/lots/diffusion_coefficients
    execute_on = timestep_begin
  []
[]

[Executioner]
  type = Transient
  num_steps = 10
[]

[Outputs]
  exodus = true
[]