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: 208875 $ $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