The Zenautics Matrix Project

2009

Version

0.07 Beta

Despite rigorous use and development since 2005, the project is considered a beta relase until sufficient feedback for the sourceforge project is available.

Quick Links to the Documentation

The Matrix Class - Zenautics::Matrix

This C++ Matrix/Vector Library provides a powerful software development tool for real and complex data manipulation. It is an easy to use, fast and memory efficient for one and/or two dimensional matrices. A great deal of effort in design provides elegant access to the Matrix for real data and for complex data or both. The Matrix is highly optimized for column-wise operations with real-only, complex, and mixed data. Since the double type is the most commonly used floating point type for demanding PC applications, this library is optimized and specific for type 'double' and 'stdcomplex<double>'.

Features

Ease of use!
Simple to compile and utilize
Real and complex data
Exception handling
Safe mode functionality (most functions return bool, true if successful, false otherwise)
Comprehensive documentation
Uses the C++ Standard Template Library
FFT/IFFT (DFT/IDFT)*
Complete statistical function set
Comprehensive operator set
Fast Inversion using Cholesky decomposition for positive definite matrices
Robust Inversion otherwise
Fantastic data file reading capabilities
Automatic ASCII file delimiter detection
Ergonomic ASCII file formatting
Very fast and efficient saving and loading of matrices to lossless compressed binary files
Plotting - line and scatter plots directly to a compressed bitmap

Professional Version

Highly optimized for INTEL processors using Intel's Integrated Performance Primitives
SIMD instruction sets result in 10X to 100X or more execution speed improvement
Comprehensive support packages available
Available via: Zenautics Technologies Inc.
The Professional Version is available free for non-commercial applications during the Beta development period. Contact glenn at zenautics.com for further information.
A 30 day evaluation license is avaiable for commerical applications. Contact glenn at zenautics.com for further information.

Main Package Contents

