SparseMatrix Class Reference

Interfaces matrix-vector operations tailored to general sparse matrices. More...

#include <Matrices.hpp>

Inheritance diagram for SparseMatrix:

List of all members.

Public Member Functions
	SparseMatrix ()
	SparseMatrix (int_t nr, int_t nc, sparse_int_t *r, sparse_int_t *c, real_t *v)
	SparseMatrix (int_t nr, int_t nc, int_t ld, const real_t *const v)
virtual	~SparseMatrix ()
virtual void	free ()
virtual Matrix *	duplicate () const
virtual void	setVal (const real_t *newVal)
virtual real_t	diag (int_t i) const
virtual BooleanType	isDiag () const
virtual real_t	getNorm (int_t type=2) const
virtual real_t	getRowNorm (int_t rNum, int_t type=2) const
virtual returnValue	getRowNorm (real_t *norm, int_t type=2) const
virtual returnValue	getRow (int_t rNum, const Indexlist *const icols, real_t alpha, real_t *row) const
virtual returnValue	getCol (int_t cNum, const Indexlist *const irows, real_t alpha, real_t *col) const
virtual returnValue	getSparseSubmatrix (int_t irowsLength, const int_t *const irowsNumber, int_t icolsLength, const int_t *const icolsNumber, int_t rowoffset, int_t coloffset, int_t &numNonzeros, int_t *irn, int_t *jcn, real_t *avals, BooleanType only_lower_triangular=BT_FALSE) const
virtual returnValue	times (int_t xN, real_t alpha, const real_t *x, int_t xLD, real_t beta, real_t *y, int_t yLD) const
virtual returnValue	transTimes (int_t xN, real_t alpha, const real_t *x, int_t xLD, real_t beta, real_t *y, int_t yLD) const
virtual returnValue	times (const Indexlist *const irows, const Indexlist *const icols, int_t xN, real_t alpha, const real_t *x, int_t xLD, real_t beta, real_t *y, int_t yLD, BooleanType yCompr=BT_TRUE) const
virtual returnValue	transTimes (const Indexlist *const irows, const Indexlist *const icols, int_t xN, real_t alpha, const real_t *x, int_t xLD, real_t beta, real_t *y, int_t yLD) const
virtual returnValue	addToDiag (real_t alpha)
sparse_int_t *	createDiagInfo ()
virtual real_t *	full () const
virtual returnValue	print (const char *name=0) const
virtual returnValue	writeToFile (FILE *output_file, const char *prefix) const
virtual returnValue	getSparseSubmatrix (const Indexlist *const irows, const Indexlist *const icols, int_t rowoffset, int_t coloffset, int_t &numNonzeros, int_t *irn, int_t *jcn, real_t *avals, BooleanType only_lower_triangular=BT_FALSE) const
virtual returnValue	getSparseSubmatrix (const Indexlist *const irows, int_t idx_icol, int_t rowoffset, int_t coloffset, int_t &numNonzeros, int_t *irn, int_t *jcn, real_t *avals, BooleanType only_lower_triangular=BT_FALSE) const
virtual returnValue	getSparseSubmatrix (int_t idx_row, const Indexlist *const icols, int_t rowoffset, int_t coloffset, int_t &numNonzeros, int_t *irn, int_t *jcn, real_t *avals, BooleanType only_lower_triangular=BT_FALSE) const
BooleanType	needToFreeMemory () const
void	doFreeMemory ()
void	doNotFreeMemory ()
Protected Attributes
int_t	nRows
int_t	nCols
sparse_int_t *	ir
sparse_int_t *	jc
sparse_int_t *	jd
real_t *	val
BooleanType	freeMemory

---

Detailed Description

Sparse matrix class (col compressed format).

Author:

Andreas Potschka, Christian Kirches, Hans Joachim Ferreau

Version:

3.2

Date:

2011-2017

---

Constructor & Destructor Documentation

SparseMatrix::SparseMatrix

