BigMatrix


1   /*
2    * Copyright 2004 The Apache Software Foundation.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.apache.commons.math.linear;
18  
19  import java.math.BigDecimal  ;
20  
21  /**
22   * Interface defining a real-valued matrix with basic algebraic operations, using
23   * BigDecimal representations for the entries.
24   * <p>
25   * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
26   * returns the element in the first row, first column of the matrix.
27   *
28   * @version $Revision$ $Date: 2005-07-02 15:38:00 -0700 (Sat, 02 Jul 2005) $
29   */
30  public interface BigMatrix {
31  
32      /**
33       * Returns a (deep) copy of this.
34       *
35       * @return matrix copy
36       */
37      BigMatrix copy();
38      
39      /**
40       * Compute the sum of this and m.
41       *
42       * @param m    matrix to be added
43       * @return     this + m
44       * @exception  IllegalArgumentException if m is not the same size as this
45       */
46      BigMatrix add(BigMatrix m) throws IllegalArgumentException  ;
47      
48      /**
49       * Compute this minus m.
50       *
51       * @param m    matrix to be subtracted
52       * @return     this + m
53       * @exception  IllegalArgumentException if m is not the same size as this
54       */
55      BigMatrix subtract(BigMatrix m) throws IllegalArgumentException  ;
56      
57       /**
58       * Returns the result of adding d to each entry of this.
59       *
60       * @param d    value to be added to each entry
61       * @return     d + this
62       */
63      BigMatrix scalarAdd(BigDecimal   d);
64      
65      /**
66       * Returns the result multiplying each entry of this by d.
67       *
68       * @param d    value to multiply all entries by
69       * @return     d * this
70       */
71      BigMatrix scalarMultiply(BigDecimal   d);
72      
73      /**
74       * Returns the result of postmultiplying this by m.
75       *
76       * @param m    matrix to postmultiply by
77       * @return     this * m
78       * @throws     IllegalArgumentException 
79       *             if columnDimension(this) != rowDimension(m)
80       */
81      BigMatrix multiply(BigMatrix m) throws IllegalArgumentException  ;
82      
83      /**
84       * Returns the result premultiplying this by <code>m</code>.
85       * @param m    matrix to premultiply by
86       * @return     m * this
87       * @throws     IllegalArgumentException
88       *             if rowDimension(this) != columnDimension(m)
89       */
90      public BigMatrix preMultiply(BigMatrix m) throws IllegalArgumentException  ;
91      
92      /**
93       * Returns matrix entries as a two-dimensional array.
94       *
95       * @return    2-dimensional array of entries
96       */
97      BigDecimal  [][] getData();
98  
99      /**
100      * Returns matrix entries as a two-dimensional array.
101      *
102      * @return    2-dimensional array of entries
103      */
104     double [][] getDataAsDoubleArray();
105 
106     /***
107      * Gets the rounding mode
108      * @return the rounding mode
109      */
110     int getRoundingMode();
111 
112     /**
113      * Returns the <a HREF="http://mathworld.wolfram.com/MaximumAbsoluteRowSumNorm.html">
114      * maximum absolute row sum norm</a> of the matrix.
115      *
116      * @return norm
117      */
118     BigDecimal   getNorm();
119     
120     /**
121      * Gets a submatrix. Rows and columns are indicated
122      * counting from 0 to n-1.
123      *
124      * @param startRow Initial row index
125      * @param endRow Final row index
126      * @param startColumn Initial column index
127      * @param endColumn Final column index
128      * @return The subMatrix containing the data of the
129      *         specified rows and columns
130      * @exception MatrixIndexException  if the indices are not valid
131      */
132     BigMatrix getSubMatrix(int startRow, int endRow, int startColumn,
133             int endColumn) throws MatrixIndexException;
134     
135     /**
136      * Gets a submatrix. Rows and columns are indicated
137      * counting from 0 to n-1.
138      *
139      * @param selectedRows Array of row indices.
140      * @param selectedColumns Array of column indices.
141      * @return The subMatrix containing the data in the
142      *         specified rows and columns
143      * @exception MatrixIndexException if row or column selections are not valid
144      */
145     BigMatrix getSubMatrix(int[] selectedRows, int[] selectedColumns)
146     throws MatrixIndexException;
147     
148     /**
149      * Returns the entries in row number <code>row</code>
150      * as a row matrix.  Row indices start at 0.
151      *
152      * @param row the row to be fetched
153      * @return row matrix
154      * @throws MatrixIndexException if the specified row index is invalid
155      */
156     BigMatrix getRowMatrix(int row) throws MatrixIndexException;
157     
158     /**
159      * Returns the entries in column number <code>column</code>
160      * as a column matrix.  Column indices start at 0.
161      *
162      * @param column the column to be fetched
163      * @return column matrix
164      * @throws MatrixIndexException if the specified column index is invalid
165      */
166     BigMatrix getColumnMatrix(int column) throws MatrixIndexException;
167     
168     /**
169      * Returns the entries in row number <code>row</code> as an array.
170      * <p>
171      * Row indices start at 0.  A <code>MatrixIndexException</code> is thrown
172      * unless <code>0 <= row < rowDimension.</code>
173      *
174      * @param row the row to be fetched
175      * @return array of entries in the row
176      * @throws MatrixIndexException if the specified row index is not valid
177      */
178     BigDecimal  [] getRow(int row) throws MatrixIndexException;
179 
180     /**
181      * Returns the entries in row number <code>row</code> as an array
182      * of double values.
183      * <p>
184      * Row indices start at 0.  A <code>MatrixIndexException</code> is thrown
185      * unless <code>0 <= row < rowDimension.</code>
186      *
187      * @param row the row to be fetched
188      * @return array of entries in the row
189      * @throws MatrixIndexException if the specified row index is not valid
190      */
191     double [] getRowAsDoubleArray(int row) throws MatrixIndexException;
192 
193     /**
194      * Returns the entries in column number <code>col</code> as an array.
195      * <p>
196      * Column indices start at 0.  A <code>MatrixIndexException</code> is thrown
197      * unless <code>0 <= column < columnDimension.</code>
198      *
199      * @param col the column to be fetched
200      * @return array of entries in the column
201      * @throws MatrixIndexException if the specified column index is not valid
202      */
203     BigDecimal  [] getColumn(int col) throws MatrixIndexException;
204 
205     /**
206      * Returns the entries in column number <code>col</code> as an array
207      * of double values.
208      * <p>
209      * Column indices start at 0.  A <code>MatrixIndexException</code> is thrown
210      * unless <code>0 <= column < columnDimension.</code>
211      *
212      * @param col the column to be fetched
213      * @return array of entries in the column
214      * @throws MatrixIndexException if the specified column index is not valid
215      */
216     double [] getColumnAsDoubleArray(int col) throws MatrixIndexException;
217 
218     /**
219      * Returns the entry in the specified row and column.
220      * <p>
221      * Row and column indices start at 0 and must satisfy 
222      * <ul>
223      * <li><code>0 <= row < rowDimension</code></li>
224      * <li><code> 0 <= column < columnDimension</code></li>
225      * </ul>
226      * otherwise a <code>MatrixIndexException</code> is thrown.
227      *
228      * @param row  row location of entry to be fetched  
229      * @param column  column location of entry to be fetched
230      * @return matrix entry in row,column
231      * @throws MatrixIndexException if the row or column index is not valid
232      */
233     BigDecimal   getEntry(int row, int column) throws MatrixIndexException;
234     
235     /**
236      * Returns the entry in the specified row and column as a double.
237      * <p>
238      * Row and column indices start at 0 and must satisfy 
239      * <ul>
240      * <li><code>0 <= row < rowDimension</code></li>
241      * <li><code> 0 <= column < columnDimension</code></li>
242      * </ul>
243      * otherwise a <code>MatrixIndexException</code> is thrown.
244      *
245      * @param row  row location of entry to be fetched
246      * @param column  column location of entry to be fetched
247      * @return matrix entry in row,column
248      * @throws MatrixIndexException if the row or column index is not valid
249      */
250     double getEntryAsDouble(int row, int column) throws MatrixIndexException;
251 
252     /**
253      * Returns the transpose of this matrix.
254      *
255      * @return transpose matrix
256      */
257     BigMatrix transpose();
258     
259     /**
260      * Returns the inverse of this matrix.
261      *
262      * @return inverse matrix
263      * @throws org.apache.commons.math.linear.InvalidMatrixException if 
264      *     this is not invertible
265      */
266     BigMatrix inverse() throws InvalidMatrixException;
267     
268     /**
269      * Returns the determinant of this matrix.
270      *
271      * @return determinant
272       *@throws org.apache.commons.math.linear.InvalidMatrixException if 
273       *    matrix is not square
274      */
275     BigDecimal   getDeterminant() throws InvalidMatrixException;
276     
277     /**
278      * Is this a square matrix?
279      * @return true if the matrix is square (rowDimension = columnDimension)
280      */
281     boolean isSquare();
282     
283     /**
284      * Is this a singular matrix?
285      * @return true if the matrix is singular
286      */
287     boolean isSingular();
288     
289     /**
290      * Returns the number of rows in the matrix.
291      *
292      * @return rowDimension
293      */
294     int getRowDimension();
295     
296     /**
297      * Returns the number of columns in the matrix.
298      *
299      * @return columnDimension
300      */
301     int getColumnDimension();
302     
303     /**
304      * Returns the <a HREF="http://mathworld.wolfram.com/MatrixTrace.html">
305      * trace</a> of the matrix (the sum of the elements on the main diagonal).
306      *
307      * @return trace
308      */
309     BigDecimal   getTrace();
310     
311     /**
312      * Returns the result of multiplying this by the vector <code>v</code>.
313      *
314      * @param v the vector to operate on
315      * @return this*v
316      * @throws IllegalArgumentException if columnDimension != v.size()
317      */
318     BigDecimal  [] operate(BigDecimal  [] v) throws IllegalArgumentException  ;
319 
320     /**
321      * Returns the (row) vector result of premultiplying this by the vector <code>v</code>.
322      *
323      * @param v the row vector to premultiply by
324      * @return v*this
325      * @throws IllegalArgumentException if rowDimension != v.size()
326      */
327     BigDecimal  [] preMultiply(BigDecimal  [] v) throws IllegalArgumentException  ;
328     
329     /**
330      * Returns the solution vector for a linear system with coefficient
331      * matrix = this and constant vector = <code>b</code>.
332      *
333      * @param b  constant vector
334      * @return vector of solution values to AX = b, where A is *this
335      * @throws IllegalArgumentException if this.rowDimension != b.length 
336      * @throws org.apache.commons.math.linear.InvalidMatrixException if this matrix is not square or is singular
337      */
338     BigDecimal  [] solve(BigDecimal  [] b) throws IllegalArgumentException  , InvalidMatrixException;
339 
340     /**
341      * Returns a matrix of (column) solution vectors for linear systems with
342      * coefficient matrix = this and constant vectors = columns of
343      * <code>b</code>. 
344      *
345      * @param b  matrix of constant vectors forming RHS of linear systems to
346      * to solve
347      * @return matrix of solution vectors
348      * @throws IllegalArgumentException if this.rowDimension != row dimension
349      * @throws org.apache.commons.math.linear.InvalidMatrixException if this matrix is not square or is singular
350      */
351     BigMatrix solve(BigMatrix b) throws IllegalArgumentException  , InvalidMatrixException;
352 }
353 
354
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags