Description

Base class for sparse direct linear solvers.

Sparse linear direct solvers. Cannot handle VI and complementarity problems, so it cannot be used with NSC formulations.

This base class manages the setup and solution of sparse linear systems in Chrono and defers to derived classes for performing the actual matrix factorization and then computing the solution vector. See ChSolverMkl (which implements Eigen's interface to the Intel MKL Pardiso solver) and ChSolverMumps (which interfaces to the MUMPS solver).

ChDirectSolverLS manages the detection and update of the matrix sparsity pattern, providing two main features:

sparsity pattern lock
sparsity pattern learning

The sparsity pattern lock skips sparsity identification or reserving memory for nonzeros on all but the first call to Setup. This feature is intended for problems where the system matrix sparsity pattern does not change significantly from call to call.
See LockSparsityPattern();

The sparsity pattern learning feature acquires the sparsity pattern in advance, in order to speed up matrix assembly. Enabled by default, the sparsity matrix learner identifies the exact matrix sparsity pattern (without actually setting any nonzeros).
See UseSparsityPatternLearner();

A further option allows the user to provide an estimate for the matrix sparsity (a value in [0,1], with 0 corresponding to a fully dense matrix). This value is used if the sparsity pattern learner is disabled if/when required to reserve space for matrix indices and nonzeros. See SetSparsityEstimate();

If appropriate and warranted by the problem setup, it is highly recommended to enable the sparsity pattern lock. This can significantly improve performance for more complex problems (larger size and/or problems which include constraints).

See ChSystemDescriptor for more information about the problem formulation and the data structures passed to the solver.

#include <ChDirectSolverLS.h>

Inheritance diagram for chrono::ChDirectSolverLS:

[legend]

Collaboration diagram for chrono::ChDirectSolverLS:

[legend]

Public Types
enum	MatrixSymmetryType { MatrixSymmetryType::GENERAL, MatrixSymmetryType::SYMMETRIC_POSDEF, MatrixSymmetryType::SYMMETRIC_INDEF, MatrixSymmetryType::STRUCTURAL_SYMMETRIC }

Public Types inherited from chrono::ChSolver
enum	Type { Type::PSOR, Type::PSSOR, Type::PJACOBI, Type::PMINRES, Type::BARZILAIBORWEIN, Type::APGD, Type::ADMM, Type::SPARSE_LU, Type::SPARSE_QR, Type::PARDISO_MKL, Type::MUMPS, Type::GMRES, Type::MINRES, Type::BICGSTAB, CUSTOM }
	Available types of solvers. More...

Public Member Functions
void	LockSparsityPattern (bool val)
	Enable/disable locking the sparsity pattern (default: false). More...

void	UseSparsityPatternLearner (bool val)
	Enable/disable use of the sparsity pattern learner (default: enabled). More...

void	ForceSparsityPatternUpdate ()
	Force a call to the sparsity pattern learner to update sparsity pattern on the underlying matrix. More...

void	SetSparsityEstimate (double sparsity)
	Set estimate for matrix sparsity, a value in [0,1], with 0 indicating a fully dense matrix (default: 0.9). More...

virtual void	SetMatrixSymmetryType (MatrixSymmetryType symmetry)
	Set the matrix symmetry type (default: GENERAL).

void	UsePermutationVector (bool val)
	Enable/disable use of permutation vector (default: false). More...

void	LeverageRhsSparsity (bool val)
	Enable/disable leveraging sparsity in right-hand side vector (default: false). More...

virtual void	EnableNullPivotDetection (bool val, double threshold=0)
	Enable detection of null pivots. More...

void	ResetTimers ()
	Reset timers for internal phases in Solve and Setup.

double	GetTimeSolve_Assembly () const
	Get cumulative time for assembly operations in Solve phase.

double	GetTimeSolve_SolverCall () const
	Get cumulative time for Pardiso calls in Solve phase.

double	GetTimeSetup_Assembly () const
	Get cumulative time for assembly operations in Setup phase.

double	GetTimeSetup_SolverCall () const
	Get cumulative time for Pardiso calls in Setup phase.

unsigned int	GetNumSetupCalls () const
	Return the number of calls to the solver's Setup function.

unsigned int	GetNumSolveCalls () const
	Return the number of calls to the solver's Setup function.

ChSparseMatrix &	GetMatrix ()
	Get a handle to the underlying matrix.

ChSparseMatrix &	A ()
	Get shortcut handle to underlying A matrix, for A*x=b.

ChVectorDynamic< double > &	x ()
	Get shortcut handle to underlying x solution vector, for A*x=b.

ChVectorDynamic< double > &	b ()
	Get shortcut handle to underlying b right hand-side known vector, for A*x=b.

virtual bool	Setup (ChSystemDescriptor &sysd) override
	Perform the solver setup operations. More...

virtual double	Solve (ChSystemDescriptor &sysd) override
	Solve linear system. More...

virtual bool	SetupCurrent ()
	Generic setup-solve without passing through the ChSystemDescriptor, in cases where a sparse matrix has been already assembled. More...

virtual double	SolveCurrent ()
	Generic setup-solve without passing through the ChSystemDescriptor, in cases where the a sparse matrix has been already assembled. More...

virtual void	ArchiveOut (ChArchiveOut &archive_out) override
	Method to allow serialization of transient data to archives.

virtual void	ArchiveIn (ChArchiveIn &archive_in) override
	Method to allow de serialization of transient data from archives.

Public Member Functions inherited from chrono::ChSolver
virtual Type	GetType () const
	Return type of the solver.

virtual ChIterativeSolver *	AsIterative ()
	Downcast to ChIterativeSolver.

void	SetVerbose (bool mv)
	Set verbose output from solver.

void	EnableWrite (bool val, const std::string &frame, const std::string &out_dir=".")
	Enable/disable debug output of matrix, RHS, and solution vector.

Protected Member Functions
virtual bool	IsIterative () const override
	Return true if iterative solver.

virtual bool	IsDirect () const override
	Return true if direct solver.

virtual ChDirectSolverLS *	AsDirect () override
	Downcast to ChDirectSolver.

virtual bool	FactorizeMatrix ()=0
	Factorize the current sparse matrix and return true if successful.

virtual bool	SolveSystem ()=0
	Solve the linear system using the current factorization and right-hand side vector. More...

virtual void	PrintErrorMessage ()=0
	Display an error message corresponding to the last failure. More...

virtual bool	SolveRequiresMatrix () const override
	Indicate whether or not the Solve() phase requires an up-to-date problem matrix. More...

Protected Attributes
ChSparseMatrix	m_mat
	problem matrix

int	m_dim
	problem size

MatrixSymmetryType	m_symmetry
	symmetry of problem matrix

double	m_sparsity
	user-supplied estimate of matrix sparsity

ChVectorDynamic< double >	m_rhs
	right-hand side vector

ChVectorDynamic< double >	m_sol
	solution vector

unsigned int	m_solve_call
	counter for calls to Solve

unsigned int	m_setup_call
	counter for calls to Setup

bool	m_lock
	is the matrix sparsity pattern locked?

bool	m_use_learner
	use the sparsity pattern learner?

bool	m_force_update
	force a call to the sparsity pattern learner?

bool	m_use_perm
	use of the permutation vector?

bool	m_use_rhs_sparsity
	leverage right-hand side sparsity?

bool	m_null_pivot_detection
	enable detection of zero pivots?

ChTimer	m_timer_setup_assembly
	timer for matrix assembly

ChTimer	m_timer_setup_solvercall
	timer for factorization

ChTimer	m_timer_solve_assembly
	timer for RHS assembly

ChTimer	m_timer_solve_solvercall
	timer for solution

Protected Attributes inherited from chrono::ChSolver
bool	verbose

bool	write_matrix

std::string	output_dir

std::string	frame_id

Member Enumeration Documentation

◆ MatrixSymmetryType

enum chrono::ChDirectSolverLS::MatrixSymmetryType

strong

Enumerator
GENERAL	unsymmetric matrix
SYMMETRIC_POSDEF	symmetric positive definite
SYMMETRIC_INDEF	symmetric indefinite
STRUCTURAL_SYMMETRIC	structurally symmetric

Member Function Documentation

◆ EnableNullPivotDetection()

virtual void chrono::ChDirectSolverLS::EnableNullPivotDetection	(	bool	val,
		double	threshold = `0`
	)

inlinevirtual

Enable detection of null pivots.

A concrete direct sparse solver may or may not support this feature.

Reimplemented in chrono::ChSolverMumps.

◆ ForceSparsityPatternUpdate()

void chrono::ChDirectSolverLS::ForceSparsityPatternUpdate ( )

inline

Force a call to the sparsity pattern learner to update sparsity pattern on the underlying matrix.

Such a call may be needed in a situation where the sparsity pattern is locked, but a change in the problem size or structure occurred. This function has no effect if the sparsity pattern learner is disabled.

◆ LeverageRhsSparsity()

void chrono::ChDirectSolverLS::LeverageRhsSparsity ( bool val )

inline

Enable/disable leveraging sparsity in right-hand side vector (default: false).

A concrete direct sparse solver may or may not support this feature.

◆ LockSparsityPattern()

void chrono::ChDirectSolverLS::LockSparsityPattern ( bool val )

inline

Enable/disable locking the sparsity pattern (default: false).

If enabled, the sparsity pattern of the problem matrix is assumed to be unchanged from call to call. Enable this option whenever possible to improve performance.

◆ PrintErrorMessage()

virtual void chrono::ChDirectSolverLS::PrintErrorMessage ( )

protectedpure virtual

Display an error message corresponding to the last failure.

This function is only called if Factorize or Solve returned false.

◆ SetSparsityEstimate()

void chrono::ChDirectSolverLS::SetSparsityEstimate ( double sparsity )

inline

Set estimate for matrix sparsity, a value in [0,1], with 0 indicating a fully dense matrix (default: 0.9).

Only used if the sparsity pattern learner is disabled.

◆ Setup()

bool chrono::ChDirectSolverLS::Setup ( ChSystemDescriptor & sysd )

overridevirtual

Perform the solver setup operations.

Here, sysd is the system description with constraints and variables. Returns true if successful and false otherwise.

Reimplemented from chrono::ChSolver.

◆ SetupCurrent()

bool chrono::ChDirectSolverLS::SetupCurrent ( )

virtual

Generic setup-solve without passing through the ChSystemDescriptor, in cases where a sparse matrix has been already assembled.

Performs the solver setup operations, assuming someone has already filled A() matrix before calling this.

◆ Solve()

double chrono::ChDirectSolverLS::Solve ( ChSystemDescriptor & sysd )

overridevirtual

Solve linear system.

Here, sysd is the system description with constraints and variables.

Implements chrono::ChSolver.

◆ SolveCurrent()

double chrono::ChDirectSolverLS::SolveCurrent ( )

virtual

Generic setup-solve without passing through the ChSystemDescriptor, in cases where the a sparse matrix has been already assembled.

Here, sysd is the system description with constraints and variables. Performs the solver setup operations, assuming someone has already filled the b() vector before calling this. Call x() afterward to get results.

◆ SolveRequiresMatrix()

virtual bool chrono::ChDirectSolverLS::SolveRequiresMatrix ( ) const

inlineoverrideprotectedvirtual

Indicate whether or not the Solve() phase requires an up-to-date problem matrix.

Typically, direct solvers only require the matrix for their Setup() phase.

Implements chrono::ChSolver.

◆ SolveSystem()

virtual bool chrono::ChDirectSolverLS::SolveSystem ( )

protectedpure virtual

Solve the linear system using the current factorization and right-hand side vector.

Load the solution vector (already of appropriate size) and return true if succesful.

◆ UsePermutationVector()

void chrono::ChDirectSolverLS::UsePermutationVector ( bool val )

inline

Enable/disable use of permutation vector (default: false).

A concrete direct sparse solver may or may not support this feature.

◆ UseSparsityPatternLearner()

void chrono::ChDirectSolverLS::UseSparsityPatternLearner ( bool val )

inline

Enable/disable use of the sparsity pattern learner (default: enabled).

Disable for smaller problems where the overhead may be too large.

The documentation for this class was generated from the following files:

/builds/uwsbel/chrono/src/chrono/solver/ChDirectSolverLS.h
/builds/uwsbel/chrono/src/chrono/solver/ChDirectSolverLS.cpp

Description

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Member Enumeration Documentation

◆ MatrixSymmetryType

Member Function Documentation

◆ EnableNullPivotDetection()

◆ ForceSparsityPatternUpdate()

◆ LeverageRhsSparsity()

◆ LockSparsityPattern()

◆ PrintErrorMessage()

◆ SetSparsityEstimate()

◆ Setup()

◆ SetupCurrent()

◆ Solve()

◆ SolveCurrent()

◆ SolveRequiresMatrix()

◆ SolveSystem()

◆ UsePermutationVector()

◆ UseSparsityPatternLearner()