Package org.apache.commons.math3.linear

# Class DiagonalMatrix

java.lang.Object
org.apache.commons.math3.linear.RealLinearOperator
org.apache.commons.math3.linear.AbstractRealMatrix
org.apache.commons.math3.linear.DiagonalMatrix

All Implemented Interfaces:
  `Serializable`, `AnyMatrix`, `RealMatrix`

public class DiagonalMatrix extends AbstractRealMatrix implements Serializable
Implementation of a diagonal matrix.

Since:
  3.1.1
See Also:
  - Serialized Form

## Constructor Summary

Constructors
Constructor
Description
`DiagonalMatrix(double[] d)`
Creates a matrix using the input array as the underlying data.
`DiagonalMatrix(double[] d, boolean copyArray)`
Creates a matrix using the input array as the underlying data.
`DiagonalMatrix(int dimension)`
Creates a matrix with the supplied dimension.

## Method Summary

Modifier and Type
Method
Description
`DiagonalMatrix`
`add(DiagonalMatrix m)`
Compute the sum of `this` and `m`.
`void`
`addToEntry(int row, int column, double increment)`
Adds (in place) the specified value to the specified entry of `this` matrix.
`RealMatrix`
`copy()`
Returns a (deep) copy of this.
`RealMatrix`
`createMatrix(int rowDimension, int columnDimension)`
Create a new RealMatrix of the same type as the instance with the supplied row and column dimensions.
`int`
`getColumnDimension()`
Returns the number of columns of this matrix.
`double[][]`
`getData()`
Returns matrix entries as a two-dimensional array.
`double[]`
`getDataRef()`
Gets a reference to the underlying data array.
`double`
`getEntry(int row, int column)`
Get the entry in the specified row and column.
`int`
`getRowDimension()`
Returns the number of rows of this matrix.
`DiagonalMatrix`
`inverse()`
Computes the inverse of this diagonal matrix.
`DiagonalMatrix`
`inverse(double threshold)`
Computes the inverse of this diagonal matrix.
`boolean`
`isSingular(double threshold)`
Returns whether this diagonal matrix is singular, i.e.
`DiagonalMatrix`
`multiply(DiagonalMatrix m)`
Returns the result of postmultiplying `this` by `m`.
`RealMatrix`
`multiply(RealMatrix m)`
Returns the result of postmultiplying `this` by `m`.
`void`
`multiplyEntry(int row, int column, double factor)`
Multiplies (in place) the specified entry of `this` matrix by the specified value.
`double[]`
`operate(double[] v)`
Returns the result of multiplying this by the vector `v`.
`double[]`
`preMultiply(double[] v)`
Returns the (row) vector result of premultiplying this by the vector `v`.
`RealVector`
`preMultiply(RealVector v)`
Returns the (row) vector result of premultiplying this by the vector `v`.
`void`
`setEntry(int row, int column, double value)`
Set the entry in the specified row and column.
`DiagonalMatrix`
`subtract(DiagonalMatrix m)`
Returns `this` minus `m`.

### Methods inherited from class org.apache.commons.math3.linear.AbstractRealMatrix

`add, copySubMatrix, copySubMatrix, equals, getColumn, getColumnMatrix, getColumnVector, getFrobeniusNorm, getNorm, getRow, getRowMatrix, getRowVector, getSubMatrix, getSubMatrix, getTrace, hashCode, isSquare, operate, power, preMultiply, scalarAdd, scalarMultiply, setColumn, setColumnMatrix, setColumnVector, setRow, setRowMatrix, setRowVector, setSubMatrix, subtract, toString, transpose, walkInColumnOrder, walkInColumnOrder, walkInColumnOrder, walkInColumnOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInOptimizedOrder, walkInRowOrder, walkInRowOrder, walkInRowOrder, walkInRowOrder`

### Methods inherited from class org.apache.commons.math3.linear.RealLinearOperator

`isTransposable, operateTranspose`

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

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

## Constructor Details

### DiagonalMatrix

public DiagonalMatrix(int dimension) throws NotStrictlyPositiveException
Creates a matrix with the supplied dimension.

Parameters:
  `dimension` - Number of rows and columns in the new matrix.
Throws:
  `NotStrictlyPositiveException` - if the dimension is not positive.

### DiagonalMatrix

