Simple C++ Numerical Toolkit (SCPPNT)

Download | Documentation | Examples | Iterators | Release Notes

Bradley A. Hanson

Release: 0.010619 (June 19, 2001)

The Simple C++ Numerical Toolkit (SCPPNT) consists of a set of classes and functions that implement simple dense matrix and vector classes and some associated algorithms. SCPPNT is a modified version of the Template Numerical Toolkit (TNT). The major changes that were made to TNT are:

  1. Row, column, and diagonal iterators were added to the matrix class, and are used in algorithms involving matrices. Some tests I have done indicate that using iterators in algorithms involving matrices can result in increased performance relative to using matrix subscripting.
  2. Assignment operators (+=, -=, *=, /=) were added to matrix and vector classes. The use of assignment operators can help eliminate the creation of temporary matrix and vector objects in computations.
  3. Errors result in an exception being thrown rather than the program being aborted. This allows programs to more gracefully deal with errors that occur in SCPPNT functions.

The matrix and vector classes in SCPPNT have an interface that is mostly compatible with TNT. The algorithms in SCPPNT involving matrices that were modified from TNT use matrix iterators rather than matrix subscripting and cannot be used with the TNT Matrix class. There are some elements of TNT that have not been implemented in SCPPNT. For example, a matrix class where the data are stored internally in column-major order (TNT class Fortran_Matrix).

I have successfully compiled programs using SCPPNT with the CodeWarrior 6.0 compiler on Mac OS and Windows NT, the gcc 2.95.2 compiler on Linux, and the free Borland 5.5 compiler on Windows 95/NT. There may be some problems in using SCPPNT with compilers that are less compliant with the C++ standard.

The current release of SCPPNT is a beta version. SCPPNT has not been extensively tested, and the public interface to classes and functions may change.

Please contact me if you have any questions or comments about this software

Download

Download SCPPNT - Zip archive containing SCPPNT source files and documentation. The files are stored with DOS line breaks (they are DOS text files).

Note: A more recent release of SCPPNT is now available at http://www.smallwaters.com (12-15-2007).

Documentation

The documentation for SCPPNT consists of this file as well as comments in the source files. The source file comments were written to be compatible with the doxygen documentation system. The source code was processed by doxygen to produce on-line documentation for the SCPPNT source code. The on-line source code documentation contains descriptions of each file, class, and function that are part of SCPPNT. This documentation is also contained in the doc/src directory of the SCPPNT distribution.

Examples

The examples directory in the SCPPNT distribution contains several SCPPNT example programs. Most of these are modified versions of TNT example programs. One of the example programs (scppnt_test.cpp) showing some basic features of SCPPNT is given below.

// scppnt_test.cpp
// Example program illustrating some basic features of
// the Simple C++ Numerical Toolkit (SCPPNT).

#include <iostream>

// Make matrix region functions available in Matrix class
#define SCPPNT_USE_REGIONS

// Unless SCPPNT_NO_DIR_PREFIX is defined the
// directory prefix scppnt/ is used for SCPPNT
// header file includes.
#include "scppnt/vec.h"
#include "scppnt/cmat.h"
#include "scppnt/matop.h"
#include "scppnt/transv.h"
#include "scppnt/region2d.h"

using namespace SCPPNT;

int main()
{

    // Construct matrix. Elements are not initialized.
    // To initialize all elements to zero use
    // Matrix<double> a(2, 2, 0.0).
    Matrix<double> a(2, 2);
    
    // Assign elements to first row using
    // Fortran-style one-based indexing.
    a(1,1) = 0.5; a(1,2) = 1.0;
    
    // Assign elements to second row using
    // C-style zero-based indexing.
    a[1][0] = 1.5; a[1][1] = 2.0;
    
    // Multiply all elements of a by 2.
    // Analogous +=, -=, and /= operators are also available
    // for both matrices and vectors.
    a *= 2.0;

    // Construct 2X3 matrix with initial elements given
    // in row-major order by an iterator.
    double belem[6] = {0.1, 0.2, 0.3, 
                       0.3, 0.2, 0.1};
    Matrix<double> b(belem,2,3);
    
    // Construct vector. Elements are not initialized.
    // To initialize all elements to zero use
    // Vector<double> v(2, 0.0).
    Vector<double> v(2);
    
    // Assign first element using
    // Fortran-style one-based indexing
    v(1) = 2.0;
    
    // Assign second element using
    // C-style zero-based indexing.
    v[1] = 3.0;
    
    // Write a, b, and v
    std::cout << "a: " << a << std::endl;
    std::cout << "b: " << b << std::endl;
    std::cout << "v: " << v << std::endl;
    
    // Create new matrix that is the
    // product of a and b.
    // Analogous + and - operators are also
    // available for both matrices and vectors.
    Matrix<double> c = a * b;

    std::cout << "c = a * b: " << c << std::endl;
    
    // Matrix product b' * a, without forming the transpose of b
    Matrix<double> e = Transpose_View< Matrix<double> >(b) * a;
    
    std::cout << "b' * a: " << e << std::endl;
    
    // Matrix times vector b' * v, without forming the transpose of b
    Vector<double> u = Transpose_View<Matrix<double> >(b) * v;
    
    std::cout << "b' * v: " << u << std::endl;

    // Create new matrix that is the transpose of c
    Matrix<double> d = transpose(c);
    
    // Upper 2X2 region of d
    Index1D J(1, 2); // Index range of 1 through 2
    Region2D< Matrix<double> > dregion = d(J,J);
    
    std::cout << "d: " << dregion << std::endl;
    
    // Multiply upper 2X2 region of d by a and store result in dregion.
    // Analogous += and -= operators are also
    // available for both matrices and vectors.
    dregion *= a;
   
    // Print product of upper 2X2 submatrix of d and v
    std::cout << "d * a: " << dregion << std::endl;

    return 0;
}

