    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.math3.linear;
    019
    020    import org.apache.commons.math3.exception.DimensionMismatchException;
    021
    022    /**
    023     * This class defines a linear operator operating on real ({@code double})
    024     * vector spaces. No direct access to the coefficients of the underlying matrix
    025     * is provided.
    026     *
    027     * The motivation for such an interface is well stated by
    028     * <a href="#BARR1994">Barrett et al. (1994)</a>:
    029     * <blockquote>
    030     *  We restrict ourselves to iterative methods, which work by repeatedly
    031     *  improving an approximate solution until it is accurate enough. These
    032     *  methods access the coefficient matrix A of the linear system only via the
    033     *  matrix-vector product y = A &middot; x
    034     *  (and perhaps z = A<sup>T</sup> &middot; x). Thus the user need only
    035     *  supply a subroutine for computing y (and perhaps z) given x, which permits
    036     *  full exploitation of the sparsity or other special structure of A.
    037     * </blockquote>
    038     * <br/>
    039     *
    040     * <dl>
    041     *  <dt><a name="BARR1994">Barret et al. (1994)</a></dt>
    042     *  <dd>
    043     *   R. Barrett, M. Berry, T. F. Chan, J. Demmel, J. M. Donato, J. Dongarra,
    044     *   V. Eijkhout, R. Pozo, C. Romine and H. Van der Vorst,
    045     *   <em>Templates for the Solution of Linear Systems: Building Blocks for
    046     *   Iterative Methods</em>, SIAM
    047     *  </dd>
    048     * </dl>
    049     *
    050     * @version $Id: RealLinearOperator.java 1416643 2012-12-03 19:37:14Z tn $
    051     * @since 3.0
    052     */
    053    public abstract class RealLinearOperator {
    054        /**
    055         * Returns the dimension of the codomain of this operator.
    056         *
    057         * @return the number of rows of the underlying matrix
    058         */
    059        public abstract int getRowDimension();
    060
    061        /**
    062         * Returns the dimension of the domain of this operator.
    063         *
    064         * @return the number of columns of the underlying matrix
    065         */
    066        public abstract int getColumnDimension();
    067
    068        /**
    069         * Returns the result of multiplying {@code this} by the vector {@code x}.
    070         *
    071         * @param x the vector to operate on
    072         * @return the product of {@code this} instance with {@code x}
    073         * @throws DimensionMismatchException if the column dimension does not match
    074         * the size of {@code x}
    075         */
    076        public abstract RealVector operate(final RealVector x)
    077            throws DimensionMismatchException;
    078
    079        /**
    080         * Returns the result of multiplying the transpose of {@code this} operator
    081         * by the vector {@code x} (optional operation). The default implementation
    082         * throws an {@link UnsupportedOperationException}. Users overriding this
    083         * method must also override {@link #isTransposable()}.
    084         *
    085         * @param x the vector to operate on
    086         * @return the product of the transpose of {@code this} instance with
    087         * {@code x}
    088         * @throws org.apache.commons.math3.exception.DimensionMismatchException
    089         * if the row dimension does not match the size of {@code x}
    090         * @throws UnsupportedOperationException if this operation is not supported
    091         * by {@code this} operator
    092         */
    093        public RealVector operateTranspose(final RealVector x)
    094            throws DimensionMismatchException, UnsupportedOperationException {
    095            throw new UnsupportedOperationException();
    096        }
    097
    098        /**
    099         * Returns {@code true} if this operator supports
    100         * {@link #operateTranspose(RealVector)}. If {@code true} is returned,
    101         * {@link #operateTranspose(RealVector)} should not throw
    102         * {@code UnsupportedOperationException}. The default implementation returns
    103         * {@code false}.
    104         *
    105         * @return {@code false}
    106         */
    107        public boolean isTransposable() {
    108            return false;
    109        }
    110    }