Package org.djunits.vecmat.dnxm

Class MatrixNxM<Q extends Quantity<Q>>

java.lang.Object

org.djunits.vecmat.def.VectorMatrix<Q,T,SI,H,TT>

org.djunits.vecmat.def.Table<Q,M,SI,H,MT>

org.djunits.vecmat.def.Matrix<Q,MatrixNxM<Q>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q>>

org.djunits.vecmat.dnxm.MatrixNxM<Q>

Type Parameters:

Q - the quantity type

All Implemented Interfaces:

Serializable, Additive<MatrixNxM<Q>>, Scalable<MatrixNxM<Q>>, Value<MatrixNxM<Q>,Q>, Hadamard<MatrixNxM<?>,MatrixNxM<SIQuantity>>

public class MatrixNxM<Q extends Quantity<Q>>
extends Matrix<Q,MatrixNxM<Q>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q>>

MatrixNxM implements a matrix with NxM 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. MatrixNxN and VectorN extend from this class.

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
MatrixNxM(DataGridSi<?> dataGridSi, Unit<?,Q> displayUnit)	Create a new NxM Matrix with a unit, based on a DataGrid storage object that contains SI data.

Method Summary

Modifier and Type	Method	Description
<TQ extends Quantity<TQ>> MatrixNxM<TQ>	as(Unit<?,TQ> targetUnit)	Return the matrix 'as' a matrix with a known quantity, using a unit to express the result in.
int	cols()	Return the number of columns.
boolean	equals(Object obj)
double[]	getColumnSi(int col)	Return an array with SI-values for the given column (0-based) from the table or matrix.
VectorN.Col<Q>	getColumnVector(int col)	Return a quantity column (0-based) from the table or matrix.
DataGridSi<?>	getDataGrid()	Return the internal datagrid object, so we can retrieve data from it.
double[]	getRowSi(int row)	Return an array with SI-values for the given row (0-based) from the table or matrix.
VectorN.Row<Q>	getRowVector(int row)	Return a quantity row (0-based) from the table or matrix.
double[]	getSiArray()	Return a row-major array of SI-values for this matrix or vector.
int	hashCode()
MatrixNxM<Q>	instantiateSi(double[] siNew)	Return a new vector or matrix with the given SI or BASE values.
MatrixNxM<SIQuantity>	instantiateSi(double[] siNew, SIUnit siUnit)	Return a new vector or matrix in SI-units with the given SI or BASE values.
VectorN.Col<Q>	mgetColumnVector(int mCol)	Return a quantity column (1-based) from the table or matrix.
VectorN.Row<Q>	mgetRowVector(int mRow)	Return a quantity row (1-based) from the table or matrix.
MatrixNxM<SIQuantity>	multiply(Matrix1x1<?> matrix)	Multiply this vector or matrix with a Matrix1x1, resulting in a MatrixNxM.
MatrixNxM<SIQuantity>	multiply(Vector1<?> vector)	Multiply this vector or matrix with a Vector1, resulting in a MatrixNxM.
MatrixNxM<SIQuantity>	multiply(Matrix2x2<?> matrix)	Multiply this vector or matrix with a Matrix2x2, resulting in a MatrixNxM.
VectorN.Col<SIQuantity>	multiply(Vector2.Col<?> vector)	Multiply this vector or matrix with a Vector2.Col, resulting in a Vector2.Col.
MatrixNxM<SIQuantity>	multiply(Matrix3x3<?> matrix)	Multiply this vector or matrix with a Matrix3x3, resulting in a MatrixNxM.
VectorN.Col<SIQuantity>	multiply(Vector3.Col<?> vector)	Multiply this vector or matrix with a Vector3.Col, resulting in a Vector3.Col.
MatrixNxM<SIQuantity>	multiply(MatrixNxN<?> matrix)	Multiply this vector or matrix with a MatrixNxM, resulting in a MatrixNxM.
VectorN.Col<SIQuantity>	multiply(VectorN.Col<?> vector)	Multiply this vector or matrix with a VectorN.Col, resulting in a VectorN.Col.
int	nonZeroCount()	Return the number of non-zero entries in the vector, matrix or table.
static <Q extends Quantity<Q>> MatrixNxM<Q>	of(double[][] gridInUnit, Unit<?,Q> unit)	Create a new MatrixNxM with a unit, based on a 2-dimensional grid with values in the given unit.
static <Q extends Quantity<Q>> MatrixNxM<Q>	of(double[] dataInUnit, int rows, int cols, Unit<?,Q> unit)	Create a new MatrixNxM with a unit, based on a row-major array with values in the given unit.
static <Q extends Quantity<Q>> MatrixNxM<Q>	of(Q[][] grid)	Create a MatrixNxM without needing generics, based on a 2-dimensional grid of quantities.
static <Q extends Quantity<Q>> MatrixNxM<Q>	of(Q[] data, int rows, int cols)	Create a MatrixNxM without needing generics, based on a row-major array of quantities.
static <Q extends Quantity<Q>> MatrixNxM<Q>	ofSi(double[][] gridSi, Unit<?,Q> displayUnit)	Create a new MatrixNxM with a unit, based on a 2-dimensional grid with SI-values.
static <Q extends Quantity<Q>> MatrixNxM<Q>	ofSi(double[] dataSi, int rows, int cols, Unit<?,Q> displayUnit)	Create a MatrixNxM without needing generics, based on a row-major array with SI-values.
int	rows()	Return the number of rows.
double	si(int row, int col)	Return the si-value at position (row, col), where both row and col are 0-based values.
MatrixNxM<Q>	transpose()	Return the transposed matrix.
double[]	unsafeSiArray()	Return a row-major possibly UNSAFE array of SI-values for this matrix or vector.

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

