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