Matrix.h and Matrix.cpp - The Matrix Class.
cmatrix.h and cmatrix.c - The core engine for the Matrix Class is written in C.
cplot.h and cplot.c - The plotting engine (refer http://sourceforge.net/projects/plot2d).
kiss_fft.h, kiss_fft.c, and _kiss_fft_guts.h - The FFT engine used (refer http://sourceforge.net/projects/kissfft).

Data Access

The Matrix treated as a real-only vector:

Matrix A(10); // Create a vector (10x1).
...
double d = A[0];  // Zero based indexing of the matrix as a real-only vector.
A[1] = d*4.0;     // Set a real value in the vector.

A.PrintStdout(4); // Print A to the standard output with a precision of 4.

The Matrix treated as a real-only matrix:

Matrix A(2,2); // Create a matrix (2x2).
...
double d = A[0][0];  // Zero based indexing of the matrix as a real-only matrix.
A[0][1] = d*4.0;

The Matrix can be treated as a complex vector:

Matrix A(10); // Create a vector (10x1).
...
double d = A(0).real();  // Zero based indexing of the matrix as a complex vector.
double v = A(0).imag();
A(1) = d; // set a real value
std::complex<double> q(1.0,-2.0);
A(2) = q; // set a complex value

or as a complex matrix:

Matrix A(2,2); // Create a matrix (2x2).
...
std::complex<double> c = B(0,0); 
double r = A(0,1).real(); 
double i = A(0,1).imag();
std::complex<double> w(1.0,-2.0);
A(1,1) = w;

Loading Matrices

For ASCII files with almost any delimiter (i.e. whitespace, comma, ';', etc), the delimiter is determined automatically. The matrix size is also determined automatically (The matrix is first loaded into a linked list. Once the matrix dimensions are known, it is then stored as a matrix. This means file data is only read once.).

e.g. "Data.txt" which is delimited by tabs.

Matrix A;
bool result;
result = A.ReadFromFile("Data.txt");

e.g. "Data.csv" which is delimited by commas.

Matrix A;
bool result;
result = A.ReadFromFile("Data.csv");

Matrices can be also stored as lossless compressed binary files.

e.g. "Data.mtx" is a compressed binary matrix file.

Matrix A;
bool result;
result = A.ReadFromFile("Data.mtx");

Outputting Matrices

Output to stdout.

Matrix A = "[ 1 2 3; 4 5 6; 7 8 9 ]"; // set the matrix from a string.
bool result;
result = A.PrintStdout();

Output to file.

Matrix A = "[ 1 2 3; 4 5 6; 7 8 9 ]"; // set the matrix from a string.
bool result;
result = A.Print("A.txt",6); // output with a precision of 6 (i.e. 6 significant digits).

Append to file.

Matrix A = "[ 1 2 3; 4 5 6; 7 8 9 ]"; // set the matrix from a string.
bool result;
result = A.Print("A.txt",6,true); // output in append mode with a precision of 6 (i.e. 6 significant digits).

Output to a lossless compressed binary file.

Matrix A = "[ 1 2 3; 4 5 6; 7 8 9 ]"; // set the matrix from a string.
bool result;
result = A.Save("A.mtx"); // save to a compressed binary using a method balanced for speed and compression efficiency.

Output to a comma delimited file.

Matrix A = "[ 1 2 3; 4 5 6; 7 8 9 ]"; // set the matrix from a string.
bool result;
result = A.PrintDelimited("A.csv",6,','); // output to a comma delimited file with a precision of 6.

Plotting Matrix Data

Matrix data can be plotted directly to a compressed (RLE) bitmap.

bool result;
Matrix X = "[ 1 2 3 4 5 6 7 8 9 10 ]"; // set the matrix from a string, row vector.
Matrix Y = X^2;
result = Plot( "testplot.bmp", "Y=X^2", "X (m)", "Y (m)", X, Y, "Y=X^2", "(m^2)" );

Equivalently, there is a member function for plotting columns of the matrix vs each other.

bool result;
X = "[ 1; 2; 3; 4; 5; 6; 7; 8; 9; 10; ]"; // set the matrix from a string, column vector.
result = X.Concatonate( X^2 );
result = X.Plot( 0, 1, "testplot2.bmp", "Y=X^2", "X (m)", "Y (m)", "Y=X^2", "(m^2)" );

Multiple series may be plotted with the member function.

bool result;
X = "[ 1; 2; 3; 4; 5; 6; 7; 8; 9; 10; ]"; // set the matrix from a string, column vector.
Y = X; 
result = X.Concatonate( Y^2 );
result = X.Concatonate( Y^3 );
result = X.Plot( 0, 1, 2, "testplot3.bmp", "Y=X^2", "X (m)", "Y (m)", "Y=X^2", "(m^2)", "Y=X^3", "(m^3)" );

Plotting multiple series.

X = "[ 1; 2; 3; 4; 5; 6; 7; 8; 9; 10; ]"; // set the matrix from a string, column vector.
Matrix Y1 = X^(0.5);
Matrix Y2 = X;
Matrix Y3 = X^2; 
Matrix Y4 = X^3; 
result = Plot( "testplot4.bmp", "Y as function of X", "X (m)", "Y (m)", X, Y1, "Y=sqrt(X)", "sqrt(m)", X, Y2, "Y=(X)", "(m)", X, Y3, "Y=X^2", "(m^2)", X, Y4, "Y=X^3", "(m^3)" );

LICENSE INFORMATION

This license is categorized as a BSD-style license (refer http://en.wikipedia.org/wiki/Bsd_license).

Redistribution pertains to the following files and their contents.

Redistribution and use in source and binary forms, with or without modification, of the specified files is permitted provided the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
The name(s) of the contributor(s) may not be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Notes

This code was developed using rigourous unit testing for every function and operation. Despite any rigorous development process, bugs are inevitable. Please report bugs and suggested fixes to glenn at zenautics.com.

Release Notes

Version 0.01 Beta

This is the first release via sourceforge. The project was privately hosted prior to this version.

Version 0.02 Beta

Some inner loop optimizations within for loops.
A few new functions:
Matrix Negate();
Matrix IdentityMinusMe();
Matrix MinusIdentity();
Matrix AddIdentity();

Version 0.03 Beta

Matrix Inversion tweaks for more efficiency.
Complex Matrix Inversion - revised so that robust inversion is always used for complex matrix inversion.
New Functions
bool Matrix::Inplace_rand - generate pseudorandom numbers with uniform distribution [0,1]
bool Matrix::Inplace_randn - generate pseudorandom numbers with standard normal distibution N(0,1)
bool Matrix::Hilbert - sets the matrix as the NxN hilbert matrix. H_ij = 1.0 / (i+j-1.0) for i=1:N, j=1:N.

Version 0.04 Beta

'explicit' keyword added to vector sytle constructor (needed for some compilers).
New Functions
bool Matrix::Swap - Swap the contents of two matrices without copying

Version 0.05 Beta

The FFT function was only computing the FFT of the first column. Fixed to compute the FFT of each column.
Efficient functions for multiplication with a matrix transpose added.
New Functions
FFT2
IFFT2
bool Inplace_TranposePreMultiply( const Matrix &B ); // A = transpose(B)*A
bool Inplace_PostMultiplyTranspose( const Matrix &B ); // A = A*transpose(B)
bool TransposeMultiply( const Matrix &B, const Matrix &C ); // A = transpose(B)*C
bool MultiplyTranspose( const Matrix &B, const Matrix &C ); // A = B*transpose(B)

Version 0.06 Beta

Bug Fix: Determinant sign error (in a few select cases the determinant had the wrong sign).
Bug Fix: SortByColumn and related functions (only the first and second column were sorted correctly).
Enhanced the Concatonate() function to allow concatonation of an empty matrix.
Efficient functions for multiplication with a matrix transpose added.
New Functions
ExtractSubMatrix
Inplace_erf
Inplace_erfc
Inplace_erfinv
Inplace_erfcinv
GetLDLt
GetUDUt
Find_EqualTo
Find_NotEqualTo
Find_LessThan
Find_MoreThan

Version 0.07 Beta

Removed a few unreference variables.
New Functions
ForceSymmetric

FFT

The Professional Version utilizes Intel's FFT (fastest FFT available). For performance comparison of the various FFT methods refer to http://www.fftw.org/benchfft/.

The Basic Version utilizes the KISS FFT software libary (http://sourceforge.net/projects/kissfft/, also BSD license).

Kiss FFT License Information

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the author nor the names of any contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.