Iterators

The matrix classes in SCPPNT provide row, column, and diagonal iterators. The Matrix<T>::begin_row(i) member function returns in iterator of type Matrix<T>::row_iterator to the first element of row i of a matrix. The Matrix<T>::begin_rows() member function returns an iterator of type Matrix<T>::rows_iterator which is an iterator over row iterators (of type Matrix<T>::row_iterator) pointing to the row iterator for the first row. The analogous functions and data types for columns are: Matrix<T>::begin_columns() which returns an iterator of type Matrix<T>::columns_iterator pointing initially to the iterator over elements in the first column, and Matrix<T>::begin_column(i) which returns an iterator of type Matrix<T>::column_iterator which points initially to the first element of column i.

The example below illustrates the use of row and column iterators. See the function matmult in matop.h for a further example of the use of row and column iterators in matrix algorithms.

#include "scppnt/cmat.h"

using namespace SCPPNT;

// 2X2 matrix with all elements initialized to 1
Matrix<double> B(2, 2, 1.0);

// m.row(i) returns an iterator of type row_iterator that can
// be used to iterate over the elements in the i-th row of the matrix.
// The iterator initially points to the first element of the i-th row.
// The following adds 1 to every element of the first row of matrix B.
Matrix<double>::row_iterator ib = B.begin_row(1);
for(int i=B.num_cols(); i--; ++ib) *ib += 1.0;

// 3X3 matrix with all elements initialized to 5
Matrix<double> A(3, 3, 5.0);

// Multiply every element of a matrix A by 2 (same as A *= 2.0).
// icols is an iterator over column iterators of matrix A.
Matrix<double>::columns_iterator icols = A.begin_columns();
for (int i = A.num_cols(); i--; ++icols)
{
    // icol is an interator over elements in a column of A
    Matrix<double>::column_iterator icol = *icols;
    for (int j = A.num_rows(); j--; ++icol) *icol *= 2.0;
}

Release Notes

Release notes for all releases are given in the file release_notes.txt in the SCPPNT distribution.

Release 0.010619 (June 19, 2001)

	Replace instances of rowit_iterator with rows_iterator, and
	instances of columnit_iterator with columns_iterator in matalg.h.
	[matalg.h]


Release 0.010516 (May 16, 2001)
	
	Corrected initialize method of Region2D and const_Region2D classes
	so that an exception is not thrown when SCPPNT_BOUNDS_CHECK is
	defined. [region2d.h]
	
	Make private member function diagonal_size() constant in
	matrix classes. [cmat.h, region2d.h]


Release 0.010515 (May 15, 2001)

	Renamed the rows(), columns(), row(), column(), and diagonal()
	member functions of the matrix classes to begin_rows(),
	begin_columns(), begin_row(), begin_column() and begin_diagonal(),
	respectively. Added member functions end_rows(), end_columns(),
	end_row(), end_column(), and end_diagonal() to return an iterator to
	one past the last element of the sequences for which the
	associated begin function return an iterator to the first
	element. [cmat.h, region2d.h, transv.h, trisolve.h, matalg.h,
	cholesky.h, qr.h, lu.h, matop.h, rowcolfunc.h]
	
	The begin_diagonal() member functions of the matrix classes
	now take two arguments: the row and column corresponding to
	the first element of the diagonal the iterator points to.
	[cmat.h, transv.h, region2d.h, qr.h, lu.h, cholesky.h,
	trisolve.h]

	Symbol BOOST_MSVC can be define when using Microsoft
	Visual C++ 6. Defining this symbol will NOT allow all
	elements of SCPPNT to be compiled with Microsoft Visual
	C++, but the basic matrix and vector operations defined
	in vec.h and cmat.h should compile. Currently, BOOST_MSVC
	is only used in vec.h. [vec.h, scppnt.h]

Software by Brad Hanson

Brad Hanson's Home Page

URL of this page: http://www.b-a-h.com/software/cpp/scppnt.html

Last updated: December 16, 2001