NEML2 syntax

The [NEML2] block in the MOOSE input file is the entry point for defining NEML2 material model(s). All parameters are listed at the bottom of the page.

commentnote

This page is user-facing, i.e., the Input file syntax section explains how to write the MOOSE input file in order to connect MOOSE to NEML2 for material modeling. For developers, please refer to the NEML2Action and NEML2ActionCommon pages regarding what objects are constructed by the underlying Action.

Input File Syntax

The basic structure of the [NEML2] block is shown below.

[NEML2<<<{"href": "index.html"}>>>]
  eager<<<{"description": "Use the cpp-eager NEML2 runtime, which embeds a Python interpreter and loads the model from the source 'input' file at runtime. Default false -- use the cpp-aoti runtime, which loads an ahead-of-time-compiled artifact (no Python at runtime) from the artifact folder given by 'input'. The 'load' parameter is only valid with eager=true."}>>> = true
  input<<<{"description": "For the cpp-eager runtime, the path to the source NEML2 '.i' model file. For the cpp-aoti runtime, any of: the artifact folder produced by neml2-compile (a self-describing directory holding metadata.json plus per-<device>/<dtype> '.pt2' binaries), the metadata.json inside it, or the neml2-compile stub '.i'. Prefer the artifact folder -- it is self-contained and relocatable as a unit, and needs no 'model' name. The stub '.i' is accepted for compatibility but points at its artifact folder by path, so the two must stay together."}>>> = 'models/custom_model.i'
  # NEML2TestModel is hosted inside MOOSE as a Python module; importing it registers the type with
  # the embedded (cpp-eager) interpreter so the input file can reference it.
  load<<<{"description": "External Python extension files (paths to .py files or package directories, resolved relative to the input file and the application's data search path) imported into the embedded interpreter before the NEML2 model is built. Importing them registers any @register_neml2_object types they define -- e.g. NEML2 models hosted inside a MOOSE app -- so the NEML2 input file can reference them. Mirrors the neml2 CLI --load flag. Only valid with the cpp-eager runtime (eager=true)."}>>> = 'models/test_models.py'
  [all]
    model<<<{"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. Required for the cpp-eager runtime, and for cpp-aoti only when 'input' is a stub '.i'; the cpp-aoti folder and metadata.json forms use the single model recorded in the artifact metadata and ignore it."}>>> = 'model'
    device<<<{"description": "Compute device(s) for the NEML2 model, each following the schema (cpu|cuda)[:<device-index>] (e.g. 'cpu', 'cuda:1'). cpp-eager pins the model to the first device. cpp-aoti dispatches over the list: a CUDA list is round-robined over the MPI ranks on each node (one device per rank when counts match, sharing when there are more ranks than devices, an error when there are fewer); a single 'cpu' runs each rank's local batch on CPU. If not specified, defaults to the compute device from the --compute-device command line argument."}>>> = 'cpu'

    # request derivatives (must be pairs of two)
    # derivative name follow moose convention, e.g., 'doutput/dinput'
    derivatives<<<{"description": "List of NEML2 derivatives to retrieve. Each entry is (output, input) -- the derivative of 'output' w.r.t. 'input' -- with an optional third element aliasing it to a custom MOOSE material property name (default d(output)/d(input))."}>>> = 'product A'

    # output to exodus
    export_outputs<<<{"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'."}>>> = 'sum product dproduct/dA'
    export_output_targets<<<{"description": "The export targets corresponding to each MOOSE material property specified in export_outputs."}>>> = 'exodus; exodus; exodus'
  []
[]
(test/tests/neml2/custom_model.i)

The [NEML2] block has two parts:

  1. A common area directly underneath the [NEML2] block.

  2. Nested sub-blocks.

In the above example, there is only one sub-block named [all]. However, there can be as many sub-blocks as appropriate. Most of the parameters specified in the common area are also applied to each sub-block. In the case where a parameter is defined both in the common area and under a sub-block, the parameter defined under the sub-block takes precedence.

Sub-blocks are used to specify multiple NEML2 material models used in the same simulation. The following example demonstrates the use of sub-blocks to specify two NEML2 material models on two different subdomains.

