View Javadoc

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