(

)

Default constructor.

Referenced by duplicate().

SparseMatrix::SparseMatrix	(	int_t	nr,
		int_t	nc,
		sparse_int_t *	r,
		sparse_int_t *	c,
		real_t *	v
	)

Constructor with arguments.

Parameters:

nr	Number of rows.
nc	Number of columns.
r	Row indices (length).
c	Indices to first entry of columns (nCols+1).
v	Vector of entries (length).

References Matrix::doNotFreeMemory().

SparseMatrix::SparseMatrix	(	int_t	nr,
		int_t	nc,
		int_t	ld,
		const real_t *const	v
	)

Constructor from dense matrix.

Parameters:

nr	Number of rows.
nc	Number of columns.
ld	Leading dimension.
v	Row major stored matrix elements.

References BT_FALSE, Matrix::doFreeMemory(), ir, isZero(), jc, nCols, nRows, real_t, and val.

SparseMatrix::~SparseMatrix

(

)

[virtual]

Destructor.

References BT_TRUE, free(), jd, and Matrix::needToFreeMemory().

---

Member Function Documentation

returnValue SparseMatrix::addToDiag

(

real_t

alpha

)

[virtual]

Adds given offset to diagonal of matrix.

Returns:

SUCCESSFUL_RETURN
RET_NO_DIAGONAL_AVAILABLE

Parameters:

alpha

Diagonal offset.

Implements Matrix.

References BT_FALSE, ir, isZero(), jd, nCols, nRows, RET_DIAGONAL_NOT_INITIALISED, RET_NO_DIAGONAL_AVAILABLE, SUCCESSFUL_RETURN, THROWERROR, and val.

sparse_int_t * SparseMatrix::createDiagInfo

(

)

Create jd field from ir and jc.

Returns:

Pointer to jd.

References ir, jc, jd, and nCols.

Referenced by QProblemB::createDiagSparseMat(), and solveOqpBenchmark().

real_t SparseMatrix::diag

(

int_t

i

)

const [virtual]

Returns i-th diagonal entry.

Returns:

i-th diagonal entry (or INFTY if diagonal does not exist)

Parameters:

i

Index.

Implements Matrix.

References INFTY, ir, jc, jd, RET_DIAGONAL_NOT_INITIALISED, THROWERROR, and val.

void Matrix::doFreeMemory

(

)

[inline, inherited]

Enables de-allocation of internal memory.

References BT_TRUE, and Matrix::freeMemory.

Referenced by QProblemB::createDiagSparseMat(), DenseMatrix::duplicate(), duplicate(), SparseMatrixRow::duplicate(), SymDenseMat::duplicateSym(), SymSparseMat::duplicateSym(), QProblemB::setupQPdataFromFile(), QProblem::setupQPdataFromFile(), solveOqpBenchmark(), SparseMatrix(), and SparseMatrixRow::SparseMatrixRow().

void Matrix::doNotFreeMemory

(

)

[inline, inherited]

Disables de-allocation of internal memory.

Referenced by free(), SparseMatrixRow::free(), Matrix::Matrix(), SparseMatrix(), and SparseMatrixRow::SparseMatrixRow().

Matrix * SparseMatrix::duplicate

(

)

const [virtual]

Returns a deep-copy of the Matrix object.

Returns:

Deep-copy of Matrix object

Implements Matrix.

Reimplemented in SymSparseMat.

References Matrix::doFreeMemory(), ir, jc, jd, nCols, nRows, real_t, SparseMatrix(), and val.

void SparseMatrix::free

(

)

[virtual]

Frees all internal memory.

Implements Matrix.

References Matrix::doNotFreeMemory(), ir, jc, and val.

Referenced by ~SparseMatrix().

real_t * SparseMatrix::full

(

)

const [virtual]

Allocates and creates dense matrix array in row major format.

Note: Calling function has to free allocated memory!

Returns:

Pointer to matrix array.