[NEML2<<<{"href": "index.html"}>>>]
  eager<<<{"description": "Use the cpp-eager NEML2 runtime, which embeds a Python interpreter and loads the model from the source 'input' file at runtime. Default false -- use the cpp-aoti runtime, which loads an ahead-of-time-compiled artifact (no Python at runtime) from the artifact folder given by 'input'. The 'load' parameter is only valid with eager=true."}>>> = true
  input<<<{"description": "For the cpp-eager runtime, the path to the source NEML2 '.i' model file. For the cpp-aoti runtime, any of: the artifact folder produced by neml2-compile (a self-describing directory holding metadata.json plus per-<device>/<dtype> '.pt2' binaries), the metadata.json inside it, or the neml2-compile stub '.i'. Prefer the artifact folder -- it is self-contained and relocatable as a unit, and needs no 'model' name. The stub '.i' is accepted for compatibility but points at its artifact folder by path, so the two must stay together."}>>> = 'models/custom_model.i'
  load<<<{"description": "External Python extension files (paths to .py files or package directories, resolved relative to the input file and the application's data search path) imported into the embedded interpreter before the NEML2 model is built. Importing them registers any @register_neml2_object types they define -- e.g. NEML2 models hosted inside a MOOSE app -- so the NEML2 input file can reference them. Mirrors the neml2 CLI --load flag. Only valid with the cpp-eager runtime (eager=true)."}>>> = 'models/test_models.py'
  device<<<{"description": "Compute device(s) for the NEML2 model, each following the schema (cpu|cuda)[:<device-index>] (e.g. 'cpu', 'cuda:1'). cpp-eager pins the model to the first device. cpp-aoti dispatches over the list: a CUDA list is round-robined over the MPI ranks on each node (one device per rank when counts match, sharing when there are more ranks than devices, an error when there are fewer); a single 'cpu' runs each rank's local batch on CPU. If not specified, defaults to the compute device from the --compute-device command line argument."}>>> = 'cpu'

  # request derivatives (must be pairs of two)
  # derivative name follow moose convention, e.g., 'doutput/dinput'
  derivatives<<<{"description": "List of NEML2 derivatives to retrieve. Each entry is (output, input) -- the derivative of 'output' w.r.t. 'input' -- with an optional third element aliasing it to a custom MOOSE material property name (default d(output)/d(input))."}>>> = 'product A'

  # output to exodus
  export_outputs<<<{"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'."}>>> = 'sum product dproduct/dA'
  export_output_targets<<<{"description": "The export targets corresponding to each MOOSE material property specified in export_outputs."}>>> = 'exodus; exodus; exodus'

  [A]
    model<<<{"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. Required for the cpp-eager runtime, and for cpp-aoti only when 'input' is a stub '.i'; the cpp-aoti folder and metadata.json forms use the single model recorded in the artifact metadata and ignore it."}>>> = 'model_A'
    block<<<{"description": "List of blocks (subdomains) where the material model is defined"}>>> = 'A'
  []
  [B]
    model<<<{"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. Required for the cpp-eager runtime, and for cpp-aoti only when 'input' is a stub '.i'; the cpp-aoti folder and metadata.json forms use the single model recorded in the artifact metadata and ignore it."}>>> = 'model_B'
    block<<<{"description": "List of blocks (subdomains) where the material model is defined"}>>> = 'B'
  []
[]
(test/tests/neml2/blocks_different_model.i)

In each sub-block, there are a total of 6 groups of parameters that can be specified:

  1. Configuration of the model

  2. Transfer of input variables

  3. Transfer of model parameters

  4. Transfer of output variables

  5. Transfer of derivatives (of output variables w.r.t. input variables)

  6. Transfer of derivatives (of output variables w.r.t. model parameters)

The configuration of model is controlled by parameters such as "model", "device", etc., each of which is explained in the syntax documentation at the bottom of the page.

NEML2 models run through one of two runtimes, selected by "eager". By default (eager = false) the cpp-aoti runtime evaluates an ahead-of-time-compiled artifact produced by neml2-compile, with no Python interpreter at runtime; here "input" is the artifact folder that neml2-compile writes (the metadata.json inside it, or the legacy <model>_aoti.i stub, are also accepted). Setting eager = true selects the cpp-eager runtime, which embeds a Python interpreter and loads the model directly from the source NEML2 input file given by "input". The cpp-eager runtime is required for NEML2 models hosted inside a MOOSE application as Python modules, which are imported via "load" (only valid with eager = true).

