cern.colt.matrix.linalg

## Interface Blas

- All Known Implementing Classes:
    SeqBlas, SmpBlas

      public interface Blas

  Subset of the BLAS (Basic Linear Algebra System); High quality "building block" routines for performing basic vector and matrix operations. Because the BLAS are efficient, portable, and widely available, they're commonly used in the development of high quality linear algebra software.

  Mostly for compatibility with legacy notations. Most operations actually just delegate to the appropriate methods directly defined on matrices and vectors.

  This class implements the BLAS functions for operations on matrices from the matrix package. It follows the spirit of the Draft Proposal for Java BLAS Interface, by Roldan Pozo of the National Institute of Standards and Technology. Interface definitions are also identical to the Ninja interface. Because the matrix package supports sections, the interface is actually simpler.

  Currently, the following operations are supported:

  1. BLAS Level 1: Vector-Vector operations
  - ddot : dot product of two vectors
  - daxpy : scalar times a vector plus a vector
  - drotg : construct a Givens plane rotation
  - drot : apply a plane rotation
  - dcopy : copy vector X into vector Y
  - dswap : interchange vectors X and Y
  - dnrm2 : Euclidean norm of a vector
  - dasum : sum of absolute values of vector components
  - dscal : scale a vector by a scalar
  - idamax: index of element with maximum absolute value
  2. 2.BLAS Level 2: Matrix-Vector operations
  - dgemv : matrix-vector multiply with general matrix
  - dger : rank-1 update on general matrix
  - dsymv : matrix-vector multiply with symmetric matrix
  - dtrmv : matrix-vector multiply with triangular matrix
  3. 3.BLAS Level 3: Matrix-Matrix operations
     - dgemm : matrix-matrix multiply with general matrices
  Version:
    0.9, 16/04/2000

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `assign(DoubleMatrix2D A, DoubleFunction function)` Assigns the result of a function to each cell; `x[row,col] = function(x[row,col])`.
    `void` | `assign(DoubleMatrix2D x, DoubleMatrix2D y, DoubleDoubleFunction function)` Assigns the result of a function to each cell; `x[row,col] = function(x[row,col],y[row,col])`.
    `double` | `dasum(DoubleMatrix1D x)` Returns the sum of absolute values; `|x[0]| + |x[1]| + ...`
    `void` | `daxpy(double alpha, DoubleMatrix1D x, DoubleMatrix1D y)` Combined vector scaling; `y = y + alpha*x`.
    `void` | `daxpy(double alpha, DoubleMatrix2D A, DoubleMatrix2D B)` Combined matrix scaling; `B = B + alpha*A`.
    `void` | `dcopy(DoubleMatrix1D x, DoubleMatrix1D y)` Vector assignment (copying); `y = x`.
    `void` | `dcopy(DoubleMatrix2D A, DoubleMatrix2D B)` Matrix assignment (copying); `B = A`.
    `double` | `ddot(DoubleMatrix1D x, DoubleMatrix1D y)` Returns the dot product of two vectors x and y, which is `Sum(x[i]*y[i])`.
    `void` | `dgemm(boolean transposeA, boolean transposeB, double alpha, DoubleMatrix2D A, DoubleMatrix2D B, double beta, DoubleMatrix2D C)` Generalized linear algebraic matrix-matrix multiply; `C = alpha*A*B + beta*C`.
    `void` | `dgemv(boolean transposeA, double alpha, DoubleMatrix2D A, DoubleMatrix1D x, double beta, DoubleMatrix1D y)` Generalized linear algebraic matrix-vector multiply; `y = alpha*A*x + beta*y`.
    `void` | `dger(double alpha, DoubleMatrix1D x, DoubleMatrix1D y, DoubleMatrix2D A)` Performs a rank 1 update; `A = A + alpha*x*y'`.
    `double` | `dnrm2(DoubleMatrix1D x)` Return the 2-norm; `sqrt(x[0]^2 + x[1]^2 + ...)`.
    `void` | `drot(DoubleMatrix1D x, DoubleMatrix1D y, double c, double s)` Applies a givens plane rotation to (x,y); `x = c*x + s*y; y = c*y - s*x`.
    `void` | `drotg(double a, double b, double[] rotvec)` Constructs a Givens plane rotation for `(a,b)`.
    `void` | `dscal(double alpha, DoubleMatrix1D x)` Vector scaling; `x = alpha*x`.
    `void` | `dscal(double alpha, DoubleMatrix2D A)` Matrix scaling; `A = alpha*A`.
    `void` | `dswap(DoubleMatrix1D x, DoubleMatrix1D y)` Swaps the elements of two vectors; `y <==> x`.
    `void` | `dswap(DoubleMatrix2D x, DoubleMatrix2D y)` Swaps the elements of two matrices; `B <==> A`.
    `void` | `dsymv(boolean isUpperTriangular, double alpha, DoubleMatrix2D A, DoubleMatrix1D x, double beta, DoubleMatrix1D y)` Symmetric matrix-vector multiplication; `y = alpha*A*x + beta*y`.
    `void` | `dtrmv(boolean isUpperTriangular, boolean transposeA, boolean isUnitTriangular, DoubleMatrix2D A, DoubleMatrix1D x)` Triangular matrix-vector multiplication; `x = A*x` or `x = A'*x`.
    `int` | `idamax(DoubleMatrix1D x)` Returns the index of largest absolute value; `i such that |x[i]| == max(|x[0]|,|x[1]|,...).`.

