View Javadoc

    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: 1.9 $ $Date: 2004/10/25 03:12:28 $
    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