1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.commons.math.linear;
18
19 /***
20 * Interface defining a real-valued matrix with basic algebraic operations.
21 * <p>
22 * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
23 * returns the element in the first row, first column of the matrix.
24 *
25 * @version $Revision: 1.25 $ $Date: 2004/10/12 06:19:50 $
26 */
27 public interface RealMatrix {
28
29 /***
30 * Returns a (deep) copy of this.
31 *
32 * @return matrix copy
33 */
34 RealMatrix copy();
35
36 /***
37 * Compute the sum of this and m.
38 *
39 * @param m matrix to be added
40 * @return this + m
41 * @throws IllegalArgumentException if m is not the same size as this
42 */
43 RealMatrix add(RealMatrix m) throws IllegalArgumentException;
44
45 /***
46 * Compute this minus m.
47 *
48 * @param m matrix to be subtracted
49 * @return this + m
50 * @throws IllegalArgumentException if m is not the same size as this
51 */
52 RealMatrix subtract(RealMatrix m) throws IllegalArgumentException;
53
54 /***
55 * Returns the result of adding d to each entry of this.
56 *
57 * @param d value to be added to each entry
58 * @return d + this
59 */
60 RealMatrix scalarAdd(double d);
61
62 /***
63 * Returns the result multiplying each entry of this by d.
64 *
65 * @param d value to multiply all entries by
66 * @return d * this
67 */
68 RealMatrix scalarMultiply(double d);
69
70 /***
71 * Returns the result of postmultiplying this by m.
72 *
73 * @param m matrix to postmultiply by
74 * @return this * m
75 * @throws IllegalArgumentException
76 * if columnDimension(this) != rowDimension(m)
77 */
78 RealMatrix multiply(RealMatrix m) throws IllegalArgumentException;
79
80 /***
81 * Returns the result premultiplying this by <code>m</code>.
82 * @param m matrix to premultiply by
83 * @return m * this
84 * @throws IllegalArgumentException
85 * if rowDimension(this) != columnDimension(m)
86 */
87 public RealMatrix preMultiply(RealMatrix m) throws IllegalArgumentException;
88
89 /***
90 * Returns matrix entries as a two-dimensional array.
91 *
92 * @return 2-dimensional array of entries
93 */
94 double[][] getData();
95
96 /***
97 * Returns the <a href="http://mathworld.wolfram.com/MaximumAbsoluteRowSumNorm.html">
98 * maximum absolute row sum norm</a> of the matrix.
99 *
100 * @return norm
101 */
102 double getNorm();
103
104 /***
105 * Gets a submatrix. Rows and columns are indicated
106 * counting from 0 to n-1.
107 *
108 * @param startRow Initial row index
109 * @param endRow Final row index
110 * @param startColumn Initial column index
111 * @param endColumn Final column index
112 * @return The subMatrix containing the data of the
113 * specified rows and columns
114 * @exception MatrixIndexException if the indices are not valid
115 */
116 RealMatrix getSubMatrix(int startRow, int endRow, int startColumn,
117 int endColumn) throws MatrixIndexException;
118
119 /***
120 * Gets a submatrix. Rows and columns are indicated
121 * counting from 0 to n-1.
122 *
123 * @param selectedRows Array of row indices.
124 * @param selectedColumns Array of column indices.
125 * @return The subMatrix containing the data in the
126 * specified rows and columns
127 * @exception MatrixIndexException if row or column selections are not valid
128 */
129 RealMatrix getSubMatrix(int[] selectedRows, int[] selectedColumns)
130 throws MatrixIndexException;
131
132 /***
133 * Returns the entries in row number <code>row</code>
134 * as a row matrix. Row indices start at 0.
135 *
136 * @param row the row to be fetched
137 * @return row matrix
138 * @throws MatrixIndexException if the specified row index is invalid
139 */
140 RealMatrix getRowMatrix(int row) throws MatrixIndexException;
141
142 /***
143 * Returns the entries in column number <code>column</code>
144 * as a column matrix. Column indices start at 0.
145 *
146 * @param column the column to be fetched
147 * @return column matrix
148 * @throws MatrixIndexException if the specified column index is invalid
149 */
150 RealMatrix getColumnMatrix(int column) throws MatrixIndexException;
151
152 /***
153 * Returns the entries in row number <code>row</code> as an array.
154 * <p>
155 * Row indices start at 0. A <code>MatrixIndexException</code> is thrown
156 * unless <code>0 <= row < rowDimension.</code>
157 *
158 * @param row the row to be fetched
159 * @return array of entries in the row
160 * @throws MatrixIndexException if the specified row index is not valid
161 */
162 double[] getRow(int row) throws MatrixIndexException;
163
164 /***
165 * Returns the entries in column number <code>col</code> as an array.
166 * <p>
167 * Column indices start at 0. A <code>MatrixIndexException</code> is thrown
168 * unless <code>0 <= column < columnDimension.</code>
169 *
170 * @param col the column to be fetched
171 * @return array of entries in the column
172 * @throws MatrixIndexException if the specified column index is not valid
173 */
174 double[] getColumn(int col) throws MatrixIndexException;
175
176 /***
177 * Returns the entry in the specified row and column.
178 * <p>
179 * Row and column indices start at 0 and must satisfy
180 * <ul>
181 * <li><code>0 <= row < rowDimension</code></li>
182 * <li><code> 0 <= column < columnDimension</code></li>
183 * </ul>
184 * otherwise a <code>MatrixIndexException</code> is thrown.
185 *
186 * @param row row location of entry to be fetched
187 * @param column column location of entry to be fetched
188 * @return matrix entry in row,column
189 * @throws MatrixIndexException if the row or column index is not valid
190 */
191 double getEntry(int row, int column) throws MatrixIndexException;
192
193 /***
194 * Returns the transpose of this matrix.
195 *
196 * @return transpose matrix
197 */
198 RealMatrix transpose();
199
200 /***
201 * Returns the inverse of this matrix.
202 *
203 * @return inverse matrix
204 * @throws InvalidMatrixException if this is not invertible
205 */
206 RealMatrix inverse() throws InvalidMatrixException;
207
208 /***
209 * Returns the determinant of this matrix.
210 *
211 * @return determinant
212 */
213 double getDeterminant();
214
215 /***
216 * Is this a square matrix?
217 * @return true if the matrix is square (rowDimension = columnDimension)
218 */
219 boolean isSquare();
220
221 /***
222 * Is this a singular matrix?
223 * @return true if the matrix is singular
224 */
225 boolean isSingular();
226
227 /***
228 * Returns the number of rows in the matrix.
229 *
230 * @return rowDimension
231 */
232 int getRowDimension();
233
234 /***
235 * Returns the number of columns in the matrix.
236 *
237 * @return columnDimension
238 */
239 int getColumnDimension();
240
241 /***
242 * Returns the <a href="http://mathworld.wolfram.com/MatrixTrace.html">
243 * trace</a> of the matrix (the sum of the elements on the main diagonal).
244 *
245 * @return trace
246 */
247 double getTrace();
248
249 /***
250 * Returns the result of multiplying this by the vector <code>v</code>.
251 *
252 * @param v the vector to operate on
253 * @return this*v
254 * @throws IllegalArgumentException if columnDimension != v.size()
255 */
256 double[] operate(double[] v) throws IllegalArgumentException;
257
258 /***
259 * Returns the (row) vector result of premultiplying this by the vector <code>v</code>.
260 *
261 * @param v the row vector to premultiply by
262 * @return v*this
263 * @throws IllegalArgumentException if rowDimension != v.size()
264 */
265 double[] preMultiply(double[] v) throws IllegalArgumentException;
266
267 /***
268 * Returns the solution vector for a linear system with coefficient
269 * matrix = this and constant vector = <code>b</code>.
270 *
271 * @param b constant vector
272 * @return vector of solution values to AX = b, where A is *this
273 * @throws IllegalArgumentException if this.rowDimension != b.length
274 * @throws InvalidMatrixException if this matrix is not square or is singular
275 */
276 double[] solve(double[] b) throws IllegalArgumentException, InvalidMatrixException;
277
278 /***
279 * Returns a matrix of (column) solution vectors for linear systems with
280 * coefficient matrix = this and constant vectors = columns of
281 * <code>b</code>.
282 *
283 * @param b matrix of constant vectors forming RHS of linear systems to
284 * to solve
285 * @return matrix of solution vectors
286 * @throws IllegalArgumentException if this.rowDimension != row dimension
287 * @throws InvalidMatrixException if this matrix is not square or is singular
288 */
289 RealMatrix solve(RealMatrix b) throws IllegalArgumentException, InvalidMatrixException;
290 }
291