\(\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}} }\)

sparse_rc

View page source

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:

1. The number of rows pattern . nr () and other . nr () are equal.

2. The number of columns pattern . nc () and other . nc () are equal.

3. The number of non-zero values pattern . nnz () and other . nnz () are equal.

4. 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.