cern.colt.matrix

## Class ObjectFactory2D

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

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

      public class ObjectFactory2D
      extends PersistentObject

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

  Construction | Use idioms like `ObjectFactory2D.dense.make(4,4)` to construct dense matrices, `ObjectFactory2D.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 block matrices | Use method `composeDiagonal` to work with diagonal block matrices.

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

      ObjectFactory2D F = ObjectFactory2D.dense;
      F.make(4,4);
      ...

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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static ObjectFactory2D` | `dense` A factory producing dense matrices.
    `static ObjectFactory2D` | `sparse` A factory producing sparse matrices.

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

      `serialVersionUID`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ObjectMatrix2D` | `appendColumns(ObjectMatrix2D A, ObjectMatrix2D B)` C = A||B; Constructs a new matrix which is the column-wise concatenation of two other matrices.
    `ObjectMatrix2D` | `appendRows(ObjectMatrix2D A, ObjectMatrix2D B)` C = A||B; Constructs a new matrix which is the row-wise concatenation of two other matrices.
    `ObjectMatrix2D` | `compose(ObjectMatrix2D[][] parts)` Constructs a block matrix made from the given parts.
    `ObjectMatrix2D` | `composeDiagonal(ObjectMatrix2D A, ObjectMatrix2D B)` Constructs a diagonal block matrix from the given parts (the direct sum of two matrices).
    `ObjectMatrix2D` | `composeDiagonal(ObjectMatrix2D A, ObjectMatrix2D B, ObjectMatrix2D C)` Constructs a diagonal block matrix from the given parts.
    `void` | `decompose(ObjectMatrix2D[][] parts, ObjectMatrix2D matrix)` Splits a block matrix into its constituent blocks; Copies blocks of a matrix into the given parts.
    `ObjectMatrix2D` | `diagonal(ObjectMatrix1D vector)` Constructs a new diagonal matrix whose diagonal elements are the elements of `vector`.
    `ObjectMatrix1D` | `diagonal(ObjectMatrix2D A)` Constructs a new vector consisting of the diagonal elements of `A`.
    `ObjectMatrix2D` | `make(int rows, int columns)` Constructs a matrix with the given shape, each cell initialized with zero.
    `ObjectMatrix2D` | `make(int rows, int columns, java.lang.Object initialValue)` Constructs a matrix with the given shape, each cell initialized with the given value.
    `ObjectMatrix2D` | `make(java.lang.Object[][] values)` Constructs a matrix with the given cell values.
    `ObjectMatrix2D` | `make(java.lang.Object[] values, int rows)` Construct a matrix from a one-dimensional column-major packed array, ala Fortran.
    `ObjectMatrix2D` | `repeat(ObjectMatrix2D A, int rowRepeat, int columnRepeat)` C = A||A||..||A; Constructs a new matrix which is duplicated both along the row and column dimension.

    - ### 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 ObjectFactory2D dense

      A factory producing dense matrices.

    - #### sparse

          public static final ObjectFactory2D sparse

      A factory producing sparse matrices.

  - ### Method Detail

    - #### appendColumns

          public ObjectMatrix2D appendColumns(ObjectMatrix2D A,
                                     ObjectMatrix2D 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 ObjectMatrix2D appendRows(ObjectMatrix2D A,
                                  ObjectMatrix2D 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

    - #### compose

          public ObjectMatrix2D compose(ObjectMatrix2D[][] parts)

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

      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`
          ObjectMatrix2D[][] 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`
          ObjectMatrix2D[][] 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`
          ObjectMatrix2D A = ascending(2,2);
          ObjectMatrix2D B = descending(2,2);
          ObjectMatrix2D _ = null;

          ObjectMatrix2D[][] 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`
          ObjectMatrix2D[][] 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 ObjectMatrix2D composeDiagonal(ObjectMatrix2D A,
                                       ObjectMatrix2D 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 ObjectMatrix2D composeDiagonal(ObjectMatrix2D A,
                                       ObjectMatrix2D B,
                                       ObjectMatrix2D 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(ObjectMatrix2D[][] parts,
                       ObjectMatrix2D matrix)

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

      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`
          ObjectMatrix2D matrix = ... ;
          ObjectMatrix2D _ = null;
          ObjectMatrix2D A,B,C,D;
          A = make(2,2); B = make (4,4);
          C = make(4,3); D = make (2,2);
          ObjectMatrix2D[][] 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.

    - #### diagonal

          public ObjectMatrix2D diagonal(ObjectMatrix1D 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 ObjectMatrix1D diagonal(ObjectMatrix2D 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.

    - #### make

          public ObjectMatrix2D make(java.lang.Object[][] 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 ObjectMatrix2D make(java.lang.Object[] 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 Objects, packed by columns (ala Fortran).
        `rows` - the number of rows.
      Throws:
        `java.lang.IllegalArgumentException` - `values.length` must be a multiple of `rows`.

    - #### make

          public ObjectMatrix2D make(int rows,
                            int columns)

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

    - #### make

          public ObjectMatrix2D make(int rows,
                            int columns,
                            java.lang.Object initialValue)

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

    - #### repeat

          public ObjectMatrix2D repeat(ObjectMatrix2D 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

Jump to the Colt Homepage