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