NEML2Action

Set up the NEML2 material model

commentnote

This page is developer-facing. Users please refer to the NEML2 syntax documentation.

Overview

This is the primary action responsible for constructing objects for transferring data back and forth between MOOSE and NEML2, as well as for executing the NEML2 model.

Four types of objects are constructed by this action:

  • Gatherer: Object responsible for gathering MOOSE data.

  • Retriever: Object responsible for retrieving NEML2 data and assigning it back to MOOSE data structures.

  • Index generator: Object responsible for generating the element-to-batch-index map.

  • Executor: Object responsible for sending data gathered by gatherers to NEML2, execute the NEML2 model, and have the outputs ready for retrieval by retrievers.

Currently supported objects are summarized below.

TypeMOOSE object(s)
GathererMOOSEQuantityToNEML2
RetrieverNEML2ToMOOSEMaterialProperty
Index generatorNEML2BatchIndexGenerator
ExecutorNEML2ModelExecutor

Multiple gatherers and retrievers may be created by this action, but each instance of the action creates one and only one index generator and executor. Each step performed by this action is explained in one of the following sections, in the order of execution.

Applying common parameters

Recall that input file parameters in the common area under the [NEML2] block defined by the NEML2ActionCommon are shared by all sub-blocks. The first step is to retrieve the common parameters and apply them to this sub-block. This happens in the constructor of the action. Note that parameters defined in the sub-block overrides the parameters defined in the common area.

Creating the NEML2 model

By the time this action "acts", the NEML2 input file must have already been parsed and loaded by NEML2ActionCommon. Therefore, the NEML2 model associated with this action can be directly created using the name given by "model".

NEML2 model introspection

If "verbose" is set to true, a high-level summary of the NEML2 model is print to the console, including model name, evaluation device, as well as a table summarizing the model's variables, parameters, and buffers.

NEML2 model allows introspection, i.e., variable and parameter names, tensor types, and storage sizes can be inferred after the model is loaded. Five maps are set up upon introspection of the NEML2 model:

  1. A map between MOOSE data structures and NEML2 input variables.

  2. A map between MOOSE data structures and NEML2 model parameters.

  3. A map between MOOSE data structures and NEML2 output variables.

  4. A map between MOOSE data structures and NEML2 output derivatives.

  5. A map between MOOSE data structures and NEML2 parameter derivatives.

These maps are used later to create objects for transferring data between MOOSE and NEML2.

Creating MOOSEToNEML2 gatherers

This step involves the creation of MOOSEToNEML2 gatherers for NEML2 input variables and model parameters. The first two maps mentioned in the previous section are used. The maps are looped through to create objects one-by-one.

Note that the correct type of object is selected/created relying on NEML2 model introspection. For example, if a NEML2 input variable is of type SR2, we can infer that the corresponding MOOSE data structure should be SymmetricRankTwoTensor.

Creating the NEML2 index generator and model executor

Next, a NEML2BatchIndexGenerator and a NEML2ModelExecutor excutor are created. The list of "gatherers" and "param_gatherers" are automatically filled out by this action.

Creating NEML2ToMOOSE retrievers

The last step is creating the NEML2ToMOOSE retrievers to retrieve NEML2 model outputs (and their derivatives) back to MOOSE. This step is similar to creating MOOSEToNEML2 gatherers.

