Colt 1.2.0

## 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
`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
`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`

Colt 1.2.0

Jump to the Colt Homepage