The base class for nonlinear parameters. More...

Detailed Description

template<typename T>
class neml2::NonlinearParameter< T >

The base class for nonlinear parameters.

The word "nonlinear" refers to the fact that the parameter can change as a function of state or forces. In other words, in the context of updating an implicit model, the value of the parameter can change fron nonlinear iteration to nonlinear iteration, as the guess of the solution keeps updating.

The output of a nonlinear parameter is not a "parameter" in our usual definition as one does not calibrate or optimize the nonlinear parameter in a training loop. However, the definition of the nonlinear parameter itself is oftentimes parameterized on a set of parameters (in the canonical definition). Those parameters can be calibrated or optimized.

Template Parameters

T	The class is templated on the output tensor type which can be any NEML2 primitive tensor type.

#include <NonlinearParameter.h>

Inheritance diagram for NonlinearParameter< T >:

[legend]

Public Member Functions
	NonlinearParameter (const OptionSet &options)

const Variable< T > &	param () const
	Get the nonlinear parameter.

Public Member Functions inherited from Model
	Model (const OptionSet &options)
	Construct a new Model object.

virtual void	to (const torch::TensorOptions &options)
	Send model to a different device or dtype.

void	diagnose (std::vector< Diagnosis > &) const override
	Check for common problems.

virtual bool	is_nonlinear_system () const
	Whether this model defines one or more nonlinear equations to be solved.

const std::vector< Model * > &	registered_models () const
	The models that may be used during the evaluation of this model.

Model *	registered_model (const std::string &name) const
	Get a registered model by its name.

std::set< VariableName >	consumed_items () const override
	The variables that this model depends on.

std::set< VariableName >	provided_items () const override
	The variables that this model defines as part of its output.

void	clear_input () override

void	clear_output () override

void	zero_input () override

void	zero_output () override

void	request_AD (VariableBase &y, const VariableBase &u)
	Request to use AD to compute the first derivative of a variable.

void	request_AD (VariableBase &y, const VariableBase &u1, const VariableBase &u2)
	Request to use AD to compute the second derivative of a variable.

virtual void	value ()
	Evalute the model.

virtual void	value_and_dvalue ()
	Evalute the model and compute its derivative.

virtual void	dvalue ()
	Evalute the derivative.

virtual void	value_and_dvalue_and_d2value ()
	Evalute the model and compute its first and second derivatives.

virtual void	d2value ()
	Evalute the second derivatives.

virtual void	dvalue_and_d2value ()
	Evalute the first and second derivatives.

virtual ValueMap	value (const ValueMap &in)
	Convenient shortcut to construct and return the model value.

virtual std::tuple< ValueMap, DerivMap >	value_and_dvalue (const ValueMap &in)
	Convenient shortcut to construct and return the model value and its derivative.

virtual DerivMap	dvalue (const ValueMap &in)
	Convenient shortcut to construct and return the derivative.

virtual std::tuple< ValueMap, DerivMap, SecDerivMap >	value_and_dvalue_and_d2value (const ValueMap &in)
	Convenient shortcut to construct and return the model's value, first and second derivative.

virtual SecDerivMap	d2value (const ValueMap &in)
	Convenient shortcut to construct and return the model's second derivative.

virtual std::tuple< DerivMap, SecDerivMap >	dvalue_and_d2value (const ValueMap &in)
	Convenient shortcut to construct and return the model's first and second derivative.

Public Member Functions inherited from Data
	Data (const OptionSet &options)
	Construct a new Data object.

const std::vector< Data * > &	registered_data () const
	All the registered data objects.

Public Member Functions inherited from NEML2Object
	NEML2Object ()=delete

	NEML2Object (NEML2Object &&)=delete

	NEML2Object (const NEML2Object &)=delete

NEML2Object &	operator= (const NEML2Object &)=delete

NEML2Object &	operator= (NEML2Object &&)=delete

virtual	~NEML2Object ()=default

	NEML2Object (const OptionSet &options)
	Construct a new NEML2Object object.

const OptionSet &	input_options () const

const std::string &	name () const
	A readonly reference to the object's name.

const std::string &	type () const
	A readonly reference to the object's type.

const std::string &	path () const
	A readonly reference to the object's path.

const std::string &	doc () const
	A readonly reference to the object's docstring.

template<typename T = NEML2Object>
const T *	host () const
	Get a readonly pointer to the host.