Implements Matrix.

References ir, jc, nCols, nRows, real_t, and val.

Referenced by print().

returnValue SparseMatrix::getCol	(	int_t	cNum,
		const Indexlist *const	irows,
		real_t	alpha,
		real_t *	col
	)		const [virtual]

Retrieve indexed entries of matrix column multiplied by alpha.

Parameters:

cNum	Column number.
irows	Index list specifying rows.
alpha	Scalar factor.
col	Output column vector.

Implements Matrix.

References BT_TRUE, ir, isEqual(), Indexlist::iSort, jc, Indexlist::number, SUCCESSFUL_RETURN, and val.

real_t SparseMatrix::getNorm

(

int_t

type = 2

)

const [virtual]

Get the N-norm of the matrix

Returns:

N-norm of the matrix

Parameters:

type	Norm type, 1: one-norm, 2: Euclidean norm.

Implements Matrix.

References jc, nCols, REFER_NAMESPACE_QPOASES, and val.

returnValue SparseMatrix::getRow	(	int_t	rNum,
		const Indexlist *const	icols,
		real_t	alpha,
		real_t *	row
	)		const [virtual]

Retrieve indexed entries of matrix row multiplied by alpha.

Parameters:

rNum	Row number.
icols	Index list specifying columns.
alpha	Scalar factor.
row	Output row vector.

Implements Matrix.

References BT_TRUE, ir, isEqual(), Indexlist::iSort, jc, Indexlist::length, nCols, Indexlist::number, SUCCESSFUL_RETURN, and val.

real_t SparseMatrix::getRowNorm	(	int_t	rNum,
		int_t	type = 2
	)		const [virtual]

Get the N-norm of a row

Returns:

N-norm of row rNum

Parameters:

rNum	Row number.
type	Norm type, 1: one-norm, 2: Euclidean norm.

Implements Matrix.

References getAbs(), getSqrt(), INFTY, ir, jc, nCols, real_t, RET_INVALID_ARGUMENTS, THROWERROR, and val.

returnValue SparseMatrix::getRowNorm	(	real_t *	norm,
		int_t	type = 2
	)		const [virtual]

Get the N-norm of all rows

Returns:

SUCCESSFUL_RETURN

Parameters:

norm	Norm of each row.
type	Norm type, 1: one-norm, 2: Euclidean norm.

Implements Matrix.

References getAbs(), getSqrt(), ir, jc, nCols, nRows, RET_INVALID_ARGUMENTS, SUCCESSFUL_RETURN, and val.

BEGIN_NAMESPACE_QPOASES returnValue Matrix::getSparseSubmatrix	(	const Indexlist *const	irows,
		const Indexlist *const	icols,
		int_t	rowoffset,
		int_t	coloffset,
		int_t &	numNonzeros,
		int_t *	irn,
		int_t *	jcn,
		real_t *	avals,
		BooleanType	only_lower_triangular = BT_FALSE
	)		const [virtual, inherited]

Retrieve entries of submatrix in Harwell-Boeing sparse format. If irn, jcn, and avals are null, this only counts the number of nonzeros. Otherwise, numNonzeros containts the size of irn, jcn, and avals on entry, and the written number of entries on return.

Returns:

SUCCESSFUL_RETURN

Parameters:

irows	Index list specifying rows.
icols	Index list specifying columns.
rowoffset	Offset for row entries.
coloffset	Offset for row entries.
numNonzeros	Number of nonzeros in submatrix.
irn	Row position of entries (as position in irows) plus rowoffset.
jcn	Column position of entries (as position in irows) plus coloffset.
avals	Numerical values of the entries.
only_lower_triangular	if true, only the lower triangular portion is returned. This can only be true for symmetric matrices and if irows==jcols.

References Indexlist::getLength(), and Indexlist::getNumberArray().

Referenced by SQProblemSchur::addConstraint(), Matrix::getSparseSubmatrix(), SQProblemSchur::removeBound(), and SQProblemSchur::resetSchurComplement().

