Open Babel  3.0
Public Member Functions | Static Public Member Functions | Friends | List of all members
matrix3x3 Class Reference

#include <openbabel/math/matrix3x3.h>

Inheritance diagram for matrix3x3:
transform3d

Public Member Functions

 matrix3x3 (void)
 
 matrix3x3 (double s)
 
 matrix3x3 (vector3 row1, vector3 row2, vector3 row3)
 
 matrix3x3 (double d[3][3])
 
 ~matrix3x3 ()
 
void GetArray (double *m)
 
const double & operator() (int row, int column) const
 
double & operator() (int row, int column)
 
matrix3x3 inverse (void) const
 
matrix3x3 transpose (void) const
 
double determinant () const
 
bool isSymmetric (void) const
 
bool isOrthogonal (void) const
 
bool isDiagonal (void) const
 
bool isUnitMatrix (void) const
 
double Get (int row, int column) const
 
void Set (int row, int column, double v)
 
void SetColumn (int column, const vector3 &v)
 
void SetRow (int row, const vector3 &v)
 
vector3 GetColumn (unsigned int col) const
 
vector3 GetRow (unsigned int row) const
 
matrix3x3operator*= (const double &c)
 
matrix3x3operator/= (const double &c)
 
void SetupRotMat (double x, double y, double z)
 
void PlaneReflection (const vector3 &norm)
 
void RotAboutAxisByAngle (const vector3 &axis, const double angle)
 
void FillOrth (double alpha, double beta, double gamma, double a, double b, double c)
 
matrix3x3 findEigenvectorsIfSymmetric (vector3 &eigenvals) const
 

Static Public Member Functions

static void jacobi (unsigned int n, double *a, double *d, double *v)
 

Friends

vector3 operator* (const matrix3x3 &, const vector3 &)
 
matrix3x3 operator* (const matrix3x3 &, const matrix3x3 &)
 
std::ostream & operator<< (std::ostream &, const matrix3x3 &)
 

Detailed Description

Represents a real 3x3 matrix.

Rotating points in space can be performed by a vector-matrix multiplication. The matrix3x3 class is designed as a helper to the vector3 class for rotating points in space. The rotation matrix may be initialised by passing in the array of floating point values, by passing euler angles, or a rotation vector and angle of rotation about that vector. Once set, the matrix3x3 class can be used to rotate vectors by the overloaded multiplication operator. The following demonstrates the usage of the matrix3x3 class:

mat.SetupRotMat(0.0,180.0,0.0); //rotate theta by 180 degrees
vector3 v = VX;
v *= mat; //apply the rotation

Constructor & Destructor Documentation

◆ matrix3x3() [1/4]

matrix3x3 ( void  )
inline

Constructs the zero-matrix.

◆ matrix3x3() [2/4]

matrix3x3 ( double  s)
inline

Constructs s times the unit matrix.

◆ matrix3x3() [3/4]

matrix3x3 ( vector3  row1,
vector3  row2,
vector3  row3 
)
inline

Constructs a matrix from row vectors.

◆ matrix3x3() [4/4]

matrix3x3 ( double  d[3][3])
inline

Constructs a matrix from a 3x3-array of doubles.

The first index represents the row, the second index the column

◆ ~matrix3x3()

~matrix3x3 ( )
inline

Destructor.

Member Function Documentation

◆ GetArray()

void GetArray ( double *  m)
inline

Access function.

Writes the matrix into the 1-dimensional array m, row by row. The array must be able to hold 9 doubles, otherwise your program will segfault.

◆ operator()() [1/2]

const double& operator() ( int  row,
int  column 
) const
inline
Returns
a constant reference to an element of the matrix. row and column must be between 0 and 2. No check is done.

◆ operator()() [2/2]

double& operator() ( int  row,
int  column 
)
inline
Returns
a non-constant reference to an element of the matrix. row and column must be between 0 and 2. No check is done.

◆ inverse()

matrix3x3 inverse ( void  ) const

Calculates the inverse of a matrix.

This method checks if the absolute value of the determinant is smaller than 1e-6. If so, nothing is done and an exception is thrown. Otherwise, the inverse matrix is calculated and returned. *this is not changed.

Warning
If the determinant is close to zero, but not == 0.0, this method may behave in unexpected ways and return almost random results; details may depend on your particular floating point implementation. The use of this method is therefore highly discouraged, unless you are certain that the determinant is in a reasonable range, away from 0.0 (Stefan Kebekus)

Referenced by OBUnitCell::CartesianToFractional(), OBUnitCell::GetFractionalMatrix(), and OBUnitCell::SetData().

◆ transpose()

matrix3x3 transpose ( void  ) const

Calculates the transpose of a matrix.

Referenced by OBUnitCell::GetCellMatrix(), and OBUnitCell::SetData().

◆ determinant()

double determinant ( void  ) const
Returns
The determinant of the matrix

◆ isSymmetric()

bool isSymmetric ( void  ) const

Checks if a matrix is symmetric.

Returns
False if there are indices i,j such that fabs(*this[i][j]-*this[j][i]) > 1e-6. Otherwise, it returns true.

◆ isOrthogonal()

bool isOrthogonal ( void  ) const
inline

Checks if a matrix is orthogonal.

This method checks if a matrix is orthogonal, i.e. if all column vectors are normalized and are mutually orthogonal. A matrix is orthogonal if, and only if the transformation it describes is orthonormal. An orthonormal transformation is a transformation that preserves length and angle.

The check is performed using the method isUnitMatrix() to check if

*this * transpose()

is a unit matrix. The criterion is therefore numerically quite tight.

◆ isDiagonal()

bool isDiagonal ( void  ) const
Returns
if a matrix is diagonal

This method returns true if and only if the matrix is (approximately) a diagonal matrix. The precision used by this function is 1e-6.

◆ isUnitMatrix()

bool isUnitMatrix ( void  ) const
Returns
if a matrix is the unit matrix

This method returns true if and only if the matrix is (approximately) equal to the identity matrix. The precision used by this function is 1e-6.

◆ Get()

double Get ( int  row,
int  column 
) const
inline

Access function.

Warning
row or column are not in the range 0..2, zero is returned !
Deprecated:
use the constant operator() instead

Referenced by vector3::operator*=().

◆ Set()

void Set ( int  row,
int  column,
double  v 
)
inline

Access function.

Warning
if row or column are not in the range 0..2, nothing will happen !
Deprecated:
use the non-constant operator() instead

◆ SetColumn()

void SetColumn ( int  column,
const vector3 v 
)

Access function.

Warning
If column is not in the range 0..2, the vector remains unchanged and an exception is thrown.

◆ SetRow()

void SetRow ( int  row,
const vector3 v 
)

Access function.

Warning
If column is not in the range 0..2, the vector remains unchanged and an exception is thrown.

◆ GetColumn()

vector3 GetColumn ( unsigned int  col) const

Access function.

Warning
If col is not in the range 0..2, an exception is thrown.

Referenced by OBUnitCell::GetA(), OBUnitCell::GetAlpha(), OBUnitCell::GetB(), OBUnitCell::GetBeta(), OBUnitCell::GetC(), and OBUnitCell::GetGamma().

◆ GetRow()

vector3 GetRow ( unsigned int  row) const

Access function.

Warning
If row is not in the range 0..2, an exception is thrown.

Referenced by OBUnitCell::GetCellVectors(), and OBUnitCell::SetData().

◆ operator*=()

matrix3x3& operator*= ( const double &  c)
inline

Multiplies all entries of the matrix by a scalar c.

◆ operator/=()

matrix3x3& operator/= ( const double &  c)
inline

Divides all entries of the matrix by a scalar c.

◆ SetupRotMat()

void SetupRotMat ( double  x,
double  y,
double  z 
)

Calculate a rotation matrix for rotation about the x, y, and z axes by the angles specified (in degrees)

Referenced by OBBuilder::Connect().

◆ PlaneReflection()

void PlaneReflection ( const vector3 norm)

Calculates a matrix that represents reflection on a plane.

Replaces *this with a matrix that represents reflection on the plane through 0 which is given by the normal vector norm.

Warning
If the vector norm has length zero, this method will generate the 0-matrix. If the length of the axis is close to zero, but not == 0.0, this method may behave in unexpected ways and return almost random results; details may depend on your particular floating point implementation. The use of this method is therefore highly discouraged, unless you are certain that the length is in a reasonable range, away from 0.0 (Stefan Kebekus)
Deprecated:
This method will probably replaced by a safer algorithm in the future.
Todo:
Replace this method with a more fool-proof version.
Parameters
normspecifies the normal to the plane

◆ RotAboutAxisByAngle()

void RotAboutAxisByAngle ( const vector3 v,
const double  angle 
)

Calculates a rotation matrix, rotating around the specified axis by the specified angle (in degrees)

Replaces *this with a matrix that represents rotation about the axis by a an angle.

Warning
If the vector axis has length zero, this method will generate the 0-matrix. If the length of the axis is close to zero, but not == 0.0, this method may behave in unexpected ways and return almost random results; details may depend on your particular floating point implementation. The use of this method is therefore highly discouraged, unless you are certain that the length is in a reasonable range, away from 0.0 (Stefan Kebekus)
Deprecated:
This method will probably replaced by a safer algorithm in the future.
Todo:
Replace this method with a more fool-proof version.
Parameters
vspecifies the axis of the rotation
angleangle in degrees (0..360)

