LibtorchModel

commentnote

This is a NEML2 model. See the NEML2 syntax documentation for guidance on using NEML2 models in a MOOSE simulation.

This model is a wrapper for evaluating PyTorch modules in .pt format, mapping an arbitrary number of inputs to an arbitrary number of outputs. See the Torch Script documentation for instructions on exporting PyTorch modules as torch scripts.

Example Input File

An example NEML2 input file is shown below. In this example, a single input inputs = 'forces/T' is mapped to a single output outputs = 'state/k_T'.

[Models]
  [kappa]
    type = LibtorchModel
    inputs = 'T'
    outputs = 'k_T'
    file_path = 'libtorch/test/thermal_conductivity_model.pt'
  []
[]
(test/tests/neml2/torchscript/thermal_conductivity.i)

The evaluated NEML2 variable value state/k_T can then be mapped back to a MOOSE material property as shown in the following input file.

[NEML2<<<{"href": "../../../syntax/NEML2/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."}>>> = 'thermal_conductivity.i'
  [thermal_conductivity_model]
    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."}>>> = 'kappa'

    # 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))."}>>> = 'k_T T'

    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'."}>>> = 'k_T dk_T/dT'
    export_output_targets<<<{"description": "The export targets corresponding to each MOOSE material property specified in export_outputs."}>>> = 'exodus; exodus'
  []
[]
(test/tests/neml2/torchscript/heat_conduction.i)

The NEML2 input file is specified inside the NEML2 block. We specify which NEML2 model to use (model = 'rom'), and specify that we want to map the non-linear T variable in MOOSE to the forces/T NEML2 variable, and the state/k_T NEML2 variable is mapped back to the k_T MOOSE material property (which is automatically generated by the action).

NEML2 also uses automatic differenciation on the libtorch model to provide arbitrary derivatives of the outputs in relation to the inputs. Here we specify that we want to calculate to populate the Jacobian in a heat conduction example problem.

References

No citations exist within this document.

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.