SetupInterface (execute_on)

Execute On

Any object inheriting from the SetupInterface, that adds the SetupInterface::validParams() within its own parameters, will have an "execute_on" parameter that can be set to various flags, the most common (default) flags are listed below.

The "execute_on" parameter can be set to a single flag or multiple flags. For example, it may be desirable to only execute an object initially because the state of the auxiliary computation does not vary. In the input file snippet below, the ElementLengthAux computation only needs to be computed initially, thus the "exeucte_on" parameter is set as such.

[AuxKernels]
  [./min]
    type = ElementLengthAux
    variable = min
    method = min
    execute_on = initial
  [../]
  [./max]
    type = ElementLengthAux
    variable = max
    method = max
    execute_on = initial
  [../]
[../]

Alternatively, it is often desirable to run a computation with multiple execute flags. For example, in the input file snippet below a TimePeriod control object that is responsible for enabling in Damper object needs to be run initially and prior to each timestep to guarantee that the damper is enabled when desired.

[Controls]
  [./damping_control]
    type = TimePeriod
    disable_objects = '*::const_damp'
    start_time = 0.25
    execute_on = 'initial timestep_begin'
  [../]
[]

Depending on the system these options or others will be available, since as discussed in Creating Custom Execute Flags custom flags may be added. The complete list of execution flags is provided by MOOSE are listed in the "registerExecFlags" function.

#ifdef HAVE_GPERFTOOLS
#include "gperftools/profiler.h"
#include "gperftools/heap-profiler.h"
#endif

// MOOSE includes
#include "MooseRevision.h"
#include "AppFactory.h"
#include "DisplacedProblem.h"
#include "NonlinearSystemBase.h"
#include "AuxiliarySystem.h"
#include "MooseSyntax.h"
#include "MooseInit.h"
#include "Executioner.h"
#include "Executor.h"
#include "PetscSupport.h"
#include "Conversion.h"
#include "CommandLine.h"
#include "InfixIterator.h"
#include "MultiApp.h"
#include "MooseUtils.h"
#include "MooseObjectAction.h"
#include "InputParameterWarehouse.h"
#include "SystemInfo.h"
#include "MooseMesh.h"
#include "FileOutput.h"
#include "ConsoleUtils.h"
#include "JsonSyntaxTree.h"
#include "JsonInputFileFormatter.h"
#include "SONDefinitionFormatter.h"
#include "RelationshipManager.h"
#include "ProxyRelationshipManager.h"
#include "Registry.h"
#include "SerializerGuard.h"
#include "PerfGraphInterface.h" // For TIME_SECTION
#include "SolutionInvalidInterface.h"
#include "Attributes.h"
#include "MooseApp.h"
#include "CommonOutputAction.h"
#include "CastUniquePointer.h"
#include "NullExecutor.h"
#include "ExecFlagRegistry.h"
#include "SolutionInvalidity.h"
#include "MooseServer.h"
#include "RestartableDataWriter.h"
#include "StringInputStream.h"

// Regular expression includes
#include "pcrecpp.h"

#include "libmesh/exodusII_io.h"
#include "libmesh/mesh_refinement.h"
#include "libmesh/string_to_enum.h"
#include "libmesh/checkpoint_io.h"
#include "libmesh/mesh_base.h"

// System include for dynamic library methods
#ifdef LIBMESH_HAVE_DLOPEN
#include <dlfcn.h>
#include <sys/utsname.h> // utsname
#endif

// C++ includes
#include <numeric> // std::accumulate
#include <fstream>
#include <sys/types.h>
#include <unistd.h>
#include <cstdlib> // for system()
#include <chrono>
#include <thread>

#define QUOTE(macro) stringifyName(macro)

The default value of "execute_on" is linear for most of MOOSE objects with the exception of:

• The auxiliary kernels have the default value of linear and timestep_end.

• The postprocessors have default value of timestep_end.

• The controls have default value of initial and timestep_end.

• The multi-apps have default value of timestep_begin.

• The user objects have default value of timestep_end.

• The outputs have default value of initial and timestep_end.

