cern.colt.matrix

## Class DoubleFactory2D

- java.lang.Object
- - cern.colt.PersistentObject
  - - cern.colt.matrix.DoubleFactory2D

- All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable

      public class DoubleFactory2D
      extends PersistentObject

  Factory for convenient construction of 2-d matrices holding `double` cells. Also provides convenient methods to compose (concatenate) and decompose (split) matrices from/to constituent blocks.

  Construction | Use idioms like `DoubleFactory2D.dense.make(4,4)` to construct dense matrices, `DoubleFactory2D.sparse.make(4,4)` to construct sparse matrices.
  Construction with initial values | Use other `make` methods to construct matrices with given initial values.
  Appending rows and columns | Use methods `appendColumns`, `appendRows` and `repeat` to append rows and columns.
  General block matrices | Use methods `compose` and `decompose` to work with general block matrices.
  Diagonal matrices | Use methods `diagonal(vector)`, `diagonal(matrix)` and `identity` to work with diagonal matrices.
  Diagonal block matrices | Use method `composeDiagonal` to work with diagonal block matrices.
  Random | Use methods `random` and `sample` to construct random matrices.

  If the factory is used frequently it might be useful to streamline the notation. For example by aliasing:

      DoubleFactory2D F = DoubleFactory2D.dense;
      F.make(4,4);
      F.descending(10,20);
      F.random(4,4);
      ...

  Version:
    1.0, 09/24/99
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static DoubleFactory2D` | `dense` A factory producing dense matrices.
    `static DoubleFactory2D` | `rowCompressed` A factory producing sparse row compressed matrices.
    `static DoubleFactory2D` | `sparse` A factory producing sparse hash matrices.

    - ### Fields inherited from class cern.colt.PersistentObject

      `serialVersionUID`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `DoubleMatrix2D` | `appendColumns(DoubleMatrix2D A, DoubleMatrix2D B)` C = A||B; Constructs a new matrix which is the column-wise concatenation of two other matrices.
    `DoubleMatrix2D` | `appendRows(DoubleMatrix2D A, DoubleMatrix2D B)` C = A||B; Constructs a new matrix which is the row-wise concatenation of two other matrices.
    `DoubleMatrix2D` | `ascending(int rows, int columns)` Constructs a matrix with cells having ascending values.
    `DoubleMatrix2D` | `compose(DoubleMatrix2D[][] parts)` Constructs a block matrix made from the given parts.
    `DoubleMatrix2D` | `composeDiagonal(DoubleMatrix2D A, DoubleMatrix2D B)` Constructs a diagonal block matrix from the given parts (the direct sum of two matrices).
    `DoubleMatrix2D` | `composeDiagonal(DoubleMatrix2D A, DoubleMatrix2D B, DoubleMatrix2D C)` Constructs a diagonal block matrix from the given parts.
    `void` | `decompose(DoubleMatrix2D[][] parts, DoubleMatrix2D matrix)` Splits a block matrix into its constituent blocks; Copies blocks of a matrix into the given parts.
    `void` | `demo1()` Demonstrates usage of this class.
    `void` | `demo2()` Demonstrates usage of this class.
    `DoubleMatrix2D` | `descending(int rows, int columns)` Constructs a matrix with cells having descending values.
    `DoubleMatrix2D` | `diagonal(DoubleMatrix1D vector)` Constructs a new diagonal matrix whose diagonal elements are the elements of `vector`.
    `DoubleMatrix1D` | `diagonal(DoubleMatrix2D A)` Constructs a new vector consisting of the diagonal elements of `A`.
    `DoubleMatrix2D` | `identity(int rowsAndColumns)` Constructs an identity matrix (having ones on the diagonal and zeros elsewhere).
    `DoubleMatrix2D` | `make(double[][] values)` Constructs a matrix with the given cell values.
    `DoubleMatrix2D` | `make(double[] values, int rows)` Construct a matrix from a one-dimensional column-major packed array, ala Fortran.
    `DoubleMatrix2D` | `make(int rows, int columns)` Constructs a matrix with the given shape, each cell initialized with zero.
    `DoubleMatrix2D` | `make(int rows, int columns, double initialValue)` Constructs a matrix with the given shape, each cell initialized with the given value.
    `DoubleMatrix2D` | `random(int rows, int columns)` Constructs a matrix with uniformly distributed values in `(0,1)` (exclusive).
    `DoubleMatrix2D` | `repeat(DoubleMatrix2D A, int rowRepeat, int columnRepeat)` C = A||A||..||A; Constructs a new matrix which is duplicated both along the row and column dimension.
    `DoubleMatrix2D` | `sample(DoubleMatrix2D matrix, double value, double nonZeroFraction)` Modifies the given matrix to be a randomly sampled matrix.
    `DoubleMatrix2D` | `sample(int rows, int columns, double value, double nonZeroFraction)` Constructs a randomly sampled matrix with the given shape.

    - ### Methods inherited from class cern.colt.PersistentObject

      `clone`

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

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### dense

          public static final DoubleFactory2D dense

      A factory producing dense matrices.

    - #### sparse

          public static final DoubleFactory2D sparse

      A factory producing sparse hash matrices.

    - #### rowCompressed

          public static final DoubleFactory2D rowCompressed

      A factory producing sparse row compressed matrices.

  - ### Method Detail

    - #### appendColumns

          public DoubleMatrix2D appendColumns(DoubleMatrix2D A,
                                     DoubleMatrix2D B)

      C = A||B; Constructs a new matrix which is the column-wise concatenation of two other matrices.

          0 1 2
          3 4 5
          appendColumns
          6 7
          8 9
          -->
          0 1 2 6 7
          3 4 5 8 9

    - #### appendRows

          public DoubleMatrix2D appendRows(DoubleMatrix2D A,
                                  DoubleMatrix2D B)

      C = A||B; Constructs a new matrix which is the row-wise concatenation of two other matrices.

          0 1
          2 3
          4 5
          appendRows
          6 7
          8 9
          -->
          0 1
          2 3
          4 5
          6 7
          8 9

    - #### ascending

          public DoubleMatrix2D ascending(int rows,
                                 int columns)

      Constructs a matrix with cells having ascending values. For debugging purposes. Example:

          0 1 2
          3 4 5

    - #### compose

          public DoubleMatrix2D compose(DoubleMatrix2D[][] parts)

      Constructs a block matrix made from the given parts. The inverse to method `decompose(DoubleMatrix2D[][], DoubleMatrix2D)`.

      All matrices of a given column within `parts` must have the same number of columns. All matrices of a given row within `parts` must have the same number of rows. Otherwise an `IllegalArgumentException` is thrown. Note that `null`s within `parts[row,col]` are an exception to this rule: they are ignored. Cells are copied. Example:

      `Code` | `Result`
          DoubleMatrix2D[][] parts1 =
          {
             { null,        make(2,2,1), null        },
             { make(4,4,2), null,        make(4,3,3) },
             { null,        make(2,2,4), null        }
          };
          System.out.println(compose(parts1));
      | `8 x 9 matrix 0 0 0 0 1 1 0 0 0 0 0 0 0 1 1 0 0 0 2 2 2 2 0 0 3 3 3 2 2 2 2 0 0 3 3 3 2 2 2 2 0 0 3 3 3 2 2 2 2 0 0 3 3 3 0 0 0 0 4 4 0 0 0 0 0 0 0 4 4 0 0 0`
          DoubleMatrix2D[][] parts3 =
          {
             { identity(3),               null,                        },
             { null,                      identity(3).viewColumnFlip() },
             { identity(3).viewRowFlip(), null                         }
          };
          System.out.println("\n"+make(parts3));
      | `9 x 6 matrix 1 0 0 0 0 0 0 1 0 0 0 0 0 0 1 0 0 0 0 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 0`
          DoubleMatrix2D A = ascending(2,2);
          DoubleMatrix2D B = descending(2,2);
          DoubleMatrix2D _ = null;

          DoubleMatrix2D[][] parts4 =
          {
             { A, _, A, _ },
             { _, A, _, B }
          };
          System.out.println("\n"+make(parts4));
      | `4 x 8 matrix 1 2 0 0 1 2 0 0 3 4 0 0 3 4 0 0 0 0 1 2 0 0 3 2 0 0 3 4 0 0 1 0`
          DoubleMatrix2D[][] parts2 =
          {
             { null,        make(2,2,1), null        },
             { make(4,4,2), null,        make(4,3,3) },
             { null,        make(2,3,4), null        }
          };
          System.out.println("\n"+Factory2D.make(parts2));
      | `IllegalArgumentException A[0,1].cols != A[2,1].cols (2 != 3)`

      Throws:
        `java.lang.IllegalArgumentException` - subject to the conditions outlined above.

    - #### composeDiagonal

          public DoubleMatrix2D composeDiagonal(DoubleMatrix2D A,
                                       DoubleMatrix2D B)

      Constructs a diagonal block matrix from the given parts (the direct sum of two matrices). That is the concatenation

          A 0
          0 B

      (The direct sum has `A.rows()+B.rows()` rows and `A.columns()+B.columns()` columns). Cells are copied.
      Returns:
        a new matrix which is the direct sum.

    - #### composeDiagonal

          public DoubleMatrix2D composeDiagonal(DoubleMatrix2D A,
                                       DoubleMatrix2D B,
                                       DoubleMatrix2D C)

      Constructs a diagonal block matrix from the given parts. The concatenation has the form

          A 0 0
          0 B 0
          0 0 C

      from the given parts. Cells are copied.

    - #### decompose

          public void decompose(DoubleMatrix2D[][] parts,
                       DoubleMatrix2D matrix)

      Splits a block matrix into its constituent blocks; Copies blocks of a matrix into the given parts. The inverse to method `compose(DoubleMatrix2D[][])`.

      All matrices of a given column within `parts` must have the same number of columns. All matrices of a given row within `parts` must have the same number of rows. Otherwise an `IllegalArgumentException` is thrown. Note that `null`s within `parts[row,col]` are an exception to this rule: they are ignored. Cells are copied. Example:

      `Code` | `matrix` | `--> parts`
          DoubleMatrix2D matrix = ... ;
          DoubleMatrix2D _ = null;
          DoubleMatrix2D A,B,C,D;
          A = make(2,2); B = make (4,4);
          C = make(4,3); D = make (2,2);
          DoubleMatrix2D[][] parts =
          {
             { _, A, _ },
             { B, _, C },
             { _, D, _ }
          };
          decompose(parts,matrix);
          System.out.println("\nA = "+A);
          System.out.println("\nB = "+B);
          System.out.println("\nC = "+C);
          System.out.println("\nD = "+D);
      | `8 x 9 matrix 9 9 9 9 1 1 9 9 9 9 9 9 9 1 1 9 9 9 2 2 2 2 9 9 3 3 3 2 2 2 2 9 9 3 3 3 2 2 2 2 9 9 3 3 3 2 2 2 2 9 9 3 3 3 9 9 9 9 4 4 9 9 9 9 9 9 9 4 4 9 9 9` | `A = 2 x 2 matrix 1 1 1 1` `B = 4 x 4 matrix 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2` `C = 4 x 3 matrix 3 3 3 3 3 3` `3 3 3` `3 3 3` `D = 2 x 2 matrix 4 4 4 4`

      Throws:
        `java.lang.IllegalArgumentException` - subject to the conditions outlined above.

    - #### demo1

          public void demo1()

      Demonstrates usage of this class.

    - #### demo2

          public void demo2()

      Demonstrates usage of this class.

    - #### descending

          public DoubleMatrix2D descending(int rows,
                                  int columns)

      Constructs a matrix with cells having descending values. For debugging purposes. Example:

          5 4 3
          2 1 0

    - #### diagonal

          public DoubleMatrix2D diagonal(DoubleMatrix1D vector)

      Constructs a new diagonal matrix whose diagonal elements are the elements of `vector`. Cells values are copied. The new matrix is not a view. Example:

          5 4 3 -->
          5 0 0
          0 4 0
          0 0 3

      Returns:
        a new matrix.

    - #### diagonal

          public DoubleMatrix1D diagonal(DoubleMatrix2D A)

      Constructs a new vector consisting of the diagonal elements of `A`. Cells values are copied. The new vector is not a view. Example:

          5 0 0 9
          0 4 0 9
          0 0 3 9
          --> 5 4 3

      Parameters:
        `A` - the matrix, need not be square.
      Returns:
        a new vector.

    - #### identity

          public DoubleMatrix2D identity(int rowsAndColumns)

      Constructs an identity matrix (having ones on the diagonal and zeros elsewhere).

    - #### make

          public DoubleMatrix2D make(double[][] values)

      Constructs a matrix with the given cell values. `values` is required to have the form `values[row][column]` and have exactly the same number of columns in every row.

      The values are copied. So subsequent changes in `values` are not reflected in the matrix, and vice-versa.

      Parameters:
        `values` - The values to be filled into the new matrix.
      Throws:
        `java.lang.IllegalArgumentException` - if `for any 1 <= row < values.length: values[row].length != values[row-1].length`.

    - #### make

          public DoubleMatrix2D make(double[] values,
                            int rows)

      Construct a matrix from a one-dimensional column-major packed array, ala Fortran. Has the form `matrix.get(row,column) == values[row + column*rows]`. The values are copied.
      Parameters:
        `values` - One-dimensional array of doubles, packed by columns (ala Fortran).
        `rows` - the number of rows.
      Throws:
        `java.lang.IllegalArgumentException` - `values.length` must be a multiple of `rows`.

    - #### make

          public DoubleMatrix2D make(int rows,
                            int columns)

      Constructs a matrix with the given shape, each cell initialized with zero.

    - #### make

          public DoubleMatrix2D make(int rows,
                            int columns,
                            double initialValue)

      Constructs a matrix with the given shape, each cell initialized with the given value.

    - #### random

          public DoubleMatrix2D random(int rows,
                              int columns)

      Constructs a matrix with uniformly distributed values in `(0,1)` (exclusive).

    - #### repeat

          public DoubleMatrix2D repeat(DoubleMatrix2D A,
                              int rowRepeat,
                              int columnRepeat)

      C = A||A||..||A; Constructs a new matrix which is duplicated both along the row and column dimension. Example:

          0 1
          2 3
          repeat(2,3) -->
          0 1 0 1 0 1
          2 3 2 3 2 3
          0 1 0 1 0 1
          2 3 2 3 2 3

    - #### sample

          public DoubleMatrix2D sample(int rows,
                              int columns,
                              double value,
                              double nonZeroFraction)

      Constructs a randomly sampled matrix with the given shape. Randomly picks exactly `Math.round(rows*columns*nonZeroFraction)` cells and initializes them to `value`, all the rest will be initialized to zero. Note that this is not the same as setting each cell with probability `nonZeroFraction` to `value`. Note: The random seed is a constant.
      Throws:
        `java.lang.IllegalArgumentException` - if `nonZeroFraction < 0 || nonZeroFraction > 1`.
      See Also:
        `RandomSampler`

    - #### sample

          public DoubleMatrix2D sample(DoubleMatrix2D matrix,
                              double value,
                              double nonZeroFraction)

      Modifies the given matrix to be a randomly sampled matrix. Randomly picks exactly `Math.round(rows*columns*nonZeroFraction)` cells and initializes them to `value`, all the rest will be initialized to zero. Note that this is not the same as setting each cell with probability `nonZeroFraction` to `value`. Note: The random seed is a constant.
      Throws:
        `java.lang.IllegalArgumentException` - if `nonZeroFraction < 0 || nonZeroFraction > 1`.
      See Also:
        `RandomSampler`

Jump to the Colt Homepage