001: /*
002: * Copyright 2004 The Apache Software Foundation.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.apache.commons.math.linear;
018:
019: import java.math.BigDecimal;
020:
021: /**
022: * Interface defining a real-valued matrix with basic algebraic operations, using
023: * BigDecimal representations for the entries.
024: * <p>
025: * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
026: * returns the element in the first row, first column of the matrix.
027: *
028: * @version $Revision: 208875 $ $Date: 2005-07-02 15:38:00 -0700 (Sat, 02 Jul 2005) $
029: */
030: public interface BigMatrix {
031:
032: /**
033: * Returns a (deep) copy of this.
034: *
035: * @return matrix copy
036: */
037: BigMatrix copy();
038:
039: /**
040: * Compute the sum of this and m.
041: *
042: * @param m matrix to be added
043: * @return this + m
044: * @exception IllegalArgumentException if m is not the same size as this
045: */
046: BigMatrix add(BigMatrix m) throws IllegalArgumentException;
047:
048: /**
049: * Compute this minus m.
050: *
051: * @param m matrix to be subtracted
052: * @return this + m
053: * @exception IllegalArgumentException if m is not the same size as this
054: */
055: BigMatrix subtract(BigMatrix m) throws IllegalArgumentException;
056:
057: /**
058: * Returns the result of adding d to each entry of this.
059: *
060: * @param d value to be added to each entry
061: * @return d + this
062: */
063: BigMatrix scalarAdd(BigDecimal d);
064:
065: /**
066: * Returns the result multiplying each entry of this by d.
067: *
068: * @param d value to multiply all entries by
069: * @return d * this
070: */
071: BigMatrix scalarMultiply(BigDecimal d);
072:
073: /**
074: * Returns the result of postmultiplying this by m.
075: *
076: * @param m matrix to postmultiply by
077: * @return this * m
078: * @throws IllegalArgumentException
079: * if columnDimension(this) != rowDimension(m)
080: */
081: BigMatrix multiply(BigMatrix m) throws IllegalArgumentException;
082:
083: /**
084: * Returns the result premultiplying this by <code>m</code>.
085: * @param m matrix to premultiply by
086: * @return m * this
087: * @throws IllegalArgumentException
088: * if rowDimension(this) != columnDimension(m)
089: */
090: public BigMatrix preMultiply(BigMatrix m)
091: throws IllegalArgumentException;
092:
093: /**
094: * Returns matrix entries as a two-dimensional array.
095: *
096: * @return 2-dimensional array of entries
097: */
098: BigDecimal[][] getData();
099:
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>
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>
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>
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>
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)
218: throws MatrixIndexException;
219:
220: /**
221: * Returns the entry in the specified row and column.
222: * <p>
223: * Row and column indices start at 0 and must satisfy
224: * <ul>
225: * <li><code>0 <= row < rowDimension</code></li>
226: * <li><code> 0 <= column < columnDimension</code></li>
227: * </ul>
228: * otherwise a <code>MatrixIndexException</code> is thrown.
229: *
230: * @param row row location of entry to be fetched
231: * @param column column location of entry to be fetched
232: * @return matrix entry in row,column
233: * @throws MatrixIndexException if the row or column index is not valid
234: */
235: BigDecimal getEntry(int row, int column)
236: throws MatrixIndexException;
237:
238: /**
239: * Returns the entry in the specified row and column as a double.
240: * <p>
241: * Row and column indices start at 0 and must satisfy
242: * <ul>
243: * <li><code>0 <= row < rowDimension</code></li>
244: * <li><code> 0 <= column < columnDimension</code></li>
245: * </ul>
246: * otherwise a <code>MatrixIndexException</code> is thrown.
247: *
248: * @param row row location of entry to be fetched
249: * @param column column location of entry to be fetched
250: * @return matrix entry in row,column
251: * @throws MatrixIndexException if the row or column index is not valid
252: */
253: double getEntryAsDouble(int row, int column)
254: throws MatrixIndexException;
255:
256: /**
257: * Returns the transpose of this matrix.
258: *
259: * @return transpose matrix
260: */
261: BigMatrix transpose();
262:
263: /**
264: * Returns the inverse of this matrix.
265: *
266: * @return inverse matrix
267: * @throws org.apache.commons.math.linear.InvalidMatrixException if
268: * this is not invertible
269: */
270: BigMatrix inverse() throws InvalidMatrixException;
271:
272: /**
273: * Returns the determinant of this matrix.
274: *
275: * @return determinant
276: *@throws org.apache.commons.math.linear.InvalidMatrixException if
277: * matrix is not square
278: */
279: BigDecimal getDeterminant() throws InvalidMatrixException;
280:
281: /**
282: * Is this a square matrix?
283: * @return true if the matrix is square (rowDimension = columnDimension)
284: */
285: boolean isSquare();
286:
287: /**
288: * Is this a singular matrix?
289: * @return true if the matrix is singular
290: */
291: boolean isSingular();
292:
293: /**
294: * Returns the number of rows in the matrix.
295: *
296: * @return rowDimension
297: */
298: int getRowDimension();
299:
300: /**
301: * Returns the number of columns in the matrix.
302: *
303: * @return columnDimension
304: */
305: int getColumnDimension();
306:
307: /**
308: * Returns the <a href="http://mathworld.wolfram.com/MatrixTrace.html">
309: * trace</a> of the matrix (the sum of the elements on the main diagonal).
310: *
311: * @return trace
312: */
313: BigDecimal getTrace();
314:
315: /**
316: * Returns the result of multiplying this by the vector <code>v</code>.
317: *
318: * @param v the vector to operate on
319: * @return this*v
320: * @throws IllegalArgumentException if columnDimension != v.size()
321: */
322: BigDecimal[] operate(BigDecimal[] v)
323: throws IllegalArgumentException;
324:
325: /**
326: * Returns the (row) vector result of premultiplying this by the vector <code>v</code>.
327: *
328: * @param v the row vector to premultiply by
329: * @return v*this
330: * @throws IllegalArgumentException if rowDimension != v.size()
331: */
332: BigDecimal[] preMultiply(BigDecimal[] v)
333: throws IllegalArgumentException;
334:
335: /**
336: * Returns the solution vector for a linear system with coefficient
337: * matrix = this and constant vector = <code>b</code>.
338: *
339: * @param b constant vector
340: * @return vector of solution values to AX = b, where A is *this
341: * @throws IllegalArgumentException if this.rowDimension != b.length
342: * @throws org.apache.commons.math.linear.InvalidMatrixException if this matrix is not square or is singular
343: */
344: BigDecimal[] solve(BigDecimal[] b) throws IllegalArgumentException,
345: InvalidMatrixException;
346:
347: /**
348: * Returns a matrix of (column) solution vectors for linear systems with
349: * coefficient matrix = this and constant vectors = columns of
350: * <code>b</code>.
351: *
352: * @param b matrix of constant vectors forming RHS of linear systems to
353: * to solve
354: * @return matrix of solution vectors
355: * @throws IllegalArgumentException if this.rowDimension != row dimension
356: * @throws org.apache.commons.math.linear.InvalidMatrixException if this matrix is not square or is singular
357: */
358: BigMatrix solve(BigMatrix b) throws IllegalArgumentException,
359: InvalidMatrixException;
360: }
|