Row and Column Index Sparsity Patterns

@(@\newcommand{\W}[1]{ \; #1 \; } \newcommand{\R}[1]{ {\rm #1} } \newcommand{\B}[1]{ {\bf #1} } \newcommand{\D}[2]{ \frac{\partial #1}{\partial #2} } \newcommand{\DD}[3]{ \frac{\partial^2 #1}{\partial #2 \partial #3} } \newcommand{\Dpow}[2]{ \frac{\partial^{#1}}{\partial {#2}^{#1}} } \newcommand{\dpow}[2]{ \frac{ {\rm d}^{#1}}{{\rm d}\, {#2}^{#1}} }@)@This is cppad-20221105 documentation. Here is a link to its current documentation . Row and Column Index Sparsity Patterns
Syntax

include

# include <cppad/utility/sparse_rc.hpp>

Constructor

sparse_rc<SizeVector>  empty

sparse_rc<SizeVector>  pattern(nr, nc, nnz)

sparse_rc<SizeVector>  pattern(other)

Assignment

pattern = other

pattern.swap(other)

Equality

equal = pattern == other

.

Setting

resize(nr, nc, nnz)

pattern.set(k, r, c)

pattern.push_back(r, c)

pattern.set_row_major()

pattern.set_col_major()

Scalars

pattern.nr()

pattern.nc()

pattern.nnz()

Vectors

const SizeVector& row( pattern.row() )

const SizeVector& col( pattern.col() )

const SizeVector& row_major( pattern.get_row_major() )

const SizeVector& col_major( pattern.get_col_major() )

row_major = pattern.row_major()

col_major = pattern.col_major()

Output

os << pattern

SizeVector
We use SizeVector to denote SimpleVector class with elements of type size_t. In addition, SimpleVector must support the swap operation between two of its vectors.

empty
This is an empty sparsity pattern. To be specific, the corresponding number of rows nr , number of columns nc , and number of possibly non-zero values nnz , are all zero.

pattern
This object is used to hold a sparsity pattern for a matrix. The sparsity pattern is const except during its constructor, resize, and set.

other

Assignment and Constructor
In the assignment and constructor, other has prototype



    const sparse_rc<SizeVector>&  other

After the assignment and constructor, pattern is an independent copy of other ; i.e. it has all the same values as other and changes to pattern do not affect other .

Move Semantics Assignment and Constructor
In the assignment and constructor, if other has prototype



    sparse_rc<SizeVector>&&  other

A move semantics version of the assignment or constructor is used; e.g., when other is a function return value.

swap
In the swap operation, other has prototype



    sparse_rc<SizeVector>&  other

After the swap operation other ( pattern ) is equivalent to pattern ( other ) before the operation.

Equality
In the equality operation, other has prototype



    const sparse_rc<SizeVector>&  other

The two sparsity patterns are equal if the following conditions hold:

The number of rows pattern.nr() and other.nr() are equal.
The number of columns pattern.nc() and other.nc() are equal.
The number of non-zero values pattern.nnz() and other.nnz() are equal.
The set of (row, column) pairs corresponding to pattern and other , are equal.

Determining equality requires sorting both patterns

nr
This argument has prototype



    size_t nr

It specifies the number of rows in the sparsity pattern. The function call nr() returns the value of nr .

nc
This argument has prototype



    size_t nc

It specifies the number of columns in the sparsity pattern. The function call nc() returns the value of nc .

nnz
This argument has prototype



    size_t nnz

It specifies the number of possibly non-zero index pairs in the sparsity pattern. The function call nnz() returns the value of nnz .

resize
The current sparsity pattern is lost and a new one is started with the specified parameters. The elements in the row and col vectors should be assigned using set.

set
This function sets the values



    row[k] = r

    col[k] = c

push_back
This function the value r to the back of row , the value c to the back of col , and increases nnz by one. This operation requires SizeVector to support the push_back operation (which is not part of the SimpleVector requirements).

k
This argument has type



    size_t k

and must be less than nnz .

r
This argument has type



    size_t r

It specifies the value assigned to row[k] and must be less than nr .

c
This argument has type



    size_t c

It specifies the value assigned to col[k] and must be less than nc .

row
This vector has size nnz and row[k] is the row index of the k-th possibly non-zero index pair in the sparsity pattern.

col
This vector has size nnz and col[k] is the column index of the k-th possibly non-zero index pair in the sparsity pattern.

row_major
This vector has prototype



    SizeVector row_major

and its size nnz . It sorts the sparsity pattern in row-major order. To be specific,



    col[ row_major[k] ] <= col[ row_major[k+1] ]

and if col[ row_major[k] ] == col[ row_major[k+1] ] ,



    row[ row_major[k] ] < row[ row_major[k+1] ]

This routine generates an assert if there are two entries with the same row and column values (if NDEBUG is not defined).

set_row_major
Store the current row major order in pattern . This can be used by the row_major function and the equality function to avoid re-sorting the pattern each time.

get_row_major
Retrieve the row major order stored in pattern by the previous set_row_major. If this order is no longer valid, the return value row_major has size zero.

col_major
This vector has prototype



    SizeVector col_major

and its size nnz . It sorts the sparsity pattern in column-major order. To be specific,



    row[ col_major[k] ] <= row[ col_major[k+1] ]

and if row[ col_major[k] ] == row[ col_major[k+1] ] ,



    col[ col_major[k] ] < col[ col_major[k+1] ]

This routine generates an assert if there are two entries with the same row and column values (if NDEBUG is not defined).

set_col_major
Store the current row major order in pattern . This can be used by the col_major function and the equality function to avoid re-sorting the pattern each time.

get_col_major
Retrieve the row major order stored in pattern by the previous set_col_major. If this order is no longer valid, the return value col_major has size zero.

Example
The file sparse_rc.cpp contains an example and test of this class.

os
If os is an std::ostream, the operation



    os << pattern

outputs pattern to the os stream. The output begins with a left brace { and ends with a right brace }. The output is in row major order and has one line for each row. The row index is output at the beginning of a line and the column indices follow.

Input File: include/cppad/utility/sparse_rc.hpp