returnValue Matrix::getSparseSubmatrix	(	const Indexlist *const	irows,
		int_t	idx_icol,
		int_t	rowoffset,
		int_t	coloffset,
		int_t &	numNonzeros,
		int_t *	irn,
		int_t *	jcn,
		real_t *	avals,
		BooleanType	only_lower_triangular = BT_FALSE
	)		const [virtual, inherited]

Retrieve entries of submatrix in Harwell-Boeing sparse format. If irn, jcn, and avals are null, this only counts the number of nonzeros. Otherwise, numNonzeros containts the size of irn, jcn, and avals on entry, and the written number of entries on return. This version retrieves one column.

Returns:

SUCCESSFUL_RETURN

Parameters:

irows	Index list specifying rows.
idx_icol	Index list specifying columns.
rowoffset	Offset for row entries.
coloffset	Offset for row entries.
numNonzeros	Number of nonzeros in submatrix.
irn	Row position of entries (as position in irows) plus rowoffset.
jcn	Column position of entries (as position in irows) plus coloffset.
avals	Numerical values of the entries.
only_lower_triangular	if true, only the lower triangular portion is returned. This can only be true for symmetric matrices and if irows==jcols.

References Indexlist::getLength(), Indexlist::getNumberArray(), and Matrix::getSparseSubmatrix().

returnValue Matrix::getSparseSubmatrix	(	int_t	idx_row,
		const Indexlist *const	icols,
		int_t	rowoffset,
		int_t	coloffset,
		int_t &	numNonzeros,
		int_t *	irn,
		int_t *	jcn,
		real_t *	avals,
		BooleanType	only_lower_triangular = BT_FALSE
	)		const [virtual, inherited]

Retrieve entries of submatrix in Harwell-Boeing sparse format. If irn, jcn, and avals are null, this only counts the number of nonzeros. Otherwise, numNonzeros containts the size of irn, jcn, and avals on entry, and the written number of entries on return. This version retrieves one row.

Returns:

SUCCESSFUL_RETURN

Parameters:

idx_row	Row number.
icols	Index list specifying columns.
rowoffset	Offset for row entries.
coloffset	Offset for row entries.
numNonzeros	Number of nonzeros in submatrix.
irn	Row position of entries (as position in irows) plus rowoffset.
jcn	Column position of entries (as position in irows) plus coloffset.
avals	Numerical values of the entries.
only_lower_triangular	if true, only the lower triangular portion is returned. This can only be true for symmetric matrices and if irows==jcols.

References Indexlist::getLength(), Indexlist::getNumberArray(), and Matrix::getSparseSubmatrix().

returnValue SparseMatrix::getSparseSubmatrix	(	int_t	irowsLength,
		const int_t *const	irowsNumber,
		int_t	icolsLength,
		const int_t *const	icolsNumber,
		int_t	rowoffset,
		int_t	coloffset,
		int_t &	numNonzeros,
		int_t *	irn,
		int_t *	jcn,
		real_t *	avals,
		BooleanType	only_lower_triangular = BT_FALSE
	)		const [virtual]

Retrieve entries of submatrix in Harwell-Boeing sparse format. If irn, jcn, and avals are null, this only counts the number of nonzeros. Otherwise, numNonzeros containts the size of irn, jcn, and avals on entry, and the written number of entries on return.

Returns:

SUCCESSFUL_RETURN

Parameters:

irowsLength	Number of rows.
irowsNumber	Array with row numbers.
icolsLength	Number of columns.
icolsNumber	Array with column numbers.
rowoffset	Offset for row entries.
coloffset	Offset for row entries.
numNonzeros	Number of nonzeros in submatrix.
irn	Row position of entries (as position in irows) plus rowoffset.
jcn	Column position of entries (as position in irows) plus coloffset.
avals	Numerical values of the entries.
only_lower_triangular	if true, only the lower triangular portion is returned. This can only be true for symmetric matrices and if irows==jcols.