"input_types" is a list of enums denoting the type of the MOOSE data structure used to hold the input variables. The following enums are supported

  • TIME: Simulation time.

  • SCALAR: The input variables are retrieved from a scalar variable and broadcast to all quadrature points.

  • FUNCTION: The input variables are retrieved from a function evaluated at each quadrature points.

  • VARIABLE: The input variables are retrieved from (auxiliary) variables interpolated at each quadrature point.

  • MATERIAL: The input variables are retrieved from material properties stored at each quadrature point.

All NEML2 input variables are automatically retrieved from the host MOOSE simulation. Quantities with the same name as each input variable are retrieved. An error is raised if ambiguity exists, in which case "input_types" and "inputs" can be used to explicitly specify the type of quantities to be retrieved.

All NEML2 output variables are retrieved and stored as MOOSE material properties after each evaluation, unless "auto_output" is set to false.

For stateful variables, i.e., input variables needing values from previous time steps (usually with suffix ~N with N being the number of steps backward in time), the corresponding MOOSE quantities from previous time steps are automatically retrieved. The advance of stateful variables is managed by the MOOSE native material system, unless "manage_state_advance" is set to true, in which case NEML2 handles the storage and advance of stateful variables. Note that currently manage_state_advance = true is not compatible with mesh change events.

It is worth noting that for "derivatives" and "parameter_derivatives", a pair of names must be specified for each entry. The first name in the pair denotes the quantity (NEML2 output variable) to take derivative of, and the second name in the pair denotes the quantity (NEML2 input variable or model parameter) to take derivative with respect to. Pairs are delimited by ;.

Inspect NEML2 information

The command-line option --parse-neml2-only can be used to inspect the NEML2 material model without running the entire simulation, i.e.


my-app-opt -i input.i --parse-neml2-only

Work scheduling and dispatching

NEML2 evaluation maps naturally onto MOOSE's MPI domain decomposition: each MPI rank evaluates the batch of quadrature points it owns. With the cpp-aoti runtime, "device" takes a list of devices and the work is dispatched with NEML2's MPI scheduler, which round-robins the device list over the MPI ranks on each node:

  • one device per rank when the rank and device counts match,

  • device sharing when there are more ranks than devices,

  • an error when there are fewer ranks than devices (idle devices are disallowed).

A single cpu entry (the default) sends every rank's local batch to the CPU. To drive several GPUs, list them, e.g. device = 'cuda:0 cuda:1 cuda:2 cuda:3'. "device_batch" optionally sets a per-device chunk size along the leading batch axis (0, the default, runs the whole local batch at once); it must have length 1 (broadcast to all devices) or the same length as "device".

The cpp-eager runtime does not dispatch; it pins the model to the first entry of "device".

schooltip

For more information on NEML2's schedulers and dispatchers, please refer to the NEML2 documentation.

