This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU* Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
Originally conceived in 1973 to support computer graphics, Vector is a modest linear algebra package specifically written for 3-dimensions. Although most of the algorithms are not restrictive, no higher space is supported. The original version was Fortran, here included with little modification. The C++ version is largely a translation of the Fortran version. 3-D vector algebra is well supported, and Vector has been widely used in the crystallographic community for programs to support graphics, analysis, and structure construction.
This release provides a vector_3d.h and vector_3d.cpp, and a FORTRAN library, and Vector_3_Test.cpp, with example/test programs
The Vector package is available at www.sourceforge.net/projects/vector. A source zip is available at downloads.sourceforge.net/vector/vector-0.1.3.zip. Later tarballs may be available.
The C++ code includes 4 classes. Vector_3 and Matrix_3x3 comprise most of the code. Line_3 and Plane_3 are small, rather incomplete classes for use with the other two.
Included also is a group of random numbers functions derived from code originally written by Rob Harrison. The function RandomOrientation, which returns a random rotation matrix, is the likely main one for use with Vector.
The header vector_3d.h and definitions source code vector_3d.cpp should be in the directory of the program to be compiled.
The provided interface is:
#include "vector_3d.h" FUNCTIONS IN Vector_3 Vector_3( void ); // constructor Default constructor - x,y,z are all initialized to DBL_MAX explicit Vector_3 ( const double arg); // constructor arg is used to initialize each of x,y,z Vector_3 ( const double ax, const double ay, const double az ); // constructor x,y,z are initialized to ax,ay,az, respectively Vector_3 ( const Vector_3& input_vector); // copy constructor the copy constructor returns a copy of input_vector virtual ~Vector_3( void ); // destructor SCALAR OPERATIONS ON VECTORS Vector_3 operator* ( const double arg ) const; returns a vector that is the input multiplied by the floating point scaling factor, arg Vector_3 operator/ ( const double arg ) const; returns a vector that is the input divided by the floating point scaling factor, arg OPERATIONS ONLY ON VECTORS double Dot ( const Vector_3& ) const; returns the dot product of two vectors Vector_3 DyadProduct ( const Vector_3& ) const; returns a vector x(result)=x1*x2, y(result)=y1*y2, z(result)=s1*z2 Vector_3 Cross ( const Vector_3& ) const; typical cross product of two vectors (also known as "vector product") Matrix_3x3 TensorProduct ( const Vector_3& ) const; where the dot product is v1 times v2-transpose, this returns v1-transpose times v2, populating a matrix with all pairs of x,y,z(1) times x,y,z(2) (also known as "outer product") Vector_3 operator+ ( const Vector_3& ) const; returns the vector sum of two vectors Vector_3 operator- ( const Vector_3& ) const; returns the vector difference of two vectors Vector_3 operator- ( void ) const; unary minus operator for a vector Vector_3& operator+= ( const Vector_3& ); in place vector sum of two vectors Vector_3& operator-= ( const Vector_3& ); in place subtraction of two vectors double Norm ( void ) const; returns the length of a vector double SquaredLength ( void ) const; returns the squared length of a vector (avoids the square root computation required by Norm(vector)) Vector_3 UnitV ( void ) const; returns a unit vector with the same direction (therefore same direction cosines) as the input vector Vector_3& operator= ( const Vector_3& ); assignment operator of vectors static Vector_3 GetCenterOfMass ( const Container& ); returns the vector to the center of mass of in input group of vectors static Matrix_3x3 Pair ( const Vector_3& v1, const Vector_3& v2, const Vector_3& v3, const Vector_3& v4 ); returns a matrix that will rotate v1 onto v3 and place v2 as close as possible to v4 while maintaining the alignment of v1,v3 static Vector_3 GetXAxis ( void ); returns the vector (1,0,0) static Vector_3 GetYAxis ( void ); returns the vector (0,1,0) static Vector_3 GetZAxis ( void ); returns the vector (0,0,1) static Vector_3 GetZeroVector (void ); returns the vector (0,0,0) bool operator== ( const Vector_3& ) const; bool operator!= ( const Vector_3& ) const; static double Angle ( const Vector_3& v1;, const Vector_3& v2, const Vector_3& v3 ); returns the angle between the vector from v2 to v1 and the vector from v2 to v3. Torsion and Angle differ from most of the functions in Vector_3 in that they use the ends of vectors static double Torsion ( const Vector_3& v1, const Vector_3& v2, const Vector_3& v3, const Vector_3& v4 ); returns the torsion angle from the sequence to the ends of v1,v2,v3,v4, respectively. Torsion and Angle differ from most of the functions in Vector_3 in that they use the ends of vectors double DistanceFromPlane ( const VPlane& ) const; returns the distance of a point from a 3-space plane double DistanceFromLine ( const VLine& ) const; returns the distance of a point from a 3-space line OPERATIONS USING MATRICES Vector_3 MV ( const Matrix_3x3& ) const; premultiply a vector by a matrix COMPLEX OPERATIONS Matrix_3x3 Rotmat ( const double angle ) const; returns the matrix that will rotate points about the input vector by the specified angle Matrix_3x3 InertiaTensorForPoint ( const double weight ) const; returns the inertia tensor for a point (used to compute best line and plane) weight is used to weight the importance of the input points ACCESS FUNCTIONS double operator ( const int& n ) const; for input values of 0,1,2, operator returns x,y,z, respectively double at ( const int& ) const; for input values of 0,1,2, at returns x,y,z, respectively friend functions Vector_3 operator* ( const double& value, const Vector_3& v ); returns a vector that is value times the input vector VPlane_3 BestPlane ( const Container& ); returns the plane that best approximates the list of points in the input container (which can be any container class, such as std::vector, that has proper iterators) VLine_3 BestLine ( const Container& ); returns the line that best approximates the list of points in the input container (which can be any container class, such as std::vector, that has proper iterators) FUNCTIONS IN Matrix_3x3 Matrix_3x3 ( void ); // constructor constructs a Matrix_3x3 with all entries initialized to DBL_MAX Matrix_3x3 ( const double, const double, const double, const double, const double, const double, const double, const double, const double ); // constructor returns a Matrix_3x3 with the elements equal to the 9 input values, in row order Matrix_3x3 ( const Matrix_3x3& ); // copy constructor virtual ~Matrix_3x3 ( void ); // destructor MATRIX/VECTOR OPERATIONS Vector_3 MV ( const Vector_3& ) const; returns a vector that is the input vector premultiplied by the input matrix OPERATIONS ON MATRICES ONLY Matrix_3x3 operator* ( const Matrix_3x3& ) const; returns the product of the two input matrices Matrix_3x3 operator+ ( const Matrix_3x3& ) const; returns the sum of the two input matrices Matrix_3x3 operator- ( const Matrix_3x3& ) const; returns the difference of the two input matrices Matrix_3x3 operator* ( const double d) const; returns a matrix that is multiplied by d Matrix_3x3 operator/ ( const double d ) const; returns a matrix that is divided by d Matrix_3x3& operator+= ( const Matrix_3x3& ); in place sum of two matrices Matrix_3x3& operator-= ( const Matrix_3x3& ); in place difference of two matrices Matrix_3x3& operator*= ( const Matrix_3x3& ); in place product of two matrices Matrix_3x3& operator= ( const Matrix_3x3& ); // copy constructor Matrix_3x3 Transpose ( void ) const; returns the transpose of the input matrix Matrix_3x3 Inver ( void ) const; returns the inverse of the input matrix void UnitMatrix ( void ); in place convesion of the input matrix to a unit matrix double Det ( void ) const; returns the determinant of the input matrix void Zero ( void ); converts the input matrix to a zero matrix bool Eigen1 ( double& eigenvalue, Vector_3& eigenvector ) const; returns the largest eigenvalue of the input matrix and its corresponding eigenvector bool Eigen3 ( std::vector
&eigenvalues, std::vector &eigenvectors ) const; returns all 3 eigenvalues of the input matrix and their corresponding eigenvectors double operator ( const int& ) const; returns the n-th element of the input matrix (in row order) Matrix_3x3 Cart( const double a, const double b, const double c, const double alpha, const double beta, const double gamma ) Cart is used to generate a matrix that will convert from coordinates in a non-orthogonal coordinate system to an orthogonal basis. This is the solution for the common problem in crystallography, where coordinates are often reported in coordinates that are measured using the unit cell dimensions. Cart will return a matrix that when multiplied by a vector expressed in fractional coordinates will generate the corresponding position in an orthonormal system. NOTE: VERY IMPORTANT: The coordinates created by that operation may NOT be comparable to those generated by some other conversion software. Each system assumes a particular relationship between the two system, and they are ALL correct. Basically, the conversion matrix can be multiplied by ANY rotation matrix at all, and the result will still generate correct orthogonal coordinates, just different ones. The inverse of the matrix that Cart generates will convert from orthogonal coordinates back to fractional ONLY IF the orginal transformation was made with the same convention that Cart uses. The convention used in Cart is that the a-crystallographic axis will be aligned parallel to x, the b-axis as close as possible to y, and the c-axis by construction of a right handed-coordinate system. OTHER FUNCTIONS static std::vector AB_BestRotationconst ContainerType& v1, const ContainerType& v2, Vector_3& centerOfMass1, Vector_3& centerOfMass2, Matrix_3x3& rotationMatrixFrom2To1, double& rmsd, const int pairCount=0 ) A common problem in crystallography is superimposing two similar structures. AB_BestRotation is a new (2009) algorithm for solving this problem. Currently, this is a somewhat preliminary version of the method. The transformations that it produces are nearly identical to the standard Kabsch algorithm's results. Interest in it centers on its abilities to use some interesting weighting schemes and possibly substructure determination. This early version does not yet implement these. Its behavior for small numbers of input points has not been fully investigated, but it seems quite stable for the number of atoms found in a typical protein structure. RETURN : the returned vector is a quaternion of four elements: cos(theta/2), sin(theta/2)*x, sin(theta/2)*y, sin(theta/2)*z), where x,y,z are the direction cosines of the axis of rotation. const ContainerType& v1 v1 is the list of input points for the first (reference) position. ContainerType can be any STL container or other containers (e.g. NearTree) that have a resonable iterator and a size() function. const ContainerType& v2 Like v1, but this is the structure to be rotated onto v1. v2 and v1 must have exactly the same number of points in corresponding positions. Vector_3& centerOfMass1 The returned center of mass of the points in v1. Vector_3& centerOfMass2 The returned center of mass of the points in v2. Matrix_3x3& rotationMatrixFrom2To1 The returned rotation matrix that will rotate v2 onto v1 (as well as possible). double& rmsd The returned root mean square distance between the corresponding points of v1 and v2. const int pairCount pairCount controls the nature of the calculation. If pairCount is zero (the default value), then every pair of atoms (that is in its original and rotated positions) is used with every other pair in the computation (an O(n^2) process). If pairCount is greater than zero, then each is compared with pairCount other pairs. If pairCount is one, then the process is exactly O(n). Larger values have the potential to give more representative output, but preliminary results seem to indicate that for a protein, this would not make much difference. For small molecules, the exhaustive search is probably safer, and is quite fast. For values of pairCount larger than 0, the other pairs are chosen by random selection. FUNCTIONS IN Line_3 Line_3 ( void ); // constructor Line_3 ( const Vector_3& direction, const Vector_3& CenterOfMass ); constructs a Line_3 given a direction of the line and a point on the line Vector_3 LineAxis ( void ) const; returns the direction vector of a Line_3 Vector_3 BasePoint ( void ) const; returns the point on a Line_3 that is closest to the coordinate system origin virtual ~Line_3 ( void ); // destructor double DistanceFromLine ( const Vector_3& v ) const; for a given point, returns the distance of the point from the input line FUNCTIONS IN Plane_3 Plane_3 ( void ); // constructor Plane_3::Plane_3 ( const Vector_3& direction, const Vector_3& CenterOfMass); constructs a plane given a vector perpendicular to the plane and a point in the plane Vector_3 NormalVector ( void ) const; returns the normal to the plane Vector_3 BasePoint ( void ) const; returns the point in the input plane that is closest to the origin virtual ~Plane_3 ( void ); // destructor double DistanceFromPlane ( const Vector_3& v ) const; returns the distance of the input point v from the input plane OTHER FUNCTIONS Matrix_3x3 RandomOrientation( void ) returns a rotation matrix from a well-sampled distribution Vector_3 RandomVector( void ) returns a vector that points in a random direction