NEML2Utils Namespace Reference

Classes
struct	Layout
struct	Layout< RankFourTensor >
struct	Layout< RankTwoTensor >
struct	Layout< Real >
struct	Layout< RealVectorValue >
struct	Layout< SymmetricRankFourTensor >
struct	Layout< SymmetricRankTwoTensor >
class	ScopedDefaultDtype
	RAII guard forcing libtorch's default scalar type to Float64 for its lifetime, restoring the previous default on destruction. More...
class	ScopedNumThreads
	RAII guard that pins libtorch's intra-op thread count for the current scope and restores the previous value on destruction. More...

Enumerations
enum class	MOOSEIOType {   TIME , SCALAR , FUNCTION , VARIABLE ,   MATERIAL }

Functions
std::string	stringify (MOOSEIOType type)
std::pair< std::string, int >	parseLag (const std::string &name)
	Parse NEML2 v3 lag notation: "var~N" is the N-th old value of a variable (var~1 == old var, var~2 == older, ...).
std::string	lagName (const std::string &base, int lag)
	Inverse of parseLag: build the variable name for a base name + lag.
bool	contains (const std::vector< std::string > &v, const std::string &s)
	Whether a vector of strings contains a given string.
template<typename T >
at::Tensor	fromBlob (const std::vector< T > &data)
	Map from std::vector<T> to an at::Tensor without copying the data.
template<typename T >
void	copyTensorToMOOSEData (const at::Tensor &src, T &dest)
	Directly copy a contiguous chunk of memory of a at::Tensor to a MOOSE data of type T.
template<typename T >
void	copyBlobToMOOSEData (const Real *src, T &dest)
	Copy one element's worth of doubles from a contiguous host buffer into a MOOSE datum of type T.
void	redirectLogsToConsole (const ConsoleStream &console)
	Route NEML2's log output into MOOSE's console.
void	dumpInputsToTorchScript (const std::map< std::string, at::Tensor > &inputs, const std::string &filename)
	Serialize a set of named NEML2 input tensors to a TorchScript archive at filename (a torch::jit::Module whose buffers are the input tensors), loadable offline in Python via torch.jit.load.
std::string	docstring (const std::string &desc)
	Augment docstring if NEML2 is not enabled.
void	assertNEML2Enabled ()
	Assert that NEML2 is enabled.

Variables
static std::string	NEML2_help_message
static const std::string	missing_neml2

Enumeration Type Documentation

MOOSEIOType

enum class NEML2Utils::MOOSEIOType

strong

Enumerator
TIME
SCALAR
FUNCTION
VARIABLE
MATERIAL

Definition at line 41 of file NEML2Utils.h.

{
  // unbatched
  TIME,
  SCALAR,
  // batched
  FUNCTION,
  VARIABLE,
  MATERIAL
};

Function Documentation

assertNEML2Enabled()

void NEML2Utils::assertNEML2Enabled

(

)

Assert that NEML2 is enabled.

A MooseError is raised if NEML2 is not enabled.

Definition at line 90 of file NEML2Utils.C.

{
#ifndef NEML2_ENABLED
  mooseError(missing_neml2);
#endif
}

Referenced by NEML2Action::NEML2Action(), NEML2ActionCommon::NEML2ActionCommon(), and NEML2ToMOOSEMaterialProperty< T >::NEML2ToMOOSEMaterialProperty().

contains()

bool NEML2Utils::contains ( const std::vector< std::string > &  v, const std::string &  s  )

inline

Whether a vector of strings contains a given string.

Definition at line 78 of file NEML2Utils.h.

{
  return std::find(v.begin(), v.end(), s) != v.end();
}

copyBlobToMOOSEData()

template<typename T >

void NEML2Utils::copyBlobToMOOSEData	(	const Real *	src,
		T &	dest
	)

Copy one element's worth of doubles from a contiguous host buffer into a MOOSE datum of type T.

This is the raw-pointer analogue of copyTensorToMOOSEData: src must point at a run of Layout<T>::strides[0] doubles (one element) inside a contiguous, host-resident, double-typed buffer – e.g. the data of a NEML2 output tensor already moved to the host. It performs a plain memcpy with no per-call at::Tensor allocation/dispatch, which matters when retrieving outputs element-by-element over a large batch. The layout assumption is identical to copyTensorToMOOSEData (row-major, matching Layout<T>).

Definition at line 195 of file NEML2Utils.h.

