Description

ChCSR3Matrix is a class that implements CSR3 sparse matrix format;.

Each of the 3 CSR arrays is stored contiguously in memory (as needed by Intel MKL Pardiso).

Building of the matrix is faster if the sparsity pattern of the matrix does not change (or change just a little). In order to let the matrix know that, set ChSparseMatrix::SetSparsityPatternLock(true). From now on, the position of the elements is kept in memory. Please mind that, when Reset() is called, only #values will be cleaned. Nothing will happen to other arrays. This means that if the sparsity pattern will change, many zeros will pollute your matrix. Do Prune() in this case.

Moreover, if the ChCSR3Matrix will be built from a ChSystemDescriptor, you can provide it to the matrix through #BindToChSystemDescriptor(). In the next call to Reset(), the ChCSR3Matrix will adapt itself to the sparsity pattern of ChSystemDescriptor. The sparsity pattern will be acquired from ChSystemDescriptor only once. To force the update call #ForceSparsityPatternUpdate()

Hints:

  • It's far better to overestimate the number of non-zero elements to avoid reallocations in memory.
  • It's preferrable to insert elements in the matrix in increasing column order (if row major) to minimize re-sorting of the elements.
  • It's better to use GetElement to read from matrix; Element() creates the space if the element does not exist.

#include <ChCSR3Matrix.h>

Inheritance diagram for chrono::ChCSR3Matrix:
Collaboration diagram for chrono::ChCSR3Matrix:

Public Member Functions

 ChCSR3Matrix (int nrows=1, int ncols=1, bool row_major_format_on=true, int nonzeros=1)
 
void SetElement (int row_sel, int col_sel, double insval, bool overwrite=true) override
 Put a new element in the matrix following CSR conventions.
 
double GetElement (int row_sel, int col_sel) const override
 
double & Element (int row_sel, int col_sel)
 
double & operator() (int row_sel, int col_sel)
 
double & operator() (int index)
 
void Reset (int nrows, int ncols, int nonzeros_hint=0) override
 The function assures that the matrix will have nrows rows and ncols columns. More...
 
bool Resize (int nrows, int ncols, int nonzeros_hint=0) override
 
int GetNNZ () const override
 Get the number of non-zero elements in this matrix.
 
int * GetCSR_LeadingIndexArray () const override
 Return the row index array in the CSR representation of this matrix if in row major format. More...
 
int * GetCSR_TrailingIndexArray () const override
 Return the column index array in the CSR representation of this matrix if in row major format. More...
 
double * GetCSR_ValueArray () const override
 Return the array of matrix values in the CSR representation of this matrix.
 
bool Compress () override
 Compress the internal arrays and purge all uninitialized elements.
 
void Trim ()
 Trims the internal arrays to have exactly the dimension needed, nothing more. More...
 
void Prune (double pruning_threshold=0)
 The same as Compress(), but also removes elements below pruning_threshold.
 
int GetTrailingIndexLength () const
 Get the length of the trailing-index array (e.g. column index if row major, row index if column major)
 
int GetTrailingIndexCapacity () const
 Get the capacity of the trailing-index array (e.g. column index if row major, row index if column major)
 
void SetMaxShifts (int max_shifts_new=std::numeric_limits< int >::max())
 Advanced use. More...
 
bool IsCompressed () const
 Check if the matrix is compressed i.e. the matrix elements are stored contiguously in the arrays.
 
bool IsRowMajor () const
 Check if the matrix is stored in row major format.
 
void LoadSparsityPattern (ChSparsityPatternLearner &sparsity_learner) override
 Acquire information about the sparsity pattern of the elements that will be put into this matrix. More...
 
int VerifyMatrix () const
 Verify if the matrix respects the CSR standard. More...
 
void ImportFromDatFile (std::string filepath="", bool row_major_format_on=true)
 
void ExportToDatFile (std::string filepath="", int precision=6) const
 
- Public Member Functions inherited from chrono::ChSparseMatrix
 ChSparseMatrix (int nrows=0, int ncols=0, int nnz=0)
 Construct a sparse matrix with 'nrows' and 'ncols' and with 'nnz' non-zero elements. More...
 
 ChSparseMatrix (const ChSparseMatrix &other)
 
int GetNumRows () const
 Get the number of rows of this matrix.
 
int GetNumColumns () const
 Get the number of columns of this matrix.
 
void SetType (SymmetryType type)
 Set the symmetry type for this sparse matrix (default: GENERAL). More...
 
SymmetryType GetType () const
 Return the symnmetery type of this matrix.
 
void SetSparsityPatternLock (bool val)
 Enable/disable a lock on the matrix sparsity pattern (default: false).
 
