VectorMatrix.java
package org.djunits.vecmat.def;
import java.lang.reflect.Array;
import org.djunits.formatter.Format;
import org.djunits.quantity.Dimensionless;
import org.djunits.quantity.SIQuantity;
import org.djunits.quantity.def.Quantity;
import org.djunits.unit.UnitInterface;
import org.djunits.unit.si.SIUnit;
import org.djunits.util.ArrayMath;
import org.djunits.util.Math2;
import org.djunits.value.Additive;
import org.djunits.value.Scalable;
import org.djunits.value.Value;
import org.djunits.vecmat.dnxm.MatrixNxM;
import org.djunits.vecmat.operations.Hadamard;
import org.djunits.vecmat.storage.DenseDoubleDataSi;
import org.djunits.vecmat.table.QuantityTable;
import org.djutils.exceptions.Throw;
/**
* VectorMatrix contains a number of standard operations on vectors and matrices of relative quantities.
* <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
* @param <U> the unit type
* @param <VM> the 'SELF' vector or matrix type
* @param <SI> the vector or matrix type with generics <SIQuantity, SIUnit<
* @param <H> the generic vector or matrix type with generics <?, ?< for Hadamard operations
*/
public abstract class VectorMatrix<Q extends Quantity<Q, U>, U extends UnitInterface<U, Q>,
VM extends VectorMatrix<Q, U, VM, SI, H>, SI extends VectorMatrix<SIQuantity, SIUnit, SI, ?, ?>,
H extends VectorMatrix<?, ?, ?, ?, ?>> implements Value<U, VM>, Scalable<VM>, Additive<VM>, Hadamard<H, SI>
{
/** */
private static final long serialVersionUID = 600L;
/** The display unit. */
private U displayUnit;
/**
* Create a new vector or matrix with a unit.
* @param displayUnit the display unit to use
*/
public VectorMatrix(final U displayUnit)
{
Throw.whenNull(displayUnit, "displayUnit");
this.displayUnit = displayUnit;
}
@Override
public U getDisplayUnit()
{
return this.displayUnit;
}
@SuppressWarnings("unchecked")
@Override
public VM setDisplayUnit(final U newUnit)
{
Throw.whenNull(this.displayUnit, "displayUnit");
this.displayUnit = newUnit;
return (VM) this;
}
/**
* Return the number of rows.
* @return the number of rows
*/
public abstract int rows();
/**
* Return the number of columns.
* @return the number of columns
*/
public abstract int cols();
/**
* Return a new vector or matrix with the given SI or BASE values.
* @param siNew the values for the new vector or matrix in row-major format
* @return a new matrix with the provided SI or BASE values
*/
public abstract VM instantiateSi(double[] siNew);
/**
* Return a new vector or matrix in SI-units with the given SI or BASE values.
* @param siNew the values for the new vector or matrix in row-major format
* @param siUnit the new unit for the new vector or matrix
* @return a new matrix with the provided SI or BASE values
*/
public abstract SI instantiateSi(double[] siNew, SIUnit siUnit);
/**
* Return a row-major array of SI-values for this matrix or vector. Note that this is NOT a safe copy.
* @return the row-major array of SI-values
*/
public abstract double[] si();
/**
* Return the si-value at position (row, col), where both row and col are 0-based values.
* @param row the row (0-based)
* @param col the column (0-based)
* @return the si-value at position (row, col)
* @throws IndexOutOfBoundsException when row or col < 0 or larger than number of rows/columns - 1.
*/
public abstract double si(int row, int col) throws IndexOutOfBoundsException;
/**
* Return the si-value at position (row, col), where both row and col are 1-based values.
* @param mRow the row (1-based)
* @param mCol the column (1-based)
* @return the si-value at position (row, col)
* @throws IndexOutOfBoundsException when row or col < 1 or larger than number of rows/columns.
*/
public double msi(final int mRow, final int mCol) throws IndexOutOfBoundsException
{
return si(mRow - 1, mCol - 1);
}
/**
* Return the quantity at position (row, col), where both row and col are 0-based values.
* @param row the row (0-based)
* @param col the column (0-based)
* @return the quantity at position (row, col)
* @throws IndexOutOfBoundsException when row or col < 0 or larger than number of rows/columns - 1.
*/
public Q get(final int row, final int col) throws IndexOutOfBoundsException
{
return getDisplayUnit().ofSi(si(row, col)).setDisplayUnit(getDisplayUnit());
}
/**
* Return the quantity at position (row, col), where both row and col are 1-based values.
* @param mRow the row (1-based)
* @param mCol the column (1-based)
* @return the quantity at position (row, col)
* @throws IndexOutOfBoundsException when row or col < 1 or larger than number of rows/columns.
*/
public Q mget(final int mRow, final int mCol) throws IndexOutOfBoundsException
{
return getDisplayUnit().ofSi(msi(mRow, mCol)).setDisplayUnit(getDisplayUnit());
}
/**
* Return the vector or matrix as a 2D array of scalars.
* @return a new Q[rows()][cols()] array; entry [i-1][j-1] contains get(i, j).
*/
@SuppressWarnings("unchecked") // cast from Array.newInstance(...) to Q[][]
public Q[][] getScalarGrid()
{
// Determine the runtime type of Q using the first cell; constructors guarantee rows, cols >= 0.
final Q first = get(0, 0);
final Class<?> qClass = first.getClass();
// Allocate a Q[rows()][cols()] array and fill it.
final Q[][] out = (Q[][]) Array.newInstance(qClass, rows(), cols());
for (int i = 0; i < rows(); i++)
{
for (int j = 0; j < cols(); j++)
{
out[i][j] = get(i, j);
}
}
return out;
}
/**
* 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.
* @param row the row number to retrieve (0-based)
* @return a row vector with the data at the given row
*/
public abstract Vector<Q, U, ?, ?, ?> getRowVector(int row);
/**
* 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.
* @param mRow the row number to retrieve (1-based)
* @return a row vector with the data at the given row
*/
public abstract Vector<Q, U, ?, ?, ?> mgetRowVector(int mRow);
/**
* 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.
* @param col the column number to retrieve (0-based)
* @return a column vector with the data at the given column
*/
public abstract Vector<Q, U, ?, ?, ?> getColumnVector(int col);
/**
* 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.
* @param mCol the column number to retrieve (1-based)
* @return a column vector with the data at the given column
*/
public abstract Vector<Q, U, ?, ?, ?> mgetColumnVector(int mCol);
/**
* Return an array with SI-values for the given row (0-based) from the vector or matrix.
* @param row the row number to retrieve (0-based)
* @return an array with SI-values with the data at the given row
*/
public abstract double[] getRowSi(int row);
/**
* Return an array with SI-values for the given row (1-based) from the vector or matrix.
* @param mRow the row number to retrieve (1-based)
* @return an array with SI-values with the data at the given row
*/
public double[] mgetRowSi(final int mRow)
{
mcheckRow(mRow);
return getRowSi(mRow - 1);
}
/**
* Return an array with SI-values for the given column (0-based) from the vector or matrix.
* @param col the column number to retrieve (0-based)
* @return an array with SI-values with the data at the given column
*/
public abstract double[] getColumnSi(int col);
/**
* Return an array with SI-values for the given column (1-based) from the vector or matrix.
* @param mCol the column number to retrieve (1-based)
* @return an array with SI-values with the data at the given column
*/
public double[] mgetColumnSi(final int mCol)
{
mcheckCol(mCol);
return getColumnSi(mCol - 1);
}
@Override
public boolean isRelative()
{
return get(0, 0).isRelative();
}
/**
* Check if the 0-based row is within bounds.
* @param row the 0-based row to check
* @throws IndexOutOfBoundsException when row is out of bounds
*/
protected void checkRow(final int row)
{
Throw.when(row < 0 || row >= rows(), IndexOutOfBoundsException.class, "Row %d out of bounds [0..%d]", row, rows() - 1);
}
/**
* Check if the 0-based column is within bounds.
* @param col the 0-based column to check
* @throws IndexOutOfBoundsException when column is out of bounds
*/
protected void checkCol(final int col)
{
Throw.when(col < 0 || col >= cols(), IndexOutOfBoundsException.class, "Column %d out of bounds [0..%d]", col,
cols() - 1);
}
/**
* Check if the 1-based row is within bounds.
* @param mRow the 1-based row to check
* @throws IndexOutOfBoundsException when row is out of bounds
*/
protected void mcheckRow(final int mRow)
{
Throw.when(mRow < 1 || mRow > rows(), IndexOutOfBoundsException.class, "Row %d out of bounds [1..%d]", mRow, rows());
}
/**
* Check if the 1-based column is within bounds.
* @param mCol the 1-based column to check
* @throws IndexOutOfBoundsException when column is out of bounds
*/
protected void mcheckCol(final int mCol)
{
Throw.when(mCol < 1 || mCol > cols(), IndexOutOfBoundsException.class, "Column %d out of bounds [1..%d]", mCol, cols());
}
/**
* Retrieve a row (0-based) from the matrix as an array of scalars.
* @param row row of the values to retrieve (0-based)
* @return the row as a Scalar array
* @throws IndexOutOfBoundsException in case row is out of bounds
*/
@SuppressWarnings("unchecked")
public Q[] getRowScalars(final int row) throws IndexOutOfBoundsException
{
checkRow(row);
// Build a Q[] of length cols() using the runtime class of the first element
Q first = get(row, 0);
Q[] out = (Q[]) Array.newInstance(first.getClass(), cols());
for (int c = 0; c < cols(); c++)
{
out[c] = get(row, c);
}
return out;
}
/**
* Retrieve a row (1-based) from the matrix as an array of scalars.
* @param mRow row of the values to retrieve (1-based)
* @return the row as a Scalar array
* @throws IndexOutOfBoundsException in case row is out of bounds
*/
public Q[] mgetRowScalars(final int mRow) throws IndexOutOfBoundsException
{
mcheckRow(mRow);
return getRowScalars(mRow - 1);
}
/**
* Retrieve a column (0-based) from the matrix as an array of scalars.
* @param col column of the values to retrieve (0-based)
* @return the column as a Scalar array
* @throws IndexOutOfBoundsException in case column is out of bounds
*/
@SuppressWarnings("unchecked")
public Q[] getColumnScalars(final int col) throws IndexOutOfBoundsException
{
checkCol(col);
Q first = get(0, col);
Q[] out = (Q[]) Array.newInstance(first.getClass(), rows());
for (int r = 0; r < rows(); r++)
{
out[r] = get(r, col);
}
return out;
}
/**
* Retrieve a column (1-based) from the matrix as an array of scalars.
* @param mCol column of the values to retrieve (1-based)
* @return the column as a Scalar array
* @throws IndexOutOfBoundsException in case column is out of bounds
*/
public Q[] mgetColumnScalars(final int mCol) throws IndexOutOfBoundsException
{
mcheckCol(mCol);
return getColumnScalars(mCol - 1);
}
/**
* Return the mean value of the elements of the vector or matrix.
* @return the mean value of the elements of the vector or matrix
*/
public Q mean()
{
return getDisplayUnit().ofSi(sum().si() / si().length).setDisplayUnit(getDisplayUnit());
}
/**
* Return the minimum value of the elements of the vector or matrix.
* @return the minimum value of the elements of the vector or matrix
*/
public Q min()
{
return getDisplayUnit().ofSi(Math2.min(si())).setDisplayUnit(getDisplayUnit());
}
/**
* Return the maximum value of the elements of the vector or matrix.
* @return the maximum value of the elements of the vector or matrix
*/
public Q max()
{
return getDisplayUnit().ofSi(Math2.max(si())).setDisplayUnit(getDisplayUnit());
}
/**
* Return the largest value of the elements of the vector or matrix.
* @return the largest value of the elements of the vector or matrix
*/
public Q mode()
{
return max();
}
/**
* Return the median value of the elements of the vector or matrix.
* @return the median value of the elements of the vector or matrix
*/
public Q median()
{
return getDisplayUnit().ofSi(Math2.median(si())).setDisplayUnit(getDisplayUnit());
}
/**
* Return the sum of the values of the elements of the vector or matrix.
* @return the sum of the values of the elements of the vector or matrix
*/
public Q sum()
{
return getDisplayUnit().ofSi(Math2.sum(si())).setDisplayUnit(getDisplayUnit());
}
/**
* Return the a vector or matrix with entries that contain the sum of the element and the increment.
* @param increment the quantity by which to increase the values of the vector or matrix
* @return a vector or matrix with elements that are incremented by the given quantity
*/
public VM add(final Q increment)
{
return instantiateSi(ArrayMath.add(si(), increment.si()));
}
/**
* Return the a vector or matrix with entries that contain the value minus the decrement.
* @param decrement the quantity by which to decrease the values of the vector or matrix
* @return a vector or matrix with elements that are decremented by the given quantity
*/
public VM subtract(final Q decrement)
{
return instantiateSi(ArrayMath.add(si(), -decrement.si()));
}
@Override
public VM add(final VM other)
{
return instantiateSi(ArrayMath.add(si(), other.si()));
}
@Override
public VM subtract(final VM other)
{
return instantiateSi(ArrayMath.subtract(si(), other.si()));
}
@Override
public VM negate()
{
return scaleBy(-1.0);
}
@Override
public VM abs()
{
return instantiateSi(ArrayMath.abs(si()));
}
@Override
public VM scaleBy(final double factor)
{
return instantiateSi(ArrayMath.scaleBy(si(), factor));
}
/**
* Multiply the elements of this vector, matrix or table by the given quantity. This is actually a Hadamard operation, but
* since it is equivalent to a scaleBy operation, it is included in this interface.
* @param quantity the scalar quantity to multiply by
* @return a vector, matrix or table where the elements have been multiplied by the given quantity
*/
public VM multiplyElements(final Dimensionless quantity)
{
return scaleBy(quantity.si());
}
/**
* Multiply the elements of this vector, matrix or table by the given quantity. This is actually a Hadamard operation, but
* since it is equivalent to a scaleBy operation, it is included in this interface.
* @param quantity the scalar quantity to multiply by
* @return a vector, matrix or table where the elements have been multiplied by the given quantity
*/
public VM divideElements(final Dimensionless quantity)
{
return scaleBy(1.0 / quantity.si());
}
@Override
public SI invertElements()
{
return (SI) instantiateSi(ArrayMath.reciprocal(si()), getDisplayUnit().siUnit().invert());
}
@Override
public SI multiplyElements(final H other)
{
return (SI) instantiateSi(ArrayMath.multiply(si(), other.si()),
getDisplayUnit().siUnit().plus(other.getDisplayUnit().siUnit()));
}
@Override
public SI divideElements(final H other)
{
return (SI) instantiateSi(ArrayMath.divide(si(), other.si()),
getDisplayUnit().siUnit().minus(other.getDisplayUnit().siUnit()));
}
@Override
public SI multiplyElements(final Quantity<?, ?> quantity)
{
return (SI) instantiateSi(ArrayMath.scaleBy(si(), quantity.si()),
getDisplayUnit().siUnit().plus(quantity.getDisplayUnit().siUnit()));
}
/**
* Convert this vector or matrix to a {@link MatrixNxM}.
* @return a {@code MatrixNxN} with identical SI data and display unit
*/
public MatrixNxM<Q, U> asMatrixNxM()
{
return new MatrixNxM<Q, U>(new DenseDoubleDataSi(si(), rows(), cols()), getDisplayUnit().getBaseUnit())
.setDisplayUnit(getDisplayUnit());
}
/**
* Convert this vector or matrix to a {@link QuantityTable}.
* @return a {@code QuantityTable} with identical SI data and display unit
*/
public QuantityTable<Q, U> asQuantityTable()
{
return new QuantityTable<Q, U>(new DenseDoubleDataSi(si(), rows(), cols()), getDisplayUnit().getBaseUnit())
.setDisplayUnit(getDisplayUnit());
}
@SuppressWarnings("checkstyle:needbraces")
@Override
public String toString(final U withUnit)
{
var s = new StringBuilder();
for (int r = 0; r < rows(); r++)
{
s.append(r == 0 ? "[" : "\n ");
for (int c = 0; c < cols(); c++)
{
if (c > 0)
s.append(", ");
s.append(Format.format(withUnit.fromBaseValue(si(r, c))));
}
}
s.append("] ");
s.append(withUnit.getDisplayAbbreviation());
return s.toString();
}
@Override
public String toString()
{
return toString(getDisplayUnit());
}
}