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-2022 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-2022 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-2022 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-2022 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 }