Package org.djunits.vecmat.dn

Class MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>

java.lang.Object

org.djunits.vecmat.def.VectorMatrix<Q,U,M,SI,H>

org.djunits.vecmat.def.Matrix<Q,U,M,SI,H>

org.djunits.vecmat.def.SquareMatrix<Q,U,MatrixNxN<Q,U>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

org.djunits.vecmat.dn.MatrixNxN<Q,U>

Type Parameters:

Q - the quantity type

U - the unit type

All Implemented Interfaces:

Serializable, Additive<MatrixNxN<Q,U>>, Scalable<MatrixNxN<Q,U>>, Value<U,MatrixNxN<Q,U>>, Hadamard<MatrixNxN<?,?>,MatrixNxN<SIQuantity,SIUnit>>

public class MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>
extends SquareMatrix<Q,U,MatrixNxN<Q,U>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

MatrixNxN implements a square matrix with NxN real-valued entries. The matrix is immutable, except for the display unit, which can be changed. Internal storage can be float or double, and dense or sparse.

Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djunits.org. The DJUNITS project is distributed under a three-clause BSD-style license.

Author:

Alexander Verbraeck

See Also:

• Serialized Form

Constructor Summary

Constructors

Constructor	Description
MatrixNxN(DataGridSi<?> dataSi, U displayUnit)	Create a new NxN Matrix with a unit, based on a DataGrid storage object that contains SI data.

Method Summary

Modifier and Type	Method	Description
MatrixNxN<SIQuantity,SIUnit>	adjugate()	Return the adjugate (classical adjoint) matrix for this matrix, often denoted as adj(M).
<TQ extends Quantity<TQ, TU>, TU extends UnitInterface<TU, TQ>> MatrixNxN<TQ,TU>	as(TU targetUnit)	Return the matrix "as" a matrix with a known quantity, using a unit to express the result in.
Matrix1x1<Q,U>	asMatrix1x1()	Convert this matrix to a Matrix1x1.
Matrix2x2<Q,U>	asMatrix2x2()	Convert this matrix to a Matrix2x2.
Matrix3x3<Q,U>	asMatrix3x3()	Convert this matrix to a Matrix3x3.
int	cols()	Return the number of columns.
MatrixNxN<SIQuantity,SIUnit>	divideElements(MatrixNxN<?,?> other)	Divide the elements of this vector, matrix or table on an element-by-element basis with those of another collection of the same type (but possibly representing another quantity).
boolean	equals(Object obj)
double[]	getColumnSi(int col)	Return an array with SI-values for the given column (0-based) from the vector or matrix.
VectorN.Col<Q,U>	getColumnVector(int col)	Return a quantity column (0-based) from the vector or matrix.
DataGridSi<?>	getDataGrid()	Return the data grid in SI units.
VectorN.Col<Q,U>	getDiagonalVector()	Retrieve the main diagonal of the matrix as a column vector.
double[]	getRowSi(int row)	Return an array with SI-values for the given row (0-based) from the vector or matrix.
VectorN.Row<Q,U>	getRowVector(int row)	Return a quantity row (0-based) from the vector or matrix.
int	hashCode()
MatrixNxN<Q,U>	instantiateSi(double[] siNew)	Return a new vector or matrix with the given SI or BASE values.
MatrixNxN<SIQuantity,SIUnit>	instantiateSi(double[] siNew, SIUnit siUnit)	Return a new vector or matrix in SI-units with the given SI or BASE values.
MatrixNxN<SIQuantity,SIUnit>	inverse()	Return the inverse of the square matrix, if the matrix is non-singular.
MatrixNxN<SIQuantity,SIUnit>	invertElements()	Invert the vector, matrix or table on an element-by-element basis.
VectorN.Col<Q,U>	mgetColumnVector(int mCol)	Return a quantity column (1-based) from the vector or matrix.
VectorN.Row<Q,U>	mgetRowVector(int mRow)	Return a quantity row (1-based) from the vector or matrix.
MatrixNxN<SIQuantity,SIUnit>	multiply(MatrixNxN<?,?> otherMat)	Multiply this matrix with another matrix using matrix multiplication and return the result.
VectorN.Col<SIQuantity,SIUnit>	multiply(VectorN.Col<?,?> otherVec)	Multiply this matrix with a column vector, resulting in a column vector.
MatrixNxN<SIQuantity,SIUnit>	multiplyElements(Quantity<?,?> quantity)	Multiply the elements of this vector, matrix or table by the given quantity.
MatrixNxN<SIQuantity,SIUnit>	multiplyElements(MatrixNxN<?,?> other)	Multiply the elements of this vector, matrix or table on an element-by-element basis with those of another collection of the same type (but possibly representing another quantity).
static <Q extends Quantity<Q, U>, U extends UnitInterface<U, Q>> MatrixNxN<Q,U>	of(double[][] valueGridInUnit, U displayUnit)	Create a new MatrixNxN with a unit, based on a 2-dimensional grid.
static <Q extends Quantity<Q, U>, U extends UnitInterface<U, Q>> MatrixNxN<Q,U>	of(double[] valueArrayInUnit, U displayUnit)	Create a new MatrixNxN with a unit, based on a 1-dimensional array.
int	rows()	Return the number of rows.
double[]	si()	Return a row-major array of SI-values for this matrix or vector.
double	si(int row, int col)	Return the si-value at position (row, col), where both row and col are 0-based values.

