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