Swap orientation plane when the singularity at \( 2 \pi \) is met with the modified Rodrigues vector. More...

Detailed Description

Swap orientation plane when the singularity at \( 2 \pi \) is met with the modified Rodrigues vector.

See the following reference for details

‍Banks, Matthew Jarrett. "Switching Methods for Three-Dimensional Rotational Dynamics Using Modified Rodrigues Parameters." (2023).

#include <FixOrientation.h>

Inheritance diagram for FixOrientation:

[legend]

Public Member Functions
	FixOrientation (const OptionSet &options)

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

virtual std::vector< Diagnosis >	preflight () const
	Check for common problems.

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

virtual void	reinit (TorchShapeRef batch_shape, int deriv_order=0, const torch::Device &device=torch::kCPU, const torch::Dtype &dtype=NEML2_DTYPE)
	Allocate storage and setup views for all the variables of this model and recursively all of the sub-models.

virtual void	reinit (const BatchTensor &tensor, int deriv_order)
	Allocate storage and setup views for all the variables of this model and recursively all of the sub-models. See the other overload for detailed description.

bool	requires_grad () const
	Whether derivative has been requested for this model.

bool	requires_2nd_grad () const
	Whether 2nd derivative has been requested for this model.

TorchSize	batch_dim () const
	This model's batch dim.

TorchShapeRef	batch_sizes () const
	This model's batch shape.

const torch::TensorOptions &	options () const
	This model's tensor options.

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.

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

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

virtual void	check_AD_limitation () const

void	input_requires_grad_ (bool req=true)
	Set requires_grad for the input variables.

bool	using_AD_1st_derivative () const
	Whether this model is using AD to get 1st derivatives.

bool	using_AD_2nd_derivative () const
	Whether this model is using AD to get 2nd derivatives.

void	use_AD_derivatives (bool first=true, bool second=true)
	Tell this model to use AD to get derivatives.

virtual void	set_input (const LabeledVector &in)
	Set `in` to be the input of this model.

virtual LabeledVector	get_output ()

virtual LabeledMatrix	get_doutput_dinput ()

virtual LabeledTensor3D	get_d2output_dinput2 ()

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

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

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

virtual void	value ()

virtual void	value_and_dvalue ()

virtual void	value_and_dvalue_and_d2value ()

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 (const OptionSet &options)
	Construct a new NEML2Object object.

virtual	~NEML2Object ()=default

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 (const OptionSet &options, NEML2Object *object)

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

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

template<typename T , typename = typename std::enable_if_t<std::is_base_of_v<BatchTensorBase<T>, T>>>
T &	get_buffer (const std::string &name)
	}@

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

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

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

template<typename T , typename = typename std::enable_if_t<std::is_base_of_v<BatchTensorBase<T>, T>>>
T &	get_parameter (const std::string &name)
	}@

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

const std::map< std::string, const VariableBase * > &	nl_params () const
	Get all nonlinear parameters.

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

Public Member Functions inherited from VariableStore
	VariableStore (const OptionSet &options, NEML2Object *object)

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

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

VariableBase *	input_view (const VariableName &)
	Get the view of an input variable.

VariableBase *	output_view (const VariableName &)
	Get the view of an output variable.

template<typename T = BatchTensor>
Variable< T > &	get_input_variable (const VariableName &name)

template<typename T = BatchTensor>
const Variable< T > &	get_input_variable (const VariableName &name) const

template<typename T = BatchTensor>
const Variable< T > &	get_output_variable (const VariableName &name)

template<typename T = BatchTensor>
const Variable< T > &	get_output_variable (const VariableName &name) const

LabeledAxis &	input_axis ()

const LabeledAxis &	input_axis () const

LabeledAxis &	output_axis ()

const LabeledAxis &	output_axis () const

Storage< VariableName, VariableBase > &	input_views ()

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

Storage< VariableName, VariableBase > &	output_views ()

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

LabeledVector &	input_storage ()

const LabeledVector &	input_storage () const

LabeledVector &	output_storage ()

const LabeledVector &	output_storage () const

LabeledMatrix &	derivative_storage ()

const LabeledMatrix &	derivative_storage () const

LabeledTensor3D &	second_derivative_storage ()

const LabeledTensor3D &	second_derivative_storage () const

Public Member Functions inherited from NonlinearSystem
	NonlinearSystem (const OptionSet &options)

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

BatchTensor	scale_residual (const BatchTensor &r) const
	Apply scaling to the residual.

BatchTensor	scale_Jacobian (const BatchTensor &J) const
	Apply scaling to the Jacobian.

BatchTensor	scale_direction (const BatchTensor &p) const
	Remove scaling from the search direction, i.e. \( J^{-1} r \).

virtual BatchTensor	solution () const
	Get the solution vector.

BatchTensor	residual (const BatchTensor &x)
	Convenient shortcut to set the current solution, assemble and return the system residual.

void	residual ()
	Convenient shortcut to assemble and return the system residual.

BatchTensor	Jacobian (const BatchTensor &x)
	Convenient shortcut to set the current solution, assemble and return the system Jacobian.

void	Jacobian ()
	Convenient shortcut to assemble and return the system Jacobian.

std::tuple< BatchTensor, BatchTensor >	residual_and_Jacobian (const BatchTensor &x)
	Convenient shortcut to set the current solution, assemble and return the system residual and Jacobian.

