Package org.djunits.value.vdouble.matrix.base

Class DoubleMatrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,M extends DoubleMatrix<U,S,V,M>>

java.lang.Object
org.djunits.value.IndexedValue<U,S,M,DM>
org.djunits.value.base.Matrix<U,S,V,DoubleVectorData,M,DoubleMatrixData>
org.djunits.value.vdouble.matrix.base.DoubleMatrix<U,S,V,M>
Type Parameters:
U - the unit
S - the scalar with unit U
V - the vector type belonging to the matrix type
M - the generic matrix type
All Implemented Interfaces:
Serializable, Cloneable, Value<U,M>
Direct Known Subclasses:
DoubleMatrixAbs, DoubleMatrixRel
public abstract class DoubleMatrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,M extends DoubleMatrix<U,S,V,M>> extends Matrix<U,S,V,DoubleVectorData,M,DoubleMatrixData>
DoubleMatrix utility methods, e.g., for creating DoubleMatrixs from different types of data.

Copyright (c) 2015-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved.
BSD-style license. See DJUNITS License.

Author:
Alexander Verbraeck, Peter Knoppers
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected DoubleMatrixData
    data
    The stored data as an object, can be sparse or dense.

  • Constructor Summary

    Constructors
    Constructor
    Description
    DoubleMatrix(DoubleMatrixData data, U unit)
    Construct a new DoubleMatrix.

  • Method Summary

    Modifier and Type
    Method
    Description
    final M
    abs()
    Return a new Scalar/Vector/Matrix with absolute value(s).
    final M
    assign(DoubleFunction doubleFunction)
    Execute a function on a cell by cell basis.
    final M
    ceil()
    Return a new Scalar/Vector/Matrix with the nearest integer value(s) above the current value(s).
    protected final void
    checkColumnIndex(int col)
    Check that provided column index is valid.
    protected final void
    checkIndex(int row, int col)
    Check that provided row and column indices are valid.
    protected final void
    checkRowIndex(int row)
    Check that provided row index is valid.
    protected final void
    checkSquare()
    Check that the matrix is square.
    int
    cols()
    Retrieve the number of columns of the matrix.
    final double
    determinantSI()
    Compute the determinant of the matrix, based on the SI values in the matrix.
    boolean
    equals(Object obj)
     
    final M
    floor()
    Return a new Scalar/Vector/Matrix with the nearest integer value(s) below the current value(s).
    S
    get(int row, int column)
    Retrieve a value from the matrix.
    V
    getColumn(int column)
    Retrieve a column from the matrix as a vector.
    S[]
    getColumnScalars(int col)
    Retrieve a column from the matrix as an array of scalars.
    double[]
    getColumnSI(int column)
    Retrieve a column from the matrix as an array of double.
    protected final DoubleMatrixData
    getData()
    Retrieve the data object.
    V
    getDiagonal()
    Retrieve the main diagonal of the matrix as a vector.
    S[]
    getDiagonalScalars()
    Retrieve the main diagonal of the matrix as an array of scalars.
    double[]
    getDiagonalSI()
    Retrieve the main diagonal of the matrix as an array of double.
    double
    getInUnit(int row, int column)
    Retrieve the value stored at a specified row and column in the original unit.
    double
    getInUnit(int row, int column, U targetUnit)
    Retrieve the value stored at a specified row and column converted into a specified unit.
    V
    getRow(int row)
    Retrieve a row from the matrix as a vector.
    S[]
    getRowScalars(int row)
    Retrieve a row from the matrix as an array of scalars.
    double[]
    getRowSI(int row)
    Retrieve a row from the matrix as an array of double.
    S[][]
    getScalars()
    Return the vector as a 2D-array of scalars.
    double
    getSI(int row, int column)
    Retrieve the value stored at a specified row and column in the standard SI unit.
    final double[][]
    getValuesInUnit()
    Create a dense double[][] array filled with the values in the original unit.
    final double[][]
    getValuesInUnit(U targetUnit)
    Create a dense double[][] array filled with the values converted into a specified unit.
    final double[][]
    getValuesSI()
    Create a dense double[][] array filled with the values in the standard SI unit.
    int
    hashCode()
     
    abstract M
    instantiateMatrix(DoubleMatrixData dmd, U displayUnit)
    Instantiate a new matrix of the class of this matrix.
    abstract S
    instantiateScalarSI(double valueSI, U displayUnit)
    Instantiate a new scalar for the class of this matrix.
    abstract V
    instantiateVector(DoubleVectorData dvd, U displayUnit)
    Instantiate a new vector of the class of this matrix.
    final M
    neg()
    Return a new Scalar/Vector/Matrix with negated value(s).
    final M
    rint()
    Return a new Scalar/Vector/Matrix with the nearest integer value(s).
    int
    rows()
    Retrieve the number of rows of the matrix.
    void
    set(int row, int column, S value)
    Set the scalar value at the specified position.
    protected void
    setData(DoubleMatrixData data)
    Set the data object.
    void
    setInUnit(int row, int column, double valueInUnit)
    Set the value, specified in the (current) display unit, at the specified position.
    void
    setInUnit(int row, int column, double valueInUnit, U valueUnit)
    Set the value, specified in the valueUnit, at the specified position.
    void
    setSI(int row, int column, double valueSI)
    Set the value, specified in the standard SI unit, at the specified position.
    M
    toDense()
    Create and return a dense version of this internal storage.
    M
    toSparse()
    Create and return a sparse version of this internal storage.
    String
    toString()
    Concise description of this value.
    String
    toString(boolean verbose, boolean withUnit)
    Somewhat verbose description of this value with optional type and unit information.
    String
    toString(U displayUnit)
    Somewhat verbose description of this value with the values expressed in the specified unit.
    String
    toString(U displayUnit, boolean verbose, boolean withUnit)
    Somewhat verbose description of this value with the values expressed in the specified unit.

    Methods inherited from class org.djunits.value.base.Matrix

    getVectorClass

    Methods inherited from class org.djunits.value.IndexedValue

    cardinality, checkCopyOnWrite, clone, getDisplayUnit, getScalarClass, getStorageType, immutable, isCopyOnWrite, isDense, isMutable, isSparse, mutable, setCopyOnWrite, setDisplayUnit, setMutable

    Methods inherited from class java.lang.Object

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

    Methods inherited from interface org.djunits.value.Value

    isAbsolute, isRelative

  • Field Details

    • data

      protected DoubleMatrixData data
      The stored data as an object, can be sparse or dense.

  • Constructor Details

    • DoubleMatrix

      public DoubleMatrix(DoubleMatrixData data, U unit)
      Construct a new DoubleMatrix.
      Parameters:
      data - DoubleMatrixData; an internal data object
      unit - U; the unit

  • Method Details

    • instantiateMatrix

      public abstract M instantiateMatrix(DoubleMatrixData dmd, U displayUnit)
      Instantiate a new matrix of the class of this matrix. This can be used instead of the DoubleMatrix.instiantiate() methods in case another matrix of this class is known. The method is faster than DoubleMatrix.instantiate, and it will also work if the matrix is user-defined.
      Parameters:
      dmd - DoubleMatrixData; the data used to instantiate the matrix
      displayUnit - U; the display unit of the matrix
      Returns:
      V; a matrix of the correct type

    • instantiateVector

      public abstract V instantiateVector(DoubleVectorData dvd, U displayUnit)
      Instantiate a new vector of the class of this matrix. This can be used instead of the DoubleVector.instiantiate() methods in case another matrix of this class is known. The method is faster than DoubleVector.instantiate, and it will also work if the matrix and/or vector are user-defined.
      Parameters:
      dvd - DoubleVectorData; the data used to instantiate the vector
      displayUnit - U; the display unit of the vector
      Returns:
      V; a vector of the correct type

    • instantiateScalarSI

      public abstract S instantiateScalarSI(double valueSI, U displayUnit)
      Instantiate a new scalar for the class of this matrix. This can be used instead of the DoubleScalar.instiantiate() methods in case a matrix of this class is known. The method is faster than DoubleScalar.instantiate, and it will also work if the matrix and/or scalar are user-defined.
      Parameters:
      valueSI - double; the SI value of the scalar
      displayUnit - U; the unit in which the value will be displayed
      Returns:
      S; a scalar of the correct type, belonging to the matrix type

    • getData

      protected final DoubleMatrixData getData()
      Description copied from class: IndexedValue
      Retrieve the data object. Method can only be used within package and by subclasses.
      Specified by:
      getData in class IndexedValue<U extends Unit<U>,S extends DoubleScalar<U,S>,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Returns:
      D; the internal data

    • setData

      protected void setData(DoubleMatrixData data)
      Description copied from class: IndexedValue
      Set the data object. Method can only be used within package and by subclasses.
      Specified by:
      setData in class IndexedValue<U extends Unit<U>,S extends DoubleScalar<U,S>,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Parameters:
      data - D; the internal data

    • getSI

      public double getSI(int row, int column) throws IndexOutOfBoundsException
      Retrieve the value stored at a specified row and column in the standard SI unit.
      Parameters:
      row - int; row of the value to retrieve
      column - int; column of the value to retrieve
      Returns:
      double; value at position row, column in the standard SI unit
      Throws:
      IndexOutOfBoundsException - when row or column out of range (row < 0 or row >= rows() or column < 0 or column >= columns())

    • getInUnit

      public double getInUnit(int row, int column) throws IndexOutOfBoundsException
      Retrieve the value stored at a specified row and column in the original unit.
      Parameters:
      row - int; row of the value to retrieve
      column - int; column of the value to retrieve
      Returns:
      double; value at position row, column in the original unit
      Throws:
      IndexOutOfBoundsException - when row or column out of range (row < 0 or row >= rows() or column < 0 or column >= columns())

    • getInUnit

      public double getInUnit(int row, int column, U targetUnit) throws IndexOutOfBoundsException
      Retrieve the value stored at a specified row and column converted into a specified unit.
      Parameters:
      row - int; row of the value to retrieve
      column - int; column of the value to retrieve
      targetUnit - U; the unit for the result
      Returns:
      double; value at position row, column converted into the specified unit
      Throws:
      IndexOutOfBoundsException - when row or column out of range (row < 0 or row >= rows() or column < 0 or column >= columns())

    • setSI

      public void setSI(int row, int column, double valueSI) throws IndexOutOfBoundsException
      Set the value, specified in the standard SI unit, at the specified position.
      Parameters:
      row - int; row of the value to set
      column - int; column of the value to set
      valueSI - double; the value, specified in the standard SI unit
      Throws:
      IndexOutOfBoundsException - when index out of range (index < 0 or index >= size())

    • setInUnit

      public void setInUnit(int row, int column, double valueInUnit) throws IndexOutOfBoundsException
      Set the value, specified in the (current) display unit, at the specified position.
      Parameters:
      row - int; row of the value to set
      column - int; column of the value to set
      valueInUnit - double; the value, specified in the (current) display unit
      Throws:
      IndexOutOfBoundsException - when index out of range (index < 0 or index >= size())

    • setInUnit

      public void setInUnit(int row, int column, double valueInUnit, U valueUnit) throws IndexOutOfBoundsException
      Set the value, specified in the valueUnit, at the specified position.
      Parameters:
      row - int; row of the value to set
      column - int; column of the value to set
      valueInUnit - double; the value, specified in the (current) display unit
      valueUnit - U; the unit in which the valueInUnit is expressed
      Throws:
      IndexOutOfBoundsException - when index out of range (index < 0 or index >= size())

    • set

      public void set(int row, int column, S value) throws IndexOutOfBoundsException
      Set the scalar value at the specified position.
      Parameters:
      row - int; row of the value to set
      column - int; column of the value to set
      value - S; the value to set
      Throws:
      IndexOutOfBoundsException - when index out of range (index < 0 or index >= size())

    • getRowSI

      public double[] getRowSI(int row) throws IndexOutOfBoundsException
      Retrieve a row from the matrix as an array of double.
      Parameters:
      row - int; row of the values to retrieve
      Returns:
      S[]; the row as a double array
      Throws:
      IndexOutOfBoundsException - in case row is out of bounds

    • getColumnSI

      public double[] getColumnSI(int column) throws IndexOutOfBoundsException
      Retrieve a column from the matrix as an array of double.
      Parameters:
      column - int; column of the values to retrieve
      Returns:
      S[]; the column as a double array
      Throws:
      IndexOutOfBoundsException - in case column is out of bounds

    • getDiagonalSI

      public double[] getDiagonalSI() throws ValueRuntimeException
      Retrieve the main diagonal of the matrix as an array of double.
      Returns:
      V; the main diagonal as a double array
      Throws:
      ValueRuntimeException - in case the matrix is not square

    • getValuesSI

      public final double[][] getValuesSI()
      Create a dense double[][] array filled with the values in the standard SI unit.
      Returns:
      double[][]; array of values in the standard SI unit

    • getValuesInUnit

      public final double[][] getValuesInUnit()
      Create a dense double[][] array filled with the values in the original unit.
      Returns:
      double[][]; the values in the original unit

    • getValuesInUnit

      public final double[][] getValuesInUnit(U targetUnit)
      Create a dense double[][] array filled with the values converted into a specified unit.
      Parameters:
      targetUnit - U; the unit into which the values are converted for use
      Returns:
      double[][]; the values converted into the specified unit

    • rows

      public int rows()
      Description copied from class: Matrix
      Retrieve the number of rows of the matrix.
      Specified by:
      rows in class Matrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,DoubleVectorData,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Returns:
      int; the number of rows of the matrix

    • cols

      public int cols()
      Description copied from class: Matrix
      Retrieve the number of columns of the matrix.
      Specified by:
      cols in class Matrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,DoubleVectorData,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Returns:
      int; the number of columns of the matrix

    • getScalars

      public S[][] getScalars()
      Description copied from class: Matrix
      Return the vector as a 2D-array of scalars.
      Specified by:
      getScalars in class Matrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,DoubleVectorData,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Returns:
      S[][]; the vector as a 2D-array of scalars

    • get

      public S get(int row, int column) throws IndexOutOfBoundsException
      Description copied from class: Matrix
      Retrieve a value from the matrix.
      Specified by:
      get in class Matrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,DoubleVectorData,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Parameters:
      row - int; row of the value to retrieve
      column - int; column of the value to retrieve
      Returns:
      S; the value as a Scalar
      Throws:
      IndexOutOfBoundsException - in case row or column is out of bounds

    • getRow

      public V getRow(int row) throws IndexOutOfBoundsException
      Description copied from class: Matrix
      Retrieve a row from the matrix as a vector.
      Specified by:
      getRow in class Matrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,DoubleVectorData,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Parameters:
      row - int; row of the values to retrieve
      Returns:
      V; the row as a Vector
      Throws:
      IndexOutOfBoundsException - in case row is out of bounds

    • getColumn

      public V getColumn(int column) throws IndexOutOfBoundsException
      Description copied from class: Matrix
      Retrieve a column from the matrix as a vector.
      Specified by:
      getColumn in class Matrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,DoubleVectorData,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Parameters:
      column - int; column of the values to retrieve
      Returns:
      V; the column as a Vector
      Throws:
      IndexOutOfBoundsException - in case column is out of bounds

    • getDiagonal

      public V getDiagonal() throws ValueRuntimeException
      Description copied from class: Matrix
      Retrieve the main diagonal of the matrix as a vector.
      Specified by:
      getDiagonal in class Matrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,DoubleVectorData,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Returns:
      V; the main diagonal as a Vector
      Throws:
      ValueRuntimeException - in case the matrix is not square

    • getRowScalars

      public S[] getRowScalars(int row) throws IndexOutOfBoundsException
      Description copied from class: Matrix
      Retrieve a row from the matrix as an array of scalars.
      Specified by:
      getRowScalars in class Matrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,DoubleVectorData,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Parameters:
      row - int; row of the values to retrieve
      Returns:
      S[]; the row as a Scalar array
      Throws:
      IndexOutOfBoundsException - in case row is out of bounds

    • getColumnScalars

      public S[] getColumnScalars(int col) throws IndexOutOfBoundsException
      Description copied from class: Matrix
      Retrieve a column from the matrix as an array of scalars.
      Specified by:
      getColumnScalars in class Matrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,DoubleVectorData,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Parameters:
      col - int; column of the values to retrieve
      Returns:
      S[]; the column as a Scalar array
      Throws:
      IndexOutOfBoundsException - in case column is out of bounds

    • getDiagonalScalars

      public S[] getDiagonalScalars() throws ValueRuntimeException
      Description copied from class: Matrix
      Retrieve the main diagonal of the matrix as an array of scalars.
      Specified by:
      getDiagonalScalars in class Matrix<U extends Unit<U>,S extends DoubleScalar<U,S>,V extends DoubleVector<U,S,V>,DoubleVectorData,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Returns:
      V; the main diagonal as a Scalar array
      Throws:
      ValueRuntimeException - in case the matrix is not square

    • toSparse

      public M toSparse()
      Description copied from class: IndexedValue
      Create and return a sparse version of this internal storage. When the data was already sparse, the current version is returned and no copy will be made of the data.
      Specified by:
      toSparse in class IndexedValue<U extends Unit<U>,S extends DoubleScalar<U,S>,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Returns:
      T; a sparse version of this internal storage

    • toDense

      public M toDense()
      Description copied from class: IndexedValue
      Create and return a dense version of this internal storage. When the data was already dense, the current version is returned and no copy will be made of the data.
      Specified by:
      toDense in class IndexedValue<U extends Unit<U>,S extends DoubleScalar<U,S>,M extends DoubleMatrix<U,S,V,M>,DoubleMatrixData>
      Returns:
      T; a dense version of this internal storage

    • assign

      public final M assign(DoubleFunction doubleFunction)
      Execute a function on a cell by cell basis. Note: May be expensive when used on sparse data.
      Parameters:
      doubleFunction - DoubleFunction; the function to apply
      Returns:
      M; this updated matrix

    • abs

      public final M abs()
      Description copied from interface: Value
      Return a new Scalar/Vector/Matrix with absolute value(s).
      Returns:
      R; a new R with absolute value(s)

    • ceil

      public final M ceil()
      Description copied from interface: Value
      Return a new Scalar/Vector/Matrix with the nearest integer value(s) above the current value(s).
      Returns:
      R; a new R with absolute value(s)

    • floor

      public final M floor()
      Description copied from interface: Value
      Return a new Scalar/Vector/Matrix with the nearest integer value(s) below the current value(s).
      Returns:
      R; a new R with absolute value(s)

    • neg

      public final M neg()
      Description copied from interface: Value
      Return a new Scalar/Vector/Matrix with negated value(s).
      Returns:
      R; a new R with negated value(s)

    • rint

      public final M rint()
      Description copied from interface: Value
      Return a new Scalar/Vector/Matrix with the nearest integer value(s). When the value is exactly in the middle between two integer values, the even one is returned.
      Returns:
      R; a new R with absolute value(s)

    • toString

      public String toString()
      Description copied from interface: Value
      Concise description of this value.
      Specified by:
      toString in interface Value<U extends Unit<U>,S extends DoubleScalar<U,S>>
      Overrides:
      toString in class Object
      Returns:
      a String with the value, non-verbose, with the unit attached.

    • toString

      public String toString(U displayUnit)
      Description copied from interface: Value
      Somewhat verbose description of this value with the values expressed in the specified unit.
      Parameters:
      displayUnit - U; the unit into which the values are converted for display
      Returns:
      String; printable string with the value contents expressed in the specified unit

    • toString

      public String toString(boolean verbose, boolean withUnit)
      Description copied from interface: Value
      Somewhat verbose description of this value with optional type and unit information.
      Parameters:
      verbose - boolean; if true; include type info; if false; exclude type info
      withUnit - boolean; if true; include the unit; of false; exclude the unit
      Returns:
      String; printable string with the value contents

    • toString

      public String toString(U displayUnit, boolean verbose, boolean withUnit)
      Description copied from interface: Value
      Somewhat verbose description of this value with the values expressed in the specified unit.
      Parameters:
      displayUnit - U; the unit into which the values are converted for display
      verbose - boolean; if true; include type info; if false; exclude type info
      withUnit - boolean; if true; include the unit; of false; exclude the unit
      Returns:
      String; printable string with the value contents

    • checkIndex

      protected final void checkIndex(int row, int col) throws IndexOutOfBoundsException
      Check that provided row and column indices are valid.
      Parameters:
      row - int; the row value to check
      col - int; the column value to check
      Throws:
      IndexOutOfBoundsException - when row or column is invalid

    • checkRowIndex

      protected final void checkRowIndex(int row) throws IndexOutOfBoundsException
      Check that provided row index is valid.
      Parameters:
      row - int; the row value to check
      Throws:
      IndexOutOfBoundsException - when row is invalid

    • checkColumnIndex

      protected final void checkColumnIndex(int col) throws IndexOutOfBoundsException
      Check that provided column index is valid.
      Parameters:
      col - int; the column value to check
      Throws:
      IndexOutOfBoundsException - when row is invalid

    • checkSquare

      protected final void checkSquare() throws ValueRuntimeException
      Check that the matrix is square.
      Throws:
      ValueRuntimeException - when matrix is not square

    • determinantSI

      public final double determinantSI() throws ValueRuntimeException
      Compute the determinant of the matrix, based on the SI values in the matrix.
      Returns:
      double; the determinant of the matrix
      Throws:
      ValueRuntimeException - when matrix is neither sparse, nor dense, or not square

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object