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