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