Referenced by OBMol::Align(), OBBuilder::Build(), OBBuilder::GetNewBondVector(), OBBuilder::IsSpiroAtom(), and OBAtom::SetHybAndGeom().

◆ FillOrth()

void FillOrth ( double  alpha,
double  beta,
double  gamma,
double  a,
double  b,
double  c 
)

Calculate an orthogonalisation matrix for a unit cell specified by the parameters alpha, beta, gamma, a, b, c where alpha, beta, and gamma are the cell angles (in degrees) and a, b, and c are the cell vector lengths Used by OBUnitCell

Referenced by OBUnitCell::SetData().

◆ findEigenvectorsIfSymmetric()

matrix3x3 findEigenvectorsIfSymmetric ( vector3 eigenvals) const

Find the eigenvalues and -vectors of a symmetric matrix.

This method employs the static method matrix3x3::jacobi(...) to find the eigenvalues and eigenvectors of a symmetric matrix. On entry it is checked if the matrix really is symmetric: if isSymmetric() returns 'false', an OBError is thrown.

Note
The jacobi algorithm is should work great for all symmetric 3x3 matrices. If you need to find the eigenvectors of a non-symmetric matrix, you might want to resort to the sophisticated routines of LAPACK.
Parameters
eigenvalsa reference to a vector3 where the eigenvalues will be stored. The eigenvalues are ordered so that eigenvals[0] <= eigenvals[1] <= eigenvals[2].
Returns
an orthogonal matrix whose ith column is an eigenvector for the eigenvalue eigenvals[i]. Here 'orthogonal' means that all eigenvectors have length one and are mutually orthogonal. The ith eigenvector can thus be conveniently accessed by the GetColumn() method, as in the following example.
// Calculate eigenvectors and -values
vector3 eigenvals;
matrix3x3 eigenmatrix = somematrix.findEigenvectorsIfSymmetric(eigenvals);
// Print the 2nd eigenvector
cout << eigenmatrix.GetColumn(1) << endl;
With these conventions, a matrix is diagonalized in the following way:
// Diagonalize the matrix
matrix3x3 diagonalMatrix = eigenmatrix.inverse() * somematrix * eigenmatrix;

◆ jacobi()

void jacobi ( unsigned int  n,
double *  a,
double *  d,
double *  v 
)
static

Eigenvalue calculation.

This static function computes the eigenvalues and eigenvectors of a SYMMETRIC nxn matrix. This method is used internally by OpenBabel, but may be useful as a general eigenvalue finder.

The algorithm uses Jacobi transformations. It is described e.g. in Wilkinson, Reinsch "Handbook for automatic computation, Volume II: Linear Algebra", part II, contribution II/1. The implementation is also similar to the implementation in this book. This method is adequate to solve the eigenproblem for small matrices, of size perhaps up to 10x10. For bigger problems, you might want to resort to the sophisticated routines of LAPACK.

Note
If you plan to find the eigenvalues of a symmetric 3x3 matrix, you will probably prefer to use the more convenient method findEigenvectorsIfSymmetric()
Parameters
nthe size of the matrix that should be diagonalized
aarray of size n^2 which holds the symmetric matrix whose eigenvectors are to be computed. The convention is that the entry in row r and column c is addressed as a[n*r+c] where, of course, 0 <= r < n and 0 <= c < n. There is no check that the matrix is actually symmetric. If it is not, the behaviour of this function is undefined. On return, the matrix is overwritten with junk.
dpointer to a field of at least n doubles which will be overwritten. On return of this function, the entries d[0]..d[n-1] will contain the eigenvalues of the matrix.
van array of size n^2 where the eigenvectors will be stored. On return, the columns of this matrix will contain the eigenvectors. The eigenvectors are normalized and mutually orthogonal.

Friends And Related Function Documentation

◆ operator* [1/2]

vector3 operator* ( const matrix3x3 m,
const vector3 v 
)
friend

Matrix-vector multiplication.

Calculates the product m*v of the matrix m and the column vector represented by v

◆ operator* [2/2]

matrix3x3 operator* ( const matrix3x3 A,
const matrix3x3 B 
)
friend

Matrix-matrix multiplication.

◆ operator<<

std::ostream& operator<< ( std::ostream &  co,
const matrix3x3 m 
)
friend

Output a text representation of a matrix.

Print a text representation of the matrix in the standardized form: [ a, b, c ]
[ d, e, f ]
[ g, h, i ]
where the letters represent the appropriate entries in the matrix. Uses the standard output format for the individual entries, separated by ", " for each column, and [ ] indicating each row.


The documentation for this class was generated from the following files: