Package org.djunits.vecmat.def

Class VectorMatrix<Q extends Quantity<Q>,VM extends VectorMatrix<Q,VM,SI,H,VMT>,SI extends VectorMatrix<SIQuantity,SI,?,?,?>,H extends VectorMatrix<?,?,?,?,?>,VMT extends VectorMatrix<Q,VMT,?,?,VM>>

java.lang.Object
org.djunits.vecmat.def.VectorMatrix<Q,VM,SI,H,VMT>
Type Parameters:
Q - the quantity type
VM - the 'SELF' vector or matrix type
SI - the vector or matrix type with generics <SIQuantity, SIUnit<
H - the generic vector or matrix type with generics <?, ?< for Hadamard operations
VMT - the type of the transposed version of the vector or matrix
All Implemented Interfaces:
Serializable, Additive<VM>, Scalable<VM>, Value<VM,Q>, Hadamard<H,SI>
Direct Known Subclasses:
Table, Vector
public abstract class VectorMatrix<Q extends Quantity<Q>,VM extends VectorMatrix<Q,VM,SI,H,VMT>,SI extends VectorMatrix<SIQuantity,SI,?,?,?>,H extends VectorMatrix<?,?,?,?,?>,VMT extends VectorMatrix<Q,VMT,?,?,VM>> extends Object implements Value<VM,Q>, Scalable<VM>, Additive<VM>, Hadamard<H,SI>
VectorMatrix contains a number of standard operations on vectors and matrices of relative quantities.

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:

  • Constructor Summary

    Constructors
    Constructor
    Description
    VectorMatrix(Unit<?,Q> displayUnit)
    Create a new vector or matrix with a unit.

  • Method Summary

    Modifier and Type
    Method
    Description
    VM
    abs()
    Make the SI-values of this element absolute.
    VM
    add(Q increment)
    Return the a vector or matrix with entries that contain the sum of the element and the increment.
    VM
    add(VM other)
    Add an element to this element, based on the SI-values.
    Matrix1x1<Q>
    asMatrix1x1()
    Convert this vector, matrix or table to a Matrix1x1.
    Matrix2x2<Q>
    asMatrix2x2()
    Convert this vector, matrix or table to a Matrix2x2.
    Matrix3x3<Q>
    asMatrix3x3()
    Convert this vector, matrix or table to a Matrix3x3.
    MatrixNxM<Q>
    asMatrixNxM()
    Convert this vector or matrix to a MatrixNxM.
    MatrixNxN<Q>
    asMatrixNxN()
    Convert this vector, matrix or table to a MatrixNxN.
    QuantityTable<Q>
    asQuantityTable()
    Convert this vector or matrix to a QuantityTable.
    Vector1<Q>
    asVector1()
    Return this vector, matrix or table as a 1-element column vector.
    Vector2.Col<Q>
    asVector2Col()
    Return this vector, matrix or table as a 2-element column vector.
    Vector2.Row<Q>
    asVector2Row()
    Return this vector, matrix or table as a 2-element row vector.
    Vector3.Col<Q>
    asVector3Col()
    Return this vector, matrix or table as a 3-element column vector.
    Vector3.Row<Q>
    asVector3Row()
    Return this vector, matrix or table as a 3-element row vector.
    VectorN.Col<Q>
    asVectorNCol()
    Convert this vector, matrix or table to an N-element column vector.
    VectorN.Row<Q>
    asVectorNRow()
    Convert this vector, matrix or table to an N-element row vector.
    protected void
    checkMultiply(Matrix<?,?,?,?,?> matrix)
    Check if the multiplication with the other matrix is valid.
    protected void
    checkMultiply(Vector<?,?,?,?,?> vector)
    Check if the multiplication with the other matrix is valid.
    abstract int
    cols()
    Return the number of columns.
    VM
    divideElements(Dimensionless quantity)
    Multiply the entries of this vector, matrix or table by the given quantity.
    SI
    divideEntries(H other)
    Divide the entries of this vector, matrix or table on an entry-by-entry basis with those of another collection of the same type (but possibly representing another quantity).
    Unit<?,Q>
    getDisplayUnit()
    Retrieve the unit of this Value.
    abstract double[]
    getSiArray()
    Return a row-major array of SI-values for this matrix or vector.
    abstract VM
    instantiateSi(double[] siNew)
    Return a new vector or matrix with the given SI or BASE values.
    abstract SI
    instantiateSi(double[] siNew, SIUnit siUnit)
    Return a new vector or matrix in SI-units with the given SI or BASE values.
    SI
    invertEntries()
    Invert the vector, matrix or table on an entry-by-entry basis.
    boolean
    isRelative()
    Indicate whether this is a Relative Value.
    Q
    max()
    Return the maximum value of the entries of the vector or matrix.
    Q
    mean()
    Return the mean value of the entries of the vector or matrix.
    Q
    median()
    Return the median value of the entries of the vector or matrix.
    Q
    min()
    Return the minimum value of the entries of the vector or matrix.
    VM
    multiplyElements(Dimensionless quantity)
    Multiply the entries of this vector, matrix or table by the given quantity.
    SI
    multiplyEntries(H other)
    Multiply the entries of this vector, matrix or table on an entry-by-entry basis with those of another collection of the same type (but possibly representing another quantity).
    SI
    multiplyEntries(Quantity<?> quantity)
    Multiply the entries of this vector, matrix or table by the given quantity.
    VM
    negate()
    Negate this element, based on the SI-values.
    int
    nnz()
    Return the number of non-zero entries in the vector, matrix or table.
    abstract int
    nonZeroCount()
    Return the number of non-zero entries in the vector, matrix or table.
    abstract int
    rows()
    Return the number of rows.
    VM
    scaleBy(double factor)
    Scale the element by a dimensionless factor, based on the SI-values.
    VM
    setDisplayUnit(Unit<?,Q> newUnit)
    Set a new display unit for the value.
    VM
    subtract(Q decrement)
    Return the a vector or matrix with entries that contain the value minus the decrement.
    VM
    subtract(VM other)
    Subtract an element from this element, based on the SI-values.
    Q
    sum()
    Return the sum of the values of the entries of the vector or matrix.
    String
    toString()
     
    abstract VMT
    transpose()
    Return a transposed vector or matrix, where rows and columns have been swapped.
    abstract double[]
    unsafeSiArray()
    Return a row-major possibly UNSAFE array of SI-values for this matrix or vector.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, 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

    format, format, isAbsolute, setDisplayUnit

  • Constructor Details

    • VectorMatrix

      public VectorMatrix(Unit<?,Q> displayUnit)
      Create a new vector or matrix with a unit.
      Parameters:
      displayUnit - the display unit to use

  • Method Details

    • getDisplayUnit

      public Unit<?,Q> getDisplayUnit()
      Description copied from interface: Value
      Retrieve the unit of this Value.
      Specified by:
      getDisplayUnit in interface Value<Q extends Quantity<Q>,VM extends VectorMatrix<Q,VM,SI,H,VMT>>
      Returns:
      the unit of this Value

    • setDisplayUnit

      public VM setDisplayUnit(Unit<?,Q> newUnit)
      Description copied from interface: Value
      Set a new display unit for the value. Internally, the value will not changed since it is stored in a base unit.
      Specified by:
      setDisplayUnit in interface Value<Q extends Quantity<Q>,VM extends VectorMatrix<Q,VM,SI,H,VMT>>
      Parameters:
      newUnit - the new display unit of this value
      Returns:
      'this' for fluent design

    • rows

      public abstract int rows()
      Return the number of rows.
      Returns:
      the number of rows

    • cols

      public abstract int cols()
      Return the number of columns.
      Returns:
      the number of columns

    • instantiateSi

      public abstract VM instantiateSi(double[] siNew)
      Return a new vector or matrix with the given SI or BASE values.
      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 abstract SI instantiateSi(double[] siNew, SIUnit siUnit)
      Return a new vector or matrix in SI-units with the given SI or BASE values.
      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

    • getSiArray

      public abstract double[] getSiArray()
      Return a row-major array of SI-values for this matrix or vector. This is guaranteed to be a safe copy.
      Returns:
      the row-major array of SI-values (safe copy)

    • unsafeSiArray

      public abstract double[] unsafeSiArray()
      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.
      Returns:
      the row-major array of SI-values (safe copy)

    • transpose

      public abstract VMT transpose()
      Return a transposed vector or matrix, where rows and columns have been swapped.
      Returns:
      a transposed vector or matrix, where rows and columns have been swapped

    • isRelative

      public boolean isRelative()
      Description copied from interface: Value
      Indicate whether this is a Relative Value.
      Specified by:
      isRelative in interface Value<Q extends Quantity<Q>,VM extends VectorMatrix<Q,VM,SI,H,VMT>>
      Returns:
      whether this is a Relative Value

    • mean

      public Q mean()
      Return the mean value of the entries of the vector or matrix.
      Returns:
      the mean value of the entries of the vector or matrix

    • min

      public Q min()
      Return the minimum value of the entries of the vector or matrix.
      Returns:
      the minimum value of the entries of the vector or matrix

    • max

      public Q max()
      Return the maximum value of the entries of the vector or matrix.
      Returns:
      the maximum value of the entries of the vector or matrix

    • median

      public Q median()
      Return the median value of the entries of the vector or matrix.
      Returns:
      the median value of the entries of the vector or matrix

    • sum

      public Q sum()
      Return the sum of the values of the entries of the vector or matrix.
      Returns:
      the sum of the values of the entries of the vector or matrix

    • add

      public VM add(Q increment)
      Return the a vector or matrix with entries that contain the sum of the element and the increment.
      Parameters:
      increment - the quantity by which to increase the values of the vector or matrix
      Returns:
      a vector or matrix with entries that are incremented by the given quantity

    • subtract

      public VM subtract(Q decrement)
      Return the a vector or matrix with entries that contain the value minus the decrement.
      Parameters:
      decrement - the quantity by which to decrease the values of the vector or matrix
      Returns:
      a vector or matrix with entries that are decremented by the given quantity

    • add

      public VM add(VM other)
      Description copied from interface: Additive
      Add an element to this element, based on the SI-values. Note that this can lead to unwanted effects for elements with Offset scales: 10 °C + 5 °C = 288.15 °C and not 15 °C.
      Specified by:
      add in interface Additive<Q extends Quantity<Q>>
      Parameters:
      other - the element to add to this element
      Returns:
      the sum of the SI-values of this element and the SI-values of the other element

    • subtract

      public VM subtract(VM other)
      Description copied from interface: Additive
      Subtract an element from this element, based on the SI-values.
      Specified by:
      subtract in interface Additive<Q extends Quantity<Q>>
      Parameters:
      other - the element to subtract from this element
      Returns:
      a new element with the SI-values of this element minus the SI-values of the other element

    • negate

      public VM negate()
      Description copied from interface: Additive
      Negate this element, based on the SI-values. Note that this can lead to unwanted effects for elements with Offset scales. A temperature in Celsius that is negated, will have its Kelvin temperatures negated.
      Specified by:
      negate in interface Additive<Q extends Quantity<Q>>
      Returns:
      a new element with all of its SI-values negated

    • abs

      public VM abs()
      Description copied from interface: Additive
      Make the SI-values of this element absolute. A new element wil be returned. Note that this can lead to unwanted effects for elements with Offset scales. A temperature of -10 degrees Celsius will have its Kelvin temperatures negated.
      Specified by:
      abs in interface Additive<Q extends Quantity<Q>>
      Returns:
      a new element with the absolute value for all of its SI-values

    • scaleBy

      public VM scaleBy(double factor)
      Description copied from interface: Scalable
      Scale the element by a dimensionless factor, based on the SI-values. Note that this can lead to unwanted effects for elements with Offset scales. 2 * 10 °C = 293.15 °C and not 20 °C.
      Specified by:
      scaleBy in interface Scalable<Q extends Quantity<Q>>
      Parameters:
      factor - the dimensionless scale factor
      Returns:
      a new element with all of its SI-values scaled by the dimensionless factor

    • nonZeroCount

      public abstract int nonZeroCount()
      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.
      Returns:
      the number of non-zero entries in the vector, matrix or table

    • nnz

      public int nnz()
      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. the acronym 'nnz' stands for 'number of non-zero entries'.
      Returns:
      the number of non-zero entries in the vector, matrix or table

    • multiplyElements

      public VM multiplyElements(Dimensionless quantity)
      Multiply the entries 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.
      Parameters:
      quantity - the scalar quantity to multiply by
      Returns:
      a vector, matrix or table where the entries have been multiplied by the given quantity

    • divideElements

      public VM divideElements(Dimensionless quantity)
      Multiply the entries 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.
      Parameters:
      quantity - the scalar quantity to multiply by
      Returns:
      a vector, matrix or table where the entries have been multiplied by the given quantity

    • invertEntries

      public SI invertEntries()
      Description copied from interface: Hadamard
      Invert the vector, matrix or table on an entry-by-entry basis.
      Specified by:
      invertEntries in interface Hadamard<Q extends Quantity<Q>,VM extends VectorMatrix<Q,VM,SI,H,VMT>>
      Returns:
      a new vector, matrix or table with an entry-by-entry inversion (1/value) of the entries

    • multiplyEntries

      public SI multiplyEntries(H other)
      Description copied from interface: Hadamard
      Multiply the entries of this vector, matrix or table on an entry-by-entry basis with those of another collection of the same type (but possibly representing another quantity).
      Specified by:
      multiplyEntries in interface Hadamard<Q extends Quantity<Q>,VM extends VectorMatrix<Q,VM,SI,H,VMT>>
      Parameters:
      other - the other collection of the same type
      Returns:
      a new vector, matrix or table with an entry-by-entry multiplication of its entries

    • divideEntries

      public SI divideEntries(H other)
      Description copied from interface: Hadamard
      Divide the entries of this vector, matrix or table on an entry-by-entry basis with those of another collection of the same type (but possibly representing another quantity).
      Specified by:
      divideEntries in interface Hadamard<Q extends Quantity<Q>,VM extends VectorMatrix<Q,VM,SI,H,VMT>>
      Parameters:
      other - the other collection of the same type
      Returns:
      a new vector, matrix or table with an entry-by-entry division of this collection's entries and other's entries

    • multiplyEntries

      public SI multiplyEntries(Quantity<?> quantity)
      Description copied from interface: Hadamard
      Multiply the entries of this vector, matrix or table by the given quantity.
      Specified by:
      multiplyEntries in interface Hadamard<Q extends Quantity<Q>,VM extends VectorMatrix<Q,VM,SI,H,VMT>>
      Parameters:
      quantity - the scalar quantity to multiply by
      Returns:
      a new vector, matrix or table where the entries have been multiplied by the given quantity

    • asMatrixNxM

      public MatrixNxM<Q> asMatrixNxM()
      Convert this vector or matrix to a MatrixNxM. The underlying data MIGHT be shared between this object and the MatrixNxM.
      Returns:
      a MatrixNxN with identical SI data and display unit

    • asQuantityTable

      public QuantityTable<Q> asQuantityTable()
      Convert this vector or matrix to a QuantityTable. The underlying data MIGHT be shared between this object and the quantity table.
      Returns:
      a QuantityTable with identical SI data and display unit

    • asVector1

      public Vector1<Q> asVector1()
      Return this vector, matrix or table as a 1-element column vector. Shape must be 1 x 1.
      Returns:
      a Vector1 with identical SI data and display unit
      Throws:
      IllegalStateException - if shape is not 1 x 1

    • asVector2Col

      public Vector2.Col<Q> asVector2Col()
      Return this vector, matrix or table as a 2-element column vector. Shape must be 2 x 1.
      Returns:
      a Vector2.Col with identical SI data and display unit
      Throws:
      IllegalStateException - if shape is not 2 x 1

    • asVector3Col

      public Vector3.Col<Q> asVector3Col()
      Return this vector, matrix or table as a 3-element column vector. Shape must be 3 x 1.
      Returns:
      a Vector3.Col with identical SI data and display unit
      Throws:
      IllegalStateException - if shape is not 3 x 1

    • asVectorNCol

      public VectorN.Col<Q> asVectorNCol()
      Convert this vector, matrix or table to an N-element column vector. Shape must be N x 1. The underlying data MIGHT be shared between this object and the VectorN.Col.
      Returns:
      a VectorN.Col with identical SI data and display unit
      Throws:
      IllegalStateException - if cols() != 1

    • asVector2Row

      public Vector2.Row<Q> asVector2Row()
      Return this vector, matrix or table as a 2-element row vector. Shape must be 1 x 2.
      Returns:
      a Vector2.Row with identical SI data and display unit
      Throws:
      IllegalStateException - if shape is not 1 x 2

    • asVector3Row

      public Vector3.Row<Q> asVector3Row()
      Return this vector, matrix or table as a 3-element row vector. Shape must be 1 x 3.
      Returns:
      a Vector3.Row with identical SI data and display unit
      Throws:
      IllegalStateException - if shape is not 1 x 3

    • asVectorNRow

      public VectorN.Row<Q> asVectorNRow()
      Convert this vector, matrix or table to an N-element row vector. Shape must be 1 x N. The underlying data MIGHT be shared between this object and the VectorN.Row.
      Returns:
      a VectorN.Row with identical SI data and display unit
      Throws:
      IllegalStateException - if rows() != 1

    • asMatrix1x1

      public Matrix1x1<Q> asMatrix1x1()
      Convert this vector, matrix or table 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> asMatrix2x2()
      Convert this vector, matrix or table 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> asMatrix3x3()
      Convert this vector, matrix or table 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

    • asMatrixNxN

      public MatrixNxN<Q> asMatrixNxN()
      Convert this vector, matrix or table to a MatrixNxN. The shape must be square. The underlying data MIGHT be shared between this object and the MatrixNxN.
      Returns:
      a MatrixNxN with identical SI data and display unit
      Throws:
      IllegalStateException - if this matrix is not square

    • checkMultiply

      protected void checkMultiply(Matrix<?,?,?,?,?> matrix)
      Check if the multiplication with the other matrix is valid. A valid matrix multiplication is (M x N) x (N x P).
      Parameters:
      matrix - the other matrix
      Throws:
      IllegalArgumentException - when this.cols() != other.rows()

    • checkMultiply

      protected void checkMultiply(Vector<?,?,?,?,?> vector)
      Check if the multiplication with the other matrix is valid. A valid matrix multiplication is (M x N) x (N x P).
      Parameters:
      vector - the other matrix
      Throws:
      IllegalArgumentException - when this.cols() != other.rows()

    • toString

      public String toString()
      Overrides:
      toString in class Object