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