https://mooseframework.inl.gov
Loading...
Searching...
No Matches
NEML2ModelInterface.h
Go to the documentation of this file.
1//* This file is part of the MOOSE framework
2//* https://mooseframework.inl.gov
3//*
4//* All rights reserved, see COPYRIGHT for full restrictions
5//* https://github.com/idaholab/moose/blob/master/COPYRIGHT
6//*
7//* Licensed under LGPL 2.1, please see LICENSE for details
8//* https://www.gnu.org/licenses/lgpl-2.1.html
9
10#pragma once
11
12#include <thread>
13#include <utility>
14#include <tuple>
15#include "NEML2Utils.h"
16#include "InputParameters.h"
17#include "libmesh/libmesh_base.h" // libMesh::n_threads()
18
19#ifdef NEML2_ENABLED
20#include "NEML2ModelHandle.h"
21#endif
22
27template <class T>
28class NEML2ModelInterface : public T
29{
30public:
32
33 template <typename... P>
34 NEML2ModelInterface(const InputParameters & params, P &&... args);
35
36#ifdef NEML2_ENABLED
37
38protected:
43 virtual void validateModel() const;
44
46 const NEML2ModelHandle & model() const { return *_model; }
47
49 NEML2ModelHandle & model() { return *_model; }
50
52 const at::Device & device() const { return _device; }
53
55 const at::Device & output_device() const { return _output_device; }
56
60 unsigned int neml2NumThreads() const { return _num_threads; }
61
62private:
66 static std::vector<std::string> loadExtensionPaths(const InputParameters & params)
67 {
68 const auto files = params.get<std::vector<DataFileName>>("load");
69 return std::vector<std::string>(files.begin(), files.end());
70 }
71
75 static std::unique_ptr<NEML2ModelHandle> makeModelHandle(const InputParameters & params,
77 {
78 // Route NEML2's log output to MOOSE's console before the model is built/evaluated.
80
81 const bool eager = params.get<bool>("eager");
82 const auto load = loadExtensionPaths(params);
83
84 // 'load' imports Python extensions into the embedded interpreter -- cpp-eager only.
85 if (!eager && !load.empty())
86 self.paramError("load",
87 "The 'load' parameter imports Python extensions into the embedded "
88 "interpreter and is only valid with the cpp-eager runtime. Set eager=true to "
89 "use it, or remove it for the cpp-aoti runtime.");
90 // 'input' is the source .i (cpp-eager) or the neml2-compile artifact folder (cpp-aoti).
91 if (!params.isParamValid("input"))
92 self.paramError(
93 "input",
94 "'input' (the NEML2 source '.i' for cpp-eager, or the neml2-compile artifact folder for "
95 "cpp-aoti) is required.");
96
97 // Device list (default: the app's libtorch compute device).
98 auto devices = params.get<std::vector<std::string>>("device");
99 if (devices.empty())
100 devices = {at::Device(self.getMooseApp().getLibtorchDevice()).str()};
101
102 // Per-device chunk sizes (default 0 = whole batch); length 1 broadcasts, else matches 'device'.
103 auto db = params.get<std::vector<unsigned int>>("device_batch");
104 if (db.empty())
105 db = {0};
106 if (db.size() != 1 && db.size() != devices.size())
107 self.paramError("device_batch",
108 "'device_batch' must have length 1 or the same length as 'device'.");
109 const std::vector<std::size_t> batch_sizes(db.begin(), db.end());
110
111 // Host MPI communicator for the cpp-aoti CUDA scheduler (read at construction only; unused for
112 // cpp-eager and for CPU dispatch).
113 const auto mpi_comm = self.comm().get();
114
115 // MOOSE drives NEML2 exclusively in Float64. Force the libtorch default dtype to Float64 while
116 // the model is built so a parameter-less eager model (whose dtype would otherwise fall back to
117 // libtorch's Float32 default) resolves to Float64 and accepts MOOSE's double inputs.
118 const NEML2Utils::ScopedDefaultDtype scoped_dtype;
119
120 return makeNEML2ModelHandle(eager,
121 std::string(params.get<DataFileName>("input")),
122 params.get<std::string>("model"),
123 devices,
124 batch_sizes,
125 &mpi_comm,
126 load);
127 }
128
132 std::unique_ptr<NEML2ModelHandle> _model;
134 const at::Device _device;
136 const at::Device _output_device;
139 const unsigned int _num_threads;
140
141#endif // NEML2_ENABLED
142};
143
144template <class T>
147{
148 InputParameters params = T::validParams();
149 params.addParam<bool>(
150 "eager",
151 false,
152 "Use the cpp-eager NEML2 runtime, which embeds a Python interpreter and loads the model "
153 "from the source 'input' file at runtime. Default false -- use the cpp-aoti runtime, which "
154 "loads an ahead-of-time-compiled artifact (no Python at runtime) from the artifact folder "
155 "given by 'input'. The 'load' parameter is only valid with eager=true.");
156 params.addParam<DataFileName>(
157 "input",
158 "For the cpp-eager runtime, the path to the source NEML2 '.i' model file. For the cpp-aoti "
159 "runtime, any of: the artifact folder produced by neml2-compile (a self-describing directory "
160 "holding metadata.json plus per-<device>/<dtype> '.pt2' binaries), the metadata.json inside "
161 "it, or the neml2-compile stub '.i'. Prefer the artifact folder -- it is self-contained and "
162 "relocatable as a unit, and needs no 'model' name. The stub '.i' is accepted for "
163 "compatibility but points at its artifact folder by path, so the two must stay together.");
164 params.addParam<std::vector<std::string>>(
165 "cli_args",
166 {},
167 "Additional command line arguments to use when parsing the NEML2 input file.");
168 params.addParam<std::vector<DataFileName>>(
169 "load",
170 {},
171 "External Python extension files (paths to .py files or package directories, resolved "
172 "relative to the input file and the application's data search path) imported into the "
173 "embedded interpreter before the NEML2 model is built. Importing them registers any "
174 "@register_neml2_object types they define -- e.g. NEML2 models hosted inside a MOOSE app -- "
175 "so the NEML2 input file can reference them. Mirrors the neml2 CLI --load flag. Only valid "
176 "with the cpp-eager runtime (eager=true).");
177 params.addParam<std::string>(
178 "model",
179 "",
180 "Name of the NEML2 model, i.e., the string inside the brackets [] in the NEML2 input file "
181 "that corresponds to the model you want to use. Required for the cpp-eager runtime, and for "
182 "cpp-aoti only when 'input' is a stub '.i'; the cpp-aoti folder and metadata.json forms use "
183 "the single model recorded in the artifact metadata and ignore it.");
184 params.addParam<std::vector<std::string>>(
185 "device",
186 {},
187 "Compute device(s) for the NEML2 model, each following the schema "
188 "(cpu|cuda)[:<device-index>] "
189 "(e.g. 'cpu', 'cuda:1'). cpp-eager pins the model to the first device. cpp-aoti dispatches "
190 "over the list: a CUDA list is round-robined over the MPI ranks on each node (one device per "
191 "rank when counts match, sharing when there are more ranks than devices, an error when there "
192 "are fewer); a single 'cpu' runs each rank's local batch on CPU. If not specified, defaults "
193 "to the compute device from the --compute-device command line argument.");
194 params.addParam<std::vector<unsigned int>>(
195 "device_batch",
196 {},
197 "Per-device chunk size along the leading batch axis (0 = run the whole local batch at once). "
198 "Must have length 1 (broadcast to all devices) or match the length of 'device'. Defaults to "
199 "0.");
200 params.addParam<std::string>(
201 "output_device",
202 "Device on which to store the model outputs, following the same schema as a single 'device' "
203 "entry. Defaults to cpu, where MOOSE consumes them. Set this only if a downstream object "
204 "needs "
205 "the outputs on a specific device.");
206 params.addParam<unsigned int>(
207 "num_threads",
208 "Number of threads to use when evaluating the NEML2 model. Defaults to the number of threads "
209 "MOOSE is run with (the --n-threads command-line value). Some models evaluate fastest with a "
210 "single thread regardless of --n-threads; set this to 1 in that case.");
211
212 return params;
213}
214
215#ifndef NEML2_ENABLED
216
217template <class T>
218template <typename... P>
220 : T(params, args...)
221{
222}
223
224#else
225
226template <class T>
227template <typename... P>
229 : T(params, args...),
230 // The cpp-eager runtime loads the model from the source .i (embedding CPython); the cpp-aoti
231 // runtime (default) loads the ahead-of-time-compiled artifact folder directly (no stub .i).
232 // makeModelHandle parses the runtime parameters; _device is the handle's resolved device.
233 _model(makeModelHandle(params, *this)),
234 _device(_model->device()),
235 // Default the output device to the host: the outputs feed MOOSE material properties, whose
236 // retrievers read them element by element, so leaving them on an accelerator would turn a
237 // single bulk device-to-host copy into thousands of per-element copies.
238 _output_device(params.isParamValid("output_device")
239 ? at::Device(params.get<std::string>("output_device"))
240 : at::Device(at::kCPU)),
241 // Default to the MOOSE/libMesh thread count (--n-threads, i.e. 1 unless set); AOTI graphs get
242 // little from intra-op threads and this avoids oversubscribing under MPI. Overridable.
243 _num_threads(params.isParamValid("num_threads") ? params.get<unsigned int>("num_threads")
244 : libMesh::n_threads())
245{
246}
247
248template <class T>
249void
251{
252 // NEML2 v3 provides no C++ diagnose() equivalent; constructing the eager model above already
253 // parses and validates it. Kept as a hook for derived classes.
254}
255
256#endif // NEML2_ENABLED
std::unique_ptr< NEML2ModelHandle > makeNEML2ModelHandle(bool eager, const std::string &input, const std::string &model, const std::vector< std::string > &devices, const std::vector< std::size_t > &batch_sizes, const void *comm, const std::vector< std::string > &load)
Construct a NEML2 model handle for the requested runtime.
void ErrorVector unsigned int
The main MOOSE class responsible for handling user-defined parameters in almost every MOOSE system.
void addParam(const std::string &name, const S &value, const std::string &doc_string)
These methods add an optional parameter and a documentation string to the InputParameters object.
std::vector< std::pair< R1, R2 > > get(const std::string &param1, const std::string &param2) const
Combine two vector parameters into a single vector of pairs.
bool isParamValid(const std::string &name) const
This method returns parameters that have been initialized in one fashion or another,...
Runtime-agnostic handle over a NEML2 v3 model.
Interface class to provide common input parameters, members, and methods for MOOSEObjects that use NE...
NEML2ModelInterface(const InputParameters &params, P &&... args)
const unsigned int _num_threads
libtorch intra-op thread count applied (scoped) during model evaluation; defaults to the MOOSE/libMes...
static std::vector< std::string > loadExtensionPaths(const InputParameters &params)
Resolve the 'load' DataFileName list (whose relative paths InputParameters has already resolved again...
static InputParameters validParams()
const NEML2ModelHandle & model() const
Get the NEML2 model handle (cpp-aoti by default, cpp-eager when eager=true)
virtual void validateModel() const
Validate the NEML2 material model.
const at::Device & output_device() const
Get the target output device.
const at::Device & device() const
Get the target compute device.
static std::unique_ptr< NEML2ModelHandle > makeModelHandle(const InputParameters &params, NEML2ModelInterface< T > &self)
Parse the runtime parameters and build the model handle.
const at::Device _output_device
The device on which to store the outputs.
const at::Device _device
The device on which to evaluate the NEML2 model (this rank's scheduler-assigned device)
unsigned int neml2NumThreads() const
libtorch intra-op thread count to use while evaluating the NEML2 model.
std::unique_ptr< NEML2ModelHandle > _model
The NEML2 material model handle.
NEML2ModelHandle & model()
Non-const access to the NEML2 model handle, for runtime parameter writes (set_parameter)
RAII guard forcing libtorch's default scalar type to Float64 for its lifetime, restoring the previous...
Definition NEML2Utils.h:249
void redirectLogsToConsole(const ConsoleStream &console)
Route NEML2's log output into MOOSE's console.
Definition NEML2Utils.C:45
The following methods are specializations for using the libMesh::Parallel::packed_range_* routines fo...