void	residual_and_Jacobian ()
	Convenient shortcut to assemble and return the system residual and Jacobian.

const BatchTensor &	residual_view () const

const BatchTensor &	Jacobian_view () const

BatchTensor	residual_norm () const
	The residual norm.

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 Member Functions
void	set_value (bool out, bool dout_din, bool d2out_din2) override
	The map between input -> output, and optionally its derivatives.

Protected Member Functions inherited from Model
virtual void	setup () override
	Setup this model.

virtual void	allocate_variables (int deriv_order, bool options_changed)
	Call VariableStore::allocate_variables recursively on all submodels.

virtual void	setup_input_views () override
	Call VariableStore::setup_input_views recursively on all submodels.

virtual void	setup_submodel_input_views ()

virtual void	setup_output_views () override
	Call VariableStore::setup_output_views recursively on all submodels.

virtual void	setup_submodel_output_views ()

virtual void	reinit_input_views () override
	Call VariableStore::reinit_input_views recursively on all submodels.

virtual void	reinit_output_views (bool out, bool dout_din=true, bool d2out_din2=true) override
	Call VariableStore::reinit_output_views recursively on all submodels.

virtual void	detach_and_zero (bool out, bool dout_din=true, bool d2out_din2=true) override
	Call VariableStore::detach_and_zero recursively on all submodels.

virtual void	set_solution (const BatchTensor &x) override
	Set `x` as the current solution of the nonlinear system.

virtual void	cache (TorchShapeRef batch_shape) override
	Cache the variable's batch shape.

virtual void	cache (const torch::TensorOptions &options)
	Cache tensor options.

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

virtual void	assemble (bool residual, bool Jacobian) override
	Compute the residual and Jacobian.

virtual void	allocate_variables (TorchShapeRef batch_shape, const torch::TensorOptions &options, bool in, bool out, bool dout_din, bool d2out_din2)
	Allocate variable storages given the batch shape and tensor options.

virtual void	cache (TorchShapeRef batch_shape)
	Cache the variable's batch shape.

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<BatchTensorBase<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<BatchTensorBase<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<BatchTensorBase<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<BatchTensorBase<T>, T>>>
const T &	declare_parameter (const std::string &name, const std::string &input_option_name)
	Declare a parameter.

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

template<typename... S>
const Variable< BatchTensor > &	declare_input_variable (TorchSize sz, S &&... name)
	Declare an input variable (with unknown base shape at compile time)

template<typename T , typename... S>
const Variable< BatchTensor > &	declare_input_variable_list (TorchSize list_size, S &&... name)
	Declare an input variable that is a list of tensors of fixed size.

template<typename T , typename... S>
Variable< T > &	declare_output_variable (S &&... name)
	Declare an output variable.

template<typename... S>
Variable< BatchTensor > &	declare_output_variable (TorchSize sz, S &&... name)
	Declare an input variable (with unknown base shape at compile time)

template<typename T , typename... S>
Variable< BatchTensor > &	declare_output_variable_list (TorchSize list_size, S &&... name)
	Declare an output variable that is a list of tensors of fixed size.

template<typename T >
VariableName	declare_variable (LabeledAxis &axis, const VariableName &var) const
	Declare an item recursively on an axis.

VariableName	declare_variable (LabeledAxis &axis, const VariableName &var, TorchSize sz) const
	Declare an item (with known storage size) recursively on an axis.

VariableName	declare_subaxis (LabeledAxis &axis, const VariableName &subaxis) const
	Declare a subaxis recursively on an axis.

Protected Attributes
Variable< Rot > &	_output
	Corrected MRP representation.

const Variable< Rot > &	_input
	MRP representation of orientations.

Real	_threshold
	Threshold for making the swap.

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

bool	_AD_1st_deriv
	Whether to use AD to compute 1st derivatives.

bool	_AD_2nd_deriv
	Whether to use AD to compute 2nd derivatives.

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

Protected Attributes inherited from NonlinearSystem
TorchSize	_ndof
	Number of degrees of freedom.

BatchTensor	_solution
	View for the solution of this nonlinear system.

BatchTensor	_residual
	View for the residual of this nonlinear system.

BatchTensor	_Jacobian
	View for the Jacobian of this nonlinear system.

BatchTensor	_scaled_residual

BatchTensor	_scaled_Jacobian

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.

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

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

Additional Inherited Members
Public Types inherited from Model
enum	Stage { SOLVING , UPDATING }

Static Public Attributes inherited from Model
static enum neml2::Model::Stage	stage = UPDATING

Constructor & Destructor Documentation

◆ FixOrientation()

FixOrientation ( const OptionSet & options )

Member Function Documentation

◆ expected_options()

OptionSet expected_options ( )

static

◆ set_value()

void set_value	(	bool	out,
		bool	dout_din,
		bool	d2out_din2 )

overrideprotectedvirtual

The map between input -> output, and optionally its derivatives.

Implements Model.

Member Data Documentation

◆ _input

const Variable<Rot>& _input

protected

MRP representation of orientations.

◆ _output

Variable<Rot>& _output

protected

Corrected MRP representation.

◆ _threshold

Real _threshold

protected

Threshold for making the swap.

Detailed Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ FixOrientation()

Member Function Documentation

◆ expected_options()

◆ set_value()

Member Data Documentation

◆ _input

◆ _output

◆ _threshold