Package com.irurueta.algebra

Class Utils

java.lang.Object
com.irurueta.algebra.Utils
public class Utils extends Object
This class contains a series of helper statistics methods that can be used to perform most typical operations in matrix algebra. Note: Depending on the situation it might be more computationally efficient to use methods implemented in Decomposer subclasses.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    DEFAULT_ORTHOGONAL_THRESHOLD
    Constant defining the default threshold to determine whether a matrix is orthonormal or not.
    static final double
    DEFAULT_SYMMETRIC_THRESHOLD
    Constant defining the default threshold to compare the different content of one matrix to check whether is symmetric.
    static final double
    EPSILON
    Constant defining machine precision
    static final double
    MIN_THRESHOLD
    Constant defining minimum allowed threshold

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Utils()
    Constructor.

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    cond(Matrix m)
    Computes condition number of provided matrix.
    static double[]
    crossProduct(double[] v1, double[] v2)
    Computes the cross product of two vectors of length 3 The cross product of two vectors a and b is denoted as 'axb' or 'a^b', resulting in a perpendicular vector to both a and b vectors.
    static void
    crossProduct(double[] v1, double[] v2, double[] result)
    Computes the cross product of two vectors of length 3 The cross product of two vectors a and b is denoted as 'axb' or 'a^b', resulting in a perpendicular vector to both a and b vectors.
    static void
    crossProduct(double[] v1, double[] v2, double[] result, Matrix jacobian1, Matrix jacobian2)
    Computes the cross product of two vectors of length 3 The cross product of two vectors a and b is denoted as 'axb' or 'a^b', resulting in a perpendicular vector to both a and b vectors.
    static double[]
    crossProduct(double[] v1, double[] v2, Matrix jacobian1, Matrix jacobian2)
    Computes the cross product of two vectors of length 3 The cross product of two vectors a and b is denoted as 'axb' or 'a^b', resulting in a perpendicular vector to both a and b vectors.
    static Matrix
    crossProduct(double[] v, Matrix m)
    Computes the cross product of one vector of length 3 and N vectors of length 3.
    static void
    crossProduct(double[] v, Matrix m, Matrix result)
    Computes the cross product of one vector of length 3 and N vectors of length 3.
    static double
    det(Matrix m)
    Computes determinant of provided matrix.
    static double
    dotProduct(double[] firstOperand, double[] secondOperand)
    Computes the dot product of provided arrays as the sum of the product of the elements of both arrays.
    static double
    dotProduct(double[] firstOperand, double[] secondOperand, Matrix jacobianFirst, Matrix jacobianSecond)
    Computes the dot product of provided arrays as the sum of the product of the elements of both arrays.
    static double
    dotProduct(Matrix firstOperand, Matrix secondOperand)
    Computes the dot product of provided matrices, as the sum of the product of the elements on both matrices, assuming that both represent column vectors.
    static double
    dotProduct(Matrix firstOperand, Matrix secondOperand, Matrix jacobianFirst, Matrix jacobianSecond)
    Computes the dot product of provided matrices, as the sum of the product of the elements on both matrices, assuming that both represent column vectors.
    private static void
    internalSkewMatrix(Matrix m, Matrix result, boolean columnwise)
    Internal method to compute skew matrix
    static Matrix
    inverse(double[] array)
    Computes array pseudo-inverse considering it as a column matrix.
    static void
    inverse(double[] array, Matrix result)
    Computes array pseudo-inverse considering it as a column matrix and stores the result in provided result matrix.
    static Matrix
    inverse(Matrix m)
    Computes matrix inverse if provided matrix is squared, or pseudo-inverse otherwise.
    static void
    inverse(Matrix m, Matrix result)
    Computes matrix inverse if provided matrix is squared, or pseudo-inverse otherwise and stores the result in provided result matrix.
    static boolean
    isOrthogonal(Matrix m)
    Checks if the matrix is orthogonal (its transpose is its inverse).
    static boolean
    isOrthogonal(Matrix m, double threshold)
    Checks if the matrix is orthogonal (its transpose is its inverse).
    static boolean
    isOrthonormal(Matrix m)
    Checks if the matrix is orthonormal up to DEFAULT_ORTHOGONAL_THRESHOLD (it is orthogonal and its Frobenius norm is one)
    static boolean
    isOrthonormal(Matrix m, double threshold)
    Checks if the matrix is orthonormal (it is orthogonal and its Frobenius norm is one)
    static boolean
    isSymmetric(Matrix m)
    Check if the matrix is symmetric.
    static boolean
    isSymmetric(Matrix m, double threshold)
    Check if the matrix is symmetric.
    static double
    norm1(double[] array)
    Computes one norm of provided input matrix.
    static double
    norm1(Matrix m)
    Computes one norm of provided input matrix.
    static double
    norm2(double[] array)
    Computes two norm of provided input array.
    static double
    norm2(Matrix m)
    Computes two norm of provided input matrix.
    static double
    normF(double[] array)
    Computes Frobenius norm of provided array.
    static double
    normF(Matrix m)
    Computes Frobenius norm of provided input matrix.
    static double
    normInf(double[] array)
    Computes infinity norm of provided input matrix.
    static double
    normInf(Matrix m)
    Computes infinity norm of provided input matrix.
    static Matrix
    pseudoInverse(double[] array)
    Computes Moore-Penrose pseudo-inverse of provided array considering it as a column matrix.
    static Matrix
    pseudoInverse(Matrix m)
    Computes Moore-Penrose pseudo-inverse of provided matrix.
    static int
    rank(Matrix m)
    Computes rank of provided matrix.
    static void
    schurc(Matrix m, int pos, boolean fromStart, boolean sqrt, Matrix result)
    Computes the Schur complement of a symmetric matrix.
    static void
    schurc(Matrix m, int pos, boolean fromStart, boolean sqrt, Matrix result, Matrix iA)
    Computes the Schur complement of a symmetric matrix.
    static void
    schurc(Matrix m, int pos, boolean fromStart, Matrix result)
    Computes the Schur complement of a symmetric matrix, returning always the full Schur complement.
    static void
    schurc(Matrix m, int pos, boolean fromStart, Matrix result, Matrix iA)
    Computes the Schur complement of a symmetric matrix, returning always the full Schur complement.
    static void
    schurc(Matrix m, int pos, Matrix result)
    Computes the Schur complement of the sub-matrix A within a symmetric matrix, returning always the full Schur complement.
    static void
    schurc(Matrix m, int pos, Matrix result, Matrix iA)
    Computes the Schur complement of the sub-matrix A within a symmetric matrix, returning always the full Schur complement.
    static Matrix
    schurcAndReturnNew(Matrix m, int pos)
    Computes the Schur complement of the sub-matrix A within a symmetric matrix, returning always the full Schur complement.
    static Matrix
    schurcAndReturnNew(Matrix m, int pos, boolean fromStart)
    Computes the Schur complement of a symmetric matrix, returning always the full Schur complement.
    static Matrix
    schurcAndReturnNew(Matrix m, int pos, boolean fromStart, boolean sqrt)
    Computes the Schur complement of a symmetric matrix.
    static Matrix
    schurcAndReturnNew(Matrix m, int pos, boolean fromStart, boolean sqrt, Matrix iA)
    Computes the Schur complement of a symmetric matrix.
    static Matrix
    schurcAndReturnNew(Matrix m, int pos, boolean fromStart, Matrix iA)
    Computes the Schur complement of a symmetric matrix, returning always the full Schur complement.
    static Matrix
    schurcAndReturnNew(Matrix m, int pos, Matrix iA)
    Computes the Schur complement of the sub-matrix A within a symmetric matrix, returning always the full Schur complement.
    static Matrix
    skewMatrix(double[] array)
    Computes the skew-symmetric matrix of provided vector of length 3.
    static void
    skewMatrix(double[] array, Matrix result)
    Computes the skew-symmetric matrix of provided vector of length 3 and stores the result in provided matrix.
    static void
    skewMatrix(double[] array, Matrix result, Matrix jacobian)
    Computes the skew-symmetric matrix of provided vector of length 3 and stores the result in provided matrix.
    static Matrix
    skewMatrix(Matrix m)
    Computes the skew-symmetric matrix of provided matrix of size 3x1 or 13.
    static void
    skewMatrix(Matrix m, Matrix result)
    Computes the skew-symmetric matrix of provided matrix of size 3x1 or 13.
    static void
    skewMatrix(Matrix m, Matrix result, Matrix jacobian)
    Computes the skew-symmetric matrix of provided matrix of size 3x1 or 13.
    static double[]
    solve(Matrix m, double[] b)
    Solves a linear system of equations of the form: m * x = b.
    static void
    solve(Matrix m, double[] b, double[] result)
    Solves a linear system of equations of the form m * x = b, where b is assumed to be the parameters column vector, x is the returned matrix containing the solution and m is the matrix of the linear system of equations.
    static Matrix
    solve(Matrix m, Matrix b)
    Solves a linear system of equations of the form: m * x = b.
    static void
    solve(Matrix m, Matrix b, Matrix result)
    Solves a linear system of equations of the form: m * x = b.
    static double
    trace(Matrix m)
    Computes trace of provided matrix.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT_SYMMETRIC_THRESHOLD

      public static final double DEFAULT_SYMMETRIC_THRESHOLD
      Constant defining the default threshold to compare the different content of one matrix to check whether is symmetric.
      See Also:

    • DEFAULT_ORTHOGONAL_THRESHOLD

      public static final double DEFAULT_ORTHOGONAL_THRESHOLD
      Constant defining the default threshold to determine whether a matrix is orthonormal or not.
      See Also:

    • EPSILON

      public static final double EPSILON
      Constant defining machine precision
      See Also:

    • MIN_THRESHOLD

      public static final double MIN_THRESHOLD
      Constant defining minimum allowed threshold
      See Also:

  • Constructor Details

    • Utils

      private Utils()
      Constructor.

  • Method Details

    • trace

      public static double trace(Matrix m)
      Computes trace of provided matrix. Trace is the sum of the elements located on the diagonal of a given matrix.
      Parameters:
      m - Input matrix.
      Returns:
      Trace of provided matrix

    • cond

      public static double cond(Matrix m) throws DecomposerException
      Computes condition number of provided matrix. Condition number determines how well-behaved a matrix is for solving a linear system of equations
      Parameters:
      m - Input matrix.
      Returns:
      Condition number of provided matrix.
      Throws:
      DecomposerException - Exception thrown if decomposition fails for any reason.
      See Also:

    • rank

      public static int rank(Matrix m) throws DecomposerException
      Computes rank of provided matrix. Rank indicates the number of linearly independent columns or rows on a matrix.
      Parameters:
      m - Input matrix.
      Returns:
      Rank of provided matrix.
      Throws:
      DecomposerException - Exception thrown if decomposition fails for any reason.

    • det

      public static double det(Matrix m) throws WrongSizeException, DecomposerException
      Computes determinant of provided matrix. Determinant can be seen geometrically as a measure of hyper-volume generated by the row/column vector contained within a given squared matrix.
      Parameters:
      m - Input matrix.
      Returns:
      Determinant of provided matrix.
      Throws:
      WrongSizeException - Exception thrown if provided matrix is not squared.
      DecomposerException - Exception thrown if decomposition fails for any reason.

    • solve

      public static void solve(Matrix m, Matrix b, Matrix result) throws WrongSizeException, RankDeficientMatrixException, DecomposerException
      Solves a linear system of equations of the form: m * x = b. Where x is the returned matrix containing the solution, m is the matrix of the linear system of equations and b is the parameters matrix.
      Parameters:
      m - Matrix of the linear system of equations.
      b - Parameters matrix.
      result - Matrix where solution of the linear system of equations will be stored. Provided matrix will be resized if needed
      Throws:
      WrongSizeException - Exception thrown if provided matrix m has less rows than columns, or if provided matrix b has a number of rows different from the number of rows of m.
      RankDeficientMatrixException - Exception thrown if provided matrix m is rank deficient.
      DecomposerException - Exception thrown if decomposition fails for any reason.

    • solve

      public static Matrix solve(Matrix m, Matrix b) throws WrongSizeException, RankDeficientMatrixException, DecomposerException
      Solves a linear system of equations of the form: m * x = b. Where x is the returned matrix containing the solution, m is the matrix of the linear system of equations and b is the parameter matrix.
      Parameters:
      m - Matrix of the linear system of equations.
      b - Parameters matrix.
      Returns:
      Solution of the linear system of equations.
      Throws:
      WrongSizeException - Exception thrown if provided matrix m has fewer rows than columns, or if provided matrix b has a number of rows different from the number of rows of m.
      RankDeficientMatrixException - Exception thrown if provided matrix m is rank deficient.
      DecomposerException - Exception thrown if decomposition fails for any reason.

    • solve

      public static void solve(Matrix m, double[] b, double[] result) throws DecomposerException
      Solves a linear system of equations of the form m * x = b, where b is assumed to be the parameters column vector, x is the returned matrix containing the solution and m is the matrix of the linear system of equations.
      Parameters:
      m - Matrix of the linear system of equations.
      b - Parameters column vector.
      result - Solution of the linear system of equations. m is rank deficient.
      Throws:
      DecomposerException - Exception thrown if decomposition fails for any reason.

    • solve

      public static double[] solve(Matrix m, double[] b) throws DecomposerException
      Solves a linear system of equations of the form: m * x = b. Where x is the returned array containing the solution, m is the matrix of the linear system of equations and b is the parameters array.
      Parameters:
      m - Matrix of the linear system of equations.
      b - Parameters array.
      Returns:
      Solution of the linear system of equations. m is rank deficient.
      Throws:
      DecomposerException - Exception thrown if decomposition fails for any reason.

    • normF

      public static double normF(Matrix m)
      Computes Frobenius norm of provided input matrix.
      Parameters:
      m - Input matrix.
      Returns:
      Frobenius norm

    • normF

      public static double normF(double[] array)
      Computes Frobenius norm of provided array.
      Parameters:
      array - Input array.
      Returns:
      Frobenius norm.

    • normInf

      public static double normInf(Matrix m)
      Computes infinity norm of provided input matrix.
      Parameters:
      m - Input matrix.
      Returns:
      Infinity norm.

    • normInf

      public static double normInf(double[] array)
      Computes infinity norm of provided input matrix.
      Parameters:
      array - Input array.
      Returns:
      Infinity norm.

    • norm2

      public static double norm2(Matrix m) throws DecomposerException
      Computes two norm of provided input matrix.
      Parameters:
      m - Input matrix.
      Returns:
      Two norm.
      Throws:
      DecomposerException - Exception thrown if decomposition fails for any reason.

    • norm2

      public static double norm2(double[] array) throws DecomposerException
      Computes two norm of provided input array.
      Parameters:
      array - Input array.
      Returns:
      Two norm
      Throws:
      DecomposerException - Exception thrown if decomposition fails for any reason.

    • norm1

      public static double norm1(Matrix m)
      Computes one norm of provided input matrix.
      Parameters:
      m - Input matrix.
      Returns:
      One norm.

    • norm1

      public static double norm1(double[] array)
      Computes one norm of provided input matrix.
      Parameters:
      array - Input array.
      Returns:
      One norm.

    • inverse

      public static void inverse(Matrix m, Matrix result) throws WrongSizeException, RankDeficientMatrixException, DecomposerException
      Computes matrix inverse if provided matrix is squared, or pseudo-inverse otherwise and stores the result in provided result matrix. Result matrix will be resized if needed
      Parameters:
      m - Matrix to be inverted.
      result - Matrix where matrix inverse is stored.
      Throws:
      WrongSizeException - Exception thrown if provided matrix m has less rows than columns.
      RankDeficientMatrixException - Exception thrown if provided matrix m is rank deficient.
      DecomposerException - Exception thrown if decomposition to compute inverse fails for any other reason.

    • inverse

      public static Matrix inverse(Matrix m) throws WrongSizeException, RankDeficientMatrixException, DecomposerException
      Computes matrix inverse if provided matrix is squared, or pseudo-inverse otherwise.
      Parameters:
      m - Matrix to be inverted.
      Returns:
      Matrix inverse.
      Throws:
      WrongSizeException - Exception thrown if provided matrix m has less rows than columns.
      RankDeficientMatrixException - Exception thrown if provided matrix m is rank deficient.
      DecomposerException - Exception thrown if decomposition to compute inverse fails for any other reason.

    • inverse

      public static void inverse(double[] array, Matrix result) throws WrongSizeException, RankDeficientMatrixException, DecomposerException
      Computes array pseudo-inverse considering it as a column matrix and stores the result in provided result matrix. Result matrix will be resized if needed
      Parameters:
      array - array to be inverted
      result - Array pseudo inverse
      Throws:
      WrongSizeException - never thrown
      RankDeficientMatrixException - Exception thrown if provided array is rank deficient.
      DecomposerException - Exception thrown if decomposition to compute inverse fails for any other reason.

    • inverse

      public static Matrix inverse(double[] array) throws WrongSizeException, RankDeficientMatrixException, DecomposerException
      Computes array pseudo-inverse considering it as a column matrix.
      Parameters:
      array - array to be inverted
      Returns:
      Array pseudo inverse
      Throws:
      WrongSizeException - never thrown
      RankDeficientMatrixException - Exception thrown if provided array is rank deficient.
      DecomposerException - Exception thrown if decomposition to compute inverse fails for any other reason.

    • pseudoInverse

      public static Matrix pseudoInverse(Matrix m) throws DecomposerException
      Computes Moore-Penrose pseudo-inverse of provided matrix. Moore-Penrose pseudo-inverse always exists for any matrix regardless of its size, and can be computed as: pinv(A) = inv(A'*A)*A' in Matlab notation. However, for computation efficiency, Singular Value Decomposition is used instead, obtaining the following expression: pinv(A) = V * pinv(W) * U'. Where W is easily invertible since it is a diagonal matrix taking into account that the inverse for singular values close to zero (for a given tolerance) is zero, whereas for the rest is their reciprocal. In other words pinv(W)(i,i) = 1./W(i,i) for W(i,i) != 0 or zero otherwise. Notice that for invertible squared matrices, the pseudo-inverse is equal to the inverse. Also notice that pseudo-inverse can be used to solve overdetermined systems of linear equations with least minimum square error (LMSE). Finally, notice that Utils.inverse(Matrix) also can return a pseudo-inverse, however, this method since it uses SVD decomposition is numerically more stable at the expense of being computationally more expensive.
      Parameters:
      m - Input matrix.
      Returns:
      Moore-Penrose matrix pseudo-inverse.
      Throws:
      DecomposerException - Exception thrown if matrix cannot be inverted, usually because matrix contains numerically unstable values such as NaN or inf.
      See Also:

    • pseudoInverse

      public static Matrix pseudoInverse(double[] array) throws DecomposerException
      Computes Moore-Penrose pseudo-inverse of provided array considering it as a column matrix.
      Parameters:
      array - Input array
      Returns:
      More-Penrose pseudo-inverse
      Throws:
      DecomposerException - Exception thrown if matrix cannot be inverted, usually because matrix contains numerically unstable values such as NaN or inf.
      See Also:

    • skewMatrix

      public static void skewMatrix(double[] array, Matrix result) throws WrongSizeException
      Computes the skew-symmetric matrix of provided vector of length 3 and stores the result in provided matrix. Skew-symmetric matrices are specially useful if several cross-products need to be done for the same first vector over different vectors. That is, having a vector a and vectors b1...bn of size 3x1: c1 = a x b1 c2 = a x b2 ... cn = a x bn Instead of computing each product separately, the second factor can be converted in a matrix where each row contains one of the vectors on the second factor: B = [b1, b2, ..., bn]; And all the cross products shown above can be computed as a single matrix multiplication in the form: C = skewMatrix(a) * B;
      Parameters:
      array - Array of length 3 that will be used to compute the skew-symmetric matrix.
      result - Matrix where skew matrix is stored. Provided matrix will be resized if needed
      Throws:
      WrongSizeException - Exception thrown if provided array doesn't have length equal to 3.

    • skewMatrix

      public static void skewMatrix(double[] array, Matrix result, Matrix jacobian) throws WrongSizeException
      Computes the skew-symmetric matrix of provided vector of length 3 and stores the result in provided matrix. If provided, jacobian is also set. Skew-symmetric matrices are specially useful if several cross-products need to be done for the same first vector over different vectors. That is, having a vector a and vectors b1...bn of size 3x1: c1 = a x b1 c2 = a x b2 ... cn = a x bn Instead of computing each product separately, the second factor can be converted in a matrix where each row contains one of the vectors on the second factor: B = [b1, b2, ..., bn]; And all the cross products shown above can be computed as a single matrix multiplication in the form: C = skewMatrix(a) * B;
      Parameters:
      array - Array of length 3 that will be used to compute the skew-symmetric matrix.
      result - Matrix where skew matrix is stored. Provided matrix will be resized if needed
      jacobian - matrix where jacobian will be stored. Must be 9x3.
      Throws:
      WrongSizeException - if provided array doesn't have length 3 or if jacobian is not 9x3 (if provided).

    • skewMatrix

      public static Matrix skewMatrix(double[] array) throws WrongSizeException
      Computes the skew-symmetric matrix of provided vector of length 3. Skew-symmetric matrices are specially useful if several cross-products need to be done for the same first vector over different vectors. That is, having a vector a and vectors b1...bn of size 3x1: c1 = a x b1 c2 = a x b2 ... cn = a x bn Instead of computing each product separately, the second factor can be converted in a matrix where each row contains one of the vectors on the second factor: B = [b1, b2, ..., bn]; And all the cross products shown above can be computed as a single matrix multiplication in the form: C = skewMatrix(a) * B;
      Parameters:
      array - Array of length 3 that will be used to compute the skew-symmetric matrix.
      Returns:
      Skew matrix.
      Throws:
      WrongSizeException - Exception thrown if provided array doesn't have length equal to 3.

    • internalSkewMatrix

      private static void internalSkewMatrix(Matrix m, Matrix result, boolean columnwise) throws WrongSizeException
      Internal method to compute skew matrix
      Parameters:
      m - Matrix of size 3x1 or 1x3 that will be used to compute the skew-symmetric matrix.
      result - Matrix where skew matrix is stored
      columnwise - boolean indicating whether m is column-wise
      Throws:
      WrongSizeException - Exception thrown if provided m matrix doesn't have proper size

    • skewMatrix

      public static void skewMatrix(Matrix m, Matrix result) throws WrongSizeException
      Computes the skew-symmetric matrix of provided matrix of size 3x1 or 13. Skew-symmetric matrices are specially useful if several cross-products need to be done for the same first vector over different vectors. That is, having a vector a and vectors b1...bn of size 3x1: c1 = a x b1 c2 = a x b2 ... cn = a x bn Instead of computing each product separately, the second factor can be converted in a matrix where each row contains one of the vectors on the second factor: B = [b1, b2, ..., bn]; And all the cross products shown above can be computed as a single matrix multiplication in the form: C = skewMatrix(a) * B; Result is stored into provided result matrix, which will be resized if needed
      Parameters:
      m - Matrix of size 3x1 or 1x3 that will be used to compute the skew-symmetric matrix.
      result - Matrix where skew matrix will be stored.
      Throws:
      WrongSizeException - Exception thrown if provided matrix is not 3x1 or 1x3.

    • skewMatrix

      public static void skewMatrix(Matrix m, Matrix result, Matrix jacobian) throws WrongSizeException
      Computes the skew-symmetric matrix of provided matrix of size 3x1 or 13. If provided, jacobian is also set. Skew-symmetric matrices are specially useful if several cross-products need to be done for the same first vector over different vectors. That is, having a vector a and vectors b1...bn of size 3x1: c1 = a x b1 c2 = a x b2 ... cn = a x bn Instead of computing each product separately, the second factor can be converted in a matrix where each row contains one of the vectors on the second factor: B = [b1, b2, ..., bn]; And all the cross products shown above can be computed as a single matrix multiplication in the form: C = skewMatrix(a) * B; Result is stored into provided result matrix, which will be resized if needed
      Parameters:
      m - Matrix of size 3x1 or 1x3 that will be used to compute the skew-symmetric matrix.
      result - Matrix where skew matrix will be stored.
      jacobian - matrix where jacobian will be stored. Must be 9x3.
      Throws:
      WrongSizeException - if provided matrix is not 3x1 or 1x3 or if jacobian is not 9x3 (if provided).

    • skewMatrix

      public static Matrix skewMatrix(Matrix m) throws WrongSizeException
      Computes the skew-symmetric matrix of provided matrix of size 3x1 or 13. Skew-symmetric matrices are specially useful if several cross-products need to be done for the same first vector over different vectors. That is, having a vector a and vectors b1...bn of size 3x1: c1 = a x b1 c2 = a x b2 ... cn = a x bn Instead of computing each product separately, the second factor can be converted in a matrix where each row contains one of the vectors on the second factor: B = [b1, b2, ..., bn]; And all the cross products shown above can be computed as a single matrix multiplication in the form: C = skewMatrix(a) * B;
      Parameters:
      m - Matrix of size 3x1 or 1x3 that will be used to compute the skew-symmetric matrix.
      Returns:
      Skew matrix.
      Throws:
      WrongSizeException - Exception thrown if provided array doesn't have length equal to 3.

    • crossProduct

      public static void crossProduct(double[] v1, double[] v2, double[] result, Matrix jacobian1, Matrix jacobian2) throws WrongSizeException
      Computes the cross product of two vectors of length 3 The cross product of two vectors a and b is denoted as 'axb' or 'a^b', resulting in a perpendicular vector to both a and b vectors. This implies the following relation: c·a = 0 c·b = 0 A cross product can be calculated as the determinant of this matrix |i j k | |a0 a1 a2| |b0 b1 b2| Resulting: a x b = (a1b2 - a2b1) i + (a2b0 - a0b2) j + (a0b1 - a1b0) k = = (a1b2 - a2b1, a2b0 - a0b2, a0b1 - a1b0) This implementation does not use the determinant to compute the cross product. A symmetric-skew matrix will be computed and used instead.
      Parameters:
      v1 - Left vector in the crossProduct operation (A in axb)
      v2 - Right vector in the crossProduct operation (b in axb)
      result - array where the cross product of vectors v1 and b2 will be stored.
      jacobian1 - jacobian of v1. Must be 3x3.
      jacobian2 - jacobian of v2. Must be 3x3.
      Throws:
      WrongSizeException - Exception thrown if provided vectors don't have length 3, or if jacobians are not 3x3.
      See Also:

    • crossProduct

      public static void crossProduct(double[] v1, double[] v2, double[] result) throws WrongSizeException
      Computes the cross product of two vectors of length 3 The cross product of two vectors a and b is denoted as 'axb' or 'a^b', resulting in a perpendicular vector to both a and b vectors. This implies the following relation: c·a = 0 c·b = 0 A cross product can be calculated as the determinant of this matrix |i j k | |a0 a1 a2| |b0 b1 b2| Resulting: a x b = (a1b2 - a2b1) i + (a2b0 - a0b2) j + (a0b1 - a1b0) k = = (a1b2 - a2b1, a2b0 - a0b2, a0b1 - a1b0) This implementation does not use the determinant to compute the cross product. A symmetric-skew matrix will be computed and used instead.
      Parameters:
      v1 - Left vector in the crossProduct operation (A in axb)
      v2 - Right vector in the crossProduct operation (b in axb)
      result - array where the cross product of vectors v1 and b2 will be stored.
      Throws:
      WrongSizeException - Exception thrown if provided vectors don't have length 3.
      See Also:

    • crossProduct

      public static double[] crossProduct(double[] v1, double[] v2) throws WrongSizeException
      Computes the cross product of two vectors of length 3 The cross product of two vectors a and b is denoted as 'axb' or 'a^b', resulting in a perpendicular vector to both a and b vectors. This implies the following relation: c·a = 0 c·b = 0 A cross product can be calculated as the determinant of this matrix |i j k | |a0 a1 a2| |b0 b1 b2| Resulting: a x b = (a1b2 - a2b1) i + (a2b0 - a0b2) j + (a0b1 - a1b0) k = = (a1b2 - a2b1, a2b0 - a0b2, a0b1 - a1b0) This implementation does not use the determinant to compute the cross product. A symmetric-skew matrix will be computed and used instead.
      Parameters:
      v1 - Left vector in the crossProduct operation (A in axb)
      v2 - Right vector in the crossProduct operation (b in axb)
      Returns:
      Vector containing the cross product of vectors v1 and b2.
      Throws:
      WrongSizeException - Exception thrown if provided vectors don't have length 3.
      See Also:

    • crossProduct

      public static double[] crossProduct(double[] v1, double[] v2, Matrix jacobian1, Matrix jacobian2) throws WrongSizeException
      Computes the cross product of two vectors of length 3 The cross product of two vectors a and b is denoted as 'axb' or 'a^b', resulting in a perpendicular vector to both a and b vectors. This implies the following relation: c·a = 0 c·b = 0 A cross product can be calculated as the determinant of this matrix |i j k | |a0 a1 a2| |b0 b1 b2| Resulting: a x b = (a1b2 - a2b1) i + (a2b0 - a0b2) j + (a0b1 - a1b0) k = = (a1b2 - a2b1, a2b0 - a0b2, a0b1 - a1b0) This implementation does not use the determinant to compute the cross product. A symmetric-skew matrix will be computed and used instead.
      Parameters:
      v1 - Left vector in the crossProduct operation (A in axb)
      v2 - Right vector in the crossProduct operation (b in axb)
      jacobian1 - jacobian of v1. Must be 3x3.
      jacobian2 - jacobian of v2. Must be 3x3.
      Returns:
      Vector containing the cross product of vectors v1 and b2.
      Throws:
      WrongSizeException - Exception thrown if provided vectors don't have length 3, or if jacobians are not 3x3.

    • crossProduct

      public static void crossProduct(double[] v, Matrix m, Matrix result) throws WrongSizeException
      Computes the cross product of one vector of length 3 and N vectors of length 3. The cross product of two vectors a and b is denoted as 'axb' or 'a^b', resulting in a perpendicular vector to both a and b vectors. This implies the following relation: c·a = 0 c·b = 0 A cross product can be calculated as the determinant of this matrix |i j k | |a0 a1 a2| |b0 b1 b2| Resulting: a x b = (a1b2 - a2b1) i + (a2b0 - a0b2) j + (a0b1 - a1b0) k = = (a1b2 - a2b1, a2b0 - a0b2, a0b1 - a1b0) This implementation does not use the determinant to compute the cross product. A symmetric-skew matrix will be computed and used instead. The result is stored into provided result matrix, which will be resized if needed
      Parameters:
      v - Left operand in crossProduct operation
      m - Right operand in crossProduct operation, matrix containing a vector in every row.
      result - Matrix where the cross products of vector v and the vectors contained in matrix m will be stored.
      Throws:
      WrongSizeException - Exception thrown if provided vectors don't have length 3 or if number of rows of provided matrix isn't 3.
      See Also:

    • crossProduct

      public static Matrix crossProduct(double[] v, Matrix m) throws WrongSizeException
      Computes the cross product of one vector of length 3 and N vectors of length 3. The cross product of two vectors a and b is denoted as 'axb' or 'a^b', resulting in a perpendicular vector to both a and b vectors. This implies the following relation: c·a = 0 c·b = 0 A cross product can be calculated as the determinant of this matrix |i j k | |a0 a1 a2| |b0 b1 b2| Resulting: a x b = (a1b2 - a2b1) i + (a2b0 - a0b2) j + (a0b1 - a1b0) k = = (a1b2 - a2b1, a2b0 - a0b2, a0b1 - a1b0) This implementation does not use the determinant to compute the cross product. A symmetric-skew matrix will be computed and used instead.
      Parameters:
      v - Left operand in crossProduct operation
      m - Right operand in crossProduct operation, matrix containing a vector in every row.
      Returns:
      Matrix containing the cross products of vector v and the vectors contained in matrix m.
      Throws:
      WrongSizeException - Exception thrown if provided vectors don't have length 3 or if number of rows of provided matrix isn't 3.
      See Also:

    • isSymmetric

      public static boolean isSymmetric(Matrix m, double threshold)
      Check if the matrix is symmetric.
      Parameters:
      m - Input matrix.
      threshold - Threshold value to determine if a matrix is symmetric. This value is typically zero or close to zero.
      Returns:
      Boolean relation whether the matrix is symmetric or not.
      Throws:
      IllegalArgumentException - Raised if provided threshold is negative

    • isSymmetric

      public static boolean isSymmetric(Matrix m)
      Check if the matrix is symmetric. DEFAULT_SYMMETRIC_THRESHOLD is used as threshold.
      Parameters:
      m - Input matrix.
      Returns:
      Boolean relation whether the matrix is symmetric or not.

    • isOrthogonal

      public static boolean isOrthogonal(Matrix m, double threshold)
      Checks if the matrix is orthogonal (its transpose is its inverse). Orthogonal matrices must be square and non-singular
      Parameters:
      m - Input matrix
      threshold - Threshold value to determine if a matrix is orthogonal. This value is typically zero or close to zero.
      Returns:
      True if matrix is orthogonal, false otherwise.
      Throws:
      IllegalArgumentException - Raised if provided threshold is negative

    • isOrthogonal

      public static boolean isOrthogonal(Matrix m)
      Checks if the matrix is orthogonal (its transpose is its inverse). DEFAULT_ORTHOGONAL_THRESHOLD is used as threshold. Orthogonal matrices must be square and non-singular
      Parameters:
      m - Input matrix.
      Returns:
      True if matrix is orthogonal, false otherwise.

    • isOrthonormal

      public static boolean isOrthonormal(Matrix m, double threshold)
      Checks if the matrix is orthonormal (it is orthogonal and its Frobenius norm is one)
      Parameters:
      m - Input matrix
      threshold - Threshold value to determine if a matrix is orthonormal. This value is typically zero or close to zero.
      Returns:
      True if matrix is orthonormal, false otherwise.
      Throws:
      IllegalArgumentException - Raised if provided threshold is negative

    • isOrthonormal

      public static boolean isOrthonormal(Matrix m)
      Checks if the matrix is orthonormal up to DEFAULT_ORTHOGONAL_THRESHOLD (it is orthogonal and its Frobenius norm is one)
      Parameters:
      m - Input matrix
      Returns:
      True if matrix is orthonormal, false otherwise.

    • dotProduct

      public static double dotProduct(double[] firstOperand, double[] secondOperand)
      Computes the dot product of provided arrays as the sum of the product of the elements of both arrays.
      Parameters:
      firstOperand - first operand.
      secondOperand - second operand.
      Returns:
      dot product.
      Throws:
      IllegalArgumentException - if first and second operands arrays don't have the same length.

    • dotProduct

      public static double dotProduct(double[] firstOperand, double[] secondOperand, Matrix jacobianFirst, Matrix jacobianSecond)
      Computes the dot product of provided arrays as the sum of the product of the elements of both arrays.
      Parameters:
      firstOperand - first operand.
      secondOperand - second operand.
      jacobianFirst - matrix where jacobian of first operand will be stored. Must be a column matrix having the same number of rows as the first operand length.
      jacobianSecond - matrix where jacobian of second operand will be stored. Must be a column matrix having the same number of rows as the second operand length.
      Returns:
      dot product.
      Throws:
      IllegalArgumentException - if first and second operands don't have the same length or if jacobian matrices are not column vectors having the same length as their respective operands.

    • dotProduct

      public static double dotProduct(Matrix firstOperand, Matrix secondOperand) throws WrongSizeException
      Computes the dot product of provided matrices, as the sum of the product of the elements on both matrices, assuming that both represent column vectors.
      Parameters:
      firstOperand - first operand.
      secondOperand - second operand.
      Returns:
      dot product.
      Throws:
      WrongSizeException - if first operand columns are not equal to second operand rows, or if first operand rows is not one, or if second operand columns is not one.

    • dotProduct

      public static double dotProduct(Matrix firstOperand, Matrix secondOperand, Matrix jacobianFirst, Matrix jacobianSecond) throws WrongSizeException
      Computes the dot product of provided matrices, as the sum of the product of the elements on both matrices, assuming that both represent column vectors.
      Parameters:
      firstOperand - first operand. Must be 1xN.
      secondOperand - second operand. Must be Nx1.
      jacobianFirst - matrix where jacobian of first operand will be stored. Must be a column matrix having the same number of rows as the first operand length. Must be Nx1.
      jacobianSecond - matrix where jacobian of second operand will be stored. Must be a column matrix having the same number of rows as the second operand length. Must be Nx1.
      Returns:
      dot product.
      Throws:
      WrongSizeException - if first operand columns are not equal to second operand rows, or if first operand rows is not one, or if second operand columns is not one.
      IllegalArgumentException - if jacobian matrices are not column vectors having the same length as their respective operands.

    • schurc

      public static void schurc(Matrix m, int pos, boolean fromStart, boolean sqrt, Matrix result, Matrix iA) throws DecomposerException, RankDeficientMatrixException
      Computes the Schur complement of a symmetric matrix. For a matrix M of size sxs having the typical partition M = [A B ; B' C] where A is posxpos, B is posx(s - pos) and C is (s-pos)x(s-pos) Then pos indicates the position that delimits the separation between these sub-matrices in the diagonal. If fromStart is true, then Schur complement of A is computed and result will have size (s-pos)x(s-pos). If fromStart is false, then Schur complement of C is computed and result will have size posxpos.

      Definitions and rationale: If M is a symmetrical matrix partitioned as: M = [M_11 M_12 ; M_12' M_22] then the Schur complement of M_11 is S = M_22 - M_12 ¡ * M_11^-1 * M_12 The optionally returned inverse block is just iA = M_11^-1 whose name comes from 'inverse of A', A given by the popular partition of M = [A B ; B' C], therefore A = M_11. If M is symmetrical and positive, then using the Cholesky decomposition M = [R_11' 0 ; R_12' R_22] * [R_11 R_12 ; 0 R_22] leads to S = R_22' * R_22 iA = (R_11' * R_11)^-1 = R_11^-1 * R_11^-T which constitutes and efficient and stable way to compute the Schur complement. The square root factors R_22 and R_11^_1 can be obtained by setting the optional flag sqrt. The Schur complement has applications for solving linear equations, and applications to probability theory to compute conditional covariances.

      Parameters:
      m - matrix to compute the Schur complement from
      pos - position to delimit the Schur complement.
      fromStart - true to compute Schur complement of A, false to compute Schur complement of C.
      sqrt - true to return the square root of the Schur complement, which is an upper triangular matrix, false to return the full Schur complement, which is S'*S.
      result - instance where the Schur complement will be stored. If needed this instance will be resized.
      iA - instance where the inverse block will be stored, if provided.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      RankDeficientMatrixException - if iA matrix is singular or numerically unstable.
      See Also:

    • schurc

      public static void schurc(Matrix m, int pos, boolean fromStart, Matrix result, Matrix iA) throws DecomposerException, RankDeficientMatrixException
      Computes the Schur complement of a symmetric matrix, returning always the full Schur complement.
      Parameters:
      m - matrix to compute the Schur complement from
      pos - position to delimit the Schur complement.
      fromStart - true to compute Schur complement of A, false to compute Schur complement of C.
      result - instance where the Schur complement will be stored. If needed this instance will be resized.
      iA - instance where the inverse block will be stored, if provided.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      RankDeficientMatrixException - if iA matrix is singular or numerically unstable.
      See Also:

    • schurc

      public static void schurc(Matrix m, int pos, Matrix result, Matrix iA) throws DecomposerException, RankDeficientMatrixException
      Computes the Schur complement of the sub-matrix A within a symmetric matrix, returning always the full Schur complement.
      Parameters:
      m - matrix to compute the Schur complement from
      pos - position to delimit the Schur complement.
      result - instance where the Schur complement will be stored. If needed this instance will be resized.
      iA - instance where the inverse block will be stored, if provided.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      RankDeficientMatrixException - if iA matrix is singular or numerically unstable.
      See Also:

    • schurcAndReturnNew

      public static Matrix schurcAndReturnNew(Matrix m, int pos, boolean fromStart, boolean sqrt, Matrix iA) throws DecomposerException, RankDeficientMatrixException
      Computes the Schur complement of a symmetric matrix.
      Parameters:
      m - matrix to compute the Schur complement from.
      pos - position to delimit the Schur complement.
      fromStart - true to compute Schur complement of A, false to compute Schur complement of C.
      sqrt - true to return the square root of the Schur complement, which is an upper triangular matrix, false to return the full Schur complement, which is S'*S.
      iA - instance where the inverse block will be stored, if provided.
      Returns:
      a new matrix containing the Schur complement.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      RankDeficientMatrixException - if iA matrix is singular or numerically unstable.
      See Also:

    • schurcAndReturnNew

      public static Matrix schurcAndReturnNew(Matrix m, int pos, boolean fromStart, Matrix iA) throws DecomposerException, RankDeficientMatrixException
      Computes the Schur complement of a symmetric matrix, returning always the full Schur complement.
      Parameters:
      m - matrix to compute the Schur complement from
      pos - position to delimit the Schur complement.
      fromStart - true to compute Schur complement of A, false to compute Schur complement of C.
      iA - instance where the inverse block will be stored, if provided.
      Returns:
      a new matrix containing the Schur complement.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      RankDeficientMatrixException - if iA matrix is singular or numerically unstable.
      See Also:

    • schurcAndReturnNew

      public static Matrix schurcAndReturnNew(Matrix m, int pos, Matrix iA) throws DecomposerException, RankDeficientMatrixException
      Computes the Schur complement of the sub-matrix A within a symmetric matrix, returning always the full Schur complement.
      Parameters:
      m - matrix to compute the Schur complement from
      pos - position to delimit the Schur complement.
      iA - instance where the inverse block will be stored, if provided.
      Returns:
      a new matrix containing the Schur complement.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      RankDeficientMatrixException - if iA matrix is singular or numerically unstable.
      See Also:

    • schurc

      public static void schurc(Matrix m, int pos, boolean fromStart, boolean sqrt, Matrix result) throws DecomposerException
      Computes the Schur complement of a symmetric matrix.
      Parameters:
      m - matrix to compute the Schur complement from.
      pos - position to delimit the Schur complement.
      fromStart - true to compute Schur complement of A, false to compute Schur complement of C.
      sqrt - true to return the square root of the Schur complement, which is an upper triangular matrix, false to return the full Schur complement, which is S'*S.
      result - instance where the Schur complement will be stored. If needed this instance will be resized.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      See Also:

    • schurc

      public static void schurc(Matrix m, int pos, boolean fromStart, Matrix result) throws DecomposerException
      Computes the Schur complement of a symmetric matrix, returning always the full Schur complement.
      Parameters:
      m - matrix to compute the Schur complement from
      pos - position to delimit the Schur complement.
      fromStart - true to compute Schur complement of A, false to compute Schur complement of C.
      result - instance where the Schur complement will be stored. If needed this instance will be resized.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      See Also:

    • schurc

      public static void schurc(Matrix m, int pos, Matrix result) throws DecomposerException
      Computes the Schur complement of the sub-matrix A within a symmetric matrix, returning always the full Schur complement.
      Parameters:
      m - matrix to compute the Schur complement from
      pos - position to delimit the Schur complement.
      result - instance where the Schur complement will be stored. If needed this instance will be resized.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      See Also:

    • schurcAndReturnNew

      public static Matrix schurcAndReturnNew(Matrix m, int pos, boolean fromStart, boolean sqrt) throws DecomposerException
      Computes the Schur complement of a symmetric matrix.
      Parameters:
      m - matrix to compute the Schur complement from.
      pos - position to delimit the Schur complement.
      fromStart - true to compute Schur complement of A, false to compute Schur complement of C.
      sqrt - true to return the square root of the Schur complement, which is an upper triangular matrix, false to return the full Schur complement, which is S'*S.
      Returns:
      a new matrix containing the Schur complement.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      See Also:

    • schurcAndReturnNew

      public static Matrix schurcAndReturnNew(Matrix m, int pos, boolean fromStart) throws DecomposerException
      Computes the Schur complement of a symmetric matrix, returning always the full Schur complement.
      Parameters:
      m - matrix to compute the Schur complement from
      pos - position to delimit the Schur complement.
      fromStart - true to compute Schur complement of A, false to compute Schur complement of C.
      Returns:
      a new matrix containing the Schur complement.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      See Also:

    • schurcAndReturnNew

      public static Matrix schurcAndReturnNew(Matrix m, int pos) throws DecomposerException
      Computes the Schur complement of the sub-matrix A within a symmetric matrix, returning always the full Schur complement.
      Parameters:
      m - matrix to compute the Schur complement from
      pos - position to delimit the Schur complement.
      Returns:
      a new matrix containing the Schur complement.
      Throws:
      IllegalArgumentException - if m is not square, pos is greater or equal than matrix size, or pos is zero.
      DecomposerException - if m is numerically unstable.
      See Also: