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 · x
034 * (and perhaps z = A<sup>T</sup> · 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 }