Solver interface¶

A common task in NEML is solving a nonlinear system of equations. For example, because NEML uses implicit time integration it must solve a nonlinear system each time it integrates a material model defined with a rate form. NEML provides an opaque mechanism for using different nonlinear equation solvers throughout the code. It does this by having objects that need to solve nonlinear equations solvable by inheriting from neml::Solvable.

class Solvable¶

Generic nonlinear solver interface.

Subclassed by neml::CreepModel, neml::LarsonMillerRelation, neml::NEMLScalarDamagedModel_sd, neml::SingleCrystalModel, neml::SmallStrainCreepPlasticity, neml::SubstepModel_sd, neml::TestPower

Public Functions

virtual size_t nparams() const = 0¶: Number of parameters in the nonlinear equation.

virtual void init_x(double *const x, TrialState *ts) = 0¶: Initialize a guess to start the solution iterations.

virtual void RJ(const double *const x, TrialState *ts, double *const R, double *const J) = 0¶: Nonlinear residual equations and corresponding jacobian.

This class requires an object implement three virtual methods:

nparams: Return the number of variables in the nonlinear system to be solved.

init_x: Given a vector of length nparams and a neml::TrialState object setup an initial guess to start the nonlinear solution iterations.

RJ: Given the current guess at the solution x (length nparams) and the neml::TrialState object return the residual equations (R, length nparams) and the Jacobian of the residual equations with respect to the variables (J, nparams $\times$ nparams).

A neml::TrialState is a completely generic object that contains any information beyond the current guess at the solution the class will need to construct an initial guess and to calculate the residual and the Jacobian. Essentially, it contains any variables that are held fixed during the nonlinear solution process. While neml::TrialState objects all inherit from a base class, this is currently entirely cosmetic.

class TrialState¶

Trial state Store data the solver needs and can be passed into solution interface

Subclassed by neml::CreepModelTrialState, neml::GITrialState, neml::LMTrialState, neml::SCTrialState, neml::SDTrialState, neml::SSCPTrialState, neml::SSPPTrialState, neml::SSRIPTrialState

Essentially they are C++ structs holding field data. Below is an example TrialState for the neml::SmallStrainPerfectPlasticity object.

/// Small strain perfect plasticity trial state
//  Store data the solver needs and can be passed into solution interface
class SSPPTrialState : public TrialState {
 public:
  double ys, T;    // Yield stress, temperature
  double ee_n[6];  // Previous value of elastic strain
  double s_n[6];   // Previous stress
  double s_tr[6];  // Elastic trial stress
  double e_np1[6]; // Next strain
  double e_n[6];   // Previous strain
  double S[36];    // Compliance
  double C[36];    // Stiffness
};

All this is a struct containing the information required to setup the nonlinear residual equations. Note this object does not contain the current value of stress or history. This information is contained (and updated) in the solution vector x.

Currently, NEML has two options for solving nonlinear equations. NEML contains a built-in implementation of the Newton-Raphson method or NEML can use the NOX <https://trilinos.org/packages/nox-and-loca/> solver contained in the Trilinos <https://trilinos.org/> package, developed by Sandia National Laboratories. The solver is configured at build time, using the CMake configuration.