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