/**
\mainpage The Zenautics Matrix Project

\htmlonly
<br><center><a href="http://sourceforge.net/projects/mtxfx">Sourceforge Project Page</a></center><br>
<br><center><a href="http://sourceforge.net/projects/mtxfx">Download Page</a></center><br>
\endhtmlonly

\section version_sec Version
0.06 Beta

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

\section quicklinkM_sec Quick Links to the Documentation

- The Matrix Class - Zenautics::Matrix \n

\section intro_sec Introduction

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 'std::complex<double>'. 
																											
\section features_sec Features		    

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

\section prof_version_sec Professional Version

- Highly optimized for INTEL processors using Intel's Integrated Performance Primitives \n
- SIMD instruction sets result in 10X to 100X or more execution speed improvement \n
- Comprehensive support packages available\n
- Available via:
\htmlonly
<a href="http://www.zenautics.com/">Zenautics Technologies Inc.</a>
\endhtmlonly
- 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.

\section package_sec 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).

\htmlonly
<br><br><hr>
\endhtmlonly

\section data_access_sec Data Access

The Matrix treated as a real-only vector:
\code
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.
\endcode

The Matrix treated as a real-only matrix:
\code
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;
\endcode

The Matrix can be treated as a complex vector:
\code
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 
\endcode 

or as a complex matrix:
\code 
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;
\endcode

\htmlonly
<br><br><hr>
\endhtmlonly

\section loading_sec 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.
\code 
Matrix A;
bool result;
result = A.ReadFromFile("Data.txt");
\endcode

e.g. "Data.csv" which is delimited by commas.
\code 
Matrix A;
bool result;
result = A.ReadFromFile("Data.csv");
\endcode

Matrices can be also stored as lossless compressed binary files.

e.g. "Data.mtx" is a compressed binary matrix file.
\code 
Matrix A;
bool result;
result = A.ReadFromFile("Data.mtx");
\endcode

\htmlonly
<br><br><hr>
\endhtmlonly

\section saving_sec Outputting Matrices

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

Output to file.
\code 
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).
\endcode

Append to file.
\code 
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).
\endcode

Output to a lossless compressed binary file.
\code 
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.
\endcode

Output to a comma delimited file.
\code 
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.
\endcode

\htmlonly
<br><br><hr>
\endhtmlonly

\section plotting_sec Plotting Matrix Data

Matrix data can be plotted directly to a compressed (RLE) bitmap.
\code 
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)" );
\endcode

<img src = "files/testplot.bmp">

Equivalently, there is a member function for plotting columns of the matrix vs each other.
\code 
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)" );
\endcode

<img src = "files/testplot2.bmp">

Multiple series may be plotted with the member function.
\code 
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 );