RealMatrix


1   /*
2    * Copyright 2003-2005 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  /**
20   * Interface defining a real-valued matrix with basic algebraic operations.
21   * <p>
22   * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
23   * returns the element in the first row, first column of the matrix.
24   * 
25   * @version $Revision$ $Date: 2005-07-02 15:38:00 -0700 (Sat, 02 Jul 2005) $
26   */
27  public interface RealMatrix {
28      /**
29       * Returns a (deep) copy of this.
30       *
31       * @return matrix copy
32       */
33      RealMatrix copy();
34  
35      /**
36       * Compute the sum of this and m.
37       *
38       * @param m    matrix to be added
39       * @return     this + m
40       * @throws  IllegalArgumentException if m is not the same size as this
41       */
42      RealMatrix add(RealMatrix m) throws IllegalArgumentException  ;
43  
44      /**
45       * Compute this minus m.
46       *
47       * @param m    matrix to be subtracted
48       * @return     this + m
49       * @throws  IllegalArgumentException if m is not the same size as this
50       */
51      RealMatrix subtract(RealMatrix m) throws IllegalArgumentException  ;
52  
53       /**
54       * Returns the result of adding d to each entry of this.
55       *
56       * @param d    value to be added to each entry
57       * @return     d + this
58       */
59      RealMatrix scalarAdd(double d);
60  
61      /**
62       * Returns the result multiplying each entry of this by d.
63       *
64       * @param d    value to multiply all entries by
65       * @return     d * this
66       */
67      RealMatrix scalarMultiply(double d);
68  
69      /**
70       * Returns the result of postmultiplying this by m.
71       *
72       * @param m    matrix to postmultiply by
73       * @return     this * m
74       * @throws     IllegalArgumentException
75       *             if columnDimension(this) != rowDimension(m)
76       */
77      RealMatrix multiply(RealMatrix m) throws IllegalArgumentException  ;
78  
79      /**
80       * Returns the result premultiplying this by <code>m</code>.
81       * @param m    matrix to premultiply by
82       * @return     m * this
83       * @throws     IllegalArgumentException
84       *             if rowDimension(this) != columnDimension(m)
85       */
86      public RealMatrix preMultiply(RealMatrix m) throws IllegalArgumentException  ;
87  
88      /**
89       * Returns matrix entries as a two-dimensional array.
90       *
91       * @return    2-dimensional array of entries
92       */
93      double[][] getData();
94  
95      /**
96       * Returns the <a HREF="http://mathworld.wolfram.com/MaximumAbsoluteRowSumNorm.html">
97       * maximum absolute row sum norm</a> of the matrix.
98       *
99       * @return norm
100      */
101     double getNorm();
102     
103     /**
104      * Gets a submatrix. Rows and columns are indicated
105      * counting from 0 to n-1.
106      *
107      * @param startRow Initial row index
108      * @param endRow Final row index
109      * @param startColumn Initial column index
110      * @param endColumn Final column index
111      * @return The subMatrix containing the data of the
112      *         specified rows and columns
113      * @exception MatrixIndexException  if the indices are not valid
114      */
115    RealMatrix getSubMatrix(int startRow, int endRow, int startColumn,
116             int endColumn) throws MatrixIndexException;
117    
118    /**
119     * Gets a submatrix. Rows and columns are indicated
120     * counting from 0 to n-1.
121     *
122     * @param selectedRows Array of row indices.
123     * @param selectedColumns Array of column indices.
124     * @return The subMatrix containing the data in the
125     *         specified rows and columns
126     * @exception MatrixIndexException if row or column selections are not valid
127     */
128    RealMatrix getSubMatrix(int[] selectedRows, int[] selectedColumns)
129    throws MatrixIndexException;
130    
131    /**
132     * Returns the entries in row number <code>row</code>
133     * as a row matrix.  Row indices start at 0.
134     *
135     * @param row the row to be fetched
136     * @return row matrix
137     * @throws MatrixIndexException if the specified row index is invalid
138     */
139    RealMatrix getRowMatrix(int row) throws MatrixIndexException;
140    
141    /**
142     * Returns the entries in column number <code>column</code>
143     * as a column matrix.  Column indices start at 0.
144     *
145     * @param column the column to be fetched
146     * @return column matrix
147     * @throws MatrixIndexException if the specified column index is invalid
148     */
149    RealMatrix getColumnMatrix(int column) throws MatrixIndexException;
150     
151     /**
152      * Returns the entries in row number <code>row</code> as an array.
153      * <p>
154      * Row indices start at 0.  A <code>MatrixIndexException</code> is thrown
155      * unless <code>0 <= row < rowDimension.</code>
156      *
157      * @param row the row to be fetched
158      * @return array of entries in the row
159      * @throws MatrixIndexException if the specified row index is not valid
160      */
161     double[] getRow(int row) throws MatrixIndexException;
162 
163     /**
164      * Returns the entries in column number <code>col</code> as an array.
165      * <p>
166      * Column indices start at 0.  A <code>MatrixIndexException</code> is thrown
167      * unless <code>0 <= column < columnDimension.</code>
168      *
169      * @param col the column to be fetched
170      * @return array of entries in the column
171      * @throws MatrixIndexException if the specified column index is not valid
172      */
173     double[] getColumn(int col) throws MatrixIndexException;
174 
175     /**
176      * Returns the entry in the specified row and column.
177      * <p>
178      * Row and column indices start at 0 and must satisfy 
179      * <ul>
180      * <li><code>0 <= row < rowDimension</code></li>
181      * <li><code> 0 <= column < columnDimension</code></li>
182      * </ul>
183      * otherwise a <code>MatrixIndexException</code> is thrown.
184      * 
185      * @param row  row location of entry to be fetched
186      * @param column  column location of entry to be fetched
187      * @return matrix entry in row,column
188      * @throws MatrixIndexException if the row or column index is not valid
189      */
190     double getEntry(int row, int column) throws MatrixIndexException;
191 
192     /**
193      * Returns the transpose of this matrix.
194      *
195      * @return transpose matrix
196      */
197     RealMatrix transpose();
198 
199     /**
200      * Returns the inverse of this matrix.
201      *
202      * @return inverse matrix
203      * @throws InvalidMatrixException if  this is not invertible
204      */
205     RealMatrix inverse() throws InvalidMatrixException;
206 
207     /**
208      * Returns the determinant of this matrix.
209      *
210      * @return determinant
211      */
212     double getDeterminant();
213 
214     /**
215      * Is this a square matrix?
216      * @return true if the matrix is square (rowDimension = columnDimension)
217      */
218     boolean isSquare();
219 
220     /**
221      * Is this a singular matrix?
222      * @return true if the matrix is singular
223      */
224     boolean isSingular();
225 
226     /**
227      * Returns the number of rows in the matrix.
228      *
229      * @return rowDimension
230      */
231     int getRowDimension();
232 
233     /**
234      * Returns the number of columns in the matrix.
235      *
236      * @return columnDimension
237      */
238     int getColumnDimension();
239 
240     /**
241      * Returns the <a HREF="http://mathworld.wolfram.com/MatrixTrace.html">
242      * trace</a> of the matrix (the sum of the elements on the main diagonal).
243      *
244      * @return trace
245      */
246     double getTrace();
247 
248     /**
249      * Returns the result of multiplying this by the vector <code>v</code>.
250      *
251      * @param v the vector to operate on
252      * @return this*v
253      * @throws IllegalArgumentException if columnDimension != v.size()
254      */
255     double[] operate(double[] v) throws IllegalArgumentException  ;
256 
257     /**
258      * Returns the (row) vector result of premultiplying this by the vector <code>v</code>.
259      *
260      * @param v the row vector to premultiply by
261      * @return v*this
262      * @throws IllegalArgumentException if rowDimension != v.size()
263      */
264     double[] preMultiply(double[] v) throws IllegalArgumentException  ;
265 
266     /**
267      * Returns the solution vector for a linear system with coefficient
268      * matrix = this and constant vector = <code>b</code>.
269      *
270      * @param b  constant vector
271      * @return vector of solution values to AX = b, where A is *this
272      * @throws IllegalArgumentException if this.rowDimension != b.length
273      * @throws InvalidMatrixException if this matrix is not square or is singular
274      */
275     double[] solve(double[] b) throws IllegalArgumentException  , InvalidMatrixException;
276 
277     /**
278      * Returns a matrix of (column) solution vectors for linear systems with
279      * coefficient matrix = this and constant vectors = columns of
280      * <code>b</code>.
281      *
282      * @param b  matrix of constant vectors forming RHS of linear systems to
283      * to solve
284      * @return matrix of solution vectors
285      * @throws IllegalArgumentException if this.rowDimension != row dimension
286      * @throws InvalidMatrixException if this matrix is not square or is singular
287      */
288     RealMatrix solve(RealMatrix b) throws IllegalArgumentException  , InvalidMatrixException;
289 }
290 
291
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags