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