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.math4.legacy.linear;
19
20 import org.apache.commons.math4.legacy.exception.DimensionMismatchException;
21
22 /**
23 * This class defines a linear operator operating on real ({@code double})
24 * vector spaces. No direct access to the coefficients of the underlying matrix
25 * is provided.
26 *
27 * The motivation for such an interface is well stated by
28 * <a href="#BARR1994">Barrett et al. (1994)</a>:
29 * <blockquote>
30 * We restrict ourselves to iterative methods, which work by repeatedly
31 * improving an approximate solution until it is accurate enough. These
32 * methods access the coefficient matrix A of the linear system only via the
33 * matrix-vector product y = A · x
34 * (and perhaps z = A<sup>T</sup> · x). Thus the user need only
35 * supply a subroutine for computing y (and perhaps z) given x, which permits
36 * full exploitation of the sparsity or other special structure of A.
37 * </blockquote>
38 * <br>
39 *
40 * <dl>
41 * <dt><a id="BARR1994">Barret et al. (1994)</a></dt>
42 * <dd>
43 * R. Barrett, M. Berry, T. F. Chan, J. Demmel, J. M. Donato, J. Dongarra,
44 * V. Eijkhout, R. Pozo, C. Romine and H. Van der Vorst,
45 * <em>Templates for the Solution of Linear Systems: Building Blocks for
46 * Iterative Methods</em>, SIAM
47 * </dd>
48 * </dl>
49 *
50 * @since 3.0
51 */
52 public abstract class RealLinearOperator {
53 /**
54 * Returns the dimension of the codomain of this operator.
55 *
56 * @return the number of rows of the underlying matrix
57 */
58 public abstract int getRowDimension();
59
60 /**
61 * Returns the dimension of the domain of this operator.
62 *
63 * @return the number of columns of the underlying matrix
64 */
65 public abstract int getColumnDimension();
66
67 /**
68 * Returns the result of multiplying {@code this} by the vector {@code x}.
69 *
70 * @param x the vector to operate on
71 * @return the product of {@code this} instance with {@code x}
72 * @throws DimensionMismatchException if the column dimension does not match
73 * the size of {@code x}
74 */
75 public abstract RealVector operate(RealVector x)
76 throws DimensionMismatchException;
77
78 /**
79 * Returns the result of multiplying the transpose of {@code this} operator
80 * by the vector {@code x} (optional operation). The default implementation
81 * throws an {@link UnsupportedOperationException}. Users overriding this
82 * method must also override {@link #isTransposable()}.
83 *
84 * @param x the vector to operate on
85 * @return the product of the transpose of {@code this} instance with
86 * {@code x}
87 * @throws org.apache.commons.math4.legacy.exception.DimensionMismatchException
88 * if the row dimension does not match the size of {@code x}
89 * @throws UnsupportedOperationException if this operation is not supported
90 * by {@code this} operator
91 */
92 public RealVector operateTranspose(final RealVector x)
93 throws DimensionMismatchException, UnsupportedOperationException {
94 throw new UnsupportedOperationException();
95 }
96
97 /**
98 * Returns {@code true} if this operator supports
99 * {@link #operateTranspose(RealVector)}. If {@code true} is returned,
100 * {@link #operateTranspose(RealVector)} should not throw
101 * {@code UnsupportedOperationException}. The default implementation returns
102 * {@code false}.
103 *
104 * @return {@code false}
105 */
106 public boolean isTransposable() {
107 return false;
108 }
109 }