1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements.  See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License.  You may obtain a copy of the License at
8  *
9  *      http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 package org.apache.commons.math3.linear;
19 
20 import org.apache.commons.math3.exception.DimensionMismatchException;
21 
22 /**
23  * This class defines a linear operator operating on real ({@code double}) vector spaces. No direct
24  * access to the coefficients of the underlying matrix is provided.
25  *
26  * <p>The motivation for such an interface is well stated by <a href="#BARR1994">Barrett et al.
27  * (1994)</a>:
28  *
29  * <blockquote>
30  *
31  * We restrict ourselves to iterative methods, which work by repeatedly improving an approximate
32  * solution until it is accurate enough. These methods access the coefficient matrix A of the linear
33  * system only via the matrix-vector product y = A &middot; x (and perhaps z = A<sup>T</sup>
34  * &middot; x). Thus the user need only supply a subroutine for computing y (and perhaps z) given x,
35  * which permits full exploitation of the sparsity or other special structure of A.
36  *
37  * </blockquote>
38  *
39  * <br>
40  *
41  * <dl>
42  *   <dt><a name="BARR1994">Barret et al. (1994)</a>
43  *   <dd>R. Barrett, M. Berry, T. F. Chan, J. Demmel, J. M. Donato, J. Dongarra, V. Eijkhout, R.
44  *       Pozo, C. Romine and H. Van der Vorst, <em>Templates for the Solution of Linear Systems:
45  *       Building Blocks for Iterative Methods</em>, SIAM
46  * </dl>
47  *
48  * @since 3.0
49  */
50 public abstract class RealLinearOperator {
51     /**
52      * Returns the dimension of the codomain of this operator.
53      *
54      * @return the number of rows of the underlying matrix
55      */
getRowDimension()56     public abstract int getRowDimension();
57 
58     /**
59      * Returns the dimension of the domain of this operator.
60      *
61      * @return the number of columns of the underlying matrix
62      */
getColumnDimension()63     public abstract int getColumnDimension();
64 
65     /**
66      * Returns the result of multiplying {@code this} by the vector {@code x}.
67      *
68      * @param x the vector to operate on
69      * @return the product of {@code this} instance with {@code x}
70      * @throws DimensionMismatchException if the column dimension does not match the size of {@code
71      *     x}
72      */
operate(final RealVector x)73     public abstract RealVector operate(final RealVector x) throws DimensionMismatchException;
74 
75     /**
76      * Returns the result of multiplying the transpose of {@code this} operator by the vector {@code
77      * x} (optional operation). The default implementation throws an {@link
78      * UnsupportedOperationException}. Users overriding this method must also override {@link
79      * #isTransposable()}.
80      *
81      * @param x the vector to operate on
82      * @return the product of the transpose of {@code this} instance with {@code x}
83      * @throws org.apache.commons.math3.exception.DimensionMismatchException if the row dimension
84      *     does not match the size of {@code x}
85      * @throws UnsupportedOperationException if this operation is not supported by {@code this}
86      *     operator
87      */
operateTranspose(final RealVector x)88     public RealVector operateTranspose(final RealVector x)
89             throws DimensionMismatchException, UnsupportedOperationException {
90         throw new UnsupportedOperationException();
91     }
92 
93     /**
94      * Returns {@code true} if this operator supports {@link #operateTranspose(RealVector)}. If
95      * {@code true} is returned, {@link #operateTranspose(RealVector)} should not throw {@code
96      * UnsupportedOperationException}. The default implementation returns {@code false}.
97      *
98      * @return {@code false}
99      */
isTransposable()100     public boolean isTransposable() {
101         return false;
102     }
103 }
104