Methods inherited from class org.djunits.vecmat.def.SquareMatrix

determinant, determinantScalar, getDiagonalScalars, getDiagonalSi, isSkewSymmetric, isSkewSymmetric, isSymmetric, isSymmetric, normFrobenius, order, trace, transpose

Methods inherited from class org.djunits.vecmat.def.Matrix

checkMultiply, checkMultiply, multiply

Methods inherited from class org.djunits.vecmat.def.VectorMatrix

abs, add, add, asMatrixNxM, asQuantityTable, checkCol, checkRow, divideElements, get, getColumnScalars, getDisplayUnit, getRowScalars, getScalarGrid, isRelative, max, mcheckCol, mcheckRow, mean, median, mget, mgetColumnScalars, mgetColumnSi, mgetRowScalars, mgetRowSi, min, mode, msi, multiplyElements, negate, scaleBy, setDisplayUnit, subtract, subtract, sum, toString, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.djunits.vecmat.operations.Hadamard

divideElements

Methods inherited from interface org.djunits.value.Scalable

divideBy

Methods inherited from interface org.djunits.value.Value

isAbsolute, setDisplayUnit

Constructor Details

MatrixNxN

public MatrixNxN(DataGridSi<?> dataSi,
 U displayUnit)

Create a new NxN Matrix with a unit, based on a DataGrid storage object that contains SI data.

Parameters:

dataSi - the data of the matrix, in SI unit.

displayUnit - the display unit to use

Throws:

IllegalArgumentException - when the number of rows or columns does not have a positive value

Method Details

of

public static <Q extends Quantity<Q,
U>,
U extends UnitInterface<U,
Q>>
MatrixNxN<Q,U> of(double[] valueArrayInUnit,
 U displayUnit)

Create a new MatrixNxN with a unit, based on a 1-dimensional array.

Type Parameters:

Q - the quantity type

U - the unit type

Parameters:

valueArrayInUnit - the matrix values {a11, a12, ..., aN1, aN32, ..., aNN} expressed in the display unit

displayUnit - the display unit to use

Returns:

a new MatrixNxN with a unit

Throws:

IllegalArgumentException - when the number of entries in the valueArray is not a perfect square

of

public static <Q extends Quantity<Q,
U>,
U extends UnitInterface<U,
Q>>
MatrixNxN<Q,U> of(double[][] valueGridInUnit,
 U displayUnit)

Create a new MatrixNxN with a unit, based on a 2-dimensional grid.

Type Parameters:

Q - the quantity type

U - the unit type

Parameters:

valueGridInUnit - the matrix values {{a11, a12, a13}, ..., {a31, a32, a33}} expressed in the display unit

displayUnit - the display unit to use

Returns:

a new MatrixNxN with a unit

Throws:

IllegalArgumentException - when valueGrid has 0 rows, or when the number of columns for one of the rows is not equal to the number of rows

instantiateSi

public MatrixNxN<Q,U> instantiateSi(double[] siNew)

Description copied from class: VectorMatrix

Return a new vector or matrix with the given SI or BASE values.

Specified by:

instantiateSi in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

siNew - the values for the new vector or matrix in row-major format

Returns:

a new matrix with the provided SI or BASE values

si

public double[] si()

Description copied from class: VectorMatrix

Return a row-major array of SI-values for this matrix or vector. Note that this is NOT a safe copy.

