Matrix3x3.java
package org.djunits.vecmat.d3;
import org.djunits.quantity.SIQuantity;
import org.djunits.quantity.def.Quantity;
import org.djunits.unit.Unit;
import org.djunits.unit.si.SIUnit;
import org.djunits.util.ArrayMath;
import org.djunits.util.MatrixMath;
import org.djunits.vecmat.NonInvertibleMatrixException;
import org.djunits.vecmat.def.SquareDenseMatrix;
import org.djutils.exceptions.Throw;
/**
* Matrix3x3 implements a matrix with 3x3 real-valued entries. The matrix is immutable, except for the display unit, which can
* be changed.
* <p>
* Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See
* for project information <a href="https://djunits.org" target="_blank">https://djunits.org</a>. The DJUNITS project is
* distributed under a <a href="https://djunits.org/docs/license.html" target="_blank">three-clause BSD-style license</a>.
* @author Alexander Verbraeck
* @param <Q> the quantity type
*/
public class Matrix3x3<Q extends Quantity<Q>> extends SquareDenseMatrix<Q, Matrix3x3<Q>, Matrix3x3<SIQuantity>, Matrix3x3<?>>
{
/** */
private static final long serialVersionUID = 600L;
/**
* Create a new Matrix3x3 with a unit.
* @param dataSi the matrix values [a11, a12, a13, a21, a22, a23, a31, a32, a33] expressed in the SI-unit
* @param displayUnit the display unit for the matrix
*/
protected Matrix3x3(final double[] dataSi, final Unit<?, Q> displayUnit)
{
super(dataSi, displayUnit, 3);
}
@Override
public Matrix3x3<Q> instantiateSi(final double[] siNew)
{
return new Matrix3x3<Q>(siNew, getDisplayUnit());
}
@Override
public Matrix3x3<SIQuantity> instantiateSi(final double[] siNew, final SIUnit siUnit)
{
return new Matrix3x3<SIQuantity>(siNew, siUnit);
}
@Override
public Vector3.Row<Q> getRowVector(final int row)
{
checkRow(row);
return new Vector3.Row<Q>(si(row, 0), si(row, 1), si(row, 2), getDisplayUnit());
}
@Override
public Vector3.Row<Q> mgetRowVector(final int mRow)
{
mcheckRow(mRow);
return new Vector3.Row<Q>(msi(mRow, 1), msi(mRow, 2), msi(mRow, 3), getDisplayUnit());
}
@Override
public Vector3.Col<Q> getColumnVector(final int col)
{
checkCol(col);
return new Vector3.Col<Q>(si(0, col), si(1, col), si(2, col), getDisplayUnit());
}
@Override
public Vector3.Col<Q> mgetColumnVector(final int mCol)
{
mcheckCol(mCol);
return new Vector3.Col<Q>(msi(1, mCol), msi(2, mCol), msi(3, mCol), getDisplayUnit());
}
@Override
public Vector3.Col<Q> getDiagonalVector() throws IllegalStateException
{
return new Vector3.Col<Q>(si(0, 0), si(1, 1), si(2, 2), getDisplayUnit());
}
@Override
public Matrix3x3<SIQuantity> inverse() throws NonInvertibleMatrixException
{
double[] invData = MatrixMath.inverse(unsafeSiArray(), 3);
return new Matrix3x3<SIQuantity>(invData, getDisplayUnit().siUnit().invert());
}
@Override
public Matrix3x3<SIQuantity> adjugate()
{
double[] invData = MatrixMath.adjugate(unsafeSiArray(), 3);
return new Matrix3x3<SIQuantity>(invData, getDisplayUnit().siUnit().pow(order() - 1));
}
@Override
public Matrix3x3<SIQuantity> invertEntries()
{
SIUnit siUnit = getDisplayUnit().siUnit().invert();
return new Matrix3x3<SIQuantity>(ArrayMath.reciprocal(unsafeSiArray()), siUnit);
}
@Override
public Matrix3x3<SIQuantity> multiplyEntries(final Matrix3x3<?> other)
{
SIUnit siUnit = SIUnit.add(getDisplayUnit().siUnit(), other.getDisplayUnit().siUnit());
return new Matrix3x3<SIQuantity>(ArrayMath.multiply(unsafeSiArray(), other.unsafeSiArray()), siUnit);
}
@Override
public Matrix3x3<SIQuantity> divideEntries(final Matrix3x3<?> other)
{
SIUnit siUnit = SIUnit.subtract(getDisplayUnit().siUnit(), other.getDisplayUnit().siUnit());
return new Matrix3x3<SIQuantity>(ArrayMath.divide(unsafeSiArray(), other.unsafeSiArray()), siUnit);
}
// ------------------------------ MATRIX MULTIPLICATION -----------------------------------
/**
* Multiply this matrix with another matrix using matrix multiplication and return the result.
* @param otherMat the matrix to multiply with.
* @return the matrix from the multiplication with the correct unit
*/
public Matrix3x3<SIQuantity> multiply(final Matrix3x3<?> otherMat)
{
checkMultiply(otherMat);
double[] resultData = MatrixMath.multiply(unsafeSiArray(), otherMat.unsafeSiArray(), 3, 3, 3);
return new Matrix3x3<SIQuantity>(resultData, getDisplayUnit().siUnit().plus(otherMat.getDisplayUnit().siUnit()));
}
/**
* Multiply this matrix with a column vector, resulting in a column vector.
* @param otherVec the column vector to multiply with
* @return the resulting vector from the multiplication
*/
public Vector3.Col<SIQuantity> multiply(final Vector3.Col<?> otherVec)
{
checkMultiply(otherVec);
double[] resultData = MatrixMath.multiply(unsafeSiArray(), otherVec.unsafeSiArray(), 3, 3, 1);
return new Vector3.Col<SIQuantity>(resultData[0], resultData[1], resultData[2],
getDisplayUnit().siUnit().plus(otherVec.getDisplayUnit().siUnit()));
}
@Override
public Matrix3x3<SIQuantity> multiplyEntries(final Quantity<?> quantity)
{
SIUnit siUnit = SIUnit.add(getDisplayUnit().siUnit(), quantity.getDisplayUnit().siUnit());
return new Matrix3x3<SIQuantity>(ArrayMath.scaleBy(unsafeSiArray(), quantity.si()), siUnit);
}
// ------------------------------------------ OF METHODS ------------------------------------------
/**
* Create a new Matrix3x3 with a unit, based on a row-major array with values in the given unit.
* @param dataInUnit the matrix values {a11, a12, 13, ..., a31, a32, a33} expressed in the unit
* @param unit the unit of the data, also used as the display unit
* @param <Q> the quantity type
* @return a new Matrix3x3 with a unit
* @throws IllegalArgumentException when dataInUnit does not contain 3x3 = 9 values
*/
public static <Q extends Quantity<Q>> Matrix3x3<Q> of(final double[] dataInUnit, final Unit<?, Q> unit)
{
Throw.whenNull(dataInUnit, "dataInUnit");
Throw.whenNull(unit, "unit");
Throw.when(dataInUnit.length != 9, IllegalArgumentException.class, "Length of array != 9 but %d", dataInUnit.length);
double[] dataSi = new double[9];
for (int i = 0; i < 9; i++)
{
dataSi[i] = unit.toBaseValue(dataInUnit[i]);
}
return new Matrix3x3<Q>(dataSi, unit);
}
/**
* Create a Matrix3x3 without needing generics, based on a row-major array with SI-values.
* @param dataSi the matrix values {a11, a12, 13, ..., a31, a32, a33} as an array using SI units
* @param displayUnit the display unit to use
* @return a new Matrix3x3 with a unit
* @param <Q> the quantity type
* @throws IllegalArgumentException when dataSi does not contain 3x3 = 9 values
*/
public static <Q extends Quantity<Q>> Matrix3x3<Q> ofSi(final double[] dataSi, final Unit<?, Q> displayUnit)
{
Throw.whenNull(dataSi, "dataSi");
Throw.whenNull(displayUnit, "displayUnit");
Throw.when(dataSi.length != 9, IllegalArgumentException.class, "Length of dataSi != 9 but %d", dataSi.length);
return new Matrix3x3<>(dataSi, displayUnit);
}
/**
* Create a Matrix3x3 without needing generics, based on a row-major array of quantities. The unit is taken from the first
* quantity in the array.
* @param data the matrix values {a11, a12, 13, ..., a31, a32, a33} expressed as an array of quantities
* @return a new Matrix3x3 with a unit
* @param <Q> the quantity type
* @throws IllegalArgumentException when data does not contain 3x3 = 9 quantities
*/
public static <Q extends Quantity<Q>> Matrix3x3<Q> of(final Q[] data)
{
Throw.whenNull(data, "data");
Throw.when(data.length != 9, IllegalArgumentException.class, "Length of data != 9 but %d", data.length);
double[] dataSi = new double[9];
for (int i = 0; i < 9; i++)
{
Throw.whenNull(data[i], "data[%d] = null", i);
dataSi[i] = data[i].si();
}
return new Matrix3x3<>(dataSi, data[0].getDisplayUnit());
}
/**
* Create a new Matrix3x3 with a unit, based on a 2-dimensional grid with SI-values.
* @param gridSi the matrix values {{a11, a12, 13}, ..., {a31, a32, a33}} expressed in the SI or base unit
* @param displayUnit the unit of the data, which will also be used as the display unit
* @param <Q> the quantity type
* @return a new Matrix3x3 with a unit
* @throws IllegalArgumentException when dataInUnit does not contain 3x3 = 9 values
*/
@SuppressWarnings("checkstyle:needbraces")
public static <Q extends Quantity<Q>> Matrix3x3<Q> ofSi(final double[][] gridSi, final Unit<?, Q> displayUnit)
{
Throw.whenNull(gridSi, "gridSi");
Throw.whenNull(displayUnit, "displayUnit");
Throw.when(gridSi.length != 3, IllegalArgumentException.class, "gridSi does not have 3 rows");
double[] dataSi = new double[9];
for (int r = 0; r < 3; r++)
{
Throw.whenNull(gridSi[r], "gridSi[%d][] = null", r);
Throw.when(gridSi[r].length != 3, IllegalArgumentException.class, "gridSi is not a 3x3 array");
for (int c = 0; c < 3; c++)
{
dataSi[r * 3 + c] = gridSi[r][c];
}
}
return new Matrix3x3<>(dataSi, displayUnit);
}
/**
* Create a new Matrix3x3 with a unit, based on a 2-dimensional grid with values in the given unit.
* @param gridInUnit the matrix values {{a11, a12, 13}, ..., {a31, a32, a33}} expressed in the unit
* @param unit the unit of the values, also used as the display unit
* @param <Q> the quantity type
* @return a new Matrix3x3 with a unit
* @throws IllegalArgumentException when dataInUnit does not contain 3x3 = 9 values
*/
@SuppressWarnings("checkstyle:needbraces")
public static <Q extends Quantity<Q>> Matrix3x3<Q> of(final double[][] gridInUnit, final Unit<?, Q> unit)
{
Throw.whenNull(gridInUnit, "gridInUnit");
Throw.whenNull(unit, "unit");
Throw.when(gridInUnit.length != 3, IllegalArgumentException.class, "gridInUnit does not have 3 rows");
double[] dataSi = new double[9];
for (int r = 0; r < 3; r++)
{
Throw.whenNull(gridInUnit[r], "gridInUnit[%d][] = null", r);
Throw.when(gridInUnit[r].length != 3, IllegalArgumentException.class, "gridInUnit is not a 3x3 array");
for (int c = 0; c < 3; c++)
{
dataSi[r * 3 + c] = unit.toBaseValue(gridInUnit[r][c]);
}
}
return new Matrix3x3<>(dataSi, unit);
}
/**
* Create a Matrix3x3 without needing generics, based on a 2-dimensional grid of quantities. The unit is taken from the
* first quantity in the grid.
* @param grid the matrix values {{a11, a12, 13}, ..., {a31, a32, a33}} expressed as a 2-dimensional array of quantities
* @return a new Matrix3x3 with a unit
* @param <Q> the quantity type
* @throws IllegalArgumentException when dataInUnit does not contain 3x3 = 9 quantities
*/
public static <Q extends Quantity<Q>> Matrix3x3<Q> of(final Q[][] grid)
{
Throw.whenNull(grid, "grid");
Throw.when(grid.length != 3, IllegalArgumentException.class, "grid does not have 3 rows");
double[] dataSi = new double[9];
for (int r = 0; r < 3; r++)
{
Throw.whenNull(grid[r], "grid[%d][] = null", r);
Throw.when(grid[r].length != 3, IllegalArgumentException.class, "grid is not a 3x3 array");
for (int c = 0; c < 3; c++)
{
Throw.whenNull(grid[r][c], "grid[%d][%d] = null", r, c);
dataSi[r * 3 + c] = grid[r][c].si();
}
}
return new Matrix3x3<>(dataSi, grid[0][0].getDisplayUnit());
}
// ------------------------------------------ AS METHODS ------------------------------------------
/**
* 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.
* @param targetUnit the unit to convert the matrix to
* @return a matrix typed in the target matrix class
* @throws IllegalArgumentException when the units do not match
* @param <TQ> target quantity type
*/
public <TQ extends Quantity<TQ>> Matrix3x3<TQ> as(final Unit<?, TQ> targetUnit) throws IllegalArgumentException
{
Throw.when(!getDisplayUnit().siUnit().equals(targetUnit.siUnit()), IllegalArgumentException.class,
"Matrix3x3.as(%s) called, but units do not match: %s <> %s", targetUnit,
getDisplayUnit().siUnit().getDisplayAbbreviation(), targetUnit.siUnit().getDisplayAbbreviation());
return new Matrix3x3<TQ>(unsafeSiArray(), targetUnit);
}
}