Version 1.0alpha
Description
This library is the first part of a greater effort to produce a class library for bioinformatics and molecular modelling. The focus of this larger library is on the algorithms used within these fields. The classes contained within the bioMath class library provide a fairly low level mathematical base to the larger library. Although the bioMath library has been designed with biomolecular applications in mind it contains classes of more general utility. For instance, the Matrix class could be used for matrix algebra in many contexts. There are many freely available matrix classes that pre-date this one but non are well suited to our needs. Most libraries provide functionality that unlikely to be used in bioinformatics and molecular modelling applications. We aim to provide an extremely simple matrix class to be used by people who may not have a particularly strong mathematical background.
The overall characteristics of the library are controlled by statements in the Typedefn.h file. This file is intended to be directly of indirectly included by every other file in the library.
Floating Point Precision
The floating point precision of the library as a whole is defined as the user defined type REAL. A typedef statement in the Typedefn.h. e.g.
typedef double REAL;
To change the precision used simply alter this statement and recompile the library. Of course not all floating point variables in the library are of type REAL, some, for instance, are fixed at type double to avoid large round off errors. In spite of this, setting REAL to be of type float may well result significant round off problems in certain calculations such as those used by the Matrix::Eigens() method.
Debugging Version of Library
If the DEBUG_VERSION symbol is defined then the library will carry out extra error checking such as some array bounds checking. This checking will obviously make the library more robust but will also increase excecution times. Simply comment the define statement in the Typedefn.h file out if the extra checking is not required.
This class contains methods for calculating the applying the least squares fit of one set of x,y,z coordinates onto another. The method used is that of Simon K. Kearsley (Acta Cryst.'89, A45, 208-10).
Usage: All members in this class are static and therefore an object need not be create before the members can be used. The methods in this class are generic algorthms and can be used with a wide range of container types. This flexibility is achieved through the use of iterators. Any container used must have an appropriate iterator type that can be used to traverse through its elements. Most methods require two iterators per container, marking the first and last element to be processed. This style of function is designed to be the same as used in the Standard Template Library.
e.g.
typedef vector::iterator iterator;
// Construct two empty vectors
vector v1,v2;
// Put some coordinates into these vector
....
// Do least squares fit on these coodinates
double rmsd =
Fitter::Fit(v1.begin(),v1.end(),v2.begin(),v2.end());
// Set up aliases of the type to be used
typedef vector::const_iterator const_iterator;
typedef LeastSquaresFit<iterator,const_iterator> Fitter;
Files: LeastSquaresFit.h
Dependencies: Matrix, NumericLimits
Authors: W.R.Pitt, D.S.Moss
Operations
This is a template class that can be used to return standard floating point constants. N.B. This file will become obsolete when the standard C++ file climits becomes more widely available. It contains a numeric_limits class which will replace NumericLimits defined below.
Usage: e.g. const float EPSILON = NumericLimits<float>::epsilon();
Restrictions: This template class only works for float, double, and long double types.
Authors: W.R.Pitt
Files: NumericLimits.h
Friends: None
Dependencies: None
Operations
This template class contains members which preform certain numerical functions. The design of this class is not object-oriented and the member functions could easily be provided as stand alone functions. The reasons for containing the functions within a class is to put them into a namespace and to make documentation easier. Standand C++ namespaces are not still not implemented in many C++ compilers but otherwise this method may well be better than putting the functions into a class. Most C++ design and automatic documentation tools do not deal with non-class parts of a library. We use Together/C++ for our documentation and this tool only produces documentation for classes and class members.
Usage: e.g. unsigned int error = NumericUtilities<float>::AreNotEqual(a,b);
Restrictions: This template class only works for float, double, and long double types.
Authors: W.R.Pitt
Files: NumericUtilities.h
Friends: None
Dependencies: NumericLimits
Operations
his class represents a mathematical vector of any dimension.
V = xi + yj + zk + ...
However, its primary use will probably in representing the position of atoms in three dimensions. The default contructor contructs a 3D Vector.
There are several types associated with this class:
value_type : same as the type REAL which is defined in
Typedefn.h
iterator : this is a STL type iterator. It can be used to
sequentailly access the elements of the Vector e.g.
const_iterator
Vector v1;
...
for (Vector::iterator i = v1.begin(); i != v1.end(); i++)
cout << *i;
: used to access const Vector.
size_type : this is an unsigned integer type that represents
the size of any Vector object.
Authors: W.R.Pitt, D.S.Moss
Files: MathVector.h, MathVector.cpp
Friends: Friend equivalents to some functions are available and are documented with these functions. Also available is: friend ostream& operator<<(ostream &os, const Matrix &m);
Dependencies: NumericLimits NumericUtilities
Operations
This class represents a mathematical Matrix of any dimension. Matrices where one of the two dimensions is unity are more efficiently modelled using the Vector class.
There are two types associated with this class:
value_type : this type is the same as the Vector::value_type
and defines the type of the elements of the Matrix.
size_type : this type is the same as the Vector::size_type and
defines the type of the Matrix indexes. It should always be an unsigned
integer type.
Authors: D.S.Moss, W.R.Pitt, I.Tickle.
Files: Matrix.h, Matrix.cpp
Friends: Friend equivalents to some functions are available and are documented with these functions. Also available is: friend ostream& operator<<(ostream &os, const Matrix &m);
Dependencies: Vector, NumericLimits, NumericUtilities
Operations
static double RMSD(ConstForwardIterator begin1, ConstForwardIterator end1, ConstForwardIterator begin2, ConstForwardIterator end2, const unsigned int nDimensions);
Calculate the root mean squared deviation of two sets of coordinates.
Restrictions: Each set must have the same number of coordinates. There is no restriction on the number of dimensions which the coordinates represent (except that it must be the same in every case). WARNING: if coordinates with varying dimensions are input then this may well not be detected.
static double Compare(ConstForwardIterator begin1, ConstForwardIterator end1, ConstForwardIterator begin2, ConstForwardIterator end2);
Calculate the root mean squared deviation after a least squares fit of the two sets of coordinates using the method of Kearsley. Both sets of coordinates remain unchanged by this function
Restrictions: Each set must have the same number of coordinates. Each coordinate must be orthogonal and in three dimensions (i.e. normal x,y,z coordinates). WARNING: if coordinates with varying dimensions are input then this may well not be detected.
static double Fit(ForwardIterator begin1, ForwardIterator end1, ConstForwardIterator begin2, ConstForwardIterator end2);
Least squares fit one set of coordinates to another using the method of Kearsley. Return the root mean squared deviation after the fit. The second set of coordinates remains unaltered by this function.
Restrictions: Each set must have the same number of coordinates. Each coordinate must be orthogonal and in three dimensions (i.e. normal x,y,z coordinates). WARNING: if coordinates with varying dimensions are input then this may well not be detected.
Returns the value of the difference between 1 and the least value greater than 1 that is representable.
static T min()
Returns the minimum finite value.
static int digits10()
Returns the number of base 10 digits which can be represented without change
static int PowerOf10(const T& x);
Returns i where x = n * 10^i and 10>n>0
static unsigned int AreNotEqual(const T& a, const T& b);
Finds the difference between two real numbers - the outputed result is the number of digits after the decimal point of the difference divided by the smallest detectable difference. The output is zero if the difference was smaller than the smallest detectable difference. The maximum output depends on the precision of the input numbers e.g for two float numbers the maximum might be 6 (FLT_DIG) and for double's it might be 15 (DBL_DIG).
Constructs a 3D vector and initialised each value to 0.0.
Vector(value_type p, value_type q, value_type r)
Constructs a 3D vector with initialization and initialises the values with the numbers given.
Vector(size_type n)
Constructor for an n dimensional vector. All n values initiated to 0.0.
Vector(const value_type* const array, const size_type& p);
Construct from a two dimensional array of REALs ( given value_type* )
Vector(const Vector &v) : vec(v.vec)
Copy constructor.
~Vector()
Destructor.
iterator begin()
Returns iterator that can be used to begin traversing through all elements of the Vector.
Same as function above but returns a const_iterator.
const_iterator begin() const
iterator end()
Returns an iterator can be used in comparison for ending traversal through the Vector.
Same as function above but returns a const_iterator.
const_iterator end() const
value_type& operator[](const size_type& i);
Returns the element, i positions from the beginning of the Vector, in constant time. (i >= 0).
Same as function above but returns a const value.
value_type operator[](const size_type& i) const;
size_type size() const
Returns the number of elements in the Vector.
value_type& operator()(const size_type& i);
Returns the i-th element in the Vector (i >= 1).
Same as function above but returns a const value.
value_type operator()(const size_type& i) const
bool operator==(const Vector& v) const;
Vector equality.
value_type MaxDifference(const Vector& v) const;
Returns the largest difference between equivalent elements in this and Vector v.
Vector& operator=(const Vector &v)
Vector assignment.
Vector operator+(const Vector &v) const;
Vector addition.
Vector operator-(const Vector &v) const;
Vector subtraction.
Vector operator-() const;
Vector negation (unary minus operator).
Vector& operator+=(const Vector &v);
Vector increment.
Vector& operator-=(const Vector &v);
Vector decrement.
Vector operator+(const value_type &s) const;
Add a scalar to each element in the Vector.
Vector operator-(const value_type &s) const;
Subtract a scalar from each element in the Vector.
Vector& operator+=(const value_type &s);
Add a scalar to each element in the Vector.
Vector& operator-=(const value_type &s);
Subtract a scalar from each element in the Vector.
value_type operator*(const Vector &v) const;
Vector scalar/dot product.
Vector operator%(const Vector &v) const;
Vector cross product.
Vector operator*(const value_type& y) const;
Vector multiplication by a scalar.
Vector& operator*=(const value_type& y);
Vector multiplication by a scalar and assignment.
Vector operator/(const value_type& y) const;
Vector division by a scalar.
Vector& operator/=(const value_type& y);
Vector division by a scalar and assignment.
value_type Distance(const Vector& v) const;
Returns the root mean square distance between this and Vector v.
unsigned int IsNotEqualTo(const Vector& v) const;
Returns zero if the cooresponding Vector elements are all identical within the floating point precision used. If they are not identical then the function finds the largest difference between cooresponding elements and outputs the number of significant digits in this difference. The range this number can take depends on the floating point precision used. The maximum is typically equal to 6 for single precision (FLT_DIG) and 15 for double precision (DBL_DIG).
value_type Modulus() const;
Returns the modulus/magnitude of the vector.
Constructor for default 3x3 matrix and initialise elements to zero.
Matrix(const size_type& s);
Constructs a unit matrix of size s*s.
Matrix(const size_type& p, const size_type& q);
Constructs a Matrix with p rows and q columns. Initialises each element to zero
Matrix(const value_type * const array, const size_type& p, const size_type& q);
Constructs a Matrix with p rows and q columns. Elements are initialised to those in array.
Matrix(const value_type& e1, const value_type& e2, const value_type& e3, const value_type& e4, const value_type& e5, const value_type& e6, const value_type& e7, const value_type& e8,const value_type& e9);
Constructor for a 3x3 Matrix with initialisation
Matrix(const Vector& axis, const value_type& angle);
Constructor for 3x3 rotation matrix for a rotation about a given axis by a given number of degrees.
Matrix(const Matrix &m);
Copy constructor
~Matrix()
Destructor
Matrix& operator=(const Matrix &m);
Matrix assignment
value_type operator()(const size_type& i, const size_type& j) const;
Read only access a matrix element given its indices e.g. x(i,j) i = row, j = column. N.B. (i,j >= 1)
Read/write access a matrix element given its indices e.g. x(i,j) i = row, j = column. N.B. (i,j >= 1)
value_type& operator()(const size_type& i, const size_type& j);
iterator operator[](const size_type& i);
Returns an iterator that points the first element of a given row. N.B. ( 0 <= i < nrows )
Returns a const iterator that points the first elment of a given row. N.B. ( 0 <= i < nrows )
const_iterator operator[](const size_type& i) const;
Matrix operator*(const Matrix& m) const;
Matrix multiplication e.g. Matrix m1,m2,m3; .... m3 = m1 * m2;
Vector operator*(const Vector &v) const;
Postmultiplication of a Matrix by a Vector. e.g. Matrix m; Vector v1,v2; ... v2 = m * v1;
Restrictions: The size of v must equal the number of columns in this Matrix.
Friend: There exists a friend function: friend Vector operator*(const Vector &v, const Matrix& m); that performs premultiplication of Matrix by a Vector. This method is slightly less efficient than postmultiplication and requires that the size of Vector v must equal the number of rows in Matrix m.
Matrix& operator*=(const value_type& r);
Multiple each element by a number
Matrix operator*(const value_type& r) const;
Multiple each element by a number
Friend: The friend function: friend Matrix operator*(const value_type& r, const Matrix& m); is also available.
Matrix& operator/=(const value_type& r);
Divide each element by a number
Matrix operator/(const value_type& r) const;
Divide each element by a number
Matrix& operator-=(const value_type &v);
Subtraction of a number from each element.
Matrix operator-(const value_type &v) const;
Subtraction of a number from each element.
Matrix& operator+=(const value_type &v);
Addition of a number to each element.
Matrix operator+(const value_type &v) const;
Addition of a number to each element.
Matrix& operator-=(const Vector &v);
Subtraction of a vector from the rows of a matrix
Restrictions: The the size of Vector v must equal the number of columns in this Matrix.
Matrix operator-(const Vector &v) const;
Subtraction of a vector from the rows of a matrix
Restrictions: The the size of Vector v must equal the number of columns in this Matrix.
Matrix& operator+=(const Vector &v);
Addition of a vector to the rows of a matrix
Restrictions: The the size of Vector v must equal the number of columns in this Matrix.
Matrix operator+(const Vector &v) const;
Addition of a vector to the rows of a matrix
Restrictions: The the size of Vector v must equal the number of columns in this Matrix.
Matrix& operator-=(const Matrix &m);
Matrix subtraction
Restrictions: The the size of Matrix m must equal the size of this Matrix.
Matrix operator-(const Matrix &m) const;
Matrix subtraction
Restrictions: The the size of Matrix m must equal the size of this Matrix.
Matrix& operator+=(const Matrix &m);
Matrix addition
Restrictions: The the size of Matrix m must equal the size of this Matrix.
Matrix operator+(const Matrix &m) const;
Matrix addition
Restrictions: The the size of Matrix m must equal the size of this Matrix.
Matrix operator&(const Matrix& m) const;
Matrix multiplication Transpose(m1) * m2 N.B. this is less efficient than (but not equivalent to) operator%
Restrictions: Both *this and the input Matrix must have the same number of rows
Matrix operator%(const Matrix& m) const;
Matrix multiplication m1 * Transpose(m2) N.B. this is more efficient than (but not equivalent to) operator&
Restrictions: Both *this and the input Matrix must have the same number of columns
bool operator==(const Matrix& m) const;
Equality operator
iterator begin()
Returns an iterator that points to the first element in the Matrix
Returns a const_iterator that points to the first element in the Matrix
const_iterator begin() const
iterator end()
Returns an iterator that can be used in a comparison for ending a traversal through this Matrix
Returns a const_iterator that can be used in a comparison for ending a traversal through this Matrix
const_iterator end() const
size_type size() const
Size of Matrix (the number of rows times the number of columns)
Matrix Adjoint() const;
Matrix adjoint
Restrictions: Square matrices only
unsigned int IsNotEqualTo(const Matrix& m) const;
Returns zero if the cooresponding Matrix elements are all identical within the floating point precision used. If they are not identical then the function finds the largest difference between cooresponding elements and outputs the number of significant digits in this difference. The range this number can take depends on the floating point precision used. The maximum is typically equal to 6 for single precision (FLT_DIG) and 15 for double precision (DBL_DIG).
void CholeskyInverse();
Inverts a positive definite square matrix.
D S Moss May 1991
Employs Cholesky decomposition in step (1). (1)M=LL(tr) (2)compute L(-1) (3)M(-1)=L(-1)(tr)L(-1)
Restrictions: Symmetric positive definite matrices only.
Vector ColumnMean() const;
Calculate the mean of each column of this Matrix and store the answer in a Vector
value_type Determinant() const;
Matrix determinant
Restrictions: Square matrices only.
void Eigens(Vector &eval, Matrix &evec) const;
Eigenvalues and eigenvectors of a symmetric matrix
Restrictions: *this matrix must be square and symmetric.
Parameters: (1) A returned vector with the same dimension as *this Matrix (n) containing eigenvalues in decreasing magnitude; (2) A returned Matrix of size n^2 containing eigenvectors stored columnwise in the same order as the eigenvalues magnitude
void Inverse();
Matrix inverse. Answer overwrites this Matrix.
value_type MaxDifference(const Matrix& m) const;
Find the largest difference between elements of matrices of the same dimensions.
Matrix Minor(size_type i, size_type j) const;
Find the minor of a square matrix.
Restrictions: This matrix must be square.
size_type ReadNRows() const
Read number of rows.
size_type ReadNCols() const
Read number of columns.
Vector ReadRow(const size_type& rowIndx) const;
Copy a row of this Matrix into a Vector
Matrix SquareInverse() const;
Calculate inverse of a small square matrix (inverse = adjoint/determinant).
void SVD(Vector& L, Matrix& V);
Single value decomposition. A = U * matL * V.transpose() where A is this Matrix. On completion, this matrix is overwritten with matrix U, the diagonal of matrix matL is written over the input Vector L and Matrix V replaces the input Matrix. The rank of the matrix is returned as the output parameter.
Matrix Transpose() const;
Matrix transpose
void WriteRow(const Vector& rowVector, const size_type& rowIndx);
Copy data from a Vector into a row of this Matrix.
Restrictions: The size of the input Vector must equal the number of columns in this Matrix.
void WriteRow(const value_type* rowArr, const size_type& rowIndx);
Copy data from an array into a row of this Matrix. This routine assumes that the size of the input array is equal the number of columns in this Matrix.
This page was created automatically using Together/C++ Information Export in
conjunction with the Borland C++ development suite.
Questions or comments are welcome, please send them to
Will Pitt.