public DiagonalMatrix(double[] d)
Creates a matrix using the input array as the underlying data.
The input array is copied, not referenced.

Parameters:
  `d` - Data for the new matrix.

### DiagonalMatrix

public DiagonalMatrix(double[] d, boolean copyArray) throws NullArgumentException
Creates a matrix using the input array as the underlying data.
If an array is created specially in order to be embedded in a this instance and not used directly, the `copyArray` may be set to `false`. This will prevent the copying and improve performance as no new array will be built and no data will be copied.

Parameters:
  `d` - Data for new matrix.
  `copyArray` - if `true`, the input array will be copied, otherwise it will be referenced.
Throws:
  `NullArgumentException` - if d is null

## Method Details

### createMatrix

public RealMatrix createMatrix(int rowDimension, int columnDimension) throws NotStrictlyPositiveException, DimensionMismatchException
Create a new RealMatrix of the same type as the instance with the supplied row and column dimensions.

Specified by:
  `createMatrix` in interface `RealMatrix`
Specified by:
  `createMatrix` in class `AbstractRealMatrix`
Parameters:
  `rowDimension` - the number of rows in the new matrix
  `columnDimension` - the number of columns in the new matrix
Returns:
  a new matrix of the same type as the instance
Throws:
  `DimensionMismatchException` - if the requested dimensions are not equal.
  `NotStrictlyPositiveException` - if row or column dimension is not positive.

### copy

public RealMatrix copy()
Returns a (deep) copy of this.

Specified by:
  `copy` in interface `RealMatrix`
Specified by:
  `copy` in class `AbstractRealMatrix`
Returns:
  matrix copy

### add

public DiagonalMatrix add(DiagonalMatrix m) throws MatrixDimensionMismatchException
Compute the sum of `this` and `m`.

Parameters:
  `m` - Matrix to be added.
Returns:
  `this + m`.
Throws:
  `MatrixDimensionMismatchException` - if `m` is not the same size as `this`.

### subtract

public DiagonalMatrix subtract(DiagonalMatrix m) throws MatrixDimensionMismatchException
Returns `this` minus `m`.

Parameters:
  `m` - Matrix to be subtracted.
Returns:
  `this - m`
Throws:
  `MatrixDimensionMismatchException` - if `m` is not the same size as `this`.

### multiply

public DiagonalMatrix multiply(DiagonalMatrix m) throws DimensionMismatchException
Returns the result of postmultiplying `this` by `m`.

Parameters:
  `m` - matrix to postmultiply by
Returns:
  `this * m`
Throws:
  `DimensionMismatchException` - if `columnDimension(this) != rowDimension(m)`

### multiply

public RealMatrix multiply(RealMatrix m) throws DimensionMismatchException
Returns the result of postmultiplying `this` by `m`.

Specified by:
  `multiply` in interface `RealMatrix`
Overrides:
  `multiply` in class `AbstractRealMatrix`
Parameters:
  `m` - matrix to postmultiply by
Returns:
  `this * m`
Throws:
  `DimensionMismatchException` - if `columnDimension(this) != rowDimension(m)`

### getData

public double[][] getData()
Returns matrix entries as a two-dimensional array.

Specified by:
  `getData` in interface `RealMatrix`
Overrides:
  `getData` in class `AbstractRealMatrix`
Returns:
  2-dimensional array of entries

### getDataRef

public double[] getDataRef()
Gets a reference to the underlying data array.

Returns:
  1-dimensional array of entries.

### getEntry

public double getEntry(int row, int column) throws OutOfRangeException
Get the entry in the specified row and column. Row and column indices start at 0.

Specified by:
  `getEntry` in interface `RealMatrix`
Specified by:
  `getEntry` in class `AbstractRealMatrix`
Parameters:
  `row` - Row index of entry to be fetched.
  `column` - Column index of entry to be fetched.
Returns:
  the matrix entry at `(row, column)`.
Throws:
  `OutOfRangeException` - if the row or column index is not valid.

### setEntry

public void setEntry(int row, int column, double value) throws OutOfRangeException, NumberIsTooLargeException
Set the entry in the specified row and column. Row and column indices start at 0.

Specified by:
  `setEntry` in interface `RealMatrix`
Specified by:
  `setEntry` in class `AbstractRealMatrix`
Parameters:
  `row` - Row index of entry to be set.
  `column` - Column index of entry to be set.
  `value` - the new value of the entry.
