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: 772119 $ $Date: 2009-05-06 05:43:28 -0400 (Wed, 06 May 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        public 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