virtual void PasteMatrix (const ChMatrix<> &matra, int insrow, int inscol, bool overwrite=true, bool transp=false)
 Paste the specified matrix into this sparse matrix at (insrow,inscol).
 
virtual void PasteClippedMatrix (const ChMatrix<> &matra, int cliprow, int clipcol, int nrows, int ncolumns, int insrow, int inscol, bool overwrite=true)
 Paste a clipped portion of the specified matrix into this sparse matrix at (insrow,inscol).
 
virtual void PasteTranspMatrix (const ChMatrix<> &matra, int insrow, int inscol)
 
virtual void PasteSumMatrix (const ChMatrix<> &matra, int insrow, int inscol)
 
virtual void PasteSumTranspMatrix (const ChMatrix<> &matra, int insrow, int inscol)
 
virtual void PasteSumClippedMatrix (const ChMatrix<> &matra, int cliprow, int clipcol, int nrows, int ncolumns, int insrow, int inscol)
 

Protected Member Functions

void reset_arrays (int lead_dim, int trail_dim, int nonzeros)
 
void insert (int &trail_sel, const int &lead_sel)
 
void copy_and_distribute (const index_vector_t &trailIndex_src, const values_vector_t &values_src, const std::vector< bool > &initialized_element_src, index_vector_t &trailIndex_dest, values_vector_t &values_dest, std::vector< bool > &initialized_element_dest, int &trail_ins, int lead_ins, int storage_augm)
 

Static Protected Member Functions

static void distribute_integer_range_on_vector (index_vector_t &vector, int initial_number, int final_number)
 

Additional Inherited Members

- Public Types inherited from chrono::ChSparseMatrix
enum  SymmetryType { GENERAL, SYMMETRIC_POSDEF, SYMMETRIC_INDEF, STRUCTURAL_SYMMETRIC }
 
- Protected Attributes inherited from chrono::ChSparseMatrix
int m_num_rows
 number of rows
 
int m_num_cols
 number of columns
 
int m_nnz
 number of non-zero elements
 
SymmetryType m_type = GENERAL
 matrix type
 
bool m_lock = false
 indicate whether or not the matrix sparsity pattern should be locked
 
bool m_update_sparsity_pattern = false
 let the matrix acquire the sparsity pattern
 

Member Function Documentation

int * chrono::ChCSR3Matrix::GetCSR_LeadingIndexArray ( ) const
overridevirtual

Return the row index array in the CSR representation of this matrix if in row major format.

Return the column index array if in col major format.

Reimplemented from chrono::ChSparseMatrix.

int * chrono::ChCSR3Matrix::GetCSR_TrailingIndexArray ( ) const
overridevirtual

Return the column index array in the CSR representation of this matrix if in row major format.

Return the row index array if in col major format.

Reimplemented from chrono::ChSparseMatrix.

void chrono::ChCSR3Matrix::LoadSparsityPattern ( ChSparsityPatternLearner sparsity_learner)
overridevirtual

Acquire information about the sparsity pattern of the elements that will be put into this matrix.

The information is provided by #m_sysd.

Reimplemented from chrono::ChSparseMatrix.

void chrono::ChCSR3Matrix::Reset ( int  nrows,
int  ncols,
int  nonzeros_hint = 0 
)
overridevirtual

The function assures that the matrix will have nrows rows and ncols columns.

The nonzeros_hint value is just a hint! The matrix can be fully reset, or partially reset (i.e. mantaining the sparsity pattern). For partial reset the following must apply:

  • nrows and ncols must not differ from the current ones
  • nonzeros_hint must not be provided (or must equal 0)
  • m_lock must be set otherwise a full reset will occur.

Implements chrono::ChSparseMatrix.

void chrono::ChCSR3Matrix::SetMaxShifts ( int  max_shifts_new = std::numeric_limits<int>::max())

Advanced use.

While setting new elements in the matrix, SetMaxShifts() tells how far the internal algorithm should look for not-initialized elements.

void chrono::ChCSR3Matrix::Trim ( )

Trims the internal arrays to have exactly the dimension needed, nothing more.

The underlying vectors are not resized (see Trim() for this), nor moved.

int chrono::ChCSR3Matrix::VerifyMatrix ( ) const

Verify if the matrix respects the CSR standard.

3 - warning message: in the row there are no initialized elements 1 - warning message: the matrix is not compressed 0 - all good! -1 - error message: leadIndex is not strictly ascending -2 - error message: there's a row that has some an uninitialized element NOT at the end of its space in trailIndex -4 - error message: trailIndex has not ascending indexes within the rows