Throws:
  `NumberIsTooLargeException` - if `row != column` and value is non-zero.
  `OutOfRangeException` - if the row or column index is not valid

### addToEntry

public void addToEntry(int row, int column, double increment) throws OutOfRangeException, NumberIsTooLargeException
Adds (in place) the specified value to the specified entry of `this` matrix. Row and column indices start at 0.

Specified by:
  `addToEntry` in interface `RealMatrix`
Overrides:
  `addToEntry` in class `AbstractRealMatrix`
Parameters:
  `row` - Row index of the entry to be modified.
  `column` - Column index of the entry to be modified.
  `increment` - value to add to the matrix entry.
Throws:
  `NumberIsTooLargeException` - if `row != column` and increment is non-zero.
  `OutOfRangeException` - if the row or column index is not valid.

### multiplyEntry

public void multiplyEntry(int row, int column, double factor) throws OutOfRangeException
Multiplies (in place) the specified entry of `this` matrix by the specified value. Row and column indices start at 0.

Specified by:
  `multiplyEntry` in interface `RealMatrix`
Overrides:
  `multiplyEntry` in class `AbstractRealMatrix`
Parameters:
  `row` - Row index of the entry to be modified.
  `column` - Column index of the entry to be modified.
  `factor` - Multiplication factor for the matrix entry.
Throws:
  `OutOfRangeException` - if the row or column index is not valid.

### getRowDimension

public int getRowDimension()
Returns the number of rows of this matrix.

Specified by:
  `getRowDimension` in interface `AnyMatrix`
Specified by:
  `getRowDimension` in class `AbstractRealMatrix`
Returns:
  the number of rows.

### getColumnDimension

public int getColumnDimension()
Returns the number of columns of this matrix.

Specified by:
  `getColumnDimension` in interface `AnyMatrix`
Specified by:
  `getColumnDimension` in class `AbstractRealMatrix`
Returns:
  the number of columns.

### operate

public double[] operate(double[] v) throws DimensionMismatchException
Returns the result of multiplying this by the vector `v`.

Specified by:
  `operate` in interface `RealMatrix`
Overrides:
  `operate` in class `AbstractRealMatrix`
Parameters:
  `v` - the vector to operate on
Returns:
  `this * v`
Throws:
  `DimensionMismatchException` - if the length of `v` does not match the column dimension of `this`.

### preMultiply

public double[] preMultiply(double[] v) throws DimensionMismatchException
Returns the (row) vector result of premultiplying this by the vector `v`.

Specified by:
  `preMultiply` in interface `RealMatrix`
Overrides:
  `preMultiply` in class `AbstractRealMatrix`
Parameters:
  `v` - the row vector to premultiply by
Returns:
  `v * this`
Throws:
  `DimensionMismatchException` - if the length of `v` does not match the row dimension of `this`.

### preMultiply

public RealVector preMultiply(RealVector v) throws DimensionMismatchException
Returns the (row) vector result of premultiplying this by the vector `v`.

Specified by:
  `preMultiply` in interface `RealMatrix`
Overrides:
  `preMultiply` in class `AbstractRealMatrix`
Parameters:
  `v` - the row vector to premultiply by
Returns:
  `v * this`
Throws:
  `DimensionMismatchException` - if the dimension of `v` does not match the row dimension of `this`.

### inverse

public DiagonalMatrix inverse() throws SingularMatrixException
Computes the inverse of this diagonal matrix.

Note: this method will use a singularity threshold of 0, use `inverse(double)` if a different threshold is needed.

Returns:
  the inverse of `m`
Throws:
  `SingularMatrixException` - if the matrix is singular
Since:
  3.3

### inverse

public DiagonalMatrix inverse(double threshold) throws SingularMatrixException
Computes the inverse of this diagonal matrix.

Parameters:
  `threshold` - Singularity threshold.
Returns:
  the inverse of `m`
Throws:
  `SingularMatrixException` - if the matrix is singular
Since:
  3.3

### isSingular

public boolean isSingular(double threshold)
Returns whether this diagonal matrix is singular, i.e. any diagonal entry is equal to `0` within the given threshold.

Parameters:
  `threshold` - Singularity threshold.
Returns:
  `true` if the matrix is singular, `false` otherwise
Since:
  3.3