View Javadoc
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&lt;LengthUnit, Length, LengthMatrix&gt;
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&lt;V&gt;; 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&lt;AreaUnit, Area, AreaMatrix&gt;
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&lt;
169      *     PositionUnit, Position, PositionMatrix, LengthUnit, Length, LengthMatrix&gt;
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&lt;
207      *     PositionUnit, Position, PositionMatrix, LengthUnit, Length, LengthMatrix&gt;
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 }