template<typename T = NEML2Object>
T *	host ()
	Get a writable pointer to the host.

Public Member Functions inherited from BufferStore
	BufferStore (OptionSet options, NEML2Object *object)

	BufferStore (const BufferStore &)=delete

	BufferStore (BufferStore &&)=delete

BufferStore &	operator= (const BufferStore &)=delete

BufferStore &	operator= (BufferStore &&)=delete

virtual	~BufferStore ()=default

const Storage< std::string, TensorValueBase > &	named_buffers () const

Storage< std::string, TensorValueBase > &	named_buffers ()

TensorValueBase &	get_buffer (const std::string &name)
	}@

const TensorValueBase &	get_buffer (const std::string &name) const
	Get a read-only reference of a buffer.

Public Member Functions inherited from ParameterStore
	ParameterStore (OptionSet options, NEML2Object *object)

	ParameterStore (const ParameterStore &)=delete

	ParameterStore (ParameterStore &&)=delete

ParameterStore &	operator= (const ParameterStore &)=delete

ParameterStore &	operator= (ParameterStore &&)=delete

virtual	~ParameterStore ()=default

const Storage< std::string, TensorValueBase > &	named_parameters () const

Storage< std::string, TensorValueBase > &	named_parameters ()

void	set_parameter (const std::string &, const Tensor &)
	}@

void	set_parameters (const std::map< std::string, Tensor > &)
	Set values for parameters.

TensorValueBase &	get_parameter (const std::string &name)
	Get a writable reference of a parameter.

const TensorValueBase &	get_parameter (const std::string &name) const
	Get a read-only reference of a parameter.

bool	has_nl_param () const
	Whether this parameter store has any nonlinear parameter.

const VariableBase *	nl_param (const std::string &) const
	Query the existence of a nonlinear parameter.

virtual std::map< std::string, const VariableBase * >	named_nonlinear_parameters (bool recursive=false) const
	Get all nonlinear parameters.

virtual std::map< std::string, Model * >	named_nonlinear_parameter_models (bool recursive=false) const
	Get all nonlinear parameters' models.

Public Member Functions inherited from VariableStore
	VariableStore (OptionSet options, Model *object)

	VariableStore (const VariableStore &)=delete

	VariableStore (VariableStore &&)=delete

VariableStore &	operator= (const VariableStore &)=delete

VariableStore &	operator= (VariableStore &&)=delete

virtual	~VariableStore ()=default

LabeledAxis &	declare_axis (const std::string &name)

virtual void	setup_layout ()
	Setup the layout of all the registered axes.

const torch::TensorOptions &	tensor_options () const
	Current tensor options.

LabeledAxis &	input_axis ()

const LabeledAxis &	input_axis () const

LabeledAxis &	output_axis ()

const LabeledAxis &	output_axis () const

Storage< VariableName, VariableBase > &	input_variables ()

const Storage< VariableName, VariableBase > &	input_variables () const

Storage< VariableName, VariableBase > &	output_variables ()

const Storage< VariableName, VariableBase > &	output_variables () const

VariableBase &	input_variable (const VariableName &)

const VariableBase &	input_variable (const VariableName &) const

VariableBase &	output_variable (const VariableName &)

const VariableBase &	output_variable (const VariableName &) const

void	assign_input (const ValueMap &vals)

void	assign_output (const ValueMap &vals)

void	assign_output_derivatives (const DerivMap &derivs)
	Assign variable derivatives.

ValueMap	collect_input () const

ValueMap	collect_output () const

DerivMap	collect_output_derivatives () const
	Collect variable derivatives.

SecDerivMap	collect_output_second_derivatives () const
	Collect variable second derivatives.

Public Member Functions inherited from NonlinearSystem
	NonlinearSystem (const NonlinearSystem &)=default

	NonlinearSystem (NonlinearSystem &&) noexcept=default

NonlinearSystem &	operator= (const NonlinearSystem &)=delete

NonlinearSystem &	operator= (NonlinearSystem &&)=delete

virtual	~NonlinearSystem ()=default

	NonlinearSystem (const OptionSet &options)

virtual void	init_scaling (const Sol< false > &x, const bool verbose=false)
	Compute algebraic Jacobian-based automatic scaling following https://cs.stanford.edu/people/paulliu/files/cs517-project.pdf.

