001: /*
002: * Copyright 2003-2005 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: /**
020: * Interface defining a real-valued matrix with basic algebraic operations.
021: * <p>
022: * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
023: * returns the element in the first row, first column of the matrix.
024: *
025: * @version $Revision: 208875 $ $Date: 2005-07-02 15:38:00 -0700 (Sat, 02 Jul 2005) $
026: */
027: public interface RealMatrix {
028: /**
029: * Returns a (deep) copy of this.
030: *
031: * @return matrix copy
032: */
033: RealMatrix copy();
034:
035: /**
036: * Compute the sum of this and m.
037: *
038: * @param m matrix to be added
039: * @return this + m
040: * @throws IllegalArgumentException if m is not the same size as this
041: */
042: RealMatrix add(RealMatrix m) throws IllegalArgumentException;
043:
044: /**
045: * Compute this minus m.
046: *
047: * @param m matrix to be subtracted
048: * @return this + m
049: * @throws IllegalArgumentException if m is not the same size as this
050: */
051: RealMatrix subtract(RealMatrix m) throws IllegalArgumentException;
052:
053: /**
054: * Returns the result of adding d to each entry of this.
055: *
056: * @param d value to be added to each entry
057: * @return d + this
058: */
059: RealMatrix scalarAdd(double d);
060:
061: /**
062: * Returns the result multiplying each entry of this by d.
063: *
064: * @param d value to multiply all entries by
065: * @return d * this
066: */
067: RealMatrix scalarMultiply(double d);
068:
069: /**
070: * Returns the result of postmultiplying this by m.
071: *
072: * @param m matrix to postmultiply by
073: * @return this * m
074: * @throws IllegalArgumentException
075: * if columnDimension(this) != rowDimension(m)
076: */
077: RealMatrix multiply(RealMatrix m) throws IllegalArgumentException;
078:
079: /**
080: * Returns the result premultiplying this by <code>m</code>.
081: * @param m matrix to premultiply by
082: * @return m * this
083: * @throws IllegalArgumentException
084: * if rowDimension(this) != columnDimension(m)
085: */
086: public RealMatrix preMultiply(RealMatrix m)
087: throws IllegalArgumentException;
088:
089: /**
090: * Returns matrix entries as a two-dimensional array.
091: *
092: * @return 2-dimensional array of entries
093: */
094: double[][] getData();
095:
096: /**
097: * Returns the <a href="http://mathworld.wolfram.com/MaximumAbsoluteRowSumNorm.html">
098: * maximum absolute row sum norm</a> of the matrix.
099: *
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,
277: InvalidMatrixException;
278:
279: /**
280: * Returns a matrix of (column) solution vectors for linear systems with
281: * coefficient matrix = this and constant vectors = columns of
282: * <code>b</code>.
283: *
284: * @param b matrix of constant vectors forming RHS of linear systems to
285: * to solve
286: * @return matrix of solution vectors
287: * @throws IllegalArgumentException if this.rowDimension != row dimension
288: * @throws InvalidMatrixException if this matrix is not square or is singular
289: */
290: RealMatrix solve(RealMatrix b) throws IllegalArgumentException,
291: InvalidMatrixException;
292: }
|