Input Parameters

  • active__all__ If specified only the blocks named will be visited and made active

    Default:__all__

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:If specified only the blocks named will be visited and made active

  • async_dispatchTrueWhether to use asynchronous dispatch.

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Whether to use asynchronous dispatch.

  • auto_outputTrueWhether to automatically retrieve all NEML2 output variables as MOOSE material properties.

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Whether to automatically retrieve all NEML2 output variables as MOOSE material properties.

  • cli_argsAdditional command line arguments to use when parsing the NEML2 input file.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:Additional command line arguments to use when parsing the NEML2 input file.

  • debug_inputs_on_failureFalseWhen a NEML2 solve fails, append a detailed dump of input tensors (defined/missing, shapes, and devices) to the error message.

    Default:False

    C++ Type:bool

    Controllable:No

    Description:When a NEML2 solve fails, append a detailed dump of input tensors (defined/missing, shapes, and devices) to the error message.

  • derivativesList of pairs of NEML2 variables to take derivatives (i.e., first in the pair w.r.t. the second in the pair).

    C++ Type:std::vector<std::vector<std::string>>

    Controllable:No

    Description:List of pairs of NEML2 variables to take derivatives (i.e., first in the pair w.r.t. the second in the pair).

  • deviceDevice on which to evaluate the NEML2 model. The string supplied must follow the following schema: (cpu|cuda)[:] where cpu or cuda specifies the device type, and : optionally specifies a device index. For example, device='cpu' sets the target compute device to be CPU, and device='cuda:1' sets the target compute device to be CUDA with device ID 1. If not specified, default to the compute device specified via the command line argument --compute-device.

    C++ Type:std::string

    Controllable:No

    Description:Device on which to evaluate the NEML2 model. The string supplied must follow the following schema: (cpu|cuda)[:] where cpu or cuda specifies the device type, and : optionally specifies a device index. For example, device='cpu' sets the target compute device to be CPU, and device='cuda:1' sets the target compute device to be CUDA with device ID 1. If not specified, default to the compute device specified via the command line argument --compute-device.

  • export_output_targetsThe export targets corresponding to each MOOSE material property specified in export_outputs.

    C++ Type:std::vector<std::vector<OutputName>>

    Controllable:No

    Description:The export targets corresponding to each MOOSE material property specified in export_outputs.

  • export_outputsList of MOOSE material properties to export which correspond to NEML2 output variables or output derivatives. Each material property's export targets can be specified by export_output_targets. The default export target is 'none'.

    C++ Type:std::vector<MaterialPropertyName>

    Unit:(no unit assumed)

    Controllable:No

    Description:List of MOOSE material properties to export which correspond to NEML2 output variables or output derivatives. Each material property's export targets can be specified by export_output_targets. The default export target is 'none'.

  • inactiveIf specified blocks matching these identifiers will be skipped.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:If specified blocks matching these identifiers will be skipped.

  • initialize_output_valuesList of MOOSE material properties whose initial values (evaluated at the 0th time step) will be used to initialize stateful properties. See the description of initialize_outputs for more details.

    C++ Type:std::vector<MaterialPropertyName>

    Unit:(no unit assumed)

    Controllable:No

    Description:List of MOOSE material properties whose initial values (evaluated at the 0th time step) will be used to initialize stateful properties. See the description of initialize_outputs for more details.

  • initialize_outputsList of MOOSE material properties to be initialized. Each these properties must correspond to a stateful NEML2 variable (which appears on both the input old state sub-axis and the output state sub-axis). These MOOSE material properties will be initialized with the values of properties specified in the initialize_output_values list.

    C++ Type:std::vector<MaterialPropertyName>

    Unit:(no unit assumed)

    Controllable:No

    Description:List of MOOSE material properties to be initialized. Each these properties must correspond to a stateful NEML2 variable (which appears on both the input old state sub-axis and the output state sub-axis). These MOOSE material properties will be initialized with the values of properties specified in the initialize_output_values list.

  • inputPath to the NEML2 input file containing the NEML2 model(s).

    C++ Type:DataFileName

    Controllable:No

    Description:Path to the NEML2 input file containing the NEML2 model(s).

  • input_kernelsNEML2 kernels defined in MOOSE that provides input data. The object name must match the input variable name.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:NEML2 kernels defined in MOOSE that provides input data. The object name must match the input variable name.

  • input_typesType of each MOOSE data to be used as NEML2 input variable

    C++ Type:MultiMooseEnum

    Options:TIME, SCALAR, FUNCTION, VARIABLE, MATERIAL

    Controllable:No

    Description:Type of each MOOSE data to be used as NEML2 input variable

  • inputsList of NEML2 input variables corresponding to each MOOSE data.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:List of NEML2 input variables corresponding to each MOOSE data.

  • manage_state_advanceFalseKeep state and forces on the device and advance it to old_state and old_forces without a roundtrip through MOOSE materials. This is only recommended for explicit time integration or when absolutely no restepping occurs (e.g. failed timesteps).

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Keep state and forces on the device and advance it to old_state and old_forces without a roundtrip through MOOSE materials. This is only recommended for explicit time integration or when absolutely no restepping occurs (e.g. failed timesteps).

  • modelName of the NEML2 model, i.e., the string inside the brackets [] in the NEML2 input file that corresponds to the model you want to use.

    C++ Type:std::string

    Controllable:No

    Description:Name of the NEML2 model, i.e., the string inside the brackets [] in the NEML2 input file that corresponds to the model you want to use.

  • output_deviceSimilar to the 'device' parameter, this parameter specifies the device on which to store the outputs. Default to be the same as 'device'.

    C++ Type:std::string

    Controllable:No

    Description:Similar to the 'device' parameter, this parameter specifies the device on which to store the outputs. Default to be the same as 'device'.

  • parameter_derivativesList of pairs of NEML2 variables to take derivatives (i.e., first in the pair w.r.t. the second in the pair).

    C++ Type:std::vector<std::vector<std::string>>

    Controllable:No

    Description:List of pairs of NEML2 variables to take derivatives (i.e., first in the pair w.r.t. the second in the pair).

  • parameter_typesType of each MOOSE data to be used as NEML2 model parameter

    C++ Type:MultiMooseEnum

    Options:TIME, SCALAR, FUNCTION, VARIABLE, MATERIAL

    Controllable:No

    Description:Type of each MOOSE data to be used as NEML2 model parameter

  • parametersList of NEML2 model parameters corresponding to each MOOSE data.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:List of NEML2 model parameters corresponding to each MOOSE data.

  • schedulerNEML2 scheduler to use to run the model. If not specified no scheduler is used and MOOSE will pass all the constitutive updates to the provided device at once.

    C++ Type:std::string

    Controllable:No

    Description:NEML2 scheduler to use to run the model. If not specified no scheduler is used and MOOSE will pass all the constitutive updates to the provided device at once.

  • skip_input_variablesList of NEML2 variables to skip when setting up the model input. If an input variable is skipped, its value will stay zero. If a required input variable is skipped, an error will be raised.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:List of NEML2 variables to skip when setting up the model input. If an input variable is skipped, its value will stay zero. If a required input variable is skipped, an error will be raised.

  • verboseTrueWhether to print additional information about the NEML2 model at the beginning of the simulation

    Default:True

    C++ Type:bool

    Controllable:No

    Description:Whether to print additional information about the NEML2 model at the beginning of the simulation

Optional Parameters

  • control_tagsAdds user-defined labels for accessing object parameters via control logic.

    C++ Type:std::vector<std::string>

    Controllable:No

    Description:Adds user-defined labels for accessing object parameters via control logic.

These input parameters correspond to the sub-blocks under the [NEML2] block. The usage of the [NEML2] block is explained in details in the NEML2 syntax documentation.

warningwarning

The detailed documentation of this object/syntax is only available when MOOSE is compiled with NEML2. To enable NEML2, please follow the NEML2 installation guide.

Advanced Parameters