format, format, format, multiply

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

checkCol, checkRow, get, getColumnScalars, getRowScalars, getScalarArray, getScalarGrid, getSiGrid, mcheckCol, mcheckRow, mget, mgetColumnScalars, mgetColumnSi, mgetRowScalars, mgetRowSi, msi

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

abs, add, add, asMatrix1x1, asMatrix2x2, asMatrix3x3, asMatrixNxM, asMatrixNxN, asQuantityTable, asVector1, asVector2Col, asVector2Row, asVector3Col, asVector3Row, asVectorNCol, asVectorNRow, checkMultiply, checkMultiply, divideElements, divideEntries, getDisplayUnit, invertEntries, isRelative, max, mean, median, min, multiplyElements, multiplyEntries, multiplyEntries, negate, nnz, scaleBy, setDisplayUnit, subtract, subtract, sum, 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

divideEntries

Methods inherited from interface org.djunits.value.Scalable

divideBy

Methods inherited from interface org.djunits.value.Value

isAbsolute, setDisplayUnit

Constructor Details

MatrixNxM

public MatrixNxM(DataGridSi<?> dataGridSi,
 Unit<?,Q> displayUnit)

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

Parameters:

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

instantiateSi

public MatrixNxM<Q> 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>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

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

instantiateSi

public MatrixNxM<SIQuantity> 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>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

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

getDataGrid

public DataGridSi<?> getDataGrid()

Return the internal datagrid object, so we can retrieve data from it.

Returns:

the internal datagrid object

getSiArray

public double[] getSiArray()

Description copied from class: VectorMatrix

Return a row-major array of SI-values for this matrix or vector. This is guaranteed to be a safe copy.

Specified by:

getSiArray in class VectorMatrix<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

Returns:

the row-major array of SI-values (safe copy)

unsafeSiArray

public double[] unsafeSiArray()

Description copied from class: VectorMatrix

Return a row-major possibly UNSAFE array of SI-values for this matrix or vector. The method might give access to the underlying data structure, so treat the data carefully.

Specified by:

unsafeSiArray in class VectorMatrix<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

Returns:

the row-major array of SI-values (safe copy)

si

public double si(int row,
 int col)
          throws IndexOutOfBoundsException

Description copied from class: Table

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

Specified by:

si in class Table<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

Parameters:

row - the row (0-based)

col - the column (0-based)

Returns:

the si-value at position (row, col)

Throws:

IndexOutOfBoundsException - when row or col < 0 or larger than number of rows/columns - 1.

getRowVector

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

Description copied from class: Table

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

Specified by:

getRowVector in class Table<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

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> mgetRowVector(int mRow)

Description copied from class: Table

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

Specified by:

mgetRowVector in class Table<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

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> getColumnVector(int col)

Description copied from class: Table

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

Specified by:

getColumnVector in class Table<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

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> mgetColumnVector(int mCol)

Description copied from class: Table

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

Specified by:

mgetColumnVector in class Table<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

Parameters:

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

Returns:

a column vector with the data at the given column

getRowSi

public double[] getRowSi(int row)

Description copied from class: Table

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

Specified by:

getRowSi in class Table<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

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: Table

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

Specified by:

getColumnSi in class Table<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

Parameters:

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

Returns:

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

rows

public int rows()

Description copied from class: VectorMatrix

Return the number of rows.

Specified by:

rows in class VectorMatrix<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

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>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

Returns:

the number of columns

nonZeroCount

public int nonZeroCount()

Description copied from class: VectorMatrix