Common 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

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

  • derivativesList of NEML2 derivatives to retrieve. Each entry is (output, input) -- the derivative of 'output' w.r.t. 'input' -- with an optional third element aliasing it to a custom MOOSE material property name (default d(output)/d(input)).

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

    Controllable:No

    Description:List of NEML2 derivatives to retrieve. Each entry is (output, input) -- the derivative of 'output' w.r.t. 'input' -- with an optional third element aliasing it to a custom MOOSE material property name (default d(output)/d(input)).

  • deviceCompute device(s) for the NEML2 model, each following the schema (cpu|cuda)[:] (e.g. 'cpu', 'cuda:1'). cpp-eager pins the model to the first device. cpp-aoti dispatches over the list: a CUDA list is round-robined over the MPI ranks on each node (one device per rank when counts match, sharing when there are more ranks than devices, an error when there are fewer); a single 'cpu' runs each rank's local batch on CPU. If not specified, defaults to the compute device from the --compute-device command line argument.

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

    Controllable:No

    Description:Compute device(s) for the NEML2 model, each following the schema (cpu|cuda)[:] (e.g. 'cpu', 'cuda:1'). cpp-eager pins the model to the first device. cpp-aoti dispatches over the list: a CUDA list is round-robined over the MPI ranks on each node (one device per rank when counts match, sharing when there are more ranks than devices, an error when there are fewer); a single 'cpu' runs each rank's local batch on CPU. If not specified, defaults to the compute device from the --compute-device command line argument.

  • device_batchPer-device chunk size along the leading batch axis (0 = run the whole local batch at once). Must have length 1 (broadcast to all devices) or match the length of 'device'. Defaults to 0.

    C++ Type:std::vector<unsigned int>

    Controllable:No

    Description:Per-device chunk size along the leading batch axis (0 = run the whole local batch at once). Must have length 1 (broadcast to all devices) or match the length of 'device'. Defaults to 0.

  • dump_inputs_on_failureFalseWhen a NEML2 constitutive solve fails (recoverable convergence failure), serialize the input tensors to a per-rank TorchScript file '_count_rank.pt' (c is a persistent failure counter). The file can be loaded offline with torch.jit.load to re-evaluate the model on the failing batch, independently of MOOSE.

    Default:False

    C++ Type:bool

    Controllable:No

    Description:When a NEML2 constitutive solve fails (recoverable convergence failure), serialize the input tensors to a per-rank TorchScript file '_count_rank.pt' (c is a persistent failure counter). The file can be loaded offline with torch.jit.load to re-evaluate the model on the failing batch, independently of MOOSE.

  • eagerFalseUse the cpp-eager NEML2 runtime, which embeds a Python interpreter and loads the model from the source 'input' file at runtime. Default false -- use the cpp-aoti runtime, which loads an ahead-of-time-compiled artifact (no Python at runtime) from the artifact folder given by 'input'. The 'load' parameter is only valid with eager=true.

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Use the cpp-eager NEML2 runtime, which embeds a Python interpreter and loads the model from the source 'input' file at runtime. Default false -- use the cpp-aoti runtime, which loads an ahead-of-time-compiled artifact (no Python at runtime) from the artifact folder given by 'input'. The 'load' parameter is only valid with eager=true.

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

  • inputFor the cpp-eager runtime, the path to the source NEML2 '.i' model file. For the cpp-aoti runtime, any of: the artifact folder produced by neml2-compile (a self-describing directory holding metadata.json plus per-/ '.pt2' binaries), the metadata.json inside it, or the neml2-compile stub '.i'. Prefer the artifact folder -- it is self-contained and relocatable as a unit, and needs no 'model' name. The stub '.i' is accepted for compatibility but points at its artifact folder by path, so the two must stay together.

    C++ Type:DataFileName

    Controllable:No

    Description:For the cpp-eager runtime, the path to the source NEML2 '.i' model file. For the cpp-aoti runtime, any of: the artifact folder produced by neml2-compile (a self-describing directory holding metadata.json plus per-/ '.pt2' binaries), the metadata.json inside it, or the neml2-compile stub '.i'. Prefer the artifact folder -- it is self-contained and relocatable as a unit, and needs no 'model' name. The stub '.i' is accepted for compatibility but points at its artifact folder by path, so the two must stay together.

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

  • loadExternal Python extension files (paths to .py files or package directories, resolved relative to the input file and the application's data search path) imported into the embedded interpreter before the NEML2 model is built. Importing them registers any @register_neml2_object types they define -- e.g. NEML2 models hosted inside a MOOSE app -- so the NEML2 input file can reference them. Mirrors the neml2 CLI --load flag. Only valid with the cpp-eager runtime (eager=true).

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

    Controllable:No

    Description:External Python extension files (paths to .py files or package directories, resolved relative to the input file and the application's data search path) imported into the embedded interpreter before the NEML2 model is built. Importing them registers any @register_neml2_object types they define -- e.g. NEML2 models hosted inside a MOOSE app -- so the NEML2 input file can reference them. Mirrors the neml2 CLI --load flag. Only valid with the cpp-eager runtime (eager=true).

  • 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. Required for the cpp-eager runtime, and for cpp-aoti only when 'input' is a stub '.i'; the cpp-aoti folder and metadata.json forms use the single model recorded in the artifact metadata and ignore it.

    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. Required for the cpp-eager runtime, and for cpp-aoti only when 'input' is a stub '.i'; the cpp-aoti folder and metadata.json forms use the single model recorded in the artifact metadata and ignore it.

  • num_threadsNumber of threads to use when evaluating the NEML2 model. Defaults to the number of threads MOOSE is run with (the --n-threads command-line value). Some models evaluate fastest with a single thread regardless of --n-threads; set this to 1 in that case.

    C++ Type:unsigned int

    Controllable:No

    Description:Number of threads to use when evaluating the NEML2 model. Defaults to the number of threads MOOSE is run with (the --n-threads command-line value). Some models evaluate fastest with a single thread regardless of --n-threads; set this to 1 in that case.

  • output_deviceDevice on which to store the model outputs, following the same schema as a single 'device' entry. Defaults to cpu, where MOOSE consumes them. Set this only if a downstream object needs the outputs on a specific device.

    C++ Type:std::string

    Controllable:No

    Description:Device on which to store the model outputs, following the same schema as a single 'device' entry. Defaults to cpu, where MOOSE consumes them. Set this only if a downstream object needs the outputs on a specific device.

  • parameter_derivativesList of NEML2 parameter derivatives to retrieve. Each entry is (output, parameter) -- the derivative of 'output' w.r.t. model 'parameter' -- with an optional third element aliasing it to a custom MOOSE material property name (default d(output)/d(parameter)).

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

    Controllable:No

    Description:List of NEML2 parameter derivatives to retrieve. Each entry is (output, parameter) -- the derivative of 'output' w.r.t. model 'parameter' -- with an optional third element aliasing it to a custom MOOSE material property name (default d(output)/d(parameter)).

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

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

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.

Advanced Parameters

Sub-block 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

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

  • batch_index_generator_nameName of the NEML2BatchIndexGenerator user object. The default name is 'neml2_index__' where is the NEML2 model's name, and is this action sub-block's name.

    C++ Type:std::string

    Controllable:No

    Description:Name of the NEML2BatchIndexGenerator user object. The default name is 'neml2_index__' where is the NEML2 model's name, and is this action sub-block's name.

  • blockList of blocks (subdomains) where the material model is defined

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

    Controllable:No

    Description:List of blocks (subdomains) where the material model is defined

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

  • derivativesList of NEML2 derivatives to retrieve. Each entry is (output, input) -- the derivative of 'output' w.r.t. 'input' -- with an optional third element aliasing it to a custom MOOSE material property name (default d(output)/d(input)).

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

    Controllable:No

    Description:List of NEML2 derivatives to retrieve. Each entry is (output, input) -- the derivative of 'output' w.r.t. 'input' -- with an optional third element aliasing it to a custom MOOSE material property name (default d(output)/d(input)).

  • deviceCompute device(s) for the NEML2 model, each following the schema (cpu|cuda)[:] (e.g. 'cpu', 'cuda:1'). cpp-eager pins the model to the first device. cpp-aoti dispatches over the list: a CUDA list is round-robined over the MPI ranks on each node (one device per rank when counts match, sharing when there are more ranks than devices, an error when there are fewer); a single 'cpu' runs each rank's local batch on CPU. If not specified, defaults to the compute device from the --compute-device command line argument.

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

    Controllable:No

    Description:Compute device(s) for the NEML2 model, each following the schema (cpu|cuda)[:] (e.g. 'cpu', 'cuda:1'). cpp-eager pins the model to the first device. cpp-aoti dispatches over the list: a CUDA list is round-robined over the MPI ranks on each node (one device per rank when counts match, sharing when there are more ranks than devices, an error when there are fewer); a single 'cpu' runs each rank's local batch on CPU. If not specified, defaults to the compute device from the --compute-device command line argument.

  • device_batchPer-device chunk size along the leading batch axis (0 = run the whole local batch at once). Must have length 1 (broadcast to all devices) or match the length of 'device'. Defaults to 0.

    C++ Type:std::vector<unsigned int>

    Controllable:No

    Description:Per-device chunk size along the leading batch axis (0 = run the whole local batch at once). Must have length 1 (broadcast to all devices) or match the length of 'device'. Defaults to 0.

  • dump_inputs_on_failureFalseWhen a NEML2 constitutive solve fails (recoverable convergence failure), serialize the input tensors to a per-rank TorchScript file '_count_rank.pt' (c is a persistent failure counter). The file can be loaded offline with torch.jit.load to re-evaluate the model on the failing batch, independently of MOOSE.

    Default:False

    C++ Type:bool

    Controllable:No

    Description:When a NEML2 constitutive solve fails (recoverable convergence failure), serialize the input tensors to a per-rank TorchScript file '_count_rank.pt' (c is a persistent failure counter). The file can be loaded offline with torch.jit.load to re-evaluate the model on the failing batch, independently of MOOSE.

  • eagerFalseUse the cpp-eager NEML2 runtime, which embeds a Python interpreter and loads the model from the source 'input' file at runtime. Default false -- use the cpp-aoti runtime, which loads an ahead-of-time-compiled artifact (no Python at runtime) from the artifact folder given by 'input'. The 'load' parameter is only valid with eager=true.

    Default:False

    C++ Type:bool

    Controllable:No

    Description:Use the cpp-eager NEML2 runtime, which embeds a Python interpreter and loads the model from the source 'input' file at runtime. Default false -- use the cpp-aoti runtime, which loads an ahead-of-time-compiled artifact (no Python at runtime) from the artifact folder given by 'input'. The 'load' parameter is only valid with eager=true.

  • executor_nameName of the NEML2ModelExecutor user object. The default name is 'neml2__' where is the NEML2 model's name, and is this action sub-block's name.

    C++ Type:std::string

    Controllable:No

    Description:Name of the NEML2ModelExecutor user object. The default name is 'neml2__' where is the NEML2 model's name, and is this action sub-block's name.

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

  • inputFor the cpp-eager runtime, the path to the source NEML2 '.i' model file. For the cpp-aoti runtime, any of: the artifact folder produced by neml2-compile (a self-describing directory holding metadata.json plus per-/ '.pt2' binaries), the metadata.json inside it, or the neml2-compile stub '.i'. Prefer the artifact folder -- it is self-contained and relocatable as a unit, and needs no 'model' name. The stub '.i' is accepted for compatibility but points at its artifact folder by path, so the two must stay together.

    C++ Type:DataFileName

    Controllable:No

    Description:For the cpp-eager runtime, the path to the source NEML2 '.i' model file. For the cpp-aoti runtime, any of: the artifact folder produced by neml2-compile (a self-describing directory holding metadata.json plus per-/ '.pt2' binaries), the metadata.json inside it, or the neml2-compile stub '.i'. Prefer the artifact folder -- it is self-contained and relocatable as a unit, and needs no 'model' name. The stub '.i' is accepted for compatibility but points at its artifact folder by path, so the two must stay together.

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

  • loadExternal Python extension files (paths to .py files or package directories, resolved relative to the input file and the application's data search path) imported into the embedded interpreter before the NEML2 model is built. Importing them registers any @register_neml2_object types they define -- e.g. NEML2 models hosted inside a MOOSE app -- so the NEML2 input file can reference them. Mirrors the neml2 CLI --load flag. Only valid with the cpp-eager runtime (eager=true).

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

    Controllable:No

    Description:External Python extension files (paths to .py files or package directories, resolved relative to the input file and the application's data search path) imported into the embedded interpreter before the NEML2 model is built. Importing them registers any @register_neml2_object types they define -- e.g. NEML2 models hosted inside a MOOSE app -- so the NEML2 input file can reference them. Mirrors the neml2 CLI --load flag. Only valid with the cpp-eager runtime (eager=true).

  • 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. Required for the cpp-eager runtime, and for cpp-aoti only when 'input' is a stub '.i'; the cpp-aoti folder and metadata.json forms use the single model recorded in the artifact metadata and ignore it.

    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. Required for the cpp-eager runtime, and for cpp-aoti only when 'input' is a stub '.i'; the cpp-aoti folder and metadata.json forms use the single model recorded in the artifact metadata and ignore it.

  • num_threadsNumber of threads to use when evaluating the NEML2 model. Defaults to the number of threads MOOSE is run with (the --n-threads command-line value). Some models evaluate fastest with a single thread regardless of --n-threads; set this to 1 in that case.

    C++ Type:unsigned int

    Controllable:No

    Description:Number of threads to use when evaluating the NEML2 model. Defaults to the number of threads MOOSE is run with (the --n-threads command-line value). Some models evaluate fastest with a single thread regardless of --n-threads; set this to 1 in that case.

  • output_deviceDevice on which to store the model outputs, following the same schema as a single 'device' entry. Defaults to cpu, where MOOSE consumes them. Set this only if a downstream object needs the outputs on a specific device.

    C++ Type:std::string

    Controllable:No

    Description:Device on which to store the model outputs, following the same schema as a single 'device' entry. Defaults to cpu, where MOOSE consumes them. Set this only if a downstream object needs the outputs on a specific device.

  • parameter_derivativesList of NEML2 parameter derivatives to retrieve. Each entry is (output, parameter) -- the derivative of 'output' w.r.t. model 'parameter' -- with an optional third element aliasing it to a custom MOOSE material property name (default d(output)/d(parameter)).

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

    Controllable:No

    Description:List of NEML2 parameter derivatives to retrieve. Each entry is (output, parameter) -- the derivative of 'output' w.r.t. model 'parameter' -- with an optional third element aliasing it to a custom MOOSE material property name (default d(output)/d(parameter)).

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

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

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.

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