Valid Parameters

  • A set of custom parameters is used to construct every object.
  • Every MOOSE-derived object must specify a validParams function.
  • In this function you must start with the parameters from your parent class (e.g., Kernel) and then specify additional parameters.
  • This function must return a set of parameters that the corresponding object requires in order to be constructed.
  • This design allows users to control any and all parameters they need for constructing objects while leaving all C++ constructors uniform and unchanged.

Defining Valid Parameters

In the .h file:

class Convection;

template<>
InputParameters validParams<Convection>();

class Convection : public Kernel
...

In the .C file:

template<>
InputParameters validParams<Convection>()
{
  InputParameters params = validParams<Kernel>();  // Must get from parent
  params.addRequiredParam<RealVectorValue>("velocity", "Velocity Vector");
  params.addParam<Real>("coefficient", "Diffusion coefficient");
  return params;
}

On the Fly Documentation

  • The parser object is capable of generating documentation from the validParams functions for each class that specializes that function.
  • Option 1: Mouse-over when using the MOOSE GUI "peacock"
  • Option 2: Generate a complete tree of registered objects
    • CLI option --dump [optional search string]
    • The search string may contain wildcard characters
    • Searches both block names and parameters
    • All parameters are printed for a matching block
  • Option 3: Generate a tree based on your input file
    • CLI option --show-input
  • Option 4: View it online
    • http://mooseframework.org/wiki/InputFileSyntax

Valid Types

  • Built-in types and std::vector are supported via templated methods:
    • addRequiredParam<Real>("required_const", "doc");
    • addParam<int>("count", 1, "doc"); // default supplied
    • addParam<unsigned int>("another_num", "doc");
    • addRequiredParam<std::vector<int> >("vec", "doc");
  • Other supported parameter types include:
    • Point
    • RealVectorValue
    • RealTensorValue
    • SubdomainID
    • BoundaryID
  • For the complete list of supported types see Parser::extractParams(...)

  • MOOSE uses a large number of string types to make Peacock more context-aware. All of these types can be treated just like strings, but will cause compile errors if mixed improperly in the template functions.
    • SubdomainName
    • BoundaryName
    • FileName
    • VariableName
    • FunctionName
    • UserObjectName
    • PostprocessorName
    • IndicatorName
    • MarkerName
    • MeshFileName
    • OutFileName
    • NonlinearVariableName
    • AuxVariableName
  • For a complete list, see the instantiations at the bottom of framework/include/utils/MooseTypes.h.

Default and Range Parameters

  • You may supply a default value for all optional parameters (not required)
addParam<RealVectorValue>("direction", RealVectorValue(0,1,0), "doc");
  • The following types allow you to supply scalar defaults in place of C++ objects:
    • Any coupled variable
    • Postprocessors (PostprocessorName)
    • Functions (FunctionName)
  • You may supply an expression to perform range checking within the parameter system.
  • You should use the name of your parameter in the expression.
addRangeCheckedParam<Real>("temp", "temp>=300 & temp<=330", "doc");
  • Function Parser Syntax http://warp.povusers.org/FunctionParser/fparser.html

MooseEnum

  • MOOSE includes a "smart" enum utility to overcome many of the deficiencies in the standard C++ enum type.
  • It works in both integer and string contexts and is self-checked for consistency.
#include "MooseEnum.h"
...
// The valid options are specified in a space separated list.
// You can optionally supply the default value as a second argument.
// MooseEnums are case preserving but case-insensitive.
MooseEnum option_enum("first=1 second fourth=4", "second");

// Use in a string context
if (option_enum == "first")
  doSomething();

// Use in an integer context
switch (option_enum)
{
  case 1: ... break;
  case 2: ... break;
  case 4: ... break;
  default: ... ;
}

Using MooseEnum with InputParameters

  • Objects that have a specific set of named options should use a MooseEnum so that parsing and error checking code can be omitted.
template<>
InputParameters validParams<MyObject>()
{
  InputParameters params = validParams<ParentObject>();
  MooseEnum component("X Y Z");  // No default supplied
  params.addRequiredParam<MooseEnum>("component", component, 
                                     "The X, Y, or Z component");
  return params;
}

...

// Assume we have saved our MooseEnum into an instance variable: _component
Real value = 0.0;
if (_component.isValid())
  value = _some_vector[_component];
  • The Peacock GUI will create a drop box when using MooseEnum.
  • If the user supplies an invalid option, the parser will catch it and throw an informative error message.

Multiple Value MooseEnums (MultiMooseEnum)

  • Works the same way as MooseEnum but supports multiple ordered options.
template<>
InputParameters validParams<MyObject>()
{
  InputParameters params = validParams<ParentObject>();
  MultiMooseEnum transforms("scale rotate translate");
  params.addRequiredParam<MultiMooseEnum>("transforms", transforms,
                                          "The transforms to perform");
  return params;
}

...

if (_transforms.isValid())
  for (unsigned int i=0; i<_transforms.size(); ++i)
    performTransform(transforms[i]);
  • Can also ask if item is stored in the MultiMooseEnum by calling transforms.contains(item);