Res< true >	scale (const Res< false > &r) const
	Apply scaling to the residual.

Res< false >	unscale (const Res< true > &r) const
	Remove scaling to the residual.

Jac< true >	scale (const Jac< false > &J) const
	Apply scaling to the Jacobian.

Jac< false >	unscale (const Jac< true > &J) const
	Remove scaling to the Jacobian.

Sol< true >	scale (const Sol< false > &u) const
	Apply scaling to the solution.

Sol< false >	unscale (const Sol< true > &u) const
	Remove scaling to the solution.

virtual void	set_guess (const Sol< true > &x) final
	Set the current guess.

template<bool scaled>
Res< scaled >	residual ()
	Assemble and return the residual.

template<bool scaled>
Res< scaled >	residual (const Sol< scaled > &x)
	Convenient shortcut to set the current guess, assemble and return the residual.

template<bool scaled>
Jac< scaled >	Jacobian ()
	Assemble and return the Jacobian.

template<bool scaled>
Jac< scaled >	Jacobian (const Sol< scaled > &x)
	Convenient shortcut to set the current guess, assemble and return the Jacobian.

template<bool scaled>
std::tuple< Res< scaled >, Jac< scaled > >	residual_and_Jacobian ()
	Assemble and return the residual and Jacobian.

template<bool scaled>
std::tuple< Res< scaled >, Jac< scaled > >	residual_and_Jacobian (const Sol< scaled > &x)
	Convenient shortcut to set the current guess, assemble and return the residual and Jacobian.

Public Member Functions inherited from DependencyDefinition< VariableName >
	DependencyDefinition ()=default

	DependencyDefinition (DependencyDefinition &&)=delete

	DependencyDefinition (const DependencyDefinition &)=delete

DependencyDefinition &	operator= (const DependencyDefinition &)=delete

DependencyDefinition &	operator= (DependencyDefinition &&)=delete

virtual	~DependencyDefinition ()=default

Public Member Functions inherited from DiagnosticsInterface
	DiagnosticsInterface ()=delete

	DiagnosticsInterface (NEML2Object *object)

	DiagnosticsInterface (DiagnosticsInterface &&)=delete

	DiagnosticsInterface (const DiagnosticsInterface &)=delete

DiagnosticsInterface &	operator= (const DiagnosticsInterface &)=delete

DiagnosticsInterface &	operator= (DiagnosticsInterface &&)=delete

virtual	~DiagnosticsInterface ()=default

template<typename... Args>
void	diagnostic_assert (std::vector< Diagnosis > &diagnoses, bool assertion, Args &&... args) const

void	diagnostic_assert_state (std::vector< Diagnosis > &diagnoses, const VariableBase &v) const

void	diagnostic_assert_old_state (std::vector< Diagnosis > &diagnoses, const VariableBase &v) const

void	diagnostic_assert_force (std::vector< Diagnosis > &diagnoses, const VariableBase &v) const

void	diagnostic_assert_old_force (std::vector< Diagnosis > &diagnoses, const VariableBase &v) const

void	diagnostic_assert_residual (std::vector< Diagnosis > &diagnoses, const VariableBase &v) const

void	diagnostic_check_input_variable (std::vector< Diagnosis > &diagnoses, const VariableBase &v) const

void	diagnostic_check_output_variable (std::vector< Diagnosis > &diagnoses, const VariableBase &v) const

Static Public Member Functions
static OptionSet	expected_options ()

Static Public Member Functions inherited from Model
static OptionSet	expected_options ()

Static Public Member Functions inherited from Data
static OptionSet	expected_options ()

Static Public Member Functions inherited from NEML2Object
static OptionSet	expected_options ()

Static Public Member Functions inherited from NonlinearSystem
static OptionSet	expected_options ()

static void	disable_automatic_scaling (OptionSet &options)

static void	enable_automatic_scaling (OptionSet &options)

Protected Attributes
Variable< T > &	_p
	The nonlinear parameter.

Protected Attributes inherited from Model
std::vector< Model * >	_registered_models
	Models this model may use during its evaluation.

Protected Attributes inherited from Data
std::vector< Data * >	_registered_data
	Registered Data objects.

Protected Attributes inherited from ParameterStore
std::map< std::string, const VariableBase * >	_nl_params
	Map from nonlinear parameter names to their corresponding variable views.

