View Javadoc

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