View Javadoc

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