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