lines 9-323 of file: include/cppad/utility/sparse_rc.hpp

{xrst_begin sparse_rc}
{xrst_spell
   nnz
   nr
   ostream
   scalars
}
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 :ref:`SimpleVector-name` class
:ref:`with elements of type<SimpleVector@Elements of Specified 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

| |tab| *row* [ *k* ] = *r*
| |tab| *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.
{xrst_toc_hidden
   example/utility/sparse_rc.cpp
}
Example
*******
The file :ref:`sparse_rc.cpp-name`
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.

{xrst_end sparse_rc}