Specified by:

si in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Returns:

the row-major array of SI-values

si

public double si(int row,
 int col)

Description copied from class: VectorMatrix

Return the si-value at position (row, col), where both row and col are 0-based values.

Specified by:

si in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

row - the row (0-based)

col - the column (0-based)

Returns:

the si-value at position (row, col)

rows

public int rows()

Description copied from class: VectorMatrix

Return the number of rows.

Specified by:

rows in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Returns:

the number of rows

cols

public int cols()

Description copied from class: VectorMatrix

Return the number of columns.

Specified by:

cols in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Returns:

the number of columns

getDataGrid

public DataGridSi<?> getDataGrid()

Return the data grid in SI units.

Returns:

the data grid in SI units

instantiateSi

public MatrixNxN<SIQuantity,SIUnit> instantiateSi(double[] siNew,
 SIUnit siUnit)

Description copied from class: VectorMatrix

Return a new vector or matrix in SI-units with the given SI or BASE values.

Specified by:

instantiateSi in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

siNew - the values for the new vector or matrix in row-major format

siUnit - the new unit for the new vector or matrix

Returns:

a new matrix with the provided SI or BASE values

getRowVector

public VectorN.Row<Q,U> getRowVector(int row)

Description copied from class: VectorMatrix

Return a quantity row (0-based) from the vector or matrix. Note that the specific vector to return can be tightened by the implementing class.

Specified by:

getRowVector in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

row - the row number to retrieve (0-based)

Returns:

a row vector with the data at the given row

mgetRowVector

public VectorN.Row<Q,U> mgetRowVector(int mRow)

Description copied from class: VectorMatrix

Return a quantity row (1-based) from the vector or matrix. Note that the specific vector to return can be tightened by the implementing class.

Specified by:

mgetRowVector in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

mRow - the row number to retrieve (1-based)

Returns:

a row vector with the data at the given row

getColumnVector

public VectorN.Col<Q,U> getColumnVector(int col)

Description copied from class: VectorMatrix

Return a quantity column (0-based) from the vector or matrix. Note that the specific vector to return can be tightened by the implementing class.

Specified by:

getColumnVector in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

col - the column number to retrieve (0-based)

Returns:

a column vector with the data at the given column

mgetColumnVector

public VectorN.Col<Q,U> mgetColumnVector(int mCol)

Description copied from class: VectorMatrix

Return a quantity column (1-based) from the vector or matrix. Note that the specific vector to return can be tightened by the implementing class.

Specified by:

mgetColumnVector in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

mCol - the column number to retrieve (1-based)

Returns:

a column vector with the data at the given column

getDiagonalVector

public VectorN.Col<Q,U> getDiagonalVector()
                                   throws IllegalStateException

Description copied from class: SquareMatrix

Retrieve the main diagonal of the matrix as a column vector.

Specified by:

getDiagonalVector in class SquareMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Returns:

the main diagonal as a Vector

Throws:

IllegalStateException

getRowSi

public double[] getRowSi(int row)

Description copied from class: VectorMatrix

Return an array with SI-values for the given row (0-based) from the vector or matrix.

Specified by:

getRowSi in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

row - the row number to retrieve (0-based)

Returns:

an array with SI-values with the data at the given row

getColumnSi

public double[] getColumnSi(int col)

Description copied from class: VectorMatrix

Return an array with SI-values for the given column (0-based) from the vector or matrix.

Specified by:

getColumnSi in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

col - the column number to retrieve (0-based)

Returns:

an array with SI-values with the data at the given column

inverse

public MatrixNxN<SIQuantity,SIUnit> inverse()
                                     throws NonInvertibleMatrixException

Description copied from class: SquareMatrix

Return the inverse of the square matrix, if the matrix is non-singular. The unit of the matrix is U^(-1).

Specified by:

inverse in class SquareMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Returns:

the inverse of the square matrix, if the matrix is non-singular

Throws:

NonInvertibleMatrixException - when the matrix is singular or cannot be inverted

adjugate

public MatrixNxN<SIQuantity,SIUnit> adjugate()

Description copied from class: SquareMatrix

Return the adjugate (classical adjoint) matrix for this matrix, often denoted as adj(M). The unit of adj(M) is U^(n-1) where n is the order of the matrix.

Specified by:

adjugate in class SquareMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Returns:

the adjugate (classical adjoint) matrix

invertElements

