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 /**
21 * Interface defining a real-valued matrix with basic algebraic operations.
22 * <p>
23 * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
24 * returns the element in the first row, first column of the matrix.</p>
25 *
26 * @version $Revision: 617953 $ $Date: 2008-02-02 22:54:00 -0700 (Sat, 02 Feb 2008) $
27 */
28 public interface RealMatrix {
29 /**
30 * Returns a (deep) copy of this.
31 *
32 * @return matrix copy
33 */
34 RealMatrix copy();
35
36 /**
37 * Compute the sum of this and m.
38 *
39 * @param m matrix to be added
40 * @return this + m
41 * @throws IllegalArgumentException if m is not the same size as this
42 */
43 RealMatrix add(RealMatrix m) throws IllegalArgumentException;
44
45 /**
46 * Compute this minus m.
47 *
48 * @param m matrix to be subtracted
49 * @return this + m
50 * @throws IllegalArgumentException if m is not the same size as this
51 */
52 RealMatrix subtract(RealMatrix m) throws IllegalArgumentException;
53
54 /**
55 * Returns the result of adding d to each entry of this.
56 *
57 * @param d value to be added to each entry
58 * @return d + this
59 */
60 RealMatrix scalarAdd(double d);
61
62 /**
63 * Returns the result multiplying each entry of this by d.
64 *
65 * @param d value to multiply all entries by
66 * @return d * this
67 */
68 RealMatrix scalarMultiply(double d);
69
70 /**
71 * Returns the result of postmultiplying this by m.
72 *
73 * @param m matrix to postmultiply by
74 * @return this * m
75 * @throws IllegalArgumentException
76 * if columnDimension(this) != rowDimension(m)
77 */
78 RealMatrix multiply(RealMatrix m) throws IllegalArgumentException;
79
80 /**
81 * Returns the result premultiplying this by <code>m</code>.
82 * @param m matrix to premultiply by
83 * @return m * this
84 * @throws IllegalArgumentException
85 * if rowDimension(this) != columnDimension(m)
86 */
87 public RealMatrix preMultiply(RealMatrix m) throws IllegalArgumentException;
88
89 /**
90 * Returns matrix entries as a two-dimensional array.
91 *
92 * @return 2-dimensional array of entries
93 */
94 double[][] getData();
95
96 /**
97 * Returns the <a href="http://mathworld.wolfram.com/MaximumAbsoluteRowSumNorm.html">
98 * maximum absolute row sum norm</a> of the matrix.
99 *
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></p>
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></p>
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.</p>
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, InvalidMatrixException;
277
278 /**
279 * Returns a matrix of (column) solution vectors for linear systems with
280 * coefficient matrix = this and constant vectors = columns of
281 * <code>b</code>.
282 *
283 * @param b matrix of constant vectors forming RHS of linear systems to
284 * to solve
285 * @return matrix of solution vectors
286 * @throws IllegalArgumentException if this.rowDimension != row dimension
287 * @throws InvalidMatrixException if this matrix is not square or is singular
288 */
289 RealMatrix solve(RealMatrix b) throws IllegalArgumentException, InvalidMatrixException;
290 }
291