chrono::ChCSR3Matrix Class Reference

## 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())

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::max() )

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