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
18package org.apache.commons.math.linear;
19
20import java.math.BigDecimal;
21
22/**
23 * Interface defining a real-valued matrix with basic algebraic operations, using
24 * BigDecimal representations for the entries.
25 * <p>
26 * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
27 * returns the element in the first row, first column of the matrix.</p>
28 *
29 * @version $Revision: 811786 $ $Date: 2009-09-06 11:36:08 +0200 (dim. 06 sept. 2009) $
30 * @deprecated as of 2.0, replaced by {@link FieldMatrix} with a {@link
31 * org.apache.commons.math.util.BigReal} parameter
32 */
33@Deprecated
34public interface BigMatrix extends AnyMatrix {
35
36    /**
37     * Returns a (deep) copy of this.
38     *
39     * @return matrix copy
40     */
41    BigMatrix copy();
42
43    /**
44     * Compute the sum of this and m.
45     *
46     * @param m    matrix to be added
47     * @return     this + m
48     * @exception  IllegalArgumentException if m is not the same size as this
49     */
50    BigMatrix add(BigMatrix m) throws IllegalArgumentException;
51
52    /**
53     * Compute this minus m.
54     *
55     * @param m    matrix to be subtracted
56     * @return     this + m
57     * @exception  IllegalArgumentException if m is not the same size as this
58     */
59    BigMatrix subtract(BigMatrix m) throws IllegalArgumentException;
60
61     /**
62     * Returns the result of adding d to each entry of this.
63     *
64     * @param d    value to be added to each entry
65     * @return     d + this
66     */
67    BigMatrix scalarAdd(BigDecimal d);
68
69    /**
70     * Returns the result multiplying each entry of this by d.
71     *
72     * @param d    value to multiply all entries by
73     * @return     d * this
74     */
75    BigMatrix scalarMultiply(BigDecimal d);
76
77    /**
78     * Returns the result of postmultiplying this by m.
79     *
80     * @param m    matrix to postmultiply by
81     * @return     this * m
82     * @throws     IllegalArgumentException
83     *             if columnDimension(this) != rowDimension(m)
84     */
85    BigMatrix multiply(BigMatrix m) throws IllegalArgumentException;
86
87    /**
88     * Returns the result premultiplying this by <code>m</code>.
89     * @param m    matrix to premultiply by
90     * @return     m * this
91     * @throws     IllegalArgumentException
92     *             if rowDimension(this) != columnDimension(m)
93     */
94    BigMatrix preMultiply(BigMatrix m) throws IllegalArgumentException;
95
96    /**
97     * Returns matrix entries as a two-dimensional array.
98     *
99     * @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
332