- - ### Method Detail

    - #### assign

          void assign(DoubleMatrix2D A,
                    DoubleFunction function)

      Assigns the result of a function to each cell; `x[row,col] = function(x[row,col])`.
      Parameters:
        `A` - the matrix to modify.
        `function` - a function object taking as argument the current cell's value.
      See Also:
        `Functions`

    - #### assign

          void assign(DoubleMatrix2D x,
                    DoubleMatrix2D y,
                    DoubleDoubleFunction function)

      Assigns the result of a function to each cell; `x[row,col] = function(x[row,col],y[row,col])`.
      Parameters:
        `x` - the matrix to modify.
        `y` - the secondary matrix to operate on.
        `function` - a function object taking as first argument the current cell's value of `this`, and as second argument the current cell's value of `y`,
      Throws:
        `java.lang.IllegalArgumentException` - if `x.columns() != y.columns() || x.rows() != y.rows()`
      See Also:
        `Functions`

    - #### dasum

          double dasum(DoubleMatrix1D x)

      Returns the sum of absolute values; `|x[0]| + |x[1]| + ...` . In fact equivalent to `x.aggregate(cern.jet.math.Functions.plus, cern.jet.math.Functions.abs)`.
      Parameters:
        `x` - the first vector.

    - #### daxpy

          void daxpy(double alpha,
                   DoubleMatrix1D x,
                   DoubleMatrix1D y)

      Combined vector scaling; `y = y + alpha*x`. In fact equivalent to `y.assign(x,cern.jet.math.Functions.plusMult(alpha))`.
      Parameters:
        `alpha` - a scale factor.
        `x` - the first source vector.
        `y` - the second source vector, this is also the vector where results are stored.
      Throws:
        `java.lang.IllegalArgumentException` - `x.size() != y.size()`..

    - #### daxpy

          void daxpy(double alpha,
                   DoubleMatrix2D A,
                   DoubleMatrix2D B)

      Combined matrix scaling; `B = B + alpha*A`. In fact equivalent to `B.assign(A,cern.jet.math.Functions.plusMult(alpha))`.
      Parameters:
        `alpha` - a scale factor.
        `A` - the first source matrix.
        `B` - the second source matrix, this is also the matrix where results are stored.
      Throws:
        `java.lang.IllegalArgumentException` - if `A.columns() != B.columns() || A.rows() != B.rows()`.

    - #### dcopy

          void dcopy(DoubleMatrix1D x,
                   DoubleMatrix1D y)

      Vector assignment (copying); `y = x`. In fact equivalent to `y.assign(x)`.
      Parameters:
        `x` - the source vector.
        `y` - the destination vector.
      Throws:
        `java.lang.IllegalArgumentException` - `x.size() != y.size()`.

    - #### dcopy

          void dcopy(DoubleMatrix2D A,
                   DoubleMatrix2D B)

      Matrix assignment (copying); `B = A`. In fact equivalent to `B.assign(A)`.
      Parameters:
        `A` - the source matrix.
        `B` - the destination matrix.
      Throws:
        `java.lang.IllegalArgumentException` - if `A.columns() != B.columns() || A.rows() != B.rows()`.

    - #### ddot

          double ddot(DoubleMatrix1D x,
                    DoubleMatrix1D y)

      Returns the dot product of two vectors x and y, which is `Sum(x[i]*y[i])`. In fact equivalent to `x.zDotProduct(y)`.
      Parameters:
        `x` - the first vector.
        `y` - the second vector.
      Returns:
        the sum of products.
      Throws:
        `java.lang.IllegalArgumentException` - if `x.size() != y.size()`.

    - #### dgemm

          void dgemm(boolean transposeA,
                   boolean transposeB,
                   double alpha,
                   DoubleMatrix2D A,
                   DoubleMatrix2D B,
                   double beta,
                   DoubleMatrix2D C)

      Generalized linear algebraic matrix-matrix multiply; `C = alpha*A*B + beta*C`. In fact equivalent to `A.zMult(B,C,alpha,beta,transposeA,transposeB)`. Note: Matrix shape conformance is checked after potential transpositions.
      Parameters:
        `transposeA` - set this flag to indicate that the multiplication shall be performed on A'.
        `transposeB` - set this flag to indicate that the multiplication shall be performed on B'.
        `alpha` - a scale factor.
        `A` - the first source matrix.
        `B` - the second source matrix.
        `beta` - a scale factor.
        `C` - the third source matrix, this is also the matrix where results are stored.
      Throws:
        `java.lang.IllegalArgumentException` - if `B.rows() != A.columns()`.
        `java.lang.IllegalArgumentException` - if `C.rows() != A.rows() || C.columns() != B.columns()`.
        `java.lang.IllegalArgumentException` - if `A == C || B == C`.

    - #### dgemv

          void dgemv(boolean transposeA,
                   double alpha,
                   DoubleMatrix2D A,
                   DoubleMatrix1D x,
                   double beta,
                   DoubleMatrix1D y)

      Generalized linear algebraic matrix-vector multiply; `y = alpha*A*x + beta*y`. In fact equivalent to `A.zMult(x,y,alpha,beta,transposeA)`. Note: Matrix shape conformance is checked after potential transpositions.
      Parameters:
        `transposeA` - set this flag to indicate that the multiplication shall be performed on A'.
        `alpha` - a scale factor.
        `A` - the source matrix.
        `x` - the first source vector.
        `beta` - a scale factor.
        `y` - the second source vector, this is also the vector where results are stored.
      Throws:
        `java.lang.IllegalArgumentException` - `A.columns() != x.size() || A.rows() != y.size())`..

    - #### dger

          void dger(double alpha,
                  DoubleMatrix1D x,
                  DoubleMatrix1D y,
                  DoubleMatrix2D A)

      Performs a rank 1 update; `A = A + alpha*x*y'`. Example:

          A = { {6,5}, {7,6} }, x = {1,2}, y = {3,4}, alpha = 1 -->
          A = { {9,9}, {13,14} }

      Parameters:
        `alpha` - a scalar.
        `x` - an m element vector.
        `y` - an n element vector.
        `A` - an m by n matrix.

    - #### dnrm2

          double dnrm2(DoubleMatrix1D x)

      Return the 2-norm; `sqrt(x[0]^2 + x[1]^2 + ...)`. In fact equivalent to `Math.sqrt(Algebra.DEFAULT.norm2(x))`.
      Parameters:
        `x` - the vector.

    - #### drot

          void drot(DoubleMatrix1D x,
                  DoubleMatrix1D y,
                  double c,
                  double s)

      Applies a givens plane rotation to (x,y); `x = c*x + s*y; y = c*y - s*x`.
      Parameters:
        `x` - the first vector.
        `y` - the second vector.
        `c` - the cosine of the angle of rotation.
        `s` - the sine of the angle of rotation.

    - #### drotg

          void drotg(double a,
                   double b,
                   double[] rotvec)

      Constructs a Givens plane rotation for `(a,b)`. Taken from the LINPACK translation from FORTRAN to Java, interface slightly modified. In the LINPACK listing DROTG is attributed to Jack Dongarra
      Parameters:
        `a` - rotational elimination parameter a.
        `b` - rotational elimination parameter b.
        `rotvec[]` - Must be at least of length 4. On output contains the values `{a,b,c,s}`.

    - #### dscal

          void dscal(double alpha,
                   DoubleMatrix1D x)

      Vector scaling; `x = alpha*x`. In fact equivalent to `x.assign(cern.jet.math.Functions.mult(alpha))`.
      Parameters:
        `alpha` - a scale factor.
        `x` - the first vector.

    - #### dscal

          void dscal(double alpha,
                   DoubleMatrix2D A)

      Matrix scaling; `A = alpha*A`. In fact equivalent to `A.assign(cern.jet.math.Functions.mult(alpha))`.
      Parameters:
        `alpha` - a scale factor.
        `A` - the matrix.

    - #### dswap

          void dswap(DoubleMatrix1D x,
                   DoubleMatrix1D y)

      Swaps the elements of two vectors; `y <==> x`. In fact equivalent to `y.swap(x)`.
      Parameters:
        `x` - the first vector.
        `y` - the second vector.
      Throws:
        `java.lang.IllegalArgumentException` - `x.size() != y.size()`.

    - #### dswap

          void dswap(DoubleMatrix2D x,
                   DoubleMatrix2D y)

      Swaps the elements of two matrices; `B <==> A`.
      Parameters:
        `A` - the first matrix.
        `B` - the second matrix.
      Throws:
        `java.lang.IllegalArgumentException` - if `A.columns() != B.columns() || A.rows() != B.rows()`.

    - #### dsymv

          void dsymv(boolean isUpperTriangular,
                   double alpha,
                   DoubleMatrix2D A,
                   DoubleMatrix1D x,
                   double beta,
                   DoubleMatrix1D y)

      Symmetric matrix-vector multiplication; `y = alpha*A*x + beta*y`. Where alpha and beta are scalars, x and y are n element vectors and A is an n by n symmetric matrix. A can be in upper or lower triangular format.
      Parameters:
        `isUpperTriangular` - is A upper triangular or lower triangular part to be used?
        `alpha` - scaling factor.
        `A` - the source matrix.
        `x` - the first source vector.
        `beta` - scaling factor.
        `y` - the second vector holding source and destination.

    - #### dtrmv

          void dtrmv(boolean isUpperTriangular,
                   boolean transposeA,
                   boolean isUnitTriangular,
                   DoubleMatrix2D A,
                   DoubleMatrix1D x)

      Triangular matrix-vector multiplication; `x = A*x` or `x = A'*x`. Where x is an n element vector and A is an n by n unit, or non-unit, upper or lower triangular matrix.
      Parameters:
        `isUpperTriangular` - is A upper triangular or lower triangular?
        `transposeA` - set this flag to indicate that the multiplication shall be performed on A'.
        `isUnitTriangular` - true --> A is assumed to be unit triangular; false --> A is not assumed to be unit triangular
        `A` - the source matrix.
        `x` - the vector holding source and destination.

    - #### idamax

          int idamax(DoubleMatrix1D x)

      Returns the index of largest absolute value; `i such that |x[i]| == max(|x[0]|,|x[1]|,...).`.
      Parameters:
        `x` - the vector to search through.
      Returns:
        the index of largest absolute value (-1 if x is empty).

Jump to the Colt Homepage