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