    001    /*
    002     * Licensed to the Apache Software Foundation (ASF) under one or more
    003     * contributor license agreements.  See the NOTICE file distributed with
    004     * this work for additional information regarding copyright ownership.
    005     * The ASF licenses this file to You under the Apache License, Version 2.0
    006     * (the "License"); you may not use this file except in compliance with
    007     * the License.  You may obtain a copy of the License at
    008     *
    009     *      http://www.apache.org/licenses/LICENSE-2.0
    010     *
    011     * Unless required by applicable law or agreed to in writing, software
    012     * distributed under the License is distributed on an "AS IS" BASIS,
    013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    014     * See the License for the specific language governing permissions and
    015     * limitations under the License.
    016     */
    017
    018    package org.apache.commons.math.linear;
    019
    020    import java.math.BigDecimal;
    021
    022    /**
    023     * Interface defining a real-valued matrix with basic algebraic operations, using
    024     * BigDecimal representations for the entries.
    025     * <p>
    026     * Matrix element indexing is 0-based -- e.g., <code>getEntry(0, 0)</code>
    027     * returns the element in the first row, first column of the matrix.</p>
    028     *
    029     * @version $Revision: 811786 $ $Date: 2009-09-06 11:36:08 +0200 (dim. 06 sept. 2009) $
    030     * @deprecated as of 2.0, replaced by {@link FieldMatrix} with a {@link
    031     * org.apache.commons.math.util.BigReal} parameter
    032     */
    033    @Deprecated
    034    public interface BigMatrix extends AnyMatrix {
    035
    036        /**
    037         * Returns a (deep) copy of this.
    038         *
    039         * @return matrix copy
    040         */
    041        BigMatrix copy();
    042
    043        /**
    044         * Compute the sum of this and m.
    045         *
    046         * @param m    matrix to be added
    047         * @return     this + m
    048         * @exception  IllegalArgumentException if m is not the same size as this
    049         */
    050        BigMatrix add(BigMatrix m) throws IllegalArgumentException;
    051
    052        /**
    053         * Compute this minus m.
    054         *
    055         * @param m    matrix to be subtracted
    056         * @return     this + m
    057         * @exception  IllegalArgumentException if m is not the same size as this
    058         */
    059        BigMatrix subtract(BigMatrix m) throws IllegalArgumentException;
    060
    061         /**
    062         * Returns the result of adding d to each entry of this.
    063         *
    064         * @param d    value to be added to each entry
    065         * @return     d + this
    066         */
    067        BigMatrix scalarAdd(BigDecimal d);
    068
    069        /**
    070         * Returns the result multiplying each entry of this by d.
    071         *
    072         * @param d    value to multiply all entries by
    073         * @return     d * this
    074         */
    075        BigMatrix scalarMultiply(BigDecimal d);
    076
    077        /**
    078         * Returns the result of postmultiplying this by m.
    079         *
    080         * @param m    matrix to postmultiply by
    081         * @return     this * m
    082         * @throws     IllegalArgumentException
    083         *             if columnDimension(this) != rowDimension(m)
    084         */
    085        BigMatrix multiply(BigMatrix m) throws IllegalArgumentException;
    086
    087        /**
    088         * Returns the result premultiplying this by <code>m</code>.
    089         * @param m    matrix to premultiply by
    090         * @return     m * this
    091         * @throws     IllegalArgumentException
    092         *             if rowDimension(this) != columnDimension(m)
    093         */
    094        BigMatrix preMultiply(BigMatrix m) throws IllegalArgumentException;
    095
    096        /**
    097         * Returns matrix entries as a two-dimensional array.
    098         *
    099         * @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