std::map< std::string, Model * >	_nl_param_models
	Map from nonlinear parameter names to models which evaluate them.

Protected Attributes inherited from NonlinearSystem
const bool	_autoscale
	If true, do automatic scaling.

const Real	_autoscale_tol
	Tolerance for convergence check of the iterative automatic scaling algorithm.

const unsigned int	_autoscale_miter
	Maximum number of iterations allowed for the iterative automatic scaling algorithm.

bool	_scaling_matrices_initialized
	Flag to indicate whether scaling matrices have been computed.

Tensor	_row_scaling
	Row scaling "matrix" – since it's a batched diagonal matrix, we are only storing its diagonals.

Tensor	_col_scaling
	Column scaling "matrix" – since it's a batched diagonal matrix, we are only storing its diagonals.

Additional Inherited Members
Protected Member Functions inherited from Model
void	setup () override
	Setup this object.

virtual void	link_input_variables ()

virtual void	link_input_variables (Model *submodel)

virtual void	link_output_variables ()

virtual void	link_output_variables (Model *submodel)

virtual void	request_AD ()

void	diagnose_nl_sys (std::vector< Diagnosis > &diagnoses) const
	Additional diagnostics for a nonlinear system.

virtual void	set_value (bool out, bool dout_din, bool d2out_din2)=0
	The map between input -> output, and optionally its derivatives.

template<typename T , typename = typename std::enable_if_t<std::is_base_of_v<Model, T>>>
T &	register_model (const std::string &name, bool nonlinear=false, bool merge_input=true)
	Register a model that the current model may use during its evaluation.

void	set_guess (const Sol< false > &) override
	Set the unscaled current guess.

void	assemble (Res< false > , Jac< false > ) override
	Compute the unscaled residual and Jacobian.

Protected Member Functions inherited from Data
template<typename T , typename = typename std::enable_if_t<std::is_base_of_v<Data, T>>>
T &	register_data (const std::string &name)

Protected Member Functions inherited from BufferStore
virtual void	send_buffers_to (const torch::TensorOptions &options)
	Send all buffers to `options`.

template<typename T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
const T &	declare_buffer (const std::string &name, const T &rawval)
	Declare a buffer.

template<typename T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
const T &	declare_buffer (const std::string &name, const CrossRef< T > &crossref)
	Declare a buffer.

template<typename T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
const T &	declare_buffer (const std::string &name, const std::string &input_option_name)
	Declare a buffer.

Protected Member Functions inherited from ParameterStore
virtual void	send_parameters_to (const torch::TensorOptions &options)
	Send parameters to options.

template<typename T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
const T &	declare_parameter (const std::string &name, const T &rawval)
	Declare a parameter.

template<typename T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
const T &	declare_parameter (const std::string &name, const CrossRef< T > &crossref, bool allow_nonlinear)
	Declare a parameter.

template<typename T , typename = typename std::enable_if_t<std::is_base_of_v<TensorBase<T>, T>>>
const T &	declare_parameter (const std::string &name, const std::string &input_option_name, bool allow_nonlinear=false)
	Declare a parameter.

Protected Member Functions inherited from VariableStore
template<typename T , typename S >
const Variable< T > &	declare_input_variable (S &&name, TensorShapeRef list_shape={}, TensorShapeRef base_shape={})
	Declare an input variable.

template<typename T , typename S >
Variable< T > &	declare_output_variable (S &&name, TensorShapeRef list_shape={}, TensorShapeRef base_shape={})
	Declare an output variable.

const VariableBase *	clone_input_variable (const VariableBase &var, const VariableName &new_name={})
	Clone a variable and put it on the input axis.

VariableBase *	clone_output_variable (const VariableBase &var, const VariableName &new_name={})
	Clone a variable and put it on the output axis.

Constructor & Destructor Documentation

◆ NonlinearParameter()

template<typename T >

NonlinearParameter ( const OptionSet & options )

Member Function Documentation

◆ expected_options()

template<typename T >

OptionSet expected_options ( )

static

◆ param()

template<typename T >

const Variable< T > & param ( ) const

inline

Get the nonlinear parameter.

Member Data Documentation

◆ _p

template<typename T >

Variable<T>& _p

protected

The nonlinear parameter.

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ NonlinearParameter()

Member Function Documentation

◆ expected_options()

◆ param()

Member Data Documentation

◆ _p