1 package org.djunits.value.base; 2 3 import org.djunits.unit.AbsoluteLinearUnit; 4 import org.djunits.unit.Unit; 5 import org.djunits.value.Absolute; 6 import org.djunits.value.IndexedValue; 7 import org.djunits.value.Relative; 8 import org.djunits.value.ValueRuntimeException; 9 10 /** 11 * Matrix to distinguish a matrix from scalars and matrixs. A possible way to implement this interface is: 12 * 13 * <pre> 14 * class LengthMatrix implements Matrix<LengthUnit, Length, LengthMatrix> 15 * </pre> 16 * 17 * Copyright (c) 2019-2023 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br> 18 * BSD-style license. See <a href="https://djunits.org/docs/license.html">DJUNITS License</a>. <br> 19 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank">Alexander Verbraeck</a> 20 * @param <U> the unit 21 * @param <S> the scalar type belonging to the matrix type 22 * @param <V> the corresponding vector type 23 * @param <M> the matrix type with the given unit 24 */ 25 public interface Matrix<U extends Unit<U>, S extends Scalar<U, S>, V extends Vector<U, S, V>, M extends Matrix<U, S, V, M>> 26 extends IndexedValue<U, S, M> 27 { 28 /** 29 * Retrieve the number of rows of the matrix. 30 * @return int; the number of rows of the matrix 31 */ 32 int rows(); 33 34 /** 35 * Retrieve the number of columns of the matrix. 36 * @return int; the number of columns of the matrix 37 */ 38 int cols(); 39 40 /** 41 * Return the class of the corresponding vector. 42 * @return Class<V>; the class of the corresponding vector 43 */ 44 Class<V> getVectorClass(); 45 46 /** 47 * Retrieve a value from the matrix. 48 * @param row int; row of the value to retrieve 49 * @param column int; column of the value to retrieve 50 * @return S; the value as a Scalar 51 * @throws ValueRuntimeException in case row or column is out of bounds 52 */ 53 S get(int row, int column) throws ValueRuntimeException; 54 55 /** 56 * Return the vector as a 2D-array of scalars. 57 * @return S[][]; the vector as a 2D-array of scalars 58 */ 59 S[][] getScalars(); 60 61 /** 62 * Retrieve a row from the matrix as a vector. 63 * @param row int; row of the values to retrieve 64 * @return V; the row as a Vector 65 * @throws ValueRuntimeException in case row is out of bounds 66 */ 67 V getRow(int row) throws ValueRuntimeException; 68 69 /** 70 * Retrieve a column from the matrix as a vector. 71 * @param column int; column of the values to retrieve 72 * @return V; the column as a Vector 73 * @throws ValueRuntimeException in case column is out of bounds 74 */ 75 V getColumn(int column) throws ValueRuntimeException; 76 77 /** 78 * Retrieve the main diagonal of the matrix as a vector. 79 * @return V; the main diagonal as a Vector 80 * @throws ValueRuntimeException in case the matrix is not square 81 */ 82 V getDiagonal() throws ValueRuntimeException; 83 84 /** 85 * Retrieve a row from the matrix as an array of scalars. 86 * @param row int; row of the values to retrieve 87 * @return S[]; the row as a Scalar array 88 * @throws ValueRuntimeException in case row is out of bounds 89 */ 90 S[] getRowScalars(int row) throws ValueRuntimeException; 91 92 /** 93 * Retrieve a column from the matrix as an array of scalars. 94 * @param column int; column of the values to retrieve 95 * @return S[]; the column as a Scalar array 96 * @throws ValueRuntimeException in case column is out of bounds 97 */ 98 S[] getColumnScalars(int column) throws ValueRuntimeException; 99 100 /** 101 * Retrieve the main diagonal of the matrix as an array of scalars. 102 * @return V; the main diagonal as a Scalar array 103 * @throws ValueRuntimeException in case the matrix is not square 104 */ 105 S[] getDiagonalScalars() throws ValueRuntimeException; 106 107 /** 108 * Methods for Relative Matrix. A possible way to implement this interface is: 109 * 110 * <pre> 111 * class AreaMatrix implements Matrix.Rel<AreaUnit, Area, AreaMatrix> 112 * </pre> 113 * 114 * Copyright (c) 2019-2023 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. 115 * <br> 116 * BSD-style license. See <a href="https://djunits.org/docs/license.html">DJUNITS License</a>. <br> 117 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank">Alexander Verbraeck</a> 118 * @param <U> the unit 119 * @param <S> the scalar type belonging to the matrix type 120 * @param <V> the corresponding vector type 121 * @param <RM> the relative matrix type with this unit 122 */ 123 interface Rel<U extends Unit<U>, S extends Scalar<U, S>, V extends Vector<U, S, V>, RM extends Matrix.Rel<U, S, V, RM>> 124 extends Matrix<U, S, V, RM>, Relative<U, RM> 125 { 126 /** 127 * Add a relative matrix to this relative mutable matrix. A new matrix is returned. The display unit of the result is 128 * the display unit of this relative matrix. The addition is done value by value and the result is stored in a new 129 * matrix. If both operands are sparse, the result is a sparse matrix, otherwise the result is a dense matrix. 130 * @param increment RM; the relative matrix (mutable or immutable, sparse or dense) to add 131 * @return RMV; the sum of this matrix and the operand as a new relative, mutable matrix 132 * @throws ValueRuntimeException in case this matrix and the operand have a different size 133 */ 134 RM plus(RM increment) throws ValueRuntimeException; 135 136 /** 137 * Subtract a relative matrix from this relative mutable matrix. The display unit of the result is the display unit of 138 * this relative matrix. The subtraction is done value by value and the result is stored in a new matrix. If both 139 * operands are sparse, the result is a sparse matrix, otherwise the result is a dense matrix. 140 * @param decrement RM; the value to subtract 141 * @return RMV; the difference of this matrix and the operand as a new relative, mutable matrix 142 * @throws ValueRuntimeException in case this matrix and the operand have a different size 143 */ 144 RM minus(RM decrement) throws ValueRuntimeException; 145 146 /** 147 * Multiply all values of this matrix by the multiplier. This only works if the matrix is mutable. 148 * @param multiplier double; the factor by which to multiply all values 149 * @return V; this modified matrix 150 * @throws ValueRuntimeException in case the matrix is immutable 151 */ 152 RM multiplyBy(double multiplier); 153 154 /** 155 * Divide all values of this matrix by the divisor. This only works if the matrix is mutable. 156 * @param divisor double; the value by which to divide all values 157 * @return V; this modified matrix 158 * @throws ValueRuntimeException in case the matrix is immutable 159 */ 160 RM divideBy(double divisor); 161 } 162 163 /** 164 * Additional methods for Relative Matrix that has a corresponding Absolute Matrix. An example is the relative matrix Length 165 * that has a corresponding absolute matrix Position. A possible way to implement this interface is: 166 * 167 * <pre> 168 * class LengthMatrix implements Matrix.RelWithAbs< 169 * PositionUnit, Position, PositionMatrix, LengthUnit, Length, LengthMatrix> 170 * </pre> 171 * 172 * Copyright (c) 2019-2023 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. 173 * <br> 174 * BSD-style license. See <a href="https://djunits.org/docs/license.html">DJUNITS License</a>. <br> 175 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank">Alexander Verbraeck</a> 176 * @param <AU> the absolute unit belonging to the relative unit 177 * @param <A> the absolute scalar type belonging to the absolute matrix type 178 * @param <AV> the corresponding absolute vector type 179 * @param <AM> the absolute matrix type 180 * @param <RU> the relative unit belonging to the absolute unit 181 * @param <R> the relative scalar type belonging to the relative matrix type 182 * @param <RV> the corresponding relative vector type 183 * @param <RM> the relative matrix type with this unit 184 */ 185 interface RelWithAbs<AU extends AbsoluteLinearUnit<AU, RU>, A extends Scalar<AU, A>, 186 AV extends Vector.Abs<AU, A, AV, RU, R, RV>, AM extends Matrix.Abs<AU, A, AV, AM, RU, R, RV, RM>, 187 RU extends Unit<RU>, R extends Scalar<RU, R>, RV extends Vector.RelWithAbs<AU, A, AV, RU, R, RV>, 188 RM extends Matrix.RelWithAbs<AU, A, AV, AM, RU, R, RV, RM>> extends Rel<RU, R, RV, RM> 189 { 190 /** 191 * Add an absolute matrix to this relative matrix. A new matrix is returned. When the matrix itself needs to be changed, 192 * use the increaseBy(V) method instead. The addition is done value by value and the result is stored in a new matrix. 193 * If both operands are sparse, the result is a sparse matrix, otherwise the result is a dense matrix. 194 * @param increment AM; the absolute matrix (mutable or immutable, sparse or dense) to add to this relative matrix 195 * @return AMV; the sum of this matrix and the operand as a new absolute, mutable matrix 196 * @throws ValueRuntimeException in case this matrix and the operand have a different size 197 */ 198 AM plus(AM increment); 199 } 200 201 /** 202 * Methods for Absolute Matrix. An example is the absolute matrix Position that has a corresponding relative matrix Length. 203 * A possible way to implement this interface is: 204 * 205 * <pre> 206 * class PositionMatrix implements Matrix.Abs< 207 * PositionUnit, Position, PositionMatrix, LengthUnit, Length, LengthMatrix> 208 * </pre> 209 * 210 * Copyright (c) 2019-2023 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. 211 * <br> 212 * BSD-style license. See <a href="https://djunits.org/docs/license.html">DJUNITS License</a>. <br> 213 * @author <a href="https://www.tudelft.nl/averbraeck" target="_blank">Alexander Verbraeck</a> 214 * @param <AU> the absolute unit belonging to the relative unit 215 * @param <A> the absolute scalar type belonging to the absolute matrix type 216 * @param <AV> the corresponding absolute vector type 217 * @param <AM> the absolute matrix type 218 * @param <RU> the relative unit belonging to the absolute unit 219 * @param <R> the relative scalar type belonging to the relative matrix type 220 * @param <RV> the corresponding relative vector type 221 * @param <RM> the relative matrix type with this unit 222 */ 223 interface Abs<AU extends AbsoluteLinearUnit<AU, RU>, A extends Scalar<AU, A>, AV extends Vector.Abs<AU, A, AV, RU, R, RV>, 224 AM extends Matrix.Abs<AU, A, AV, AM, RU, R, RV, RM>, RU extends Unit<RU>, R extends Scalar<RU, R>, 225 RV extends Vector.RelWithAbs<AU, A, AV, RU, R, RV>, RM extends Matrix.RelWithAbs<AU, A, AV, AM, RU, R, RV, RM>> 226 extends Matrix<AU, A, AV, AM>, Absolute 227 { 228 /** 229 * Add a relative matrix to this absolute matrix. A new absolute matrix is returned. The display unit of the new matrix 230 * is the display unit of this absolute matrix. The addition is done value by value and the result is stored in a new 231 * matrix. If both operands are sparse, the result is a sparse matrix, otherwise the result is a dense matrix. 232 * @param increment RM; the relative matrix (mutable or immutable, sparse or dense) to add to this absolute matrix 233 * @return AIV; the sum of this value and the operand as a new absolute, immutable matrix 234 * @throws ValueRuntimeException in case this matrix and the operand have a different size 235 */ 236 AM plus(RM increment) throws ValueRuntimeException; 237 238 /** 239 * Subtract a relative matrix from this absolute matrix. A new absolute matrix is returned. The display unit of the new 240 * matrix is the display unit of this absolute matrix. The subtraction is done value by value and the result is stored 241 * in a new matrix. If both operands are sparse, the result is a sparse matrix, otherwise the result is a dense matrix. 242 * @param decrement RM; the relative matrix (mutable or immutable, sparse or dense) to subtract from this absolute 243 * matrix 244 * @return AIV; the difference of this value and the operand as a new absolute, immutable matrix 245 * @throws ValueRuntimeException in case this matrix and the operand have a different size 246 */ 247 AM minus(RM decrement) throws ValueRuntimeException; 248 249 /** 250 * Subtract an absolute matrix from this absolute matrix. A new relative matrix is returned. The display unit of the new 251 * matrix is the relative counterpart of the display unit of this absolute matrix. The subtraction is done value by 252 * value and the result is stored in a new matrix. If both operands are sparse, the result is a sparse matrix, otherwise 253 * the result is a dense matrix. 254 * @param decrement AM; the absolute matrix (mutable or immutable, sparse or dense) to subtract from this absolute 255 * matrix 256 * @return RIV; the difference of this value and the operand as a new relative, immutable matrix 257 * @throws ValueRuntimeException in case this matrix and the operand have a different size 258 */ 259 RM minus(AM decrement) throws ValueRuntimeException; 260 } 261 262 }