Implements Matrix.

References BT_FALSE, ir, jc, nRows, RET_INVALID_ARGUMENTS, SUCCESSFUL_RETURN, THROWERROR, and val.

BooleanType SparseMatrix::isDiag

(

)

const [virtual]

Checks whether matrix is square and diagonal.

Returns:

BT_TRUE iff matrix is square and diagonal;
BT_FALSE otherwise.

Implements Matrix.

References BT_FALSE, BT_TRUE, ir, jc, nCols, and nRows.

BooleanType Matrix::needToFreeMemory

(

)

const [inline, inherited]

Returns whether internal memory needs to be de-allocated.

Returns:

BT_TRUE iff internal memory needs to be de-allocated,
BT_FALSE otherwise

References Matrix::freeMemory.

Referenced by DenseMatrix::duplicate(), SymDenseMat::duplicateSym(), DenseMatrix::~DenseMatrix(), ~SparseMatrix(), and SparseMatrixRow::~SparseMatrixRow().

returnValue SparseMatrix::print

(

const char *

name = 0

)

const [virtual]

Prints matrix to screen.

Returns:

SUCCESSFUL_RETURN

Parameters:

name	Name of matrix.

Implements Matrix.

References full(), nCols, nRows, real_t, and REFER_NAMESPACE_QPOASES.

void SparseMatrix::setVal

(

const real_t *

newVal

)

[virtual]

Sets value array.

Thanks to Frank Chuang.

Parameters:

newVal

...

References jc, nCols, and val.

returnValue SparseMatrix::times	(	int_t	xN,
		real_t	alpha,
		const real_t *	x,
		int_t	xLD,
		real_t	beta,
		real_t *	y,
		int_t	yLD
	)		const [virtual]

Evaluate Y=alpha*A*X + beta*Y.

Parameters:

xN	Number of vectors to multiply.
alpha	Scalar factor for matrix vector product.
x	Input vector to be multiplied.
xLD	Leading dimension of input x.
beta	Scalar factor for y.
y	Output vector of results.
yLD	Leading dimension of output y.

Implements Matrix.

References BT_FALSE, BT_TRUE, ir, isEqual(), isZero(), jc, nCols, nRows, SUCCESSFUL_RETURN, and val.

returnValue SparseMatrix::times	(	const Indexlist *const	irows,
		const Indexlist *const	icols,
		int_t	xN,
		real_t	alpha,
		const real_t *	x,
		int_t	xLD,
		real_t	beta,
		real_t *	y,
		int_t	yLD,
		BooleanType	yCompr = BT_TRUE
	)		const [virtual]

Evaluate matrix vector product with submatrix given by Indexlist.

Parameters:

irows	Index list specifying rows.
icols	Index list specifying columns.
xN	Number of vectors to multiply.
alpha	Scalar factor for matrix vector product.
x	Input vector to be multiplied.
xLD	Leading dimension of input x.
beta	Scalar factor for y.
y	Output vector of results.
yLD	Leading dimension of output y.
yCompr	Compressed storage for y.

Implements Matrix.

References BT_FALSE, BT_TRUE, getAbs(), getMax(), ir, isEqual(), Indexlist::iSort, isZero(), jc, Indexlist::length, nCols, nRows, Indexlist::number, real_t, SUCCESSFUL_RETURN, and val.

returnValue SparseMatrix::transTimes	(	int_t	xN,
		real_t	alpha,
		const real_t *	x,
		int_t	xLD,
		real_t	beta,
		real_t *	y,
		int_t	yLD
	)		const [virtual]

Evaluate Y=alpha*A'*X + beta*Y.

Parameters:

xN	Number of vectors to multiply.
alpha	Scalar factor for matrix vector product.
x	Input vector to be multiplied.
xLD	Leading dimension of input x.
beta	Scalar factor for y.
y	Output vector of results.
yLD	Leading dimension of output y.

