2
0
mirror of https://github.com/boostorg/ublas.git synced 2026-02-14 13:12:14 +00:00
Files
ublas/doc/matrix_sparse.htm
Jörg Walter 058e8a8820 Merge.
svn path=/trunk/boost/libs/numeric/ublas/; revision=15321
2002-09-14 09:48:41 +00:00

623 lines
23 KiB
HTML
Raw Blame History

<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
<title>Sparse Matrix</title>
</head>
<body bgcolor="#FFFFFF">
<h1><img src="c++boost.gif" alt="c++boost.gif" align="center"
width="277" height="86">Sparse Matrix</h1>
<h2><a name="sparse_matrix"></a>Sparse Matrix</h2>
<h4>Description</h4>
<p>The templated class <code>sparse_matrix&lt;T, F, A&gt; </code>is
the base container adaptor for sparse matrices. For a <em>(m x n</em>)-dimensional
sparse matrix and <em>0 &lt;= i &lt; m</em>,<em> 0 &lt;= j &lt; n</em>
every non-zero element <em>m</em><sub><em>i, j</em></sub> is
mapped to the <em>(i x n + j)-</em>th element of the container
for row major orientation or the <em>(i + j x m)-</em>th element
of the container for column major orientation.</p>
<h4>Example</h4>
<pre>int main () {
using namespace boost::numeric::ublas;
sparse_matrix&lt;double&gt; m (3, 3, 3 * 3);
for (int i = 0; i &lt; m.size1 (); ++ i)
for (int j = 0; j &lt; m.size2 (); ++ j)
m (i, j) = 3 * i + j;
std::cout &lt;&lt; m &lt;&lt; std::endl;
}</pre>
<h4>Definition</h4>
<p>Defined in the header matrix_sparse.hpp.</p>
<h4>Template parameters</h4>
<table border="1">
<tr>
<th>Parameter </th>
<th>Description </th>
<th>Default </th>
</tr>
<tr>
<td><code>T</code> </td>
<td>The type of object stored in the sparse matrix. </td>
<td>&nbsp;</td>
</tr>
<tr>
<td><code>F</code></td>
<td>Functor describing the storage organization. <a href="#sparse_matrix_1">[1]</a></td>
<td><code>row_major</code></td>
</tr>
<tr>
<td><code>A</code></td>
<td>The type of the adapted array. <a href="#sparse_matrix_2">[2]</a></td>
<td><code>map_array&lt;std::size_t, T&gt;</code></td>
</tr>
</table>
<h4>Model of</h4>
<p><a href="container.htm#matrix">Matrix</a>. </p>
<h4>Type requirements</h4>
<p>None, except for those imposed by the requirements of <a
href="container.htm#matrix">Matrix</a>.</p>
<h4>Public base classes</h4>
<p><code>matrix_expression&lt;sparse_matrix&lt;T, F, A&gt; &gt;</code>
</p>
<h4>Members</h4>
<table border="1">
<tr>
<th>Member </th>
<th>Description </th>
</tr>
<tr>
<td><code>sparse_matrix ()</code> </td>
<td>Allocates a <code>sparse_matrix </code>that holds at
most zero rows of zero elements.</td>
</tr>
<tr>
<td><code>sparse_matrix (size_type size1, size_type2,
size_type non_zeros)</code></td>
<td>Allocates a <code>sparse_matrix </code>that holds at
most <code>size1 </code>rows of <code>size2 </code>elements.</td>
</tr>
<tr>
<td><code>sparse_matrix (const sparse_matrix &amp;m)</code></td>
<td>The copy constructor.</td>
</tr>
<tr>
<td><code>template&lt;class AE&gt;<br>
sparse_matrix (size_type non_zeros, const
matrix_expression&lt;AE&gt; &amp;ae)</code></td>
<td>The extended copy constructor.</td>
</tr>
<tr>
<td><code>void resize (size_type size1, size_type size2,
size_type non_zeros)</code></td>
<td>Reallocates a <code>sparse_matrix </code>to hold at
most <code>size1 </code>rows of <code>size2 </code>elements.
The content of the <code>sparse_matrix </code>is
preserved.</td>
</tr>
<tr>
<td><code>size_type size1 () const</code></td>
<td>Returns the number of rows. </td>
</tr>
<tr>
<td><code>size_type size2 () const</code></td>
<td>Returns the number of columns. </td>
</tr>
<tr>
<td><code>const_reference operator () (size_type i,
size_type j) const</code></td>
<td>Returns the value of the <code>j</code>-th element in
the<code> i</code>-th row. </td>
</tr>
<tr>
<td><code>reference operator () (size_type i, size_type
j)</code></td>
<td>Returns a reference of the <code>j</code>-th element
in the<code> i</code>-th row. </td>
</tr>
<tr>
<td><code>sparse_matrix &amp;operator = (const
sparse_matrix &amp;m)</code></td>
<td>The assignment operator.</td>
</tr>
<tr>
<td><code>sparse_matrix &amp;assign_temporary
(sparse_matrix &amp;m)</code></td>
<td>Assigns a temporary. May change the sparse matrix <code>m</code>.</td>
</tr>
<tr>
<td><code>template&lt;class AE&gt;<br>
sparse_matrix &amp;operator = (const
matrix_expression&lt;AE&gt; &amp;ae)</code></td>
<td>The extended assignment operator.</td>
</tr>
<tr>
<td><code>template&lt;class AE&gt;<br>
sparse_matrix &amp;assign (const
matrix_expression&lt;AE&gt; &amp;ae)</code></td>
<td>Assigns a matrix expression to the sparse matrix.
Left and right hand side of the assignment should be
independent.</td>
</tr>
<tr>
<td><code>template&lt;class AE&gt;<br>
sparse_matrix &amp;operator += (const
matrix_expression&lt;AE&gt; &amp;ae)</code></td>
<td>A computed assignment operator. Adds the matrix
expression to the sparse matrix.</td>
</tr>
<tr>
<td><code>template&lt;class AE&gt;<br>
sparse_matrix &amp;plus_assign (const
matrix_expression&lt;AE&gt; &amp;ae)</code></td>
<td>Adds a matrix expression to the sparse matrix. Left
and right hand side of the assignment should be
independent.</td>
</tr>
<tr>
<td><code>template&lt;class AE&gt;<br>
sparse_matrix &amp;operator -= (const
matrix_expression&lt;AE&gt; &amp;ae)</code></td>
<td>A computed assignment operator. Subtracts the matrix
expression from the sparse matrix.</td>
</tr>
<tr>
<td><code>template&lt;class AE&gt;<br>
sparse_matrix &amp;minus_assign (const
matrix_expression&lt;AE&gt; &amp;ae)</code></td>
<td>Subtracts a matrix expression from the sparse matrix.
Left and right hand side of the assignment should be
independent.</td>
</tr>
<tr>
<td><code>template&lt;class AT&gt;<br>
sparse_matrix &amp;operator *= (const AT &amp;at)</code></td>
<td>A computed assignment operator. Multiplies the sparse
matrix with a scalar.</td>
</tr>
<tr>
<td><code>template&lt;class AT&gt;<br>
sparse_matrix &amp;operator /= (const AT &amp;at)</code></td>
<td>A computed assignment operator. Divides the sparse
matrix through a scalar.</td>
</tr>
<tr>
<td><code>void swap (sparse_matrix &amp;m)</code></td>
<td>Swaps the contents of the sparse matrices. </td>
</tr>
<tr>
<td><code>void insert (size_type i, size_type j,
const_reference t)</code></td>
<td>Inserts the value <code>t</code> at the <code>j</code>-th
element of the <code>i</code>-th row.</td>
</tr>
<tr>
<td><code>void erase (size_type i, size_type j)</code></td>
<td>Erases the value at the <code>j</code>-th element of
the <code>i</code>-th row.</td>
</tr>
<tr>
<td><code>void clear ()</code></td>
<td>Clears the sparse matrix.</td>
</tr>
<tr>
<td><code>const_iterator1 begin1 () const</code></td>
<td>Returns a <code>const_iterator1</code> pointing to
the beginning of the <code>sparse_matrix</code>. </td>
</tr>
<tr>
<td><code>const_iterator1 end1 () const</code></td>
<td>Returns a <code>const_iterator1</code> pointing to
the end of the <code>sparse_matrix</code>. </td>
</tr>
<tr>
<td><code>iterator1 begin1 () </code></td>
<td>Returns a <code>iterator1</code> pointing to the
beginning of the <code>sparse_matrix</code>. </td>
</tr>
<tr>
<td><code>iterator1 end1 () </code></td>
<td>Returns a <code>iterator1</code> pointing to the end
of the <code>sparse_matrix</code>. </td>
</tr>
<tr>
<td><code>const_iterator2 begin2 () const</code></td>
<td>Returns a <code>const_iterator2</code> pointing to
the beginning of the <code>sparse_matrix</code>. </td>
</tr>
<tr>
<td><code>const_iterator2 end2 () const</code></td>
<td>Returns a <code>const_iterator2</code> pointing to
the end of the <code>sparse_matrix</code>. </td>
</tr>
<tr>
<td><code>iterator2 begin2 () </code></td>
<td>Returns a <code>iterator2</code> pointing to the
beginning of the <code>sparse_matrix</code>. </td>
</tr>
<tr>
<td><code>iterator2 end2 () </code></td>
<td>Returns a <code>iterator2</code> pointing to the end
of the <code>sparse_matrix</code>. </td>
</tr>
<tr>
<td><code>const_reverse_iterator1 rbegin1 () const</code></td>
<td>Returns a <code>const_reverse_iterator1</code>
pointing to the beginning of the reversed <code>sparse_matrix</code>.
</td>
</tr>
<tr>
<td><code>const_reverse_iterator1 rend1 () const</code></td>
<td>Returns a <code>const_reverse_iterator1</code>
pointing to the end of the reversed <code>sparse_matrix</code>.
</td>
</tr>
<tr>
<td><code>reverse_iterator1 rbegin1 () </code></td>
<td>Returns a <code>reverse_iterator1</code> pointing to
the beginning of the reversed <code>sparse_matrix</code>.
</td>
</tr>
<tr>
<td><code>reverse_iterator1 rend1 () </code></td>
<td>Returns a <code>reverse_iterator1</code> pointing to
the end of the reversed <code>sparse_matrix</code>. </td>
</tr>
<tr>
<td><code>const_reverse_iterator2 rbegin2 () const</code></td>
<td>Returns a <code>const_reverse_iterator2</code>
pointing to the beginning of the reversed <code>sparse_matrix</code>.
</td>
</tr>
<tr>
<td><code>const_reverse_iterator2 rend2 () const</code></td>
<td>Returns a <code>const_reverse_iterator2</code>
pointing to the end of the reversed <code>sparse_matrix</code>.
</td>
</tr>
<tr>
<td><code>reverse_iterator2 rbegin2 () </code></td>
<td>Returns a <code>reverse_iterator2</code> pointing to
the beginning of the reversed <code>sparse_matrix</code>.
</td>
</tr>
<tr>
<td><code>reverse_iterator2 rend2 () </code></td>
<td>Returns a <code>reverse_iterator2</code> pointing to
the end of the reversed <code>sparse_matrix</code>. </td>
</tr>
</table>
<h4>Notes</h4>
<p><a name="#sparse_matrix_1">[1]</a> Supported parameters for the storage organization are
<code>row_major</code> and <code>column_major</code>.</p>
<p><a name="#sparse_matrix_2">[2]</a> Supported parameters for the adapted array are
<code>map_array&lt;std::size_t, T&gt</code> and <code>std::map&lt;std::size_t, T&gt</code>.
</p>
<h4>Interface</h4>
<pre><code> // Array based sparse matrix class
template&lt;class T, class F, class A&gt;
class sparse_matrix:
public matrix_expression&lt;sparse_matrix&lt;T, F, A&gt; &gt; {
public:
typedef std::size_t size_type;
typedef std::ptrdiff_t difference_type;
typedef T value_type;
typedef const T &amp;const_reference;
typedef T &amp;reference;
typedef const T *const_pointer;
typedef T *pointer;
typedef F functor_type;
typedef A array_type;
typedef const A const_array_type;
typedef const sparse_matrix&lt;T, F, A&gt; const_self_type;
typedef sparse_matrix&lt;T, F, A&gt; self_type;
typedef const matrix_const_reference&lt;const_self_type&gt; const_closure_type;
typedef matrix_reference&lt;self_type&gt; closure_type;
typedef typename A::const_iterator const_iterator_type;
typedef typename A::iterator iterator_type;
typedef sparse_tag storage_category;
typedef typename F::orientation_category orientation_category;
// Construction and destruction
sparse_matrix ();
sparse_matrix (size_type size1, size_type size2, size_type non_zeros = 0);
sparse_matrix (const sparse_matrix &amp;m);
template&lt;class AE&gt;
sparse_matrix (const matrix_expression&lt;AE&gt; &amp;ae, size_type non_zeros = 0);
// Accessors
size_type size1 () const;
size_type size2 () const;
size_type non_zeros () const;
const_array_type &amp;data () const;
array_type &amp;data ();
// Resizing
void resize (size_type size1, size_type size2, size_type non_zeros = 0);
// Element access
const_reference operator () (size_type i, size_type j) const;
reference operator () (size_type i, size_type j);
// Assignment
sparse_matrix &amp;operator = (const sparse_matrix &amp;m);
sparse_matrix &amp;assign_temporary (sparse_matrix &amp;m);
template&lt;class AE&gt;
sparse_matrix &amp;operator = (const matrix_expression&lt;AE&gt; &amp;ae);
template&lt;class AE&gt;
sparse_matrix &amp;reset (const matrix_expression&lt;AE&gt; &amp;ae);
template&lt;class AE&gt;
sparse_matrix &amp;assign (const matrix_expression&lt;AE&gt; &amp;ae);
template&lt;class AE&gt;
sparse_matrix&amp; operator += (const matrix_expression&lt;AE&gt; &amp;ae);
template&lt;class AE&gt;
sparse_matrix &amp;plus_assign (const matrix_expression&lt;AE&gt; &amp;ae);
template&lt;class AE&gt;
sparse_matrix&amp; operator -= (const matrix_expression&lt;AE&gt; &amp;ae);
template&lt;class AE&gt;
sparse_matrix &amp;minus_assign (const matrix_expression&lt;AE&gt; &amp;ae);
template&lt;class AT&gt;
sparse_matrix&amp; operator *= (const AT &amp;at);
template&lt;class AT&gt;
sparse_matrix&amp; operator /= (const AT &amp;at);
// Swapping
void swap (sparse_matrix &amp;m);
friend void swap (sparse_matrix &amp;m1, sparse_matrix &amp;m2);
// Element insertion and erasure
void insert (size_type i, size_type j, const_reference t);
void erase (size_type i, size_type j);
void clear ();
class const_iterator1;
class iterator1;
class const_iterator2;
class iterator2;
typedef reverse_iterator_base1&lt;const_iterator1&gt; const_reverse_iterator1;
typedef reverse_iterator_base1&lt;iterator1&gt; reverse_iterator1;
typedef reverse_iterator_base2&lt;const_iterator2&gt; const_reverse_iterator2;
typedef reverse_iterator_base2&lt;iterator2&gt; reverse_iterator2;
// Element lookup
const_iterator1 find1 (int rank, size_type i, size_type j) const;
iterator1 find1 (int rank, size_type i, size_type j);
const_iterator2 find2 (int rank, size_type i, size_type j) const;
iterator2 find2 (int rank, size_type i, size_type j);
const_iterator1 find_first1 (int rank, size_type i, size_type j) const;
iterator1 find_first1 (int rank, size_type i, size_type j);
const_iterator1 find_last1 (int rank, size_type i, size_type j) const;
iterator1 find_last1 (int rank, size_type i, size_type j);
const_iterator2 find_first2 (int rank, size_type i, size_type j) const;
iterator2 find_first2 (int rank, size_type i, size_type j);
const_iterator2 find_last2 (int rank, size_type i, size_type j) const;
iterator2 find_last2 (int rank, size_type i, size_type j);
// Iterators simply are pointers.
class const_iterator1:
public container_const_reference&lt;sparse_matrix&gt;,
public bidirectional_iterator_base&lt;const_iterator1, value_type&gt; {
public:
typedef sparse_bidirectional_iterator_tag iterator_category;
typedef typename sparse_matrix::difference_type difference_type;
typedef typename sparse_matrix::value_type value_type;
typedef typename sparse_matrix::const_reference reference;
typedef typename sparse_matrix::const_pointer pointer;
typedef const_iterator2 dual_iterator_type;
typedef const_reverse_iterator2 dual_reverse_iterator_type;
typedef typename functor_type::functor1_type functor1_type;
// Construction and destruction
const_iterator1 ();
const_iterator1 (const sparse_matrix &amp;m, int rank, size_type i, size_type j, const const_iterator_type &amp;it);
const_iterator1 (const iterator1 &amp;it);
// Arithmetic
const_iterator1 &amp;operator ++ ();
const_iterator1 &amp;operator -- ();
// Dereference
reference operator * () const;
const_iterator2 begin () const;
const_iterator2 end () const;
const_reverse_iterator2 rbegin () const;
const_reverse_iterator2 rend () const;
// Indices
size_type index1 () const;
size_type index2 () const;
// Assignment
const_iterator1 &amp;operator = (const const_iterator1 &amp;it);
// Comparison
bool operator == (const const_iterator1 &amp;it) const;
};
const_iterator1 begin1 () const;
const_iterator1 end1 () const;
class iterator1:
public container_reference&lt;sparse_matrix&gt;,
public bidirectional_iterator_base&lt;iterator1, value_type&gt; {
public:
typedef sparse_bidirectional_iterator_tag iterator_category;
typedef typename sparse_matrix::difference_type difference_type;
typedef typename sparse_matrix::value_type value_type;
typedef typename sparse_matrix::reference reference;
typedef typename sparse_matrix::pointer pointer;
typedef iterator2 dual_iterator_type;
typedef reverse_iterator2 dual_reverse_iterator_type;
typedef typename functor_type::functor1_type functor1_type;
// Construction and destruction
iterator1 ();
iterator1 (sparse_matrix &amp;m, int rank, size_type i, size_type j, const iterator_type &amp;it);
// Arithmetic
iterator1 &amp;operator ++ ();
iterator1 &amp;operator -- ();
// Dereference
reference operator * () const;
iterator2 begin () const;
iterator2 end () const;
reverse_iterator2 rbegin () const;
reverse_iterator2 rend () const;
// Indices
size_type index1 () const;
size_type index2 () const;
// Assignment
iterator1 &amp;operator = (const iterator1 &amp;it);
// Comparison
bool operator == (const iterator1 &amp;it) const;
};
iterator1 begin1 ();
iterator1 end1 ();
class const_iterator2:
public container_const_reference&lt;sparse_matrix&gt;,
public bidirectional_iterator_base&lt;const_iterator2, value_type&gt; {
public:
typedef sparse_bidirectional_iterator_tag iterator_category;
typedef typename sparse_matrix::difference_type difference_type;
typedef typename sparse_matrix::value_type value_type;
typedef typename sparse_matrix::const_reference reference;
typedef typename sparse_matrix::const_pointer pointer;
typedef const_iterator1 dual_iterator_type;
typedef const_reverse_iterator1 dual_reverse_iterator_type;
typedef typename functor_type::functor2_type functor2_type;
// Construction and destruction
const_iterator2 ();
const_iterator2 (const sparse_matrix &amp;m, int rank, size_type i, size_type j, const const_iterator_type &amp;it);
const_iterator2 (const iterator2 &amp;it);
// Arithmetic
const_iterator2 &amp;operator ++ ();
const_iterator2 &amp;operator -- ();
// Dereference
reference operator * () const;
const_iterator1 begin () const;
const_iterator1 end () const;
const_reverse_iterator1 rbegin () const;
const_reverse_iterator1 rend () const;
// Indices
size_type index1 () const;
size_type index2 () const;
// Assignment
const_iterator2 &amp;operator = (const const_iterator2 &amp;it);
// Comparison
bool operator == (const const_iterator2 &amp;it) const;
};
const_iterator2 begin2 () const;
const_iterator2 end2 () const;
class iterator2:
public container_reference&lt;sparse_matrix&gt;,
public bidirectional_iterator_base&lt;iterator2, value_type&gt; {
public:
typedef sparse_bidirectional_iterator_tag iterator_category;
typedef typename sparse_matrix::difference_type difference_type;
typedef typename sparse_matrix::value_type value_type;
typedef typename sparse_matrix::reference reference;
typedef typename sparse_matrix::pointer pointer;
typedef iterator1 dual_iterator_type;
typedef reverse_iterator1 dual_reverse_iterator_type;
typedef typename functor_type::functor2_type functor2_type;
// Construction and destruction
iterator2 ();
iterator2 (sparse_matrix &amp;m, int rank, size_type i, size_type j, const iterator_type &amp;it);
// Arithmetic
iterator2 &amp;operator ++ ();
iterator2 &amp;operator -- ();
// Dereference
reference operator * () const;
iterator1 begin () const;
iterator1 end () const;
reverse_iterator1 rbegin () const;
reverse_iterator1 rend () const;
// Indices
size_type index1 () const;
size_type index2 () const;
// Assignment
iterator2 &amp;operator = (const iterator2 &amp;it);
// Comparison
bool operator == (const iterator2 &amp;it) const;
};
iterator2 begin2 ();
iterator2 end2 ();
// Reverse iterators
const_reverse_iterator1 rbegin1 () const;
const_reverse_iterator1 rend1 () const;
reverse_iterator1 rbegin1 ();
reverse_iterator1 rend1 ();
const_reverse_iterator2 rbegin2 () const;
const_reverse_iterator2 rend2 () const;
reverse_iterator2 rbegin2 ();
reverse_iterator2 rend2 ();
};</code></pre>
<hr>
<p>Copyright (<28>) 2000-2002 Joerg Walter, Mathias Koch <br>
Permission to copy, use, modify, sell and distribute this
document is granted provided this copyright notice appears in all
copies. This document is provided ``as is'' without express or
implied warranty, and with no claim as to its suitability for any
purpose.</p>
<p>Last revised: 8/3/2002</p>
</body>
</html>