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 package org.apache.commons.math4.legacy.linear;
18
19 import org.apache.commons.math4.legacy.exception.MathUnsupportedOperationException;
20
21 /**
22 * This is the base class for all events occurring during the iterations of a
23 * {@link IterativeLinearSolver}.
24 *
25 * @since 3.0
26 */
27 public abstract class IterativeLinearSolverEvent
28 extends IterationEvent {
29 /** Serialization identifier. */
30 private static final long serialVersionUID = 20120129L;
31
32 /**
33 * Creates a new instance of this class.
34 *
35 * @param source the iterative algorithm on which the event initially
36 * occurred
37 * @param iterations the number of iterations performed at the time
38 * {@code this} event is created
39 */
40 public IterativeLinearSolverEvent(final Object source, final int iterations) {
41 super(source, iterations);
42 }
43
44 /**
45 * Returns the current right-hand side of the linear system to be solved.
46 * This method should return an unmodifiable view, or a deep copy of the
47 * actual right-hand side vector, in order not to compromise subsequent
48 * iterations of the source {@link IterativeLinearSolver}.
49 *
50 * @return the right-hand side vector, b
51 */
52 public abstract RealVector getRightHandSideVector();
53
54 /**
55 * Returns the norm of the residual. The returned value is not required to
56 * be <em>exact</em>. Instead, the norm of the so-called <em>updated</em>
57 * residual (if available) should be returned. For example, the
58 * {@link ConjugateGradient conjugate gradient} method computes a sequence
59 * of residuals, the norm of which is cheap to compute. However, due to
60 * accumulation of round-off errors, this residual might differ from the
61 * true residual after some iterations. See e.g. A. Greenbaum and
62 * Z. Strakos, <em>Predicting the Behavior of Finite Precision Lanzos and
63 * Conjugate Gradient Computations</em>, Technical Report 538, Department of
64 * Computer Science, New York University, 1991 (available
65 * <a href="http://www.archive.org/details/predictingbehavi00gree">here</a>).
66 *
67 * @return the norm of the residual, ||r||
68 */
69 public abstract double getNormOfResidual();
70
71 /**
72 * <p>
73 * Returns the residual. This is an optional operation, as all iterative
74 * linear solvers do not provide cheap estimate of the updated residual
75 * vector, in which case
76 * </p>
77 * <ul>
78 * <li>this method should throw a
79 * {@link MathUnsupportedOperationException},</li>
80 * <li>{@link #providesResidual()} returns {@code false}.</li>
81 * </ul>
82 * <p>
83 * The default implementation throws a
84 * {@link MathUnsupportedOperationException}. If this method is overridden,
85 * then {@link #providesResidual()} should be overridden as well.
86 * </p>
87 *
88 * @return the updated residual, r
89 */
90 public RealVector getResidual() {
91 throw new MathUnsupportedOperationException();
92 }
93
94 /**
95 * Returns the current estimate of the solution to the linear system to be
96 * solved. This method should return an unmodifiable view, or a deep copy of
97 * the actual current solution, in order not to compromise subsequent
98 * iterations of the source {@link IterativeLinearSolver}.
99 *
100 * @return the solution, x
101 */
102 public abstract RealVector getSolution();
103
104 /**
105 * Returns {@code true} if {@link #getResidual()} is supported. The default
106 * implementation returns {@code false}.
107 *
108 * @return {@code false} if {@link #getResidual()} throws a
109 * {@link MathUnsupportedOperationException}
110 */
111 public boolean providesResidual() {
112 return false;
113 }
114 }