{
  std::memcpy(reinterpret_cast<Real *>(&dest), src, Layout<T>::strides[0] * sizeof(Real));
}

copyTensorToMOOSEData()

template<typename T >

void NEML2Utils::copyTensorToMOOSEData	(	const at::Tensor &	src,
		T &	dest
	)

Directly copy a contiguous chunk of memory of a at::Tensor to a MOOSE data of type T.

This assumes the at::Tensor and T have the same layout, for example both row-major with T = RankTwoTensor. If the layouts are different, we may need to reshape/reorder/transpose the at::Tensor before copying.

For this method to work,

1. the address of dest must align with the first element of the data,
2. the number of elements in dest must match the number of elements in src,
3. the src tensor must be of type at::kDouble, and
4. data in dest must be reinterpretable as Real.

Definition at line 166 of file NEML2Utils.h.

{
  if (src.dtype() != at::kDouble)
    mooseError(
        "Cannot copy at::Tensor with dtype ", src.dtype(), " into ", demangle(typeid(T).name()));
  if (src.numel() != Layout<T>::strides[0])
    mooseError("Cannot copy at::Tensor with shape ",
               src.sizes(),
               " into ",
               demangle(typeid(T).name()),
               " with different number of elements.");
  auto dest_tensor = at::from_blob(
      reinterpret_cast<Real *>(&dest), Layout<T>::shape, at::TensorOptions().dtype(at::kDouble));
  dest_tensor.copy_(src.reshape(Layout<T>::shape));
}

docstring()

std::string NEML2Utils::docstring

(

const std::string &

desc

)

Augment docstring if NEML2 is not enabled.

Definition at line 80 of file NEML2Utils.C.

{
#ifndef NEML2_ENABLED
  return missing_neml2 + " (Original description: " + desc + ")";
#else
  return desc;
#endif
}

dumpInputsToTorchScript()

void NEML2Utils::dumpInputsToTorchScript	(	const std::map< std::string, at::Tensor > &	inputs,
		const std::string &	filename
	)

Serialize a set of named NEML2 input tensors to a TorchScript archive at filename (a torch::jit::Module whose buffers are the input tensors), loadable offline in Python via torch.jit.load.

Used to capture the exact inputs of a failed constitutive solve so the model can be re-evaluated independently of MOOSE. Buffer names are the input variable names with characters that are not valid identifiers ('~', '/') replaced by '_'; the original names are recoverable from the NEML2 model's input list.

Definition at line 25 of file NEML2Utils.C.

{
  // Stash each defined input tensor (moved to host) as a buffer on a TorchScript module, then save.
  // Buffer names must be valid identifiers, so sanitize '~'/'/' etc. to '_'.
  torch::jit::Module mod("neml2_failed_inputs");
  for (const auto & [name, tensor] : inputs)
  {
    if (!tensor.defined())
      continue;
    std::string key = name;
    for (auto & c : key)
      if (!std::isalnum(static_cast<unsigned char>(c)) && c != '_')
        c = '_';
    mod.register_buffer(key, tensor.detach().to(at::kCPU).contiguous());
  }
  mod.save(filename);
}

fromBlob()

template<typename T >

at::Tensor NEML2Utils::fromBlob

(

const std::vector< T > &

data

)

Map from std::vector<T> to an at::Tensor without copying the data.

This method is used in gatherers which gather data from MOOSE as input variables to the NEML2 material model. So in theory, we only need to provide Layout specializations for MOOSE types that can potentially be used as NEML2 input variables. The returned tensor has shape (data.size(), *Layout<T>::shape), i.e. a leading batch axis followed by the variable's base shape, which is the (*B, *base_shape) convention NEML2 v3's C++ API expects.

For this method to work, the underlying data in data must be reinterpretable as Real (at::kDouble). The data class T must also be aligned and follow the striding implied by Layout<T>::shape. The data class T must also have no padding or overhead.

Definition at line 139 of file NEML2Utils.h.

{
  // Full shape: leading batch dim followed by the base shape.
  std::vector<int64_t> shape;
  shape.reserve(1 + Layout<T>::shape.size());
  shape.push_back(static_cast<int64_t>(data.size()));
  shape.insert(shape.end(), Layout<T>::shape.begin(), Layout<T>::shape.end());
  // The const_cast is fine because torch works with non-const ptr so that it can optionally handle
  // deallocation. But we are not going to let torch do that.
  return at::from_blob(const_cast<T *>(data.data()), shape, at::TensorOptions().dtype(at::kDouble));
}

