001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 package org.apache.commons.math.linear;
019
020 import java.math.BigDecimal;
021
022 /**
023 * Interface defining a real-valued matrix with basic algebraic operations, using
024 * BigDecimal representations for the entries.
025 * <p>
026 * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
027 * returns the element in the first row, first column of the matrix.</p>
028 *
029 * @version $Revision: 811786 $ $Date: 2009-09-06 11:36:08 +0200 (dim. 06 sept. 2009) $
030 * @deprecated as of 2.0, replaced by {@link FieldMatrix} with a {@link
031 * org.apache.commons.math.util.BigReal} parameter
032 */
033 @Deprecated
034 public interface BigMatrix extends AnyMatrix {
035
036 /**
037 * Returns a (deep) copy of this.
038 *
039 * @return matrix copy
040 */
041 BigMatrix copy();
042
043 /**
044 * Compute the sum of this and m.
045 *
046 * @param m matrix to be added
047 * @return this + m
048 * @exception IllegalArgumentException if m is not the same size as this
049 */
050 BigMatrix add(BigMatrix m) throws IllegalArgumentException;
051
052 /**
053 * Compute this minus m.
054 *
055 * @param m matrix to be subtracted
056 * @return this + m
057 * @exception IllegalArgumentException if m is not the same size as this
058 */
059 BigMatrix subtract(BigMatrix m) throws IllegalArgumentException;
060
061 /**
062 * Returns the result of adding d to each entry of this.
063 *
064 * @param d value to be added to each entry
065 * @return d + this
066 */
067 BigMatrix scalarAdd(BigDecimal d);
068
069 /**
070 * Returns the result multiplying each entry of this by d.
071 *
072 * @param d value to multiply all entries by
073 * @return d * this
074 */
075 BigMatrix scalarMultiply(BigDecimal d);
076
077 /**
078 * Returns the result of postmultiplying this by m.
079 *
080 * @param m matrix to postmultiply by
081 * @return this * m
082 * @throws IllegalArgumentException
083 * if columnDimension(this) != rowDimension(m)
084 */
085 BigMatrix multiply(BigMatrix m) throws IllegalArgumentException;
086
087 /**
088 * Returns the result premultiplying this by <code>m</code>.
089 * @param m matrix to premultiply by
090 * @return m * this
091 * @throws IllegalArgumentException
092 * if rowDimension(this) != columnDimension(m)
093 */
094 BigMatrix preMultiply(BigMatrix m) throws IllegalArgumentException;
095
096 /**
097 * Returns matrix entries as a two-dimensional array.
098 *
099 * @return 2-dimensional array of entries
100 */
101 BigDecimal[][] getData();
102
103 /**
104 * Returns matrix entries as a two-dimensional array.
105 *
106 * @return 2-dimensional array of entries
107 */
108 double [][] getDataAsDoubleArray();
109
110 /***
111 * Gets the rounding mode
112 * @return the rounding mode
113 */
114 int getRoundingMode();
115
116 /**
117 * Returns the <a href="http://mathworld.wolfram.com/MaximumAbsoluteRowSumNorm.html">
118 * maximum absolute row sum norm</a> of the matrix.
119 *
120 * @return norm
121 */
122 BigDecimal getNorm();
123
124 /**
125 * Gets a submatrix. Rows and columns are indicated
126 * counting from 0 to n-1.
127 *
128 * @param startRow Initial row index
129 * @param endRow Final row index
130 * @param startColumn Initial column index
131 * @param endColumn Final column index
132 * @return The subMatrix containing the data of the
133 * specified rows and columns
134 * @exception MatrixIndexException if the indices are not valid
135 */
136 BigMatrix getSubMatrix(int startRow, int endRow, int startColumn,
137 int endColumn) throws MatrixIndexException;
138
139 /**
140 * Gets a submatrix. Rows and columns are indicated
141 * counting from 0 to n-1.
142 *
143 * @param selectedRows Array of row indices.
144 * @param selectedColumns Array of column indices.
145 * @return The subMatrix containing the data in the
146 * specified rows and columns
147 * @exception MatrixIndexException if row or column selections are not valid
148 */
149 BigMatrix getSubMatrix(int[] selectedRows, int[] selectedColumns)
150 throws MatrixIndexException;
151
152 /**
153 * Returns the entries in row number <code>row</code>
154 * as a row matrix. Row indices start at 0.
155 *
156 * @param row the row to be fetched
157 * @return row matrix
158 * @throws MatrixIndexException if the specified row index is invalid
159 */
160 BigMatrix getRowMatrix(int row) throws MatrixIndexException;
161
162 /**
163 * Returns the entries in column number <code>column</code>
164 * as a column matrix. Column indices start at 0.
165 *
166 * @param column the column to be fetched
167 * @return column matrix
168 * @throws MatrixIndexException if the specified column index is invalid
169 */
170 BigMatrix getColumnMatrix(int column) throws MatrixIndexException;
171
172 /**
173 * Returns the entries in row number <code>row</code> as an array.
174 * <p>
175 * Row indices start at 0. A <code>MatrixIndexException</code> is thrown
176 * unless <code>0 <= row < rowDimension.</code></p>
177 *
178 * @param row the row to be fetched
179 * @return array of entries in the row
180 * @throws MatrixIndexException if the specified row index is not valid
181 */
182 BigDecimal[] getRow(int row) throws MatrixIndexException;
183
184 /**
185 * Returns the entries in row number <code>row</code> as an array
186 * of double values.
187 * <p>
188 * Row indices start at 0. A <code>MatrixIndexException</code> is thrown
189 * unless <code>0 <= row < rowDimension.</code></p>
190 *
191 * @param row the row to be fetched
192 * @return array of entries in the row
193 * @throws MatrixIndexException if the specified row index is not valid
194 */
195 double [] getRowAsDoubleArray(int row) throws MatrixIndexException;
196
197 /**
198 * Returns the entries in column number <code>col</code> as an array.
199 * <p>
200 * Column indices start at 0. A <code>MatrixIndexException</code> is thrown
201 * unless <code>0 <= column < columnDimension.</code></p>
202 *
203 * @param col the column to be fetched
204 * @return array of entries in the column
205 * @throws MatrixIndexException if the specified column index is not valid
206 */
207 BigDecimal[] getColumn(int col) throws MatrixIndexException;
208
209 /**
210 * Returns the entries in column number <code>col</code> as an array
211 * of double values.
212 * <p>
213 * Column indices start at 0. A <code>MatrixIndexException</code> is thrown
214 * unless <code>0 <= column < columnDimension.</code></p>
215 *
216 * @param col the column to be fetched
217 * @return array of entries in the column
218 * @throws MatrixIndexException if the specified column index is not valid
219 */
220 double [] getColumnAsDoubleArray(int col) throws MatrixIndexException;
221
222 /**
223 * Returns the entry in the specified row and column.
224 * <p>
225 * Row and column indices start at 0 and must satisfy
226 * <ul>
227 * <li><code>0 <= row < rowDimension</code></li>
228 * <li><code> 0 <= column < columnDimension</code></li>
229 * </ul>
230 * otherwise a <code>MatrixIndexException</code> is thrown.</p>
231 *
232 * @param row row location of entry to be fetched
233 * @param column column location of entry to be fetched
234 * @return matrix entry in row,column
235 * @throws MatrixIndexException if the row or column index is not valid
236 */
237 BigDecimal getEntry(int row, int column) throws MatrixIndexException;
238
239 /**
240 * Returns the entry in the specified row and column as a double.
241 * <p>
242 * Row and column indices start at 0 and must satisfy
243 * <ul>
244 * <li><code>0 <= row < rowDimension</code></li>
245 * <li><code> 0 <= column < columnDimension</code></li>
246 * </ul>
247 * otherwise a <code>MatrixIndexException</code> is thrown.</p>
248 *
249 * @param row row location of entry to be fetched
250 * @param column column location of entry to be fetched
251 * @return matrix entry in row,column
252 * @throws MatrixIndexException if the row or column index is not valid
253 */
254 double getEntryAsDouble(int row, int column) 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 * Returns the <a href="http://mathworld.wolfram.com/MatrixTrace.html">
283 * trace</a> of the matrix (the sum of the elements on the main diagonal).
284 *
285 * @return trace
286 */
287 BigDecimal getTrace();
288
289 /**
290 * Returns the result of multiplying this by the vector <code>v</code>.
291 *
292 * @param v the vector to operate on
293 * @return this*v
294 * @throws IllegalArgumentException if columnDimension != v.size()
295 */
296 BigDecimal[] operate(BigDecimal[] v) throws IllegalArgumentException;
297
298 /**
299 * Returns the (row) vector result of premultiplying this by the vector <code>v</code>.
300 *
301 * @param v the row vector to premultiply by
302 * @return v*this
303 * @throws IllegalArgumentException if rowDimension != v.size()
304 */
305 BigDecimal[] preMultiply(BigDecimal[] v) throws IllegalArgumentException;
306
307 /**
308 * Returns the solution vector for a linear system with coefficient
309 * matrix = this and constant vector = <code>b</code>.
310 *
311 * @param b constant vector
312 * @return vector of solution values to AX = b, where A is *this
313 * @throws IllegalArgumentException if this.rowDimension != b.length
314 * @throws org.apache.commons.math.linear.InvalidMatrixException if this matrix is not square or is singular
315 */
316 BigDecimal[] solve(BigDecimal[] b) throws IllegalArgumentException, InvalidMatrixException;
317
318 /**
319 * Returns a matrix of (column) solution vectors for linear systems with
320 * coefficient matrix = this and constant vectors = columns of
321 * <code>b</code>.
322 *
323 * @param b matrix of constant vectors forming RHS of linear systems to
324 * to solve
325 * @return matrix of solution vectors
326 * @throws IllegalArgumentException if this.rowDimension != row dimension
327 * @throws org.apache.commons.math.linear.InvalidMatrixException if this matrix is not square or is singular
328 */
329 BigMatrix solve(BigMatrix b) throws IllegalArgumentException, InvalidMatrixException;
330 }
331