Implements Matrix.

References BT_FALSE, BT_TRUE, ir, isEqual(), isZero(), jc, nCols, SUCCESSFUL_RETURN, and val.

returnValue SparseMatrix::transTimes	(	const Indexlist *const	irows,
		const Indexlist *const	icols,
		int_t	xN,
		real_t	alpha,
		const real_t *	x,
		int_t	xLD,
		real_t	beta,
		real_t *	y,
		int_t	yLD
	)		const [virtual]

Evaluate matrix transpose vector product.

Parameters:

irows	Index list specifying rows.
icols	Index list specifying columns.
xN	Number of vectors to multiply.
alpha	Scalar factor for matrix vector product.
x	Input vector to be multiplied.
xLD	Leading dimension of input x.
beta	Scalar factor for y.
y	Output vector of results.
yLD	Leading dimension of output y.

Implements Matrix.

References BT_FALSE, BT_TRUE, ir, isEqual(), Indexlist::iSort, isZero(), jc, Indexlist::length, nRows, Indexlist::number, real_t, SUCCESSFUL_RETURN, and val.

returnValue SparseMatrix::writeToFile	(	FILE *	output_file,
		const char *	prefix
	)		const [virtual]

Write matrix to file.

Returns:

SUCCESSFUL_RETURN

Implements Matrix.

References ir, jc, nCols, SUCCESSFUL_RETURN, and val.

---

Member Data Documentation

BooleanType Matrix::freeMemory [protected, inherited]

Indicating whether internal memory needs to be de-allocated.

Referenced by Matrix::doFreeMemory(), and Matrix::needToFreeMemory().

sparse_int_t* SparseMatrix::ir [protected]

Row indices (length).

Referenced by addToDiag(), SymSparseMat::bilinear(), createDiagInfo(), diag(), duplicate(), SymSparseMat::duplicateSym(), free(), full(), getCol(), getRow(), getRowNorm(), getSparseSubmatrix(), isDiag(), SparseMatrix(), times(), transTimes(), and writeToFile().

sparse_int_t* SparseMatrix::jc [protected]

Indices to first entry of columns (nCols+1).

Referenced by SymSparseMat::bilinear(), createDiagInfo(), diag(), duplicate(), SymSparseMat::duplicateSym(), free(), full(), getCol(), getNorm(), getRow(), getRowNorm(), getSparseSubmatrix(), isDiag(), setVal(), SparseMatrix(), times(), transTimes(), and writeToFile().

sparse_int_t* SparseMatrix::jd [protected]

Indices to first entry of lower triangle (including diagonal) (nCols).

Referenced by addToDiag(), SymSparseMat::bilinear(), createDiagInfo(), diag(), duplicate(), SymSparseMat::duplicateSym(), and ~SparseMatrix().

int_t SparseMatrix::nCols [protected]

Number of columns.

Referenced by addToDiag(), createDiagInfo(), duplicate(), SymSparseMat::duplicateSym(), full(), getNorm(), getRow(), getRowNorm(), isDiag(), print(), setVal(), SparseMatrix(), times(), transTimes(), and writeToFile().

int_t SparseMatrix::nRows [protected]

Number of rows.

Referenced by addToDiag(), duplicate(), SymSparseMat::duplicateSym(), full(), getRowNorm(), getSparseSubmatrix(), isDiag(), print(), SparseMatrix(), times(), and transTimes().

real_t* SparseMatrix::val [protected]

Vector of entries (length).

Referenced by addToDiag(), SymSparseMat::bilinear(), diag(), duplicate(), SymSparseMat::duplicateSym(), free(), full(), getCol(), getNorm(), getRow(), getRowNorm(), getSparseSubmatrix(), setVal(), SparseMatrix(), times(), transTimes(), and writeToFile().

---

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

• include/qpOASES/Matrices.hpp
• src/Matrices.cpp