public MatrixNxN<SIQuantity,SIUnit> invertElements()

Description copied from interface: Hadamard

Invert the vector, matrix or table on an element-by-element basis.

Specified by:

invertElements in interface Hadamard<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>

Overrides:

invertElements in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Returns:

a vector, matrix or table with an element-by-element inversion (1/value) of the elements

multiplyElements

public MatrixNxN<SIQuantity,SIUnit> multiplyElements(MatrixNxN<?,?> other)

Description copied from interface: Hadamard

Multiply the elements of this vector, matrix or table on an element-by-element basis with those of another collection of the same type (but possibly representing another quantity).

Specified by:

multiplyElements in interface Hadamard<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>

Overrides:

multiplyElements in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

other - the other collection of the same type

Returns:

a vector, matrix or table with an element-by-element multiplication of its elements

divideElements

public MatrixNxN<SIQuantity,SIUnit> divideElements(MatrixNxN<?,?> other)

Description copied from interface: Hadamard

Divide the elements of this vector, matrix or table on an element-by-element basis with those of another collection of the same type (but possibly representing another quantity).

Specified by:

divideElements in interface Hadamard<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>

Overrides:

divideElements in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

other - the other collection of the same type

Returns:

a vector, matrix or table with an element-by-element division of this collection's elements and other's elements

multiplyElements

public MatrixNxN<SIQuantity,SIUnit> multiplyElements(Quantity<?,?> quantity)

Description copied from interface: Hadamard

Multiply the elements of this vector, matrix or table by the given quantity.

Specified by:

multiplyElements in interface Hadamard<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>

Overrides:

multiplyElements in class VectorMatrix<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>,MatrixNxN<Q extends Quantity<Q,U>,U extends UnitInterface<U,Q>>,MatrixNxN<SIQuantity,SIUnit>,MatrixNxN<?,?>>

Parameters:

quantity - the scalar quantity to multiply by

Returns:

a vector, matrix or table where the elements have been multiplied by the given quantity

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

multiply

public MatrixNxN<SIQuantity,SIUnit> multiply(MatrixNxN<?,?> otherMat)

Multiply this matrix with another matrix using matrix multiplication and return the result.

The unit of the result is the SI-unit “sum” of this matrix and the other matrix (i.e., U.plus(V) on the underlying SIUnits).

Parameters:

otherMat - the right-hand matrix to multiply with

Returns:

the product matrix with the correct SI unit

multiply

public VectorN.Col<SIQuantity,SIUnit> multiply(VectorN.Col<?,?> otherVec)

Multiply this matrix with a column vector, resulting in a column vector.

The unit of the result is the SI-unit “sum” of this matrix and the vector (i.e., U.plus(V) on the underlying SIUnits).

Parameters:

otherVec - the column vector to multiply with (size N)

Returns:

the resulting column vector from the multiplication

Throws:

IllegalArgumentException - if the vector size does not equal order()

as

public <TQ extends Quantity<TQ,
TU>,
TU extends UnitInterface<TU,
TQ>>
MatrixNxN<TQ,TU> as(TU targetUnit)

Return the matrix "as" a matrix with a known quantity, using a unit to express the result in.

The SI units of this matrix and the target unit must match; otherwise an IllegalArgumentException is thrown. The returned matrix shares the SI values but has the specified display unit.

Type Parameters:

TQ - target quantity type

TU - target unit type

Parameters:

targetUnit - the unit to convert the matrix to

Returns:

a matrix typed in the target quantity with the specified display unit

Throws:

IllegalArgumentException - when the units do not match

asMatrix1x1

public Matrix1x1<Q,U> asMatrix1x1()

Convert this matrix to a Matrix1x1. The shape must be 1 x 1.

Returns:

a Matrix1x1 with identical SI data and display unit

Throws:

IllegalStateException - if this matrix is not 1 x 1

asMatrix2x2

public Matrix2x2<Q,U> asMatrix2x2()

Convert this matrix to a Matrix2x2. The shape must be 2 x 2.

Returns:

a Matrix2x2 with identical SI data and display unit

Throws:

IllegalStateException - if this matrix is not 2 x 2

asMatrix3x3

public Matrix3x3<Q,U> asMatrix3x3()

Convert this matrix to a Matrix3x3. The shape must be 3 x 3.

Returns:

a Matrix3x3 with identical SI data and display unit

Throws:

IllegalStateException - if this matrix is not 3 x 3