• The default value for a transfer is set to be the same as the execute_on value of its corresponding sub-application.

Several objects in the framework have custom or selected default "execute_on". The default value for all objects including objects in MOOSE modules and MOOSE-based applications can be found in their parameter list.

Modifying Execute On

When creating objects that inherit from SetupInterface it is possible to set, add, or remove available execute flags by retrieving and then modifying the ExecFlagEnum parameter. For example, consider the snippet below (see Output.C).

  ExecFlagEnum & exec_enum = params.set<ExecFlagEnum>("execute_on", true);
  exec_enum = Output::getDefaultExecFlagEnum();
  exec_enum = {EXEC_INITIAL, EXEC_TIMESTEP_END};
  params.setDocString("execute_on", exec_enum.getDocString());

First, the "execute_on" is retrieved for modification by using the "set" method. Notice, that a second boolean argument is passed to "set", this second flag enables "quiet mode". Quiet mode will modify the parameter silently as if the default was the modified parameter. In this case, the parameter will be listed as un-modified by the user. That is, InputParameters::isParamSetByUser returns false, if quiet mode is not enabled this method would return true.

Second, the two new execution flags are added (EXEC_FINAL and EXEC_FAILED), therefore these additional options are available to all classes (all Output objects in this case) that inherit from this object.

Third, the default active flags are set to EXEC_INITIAL and EXEC_TIMESTEP_END, which are the defaults for all Output objects.

Finally, the documentation string for the "execute_on" parameter for the Output objects is update to reflect the changes made to the parameter. The ExecFlagEnum has a convenience function that generates a documentation string that includes the available options in the string.

Virtual Setup Methods

The SetupInterface includes virtual methods that correspond to the primary execute flags with MOOSE, these methods are listed in the header as shown here.

/**
* Gets called at the beginning of the simulation before this object is asked to do its job
*/
virtual void initialSetup();
/**
* Gets called at the beginning of the timestep before this object is asked to do its job
*/
virtual void timestepSetup();
/**
* Gets called just before the Jacobian is computed and before this object is asked to do its job
*/
virtual void jacobianSetup();
/**
* Gets called just before the residual is computed and before this object is asked to do its job
*/
virtual void residualSetup();
/**
* Gets called when the subdomain changes (i.e. in a Jacobian or residual loop) and before this
* object is asked to do its job
*/
virtual void subdomainSetup();
/**
* Gets called in FEProblemBase::execute() for execute flags other than initial, timestep_begin,
* nonlinear, linear and subdomain
*/
virtual void customSetup(const ExecFlagType & /*exec_type*/) {}

In general, these methods should be utilized to perform "setup" procedures prior to the calls to execute for the corresponding execute flag.

There is also a generic setup function "customSetup" that takes an execute flag as the argument. This function is called by MOOSE when performing evaluations of objects on the custom execute flags in Creating Custom Execute Flags.

Creating Custom Execute Flags

It is possible to create custom execute flags for an application. To create at utilize a custom execute flag the following steps should be followed.

#pragma once

#include "Moose.h"

namespace LevelSet
{
extern const ExecFlagType EXEC_ADAPT_MESH;
extern const ExecFlagType EXEC_COMPUTE_MARKERS;
}

// Level set includes
#include "LevelSetTypes.h"

// MOOSE includes
#include "ExecFlagRegistry.h"

const ExecFlagType LevelSet::EXEC_ADAPT_MESH = registerExecFlag("ADAPT_MESH");
const ExecFlagType LevelSet::EXEC_COMPUTE_MARKERS = registerExecFlag("COMPUTE_MARKERS");

ExecFlagEnum & exec = params.set<ExecFlagEnum>("execute_on");
exec.addAvailableFlags(LevelSet::EXEC_ADAPT_MESH, LevelSet::EXEC_COMPUTE_MARKERS);
exec = {LevelSet::EXEC_COMPUTE_MARKERS, LevelSet::EXEC_ADAPT_MESH};

execMultiAppTransfers(LevelSet::EXEC_ADAPT_MESH, MultiAppTransfer::TO_MULTIAPP);