datan

## Class DatanMatrix

- java.lang.Object
- - datan.DatanMatrix

-     public class DatanMatrix
      extends java.lang.Object

  A class representing a matrix.
  Author:
    Siegmund Brandt.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `DatanMatrix(DatanMatrix b)` Creates a matrix which is a copy of b.
    `DatanMatrix(DatanVector v)` Creates a matrix with only one column representing vector v).
    `DatanMatrix(double[] a)` Creates a matrix with only one column the elements of which are given by a.
    `DatanMatrix(double[][] a)` Creates a matrix the elements of which are given by a.
    `DatanMatrix(int n)` Creates an (n x n) unit matrix.
    `DatanMatrix(int m, int n)` Creates an (n x m) matrix all elements of which contain a zero (null matrix).

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `DatanMatrix` | `add(DatanMatrix b)` Returns the sum with the matrix b.
    `void` | `applyGivensTransformation(double[] z, double[] cs)` Applies Givens Transformation to the two vector components z.
    `void` | `applyHouseholderTransformation(DatanVector v, DatanVector c, int p, int l, double[] param)` Applies Householder Transformation to Vector c.
    `DatanMatrix` | `choleskyDecomposition()` Returns Cholesky decomposition of this matrix , which has to be symmetric positve definite.
    `void` | `choleskyInversion()` Cholesky inversion (in place) of this matrix, which has to be positive definite symmetric.
    `DatanMatrix` | `choleskyMultiply(DatanMatrix a)` Returns product of this matrix (assumed to be of upper triangular form) with matrix a.
    `DatanVector` | `choleskyMultiply(DatanVector a)` Returns product of this matrix (assumed to be of upper triangular form) with vector a.
    `void` | `defineAndApplyGivensTransformation(double[] v, double[] cs)` Defines Givens transformation and applies it to the defining vector.
    `void` | `defineGivensTransformation(double[] v, double[] cs)` Defines Givens transformation.
    `void` | `defineHouseholderTransformation(DatanVector v, int p, int l, double[] param)` Defines a Householder Transformation.
    `DatanVector` | `getColumn(int k)` Returns the column vector with column index k.
    `double` | `getElement(int i, int j)` Returns element (i,j).
    `int` | `getNumberOfColumns()` Returns number of columns.
    `int` | `getNumberOfRows()` Returns number of rows.
    `DatanVector` | `getRow(int k)` Returns the row vector with row index k.
    `DatanMatrix` | `getSubmatrix(int k, int l, int m0, int n0)` Returns a submatrix.
    `DatanMatrix` | `inverse()` Returns inverse of this matrix, which has to be squre and nonsingualar.
    `DatanVector` | `leastSquaresWithConstraints(DatanVector b, DatanMatrix e, DatanVector d, DatanVector r, double frac, boolean[] ok)` finds solution vector x for least squares problem with constraints.
    `void` | `marquardt(DatanVector bvec, double lambda, DatanVector x1, DatanVector x2, double frac, boolean[] ok)` Yields the solution vectors (x1 and x2) appearing in Marquardt's method to solve the matrix equation a x = b, where a is this matrix.
    `void` | `matrixEquation(DatanMatrix a)` Solves matrix equation a x = b where b is original matrix; after call it contains the solution x.
    `DatanMatrix` | `multiply(DatanMatrix b)` Returns the matrix obtained by multipying this matrix from the right with the matrix b.
    `DatanVector` | `multiply(DatanVector v)` Returns the vector obtained by multipying this matrix from the right with the (column) vector v.
    `DatanMatrix` | `multiply(double s)` Returns the product of this matrix and the scalar s.
    `DatanMatrix` | `multiplyTransposedWith(DatanMatrix b)` Returns the matrix obtained by multipying the transposed of this matrix from the right with the matrix b.
    `DatanMatrix` | `multiplyWithTransposed(DatanMatrix b)` Returns the matrix obtained by multipying this matrix from the right with the transposed of matrix b.
    `DatanMatrix` | `pseudoInverse()` Returns the pseudoinverse of this matrix, using the singular value decomposition; this call without argument should be used in unproblematic cases only, since it does not provide a check of convergence of the method and further information.
    `DatanMatrix` | `pseudoInverse(DatanVector r, double frac, int[] nsv, boolean[] ok, DatanVector d, DatanMatrix[] u, DatanMatrix[] v)` Returns the pseudoinverse of this matrix, using the singular value decomposition.
    `void` | `putColumn(int k, DatanVector b)` Replaces the column vector with column index k by (column) vector b.
    `void` | `putRow(int k, DatanVector b)` Replaces the row vector with column index k by (row) vector b.
    `void` | `putSubmatrix(int m0, int n0, DatanMatrix b)` Replaces a submatrix.
    `void` | `setElement(int i, int j, double in)` sets element (i,j) ti in.
    `DatanMatrix` | `singularValueDecomposition(DatanMatrix b)` Returns solution matrix x of matrix equation a x = b (where a is this matix and b the matrix in the argument of the metod) using singular value decomposition; this call with only one argument should be used in unproblematic cases only, since it does not provide a check of convergence of the method and further information.
    `DatanMatrix` | `singularValueDecomposition(DatanMatrix b, DatanVector r, double frac, int[] nsv, boolean[] ok)` Returns solution matrix x of matrix equation a x = b (where a is this matix) using singular value decomposition;
    `DatanVector` | `singularValueDecomposition(DatanVector b, double[] r, double frac, int[] nsv, boolean[] ok)` Returns solution vector x of matrix equation a x = b (where a is this matix) using singular value decomposition;
    `DatanMatrix` | `sub(DatanMatrix b)` Returns the difference between this matrix and the matrix b.
    `void` | `svm(DatanMatrix b, DatanVector d, double lambda, DatanVector x1, DatanVector x2, double frac)` Performs singular value analysis and application of Marquardt method.
    `java.lang.String` | `toString()` Writes the matrix onto a string, using 5 fraction digits.
    `java.lang.String` | `toString(java.lang.String fmt)` Writes the matrix onto a string.
    `DatanMatrix` | `transpose()` Returns the transposed matrix.
    `void` | `write()` Writes the matrix to standard output.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### DatanMatrix

          public DatanMatrix(DatanMatrix b)

      Creates a matrix which is a copy of b.

    - #### DatanMatrix

          public DatanMatrix(int n)

      Creates an (n x n) unit matrix.

    - #### DatanMatrix

          public DatanMatrix(int m,
                     int n)

      Creates an (n x m) matrix all elements of which contain a zero (null matrix).

    - #### DatanMatrix

          public DatanMatrix(double[][] a)

      Creates a matrix the elements of which are given by a.

    - #### DatanMatrix

          public DatanMatrix(double[] a)

      Creates a matrix with only one column the elements of which are given by a.

    - #### DatanMatrix

          public DatanMatrix(DatanVector v)

      Creates a matrix with only one column representing vector v).

  - ### Method Detail

    - #### getNumberOfRows

          public int getNumberOfRows()

      Returns number of rows.

    - #### getNumberOfColumns

          public int getNumberOfColumns()

      Returns number of columns.

    - #### getElement

          public double getElement(int i,
                          int j)

      Returns element (i,j).

    - #### setElement

          public void setElement(int i,
                        int j,
                        double in)

      sets element (i,j) ti in.

    - #### transpose

          public DatanMatrix transpose()

      Returns the transposed matrix.

    - #### add

          public DatanMatrix add(DatanMatrix b)

      Returns the sum with the matrix b.
      Parameters:
        `b` - the matrix to be added.
      Returns:
        the desired sum.

    - #### sub

          public DatanMatrix sub(DatanMatrix b)

      Returns the difference between this matrix and the matrix b.
      Parameters:
        `b` - the matrix to be added.
      Returns:
        the desired difference.

    - #### multiply

          public DatanMatrix multiply(double s)

      Returns the product of this matrix and the scalar s.
      Parameters:
        `s` - scalar factor.
      Returns:
        the desired product.

    - #### multiply

          public DatanVector multiply(DatanVector v)

      Returns the vector obtained by multipying this matrix from the right with the (column) vector v.
      Parameters:
        `v` - the vector to be multiplied with.
      Returns:
        the desired product.

    - #### multiply

          public DatanMatrix multiply(DatanMatrix b)

      Returns the matrix obtained by multipying this matrix from the right with the matrix b.
      Parameters:
        `b` - the matrix to be multiplied with from the right.
      Returns:
        the desired product.

    - #### multiplyWithTransposed

          public DatanMatrix multiplyWithTransposed(DatanMatrix b)

      Returns the matrix obtained by multipying this matrix from the right with the transposed of matrix b.
      Parameters:
        `b` - the matrix, the transposed of which is to be multiplied with from the right.
      Returns:
        the desired product.

    - #### multiplyTransposedWith

          public DatanMatrix multiplyTransposedWith(DatanMatrix b)

      Returns the matrix obtained by multipying the transposed of this matrix from the right with the matrix b.
      Parameters:
        `b` - the matrix, with which the transposed is to be multiplied with from the right.
      Returns:
        the desired product.

    - #### getSubmatrix

          public DatanMatrix getSubmatrix(int k,
                                 int l,
                                 int m0,
                                 int n0)

      Returns a submatrix.
      Parameters:
        `k` - number of rows of the submatrix.
        `l` - number of columnss of the submatrix.
        `m0` - row nomber of starting position of submatrix in the original matrix.
        `n0` - column starting position of submatrix in the original matrix.
      Returns:
        the desired submatrix.

    - #### putSubmatrix

          public void putSubmatrix(int m0,
                          int n0,
                          DatanMatrix b)

      Replaces a submatrix.
      Parameters:
        `m0` - row nomber of starting position of submatrix in the original matrix.
        `n0` - column starting position of submatrix in the original matrix.
        `b` - the matrix to be placed there instead.

    - #### getColumn

          public DatanVector getColumn(int k)

      Returns the column vector with column index k.
      Parameters:
        `k` - index of column.
      Returns:
        the desired column vector.

    - #### putColumn

          public void putColumn(int k,
                       DatanVector b)

      Replaces the column vector with column index k by (column) vector b.
      Parameters:
        `k` - number of column.
        `b` - vector replacing that column.

    - #### getRow

          public DatanVector getRow(int k)

      Returns the row vector with row index k.
      Parameters:
        `k` - number of row.
      Returns:
        the desired row vector.

    - #### putRow

          public void putRow(int k,
                    DatanVector b)

      Replaces the row vector with column index k by (row) vector b.
      Parameters:
        `k` - number of row.
        `b` - vector replacing that row.

    - #### matrixEquation

          public void matrixEquation(DatanMatrix a)

      Solves matrix equation a x = b where b is original matrix; after call it contains the solution x.
      Parameters:
        `a` - (n x n) matrix.

    - #### inverse

          public DatanMatrix inverse()

      Returns inverse of this matrix, which has to be squre and nonsingualar.

    - #### choleskyDecomposition

          public DatanMatrix choleskyDecomposition()

      Returns Cholesky decomposition of this matrix , which has to be symmetric positve definite.

    - #### choleskyMultiply

          public DatanMatrix choleskyMultiply(DatanMatrix a)

      Returns product of this matrix (assumed to be of upper triangular form) with matrix a.

    - #### choleskyMultiply

          public DatanVector choleskyMultiply(DatanVector a)

      Returns product of this matrix (assumed to be of upper triangular form) with vector a.

    - #### choleskyInversion

          public void choleskyInversion()

      Cholesky inversion (in place) of this matrix, which has to be positive definite symmetric.

    - #### singularValueDecomposition

          public DatanMatrix singularValueDecomposition(DatanMatrix b)

      Returns solution matrix x of matrix equation a x = b (where a is this matix and b the matrix in the argument of the metod) using singular value decomposition; this call with only one argument should be used in unproblematic cases only, since it does not provide a check of convergence of the method and further information.

    - #### singularValueDecomposition

          public DatanVector singularValueDecomposition(DatanVector b,
                                               double[] r,
                                               double frac,
                                               int[] nsv,
                                               boolean[] ok)

      Returns solution vector x of matrix equation a x = b (where a is this matix) using singular value decomposition;
      Parameters:
        `b` - vector b
        `frac` - fraction f; if smax is the largest singualr value, then all singular values < smin = f smax are set equal to zero. If frac = 0, then it is assumed to be 1.E-15.
        `r` - array containing the squares of the residuals (available AFTER completion of the method)
        `nsv` - nsv[0] contains the number of singular values not set equal to zero (available AFTER completion of the method)
        `ok` - ok[0] = true if method has converged, = false otherwise (available AFTER completion of the method)

    - #### singularValueDecomposition

          public DatanMatrix singularValueDecomposition(DatanMatrix b,
                                               DatanVector r,
                                               double frac,
                                               int[] nsv,
                                               boolean[] ok)

      Returns solution matrix x of matrix equation a x = b (where a is this matix) using singular value decomposition;
      Parameters:
        `b` - matrix b
        `frac` - fraction f; if smax is the largest singualr value, then all singular values < smin = f smax are set equal to zero. If frac = 0, then it is assumed to be 1.E-15.
        `r` - vector containing the squares of the residuals (available AFTER completion of the method)
        `nsv` - nsv[0] contains the number of singular values not set equal to zero (available AFTER completion of the method)
        `ok` - ok[0] = true if method has converged, = false otherwise (available AFTER completion of the method)

    - #### marquardt

          public void marquardt(DatanVector bvec,
                       double lambda,
                       DatanVector x1,
                       DatanVector x2,
                       double frac,
                       boolean[] ok)

      Yields the solution vectors (x1 and x2) appearing in Marquardt's method to solve the matrix equation a x = b, where a is this matrix.
      Parameters:
        `bvec` - vector b
        `frac` - parameter f needed in singular value decomposition. If frac = 0, then it is assumed to be 1.E-15.
        `lambda` - Marquardt's parameter
        `x1` - solution vector x1 (available AFTER completion of the method)
        `x2` - solution vector x2 (available AFTER completion of the method)
        `ok` - ok[0] = true if method has converged, = false otherwise (available AFTER completion of the method)

    - #### pseudoInverse

          public DatanMatrix pseudoInverse(DatanVector r,
                                  double frac,
                                  int[] nsv,
                                  boolean[] ok,
                                  DatanVector d,
                                  DatanMatrix[] u,
                                  DatanMatrix[] v)

      Returns the pseudoinverse of this matrix, using the singular value decomposition.
      Parameters:
        `frac` - fraction f; if smax is the largest singualr value, then all singular values < smin = f smax are set equal to zero. If frac = 0, then it is assumed to be 1.E-15.
        `r` - vector containing the squares of the residuals (available AFTER completion of the method)
        `nsv` - nsv[0] contains the number of singular values not set equal to zero (available AFTER completion of the method)
        `ok` - ok[0] = true if method has converged, = false otherwise (available AFTER completion of the method)
        `d` - vector, the elements of which are the diagiagonal elements of a square matrix D whose other elements are zero (available AFTER completion of the method)
        `u` - u[0] orthoganal matrix (available AFTER completion of the method)
        `v` - v[0] orthoganal matrix (available AFTER completion of the method); u D v(transposed) is equal to the original matrix

    - #### pseudoInverse

          public DatanMatrix pseudoInverse()

      Returns the pseudoinverse of this matrix, using the singular value decomposition; this call without argument should be used in unproblematic cases only, since it does not provide a check of convergence of the method and further information.

    - #### svm

          public void svm(DatanMatrix b,
                 DatanVector d,
                 double lambda,
                 DatanVector x1,
                 DatanVector x2,
                 double frac)

      Performs singular value analysis and application of Marquardt method.

    - #### leastSquaresWithConstraints

          public DatanVector leastSquaresWithConstraints(DatanVector b,
                                                DatanMatrix e,
                                                DatanVector d,
                                                DatanVector r,
                                                double frac,
                                                boolean[] ok)

      finds solution vector x for least squares problem with constraints. The least squares problem is r^2 = (a x - b)^2 = min; the constraints are e x = b. The original matrix is a.
      Parameters:
        `b` - vector b
        `e` - matrix e
        `frac` - parameter for singular value decomposition (normally 0.)
        `r` - r[0] residual r^2 - available after application of method.
        `ok` - ok[0] true if method converged (false otherwise) - available after application of method.

    - #### defineGivensTransformation

          public void defineGivensTransformation(double[] v,
                                        double[] cs)

      Defines Givens transformation.
      Parameters:
        `v` - vector elements v1, v2.
        `cs` - contains (after application of method) the two parameters cs[0] = c and cs[1] = s.

    - #### defineAndApplyGivensTransformation

          public void defineAndApplyGivensTransformation(double[] v,
                                                double[] cs)

      Defines Givens transformation and applies it to the defining vector.
      Parameters:
        `v` - vector elements v1, v2; after application of method it contains the transformed elements.
        `cs` - contains (after application of method) the two parameters cs[0] = c and cs[1] = s.

    - #### applyGivensTransformation

          public void applyGivensTransformation(double[] z,
                                       double[] cs)

      Applies Givens Transformation to the two vector components z.
      Parameters:
        `z` - vector elements z1, z2; after application of method it contains the transformed elements.
        `cs` - the two parameters cs[0] = c and cs[1] = s defining the transformation.

    - #### defineHouseholderTransformation

          public void defineHouseholderTransformation(DatanVector v,
                                             int p,
                                             int l,
                                             double[] param)

      Defines a Householder Transformation.
      Parameters:
        `v` - vector.
        `p` - vector index.
        `l` - vector index.
        `param` - parameters of transformation (after application of method): param[0] = up, param[1] = b.

    - #### applyHouseholderTransformation

          public void applyHouseholderTransformation(DatanVector v,
                                            DatanVector c,
                                            int p,
                                            int l,
                                            double[] param)

      Applies Householder Transformation to Vector c.
      Parameters:
        `v` - transformation defining vector.
        `c` - vector to be transformed (contains transformed vector after application).
        `p` - vector index.
        `l` - vector index.
        `param` - parameters of transformation: param[0] = up, param[1] = b.

    - #### write

          public void write()

      Writes the matrix to standard output.

    - #### toString

          public java.lang.String toString()

      Writes the matrix onto a string, using 5 fraction digits.
      Overrides:
        `toString` in class `java.lang.Object`

    - #### toString

          public java.lang.String toString(java.lang.String fmt)

      Writes the matrix onto a string.
      Parameters:
        `fmt` - formatstring, e.g., "%15.10f"