Referenced by MOOSEQuantityToNEML2< T, state >::gatheredData().

lagName()

std::string NEML2Utils::lagName ( const std::string &  base, int  lag  )

inline

Inverse of parseLag: build the variable name for a base name + lag.

Definition at line 71 of file NEML2Utils.h.

{
  return lag == 0 ? base : base + "~" + std::to_string(lag);
}

Referenced by lagName().

parseLag()

std::pair< std::string, int > NEML2Utils::parseLag ( const std::string &  name )

inline

Parse NEML2 v3 lag notation: "var~N" is the N-th old value of a variable (var~1 == old var, var~2 == older, ...).

Returns {base_name, lag}; lag == 0 when there is no "~N" suffix. Defined here (shared, namespaced, inline) so the NEML2 unity build does not see duplicate definitions.

Definition at line 58 of file NEML2Utils.h.

{
  const auto pos = name.rfind('~');
  if (pos == std::string::npos)
    return {name, 0};
  const auto suffix = name.substr(pos + 1);
  if (suffix.empty() || suffix.find_first_not_of("0123456789") != std::string::npos)
    return {name, 0};
  return {name.substr(0, pos), std::stoi(suffix)};
}

Referenced by parseLag().

redirectLogsToConsole()

void NEML2Utils::redirectLogsToConsole

(

const ConsoleStream &

console

)

Route NEML2's log output into MOOSE's console.

NEML2 v3 emits its diagnostics (warnings, per-solve info, debug detail across all evaluation routes) through a single process-global sink. This installs a sink that writes each already-formatted line (carrying the [neml2:<channel>] prefix) to console, so NEML2's output lands in MOOSE's console instead of raw stdout/stderr. Verbosity levels are left at NEML2's defaults. The sink captures a copy of console (bound to the app-owned OutputWarehouse, valid for the app's lifetime); calling this again – e.g. once per [NEML2] block – is idempotent.

Definition at line 45 of file NEML2Utils.C.

{
  // Capture a copy of the ConsoleStream (it binds the app-owned OutputWarehouse by reference, so
  // the copy stays valid for the app's lifetime) and hand every NEML2 log line to it. The line
  // already carries the [neml2:<channel>] prefix; NEML2's verbosity levels are left at their
  // defaults.
  neml2::aoti::log::set_sink([console](neml2::aoti::log::Level, const std::string & line)
                             { console << line << std::endl; });
}

Referenced by NEML2ModelInterface< T >::makeModelHandle(), and NEML2Action::NEML2Action().

stringify()

std::string NEML2Utils::stringify

(

MOOSEIOType

type

)

Definition at line 56 of file NEML2Utils.C.

{
  switch (type)
  {
    case NEML2Utils::MOOSEIOType::TIME:
      return "TIME";
    case NEML2Utils::MOOSEIOType::SCALAR:
      return "SCALAR";
    case NEML2Utils::MOOSEIOType::FUNCTION:
      return "FUNCTION";
    case NEML2Utils::MOOSEIOType::VARIABLE:
      return "VARIABLE";
    case NEML2Utils::MOOSEIOType::MATERIAL:
      return "MATERIAL";
    default:
      mooseError("Unknown MOOSE IO type.");
  }
}

Referenced by NEML2Action::printSummary().

Variable Documentation

missing_neml2

const std::string NEML2Utils::missing_neml2

static

Initial value:

= "The `NEML2` library is required but not enabled. Refer "
                                         "to the documentation for guidance on how to enable it."

Definition at line 76 of file NEML2Utils.C.

Referenced by assertNEML2Enabled(), and docstring().

NEML2_help_message

std::string NEML2Utils::NEML2_help_message

static

Initial value:

= R""""(
==============================================================================
To debug NEML2 related issues:
1. Build and run MOOSE in dbg mode.
2. Re-run the simulation using the dbg executable, and often times
   NEML2 will provide a more helpful error message.
3. If the error message is not helpful, or if there is still no error message,
   run the simulation through a debugger: See
   https://mooseframework.inl.gov/application_development/debugging.html
4. If the issue is due to a NEML2 bug, feel free to report it at
   https://github.com/applied-material-modeling/neml2/issues
==============================================================================
)""""

Definition at line 263 of file NEML2Utils.h.

Referenced by NEML2ModelExecutor::extractOutputs(), NEML2ModelExecutor::fillInputs(), and NEML2ModelExecutor::solve().