Get Vector at SourceForge.net. Fast, secure and Free Open Source software downloads

Vector

Release 0.1.3
1 December 2009
© Copyright 1973, 2009 Larry Andrews. All rights reserved

YOU MAY REDISTRIBUTE Vector UNDER THE TERMS OF THE LGPL

LGPL NOTICES

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.


Contents



Installation

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_BestRotation
                                    const 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





Updated 1 December 2009