Return the number of non-zero entries in the vector, matrix or table. Note that NaN and Infinity count as a non-zero element. The value -0.0 counts as 0.0.

Specified by:

nonZeroCount in class VectorMatrix<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

Returns:

the number of non-zero entries in the vector, matrix or table

transpose

public MatrixNxM<Q> transpose()

Return the transposed matrix. A transposed matrix has the same unit as the original one.

Specified by:

transpose in class VectorMatrix<Q extends Quantity<Q>,MatrixNxM<Q extends Quantity<Q>>,MatrixNxM<SIQuantity>,MatrixNxM<?>,MatrixNxM<Q extends Quantity<Q>>>

Returns:

the transposed matrix

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object obj)

Overrides:

equals in class Object

multiply

public MatrixNxM<SIQuantity> multiply(Matrix1x1<?> matrix)

Multiply this vector or matrix with a Matrix1x1, resulting in a MatrixNxM. The multiplication is a (Mx1) x (1x1) matrix multiplication resulting in an (Mx1) matrix.

Parameters:

matrix - the matrix to multiply with

Returns:

a MatrixNxM of an SIQuantity as the result of the matrix multiplication

Throws:

IllegalArgumentException - when the number of columns of this matrix does not equal the number of rows of the matrix or vector to multiply with

multiply

public MatrixNxM<SIQuantity> multiply(Matrix2x2<?> matrix)

Multiply this vector or matrix with a Matrix2x2, resulting in a MatrixNxM. The multiplication is a (Mx2) x (2x2) matrix multiplication resulting in an (Mx2) matrix.

Parameters:

matrix - the matrix to multiply with

Returns:

a MatrixNxM of an SIQuantity as the result of the matrix multiplication

Throws:

IllegalArgumentException - when the number of columns of this matrix does not equal the number of rows of the matrix or vector to multiply with

multiply

public MatrixNxM<SIQuantity> multiply(Matrix3x3<?> matrix)

Multiply this vector or matrix with a Matrix3x3, resulting in a MatrixNxM. The multiplication is a (Mx3) x (3x3) matrix multiplication resulting in an (Mx3) matrix.

Parameters:

matrix - the matrix to multiply with

Returns:

a MatrixNxM of an SIQuantity as the result of the matrix multiplication

Throws:

IllegalArgumentException - when the number of columns of this matrix does not equal the number of rows of the matrix or vector to multiply with

multiply

public MatrixNxM<SIQuantity> multiply(MatrixNxN<?> matrix)

Multiply this vector or matrix with a MatrixNxM, resulting in a MatrixNxM. The multiplication is a (NxM) x (MxP) matrix multiplication resulting in an (NxP) matrix.

Parameters:

matrix - the matrix to multiply with

Returns:

a MatrixNxM of an SIQuantity as the result of the matrix multiplication

Throws:

IllegalArgumentException - when the number of columns of this matrix does not equal the number of rows of the matrix or vector to multiply with

multiply

public MatrixNxM<SIQuantity> multiply(Vector1<?> vector)

Multiply this vector or matrix with a Vector1, resulting in a MatrixNxM. The multiplication is a (Mx1) x (1x1) matrix multiplication resulting in an (Mx1) matrix.

Parameters:

vector - the vector to multiply with

Returns:

a MatrixNxM of an SIQuantity as the result of the matrix multiplication

Throws:

IllegalArgumentException - when the number of columns of this matrix does not equal the number of rows of the vector to multiply with

multiply

public VectorN.Col<SIQuantity> multiply(Vector2.Col<?> vector)

Multiply this vector or matrix with a Vector2.Col, resulting in a Vector2.Col. The multiplication is a (Mx2) x (2x1) matrix multiplication resulting in an (Mx1) column vector.

Parameters:

vector - the vector to multiply with

Returns:

a VectorN.Col of an SIQuantity as the result of the matrix multiplication

Throws:

IllegalArgumentException - when the number of columns of this matrix does not equal the number of rows of the vector to multiply with

multiply

public VectorN.Col<SIQuantity> multiply(Vector3.Col<?> vector)

Multiply this vector or matrix with a Vector3.Col, resulting in a Vector3.Col. The multiplication is a (Mx3) x (3x1) matrix multiplication resulting in an (Mx1) column vector.

Parameters:

vector - the vector to multiply with

Returns:

a VectorN.Col of an SIQuantity as the result of the matrix multiplication

Throws:

IllegalArgumentException - when the number of columns of this matrix does not equal the number of rows of the vector to multiply with

multiply

public VectorN.Col<SIQuantity> multiply(VectorN.Col<?> vector)

Multiply this vector or matrix with a VectorN.Col, resulting in a VectorN.Col. The multiplication is a (MxN) x (Nx1) matrix multiplication resulting in an (Mx1) column vector.

Parameters:

vector - the vector to multiply with

Returns:

a VectorN.Col of an SIQuantity as the result of the matrix multiplication

Throws:

IllegalArgumentException - when the number of columns of this matrix does not equal the number of rows of the vector to multiply with

of

public static <Q extends Quantity<Q>> MatrixNxM<Q> of(double[] dataInUnit,
 int rows,
 int cols,
 Unit<?,Q> unit)

Create a new MatrixNxM with a unit, based on a row-major array with values in the given unit.

Type Parameters:

Q - the quantity type

Parameters:

dataInUnit - the matrix values {a11, a12, ..., A1M, ..., aN1, aN2, ..., aNM} expressed in the unit

rows - the number of rows

cols - the number of columns

unit - the unit of the data, also used as the display unit

Returns:

a new MatrixNxM with a unit

Throws:

IllegalArgumentException - when dataInUnit does not contain a square number of values

ofSi

public static <Q extends Quantity<Q>> MatrixNxM<Q> ofSi(double[] dataSi,
 int rows,
 int cols,
 Unit<?,Q> displayUnit)

Create a MatrixNxM without needing generics, based on a row-major array with SI-values.

Type Parameters:

Q - the quantity type

Parameters:

dataSi - the matrix values {a11, a12, ..., A1M, ..., aN1, aN2, ..., aNM} as an array using SI units

rows - the number of rows

cols - the number of columns

displayUnit - the display unit to use

Returns:

a new MatrixNxM with a unit

Throws:

IllegalArgumentException - when dataSi does not contain a square number of values

of

public static <Q extends Quantity<Q>> MatrixNxM<Q> of(Q[] data,
 int rows,
 int cols)

Create a MatrixNxM without needing generics, based on a row-major array of quantities. The unit is taken from the first quantity in the array.

Type Parameters:

Q - the quantity type

Parameters:

data - the matrix values {a11, a12, ..., A1M, ..., aN1, aN2, ..., aNM} expressed as an array of quantities

rows - the number of rows

cols - the number of columns

Returns:

a new MatrixNxM with a unit

Throws:

IllegalArgumentException - when data does not contain a square number of quantities

ofSi

public static <Q extends Quantity<Q>> MatrixNxM<Q> ofSi(double[][] gridSi,
 Unit<?,Q> displayUnit)

Create a new MatrixNxM with a unit, based on a 2-dimensional grid with SI-values.

Type Parameters:

Q - the quantity type

Parameters:

gridSi - the matrix values {{a11, a12, ..., A1M}, ..., {aN1, aN2, ..., aNM}} expressed in the SI or base unit

displayUnit - the unit of the data, which will also be used as the display unit

Returns:

a new MatrixNxM with a unit

Throws:

IllegalArgumentException - when dataInUnit does not contain a square number of values

of

public static <Q extends Quantity<Q>> MatrixNxM<Q> of(double[][] gridInUnit,
 Unit<?,Q> unit)

Create a new MatrixNxM with a unit, based on a 2-dimensional grid with values in the given unit.

Type Parameters:

Q - the quantity type

Parameters:

gridInUnit - the matrix values {{a11, a12, ..., A1M}, ..., {aN1, aN2, ..., aNM}} expressed in the unit

unit - the unit of the values, also used as the display unit

Returns:

a new MatrixNxM with a unit

Throws:

IllegalArgumentException - when dataInUnit does not contain a square number of values

of

public static <Q extends Quantity<Q>> MatrixNxM<Q> of(Q[][] grid)

Create a MatrixNxM without needing generics, based on a 2-dimensional grid of quantities. The unit is taken from the first quantity in the grid.

Type Parameters:

Q - the quantity type

Parameters:

grid - the matrix values {{a11, a12, ..., A1M}, ..., {aN1, aN2, ..., aNM}} expressed as a 2-dimensional array of quantities

Returns:

a new MatrixNxM with a unit

Throws:

IllegalArgumentException - when dataInUnit does not contain a square number of quantities

as

public <TQ extends Quantity<TQ>> MatrixNxM<TQ> as(Unit<?,TQ> targetUnit)
                                           throws IllegalArgumentException

Return the matrix 'as' a matrix with a known quantity, using a unit to express the result in. Throw a Runtime exception when the SI units of this vector and the target vector do not match.

Type Parameters:

TQ - target quantity type

Parameters:

targetUnit - the unit to convert the matrix to

Returns:

a matrix typed in the target matrix class

Throws:

IllegalArgumentException - when the units do not match