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