    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    package org.apache.commons.math3.linear;
    018
    019    import org.apache.commons.math3.util.IterationEvent;
    020    import org.apache.commons.math3.exception.MathUnsupportedOperationException;
    021
    022    /**
    023     * This is the base class for all events occuring during the iterations of a
    024     * {@link IterativeLinearSolver}.
    025     *
    026     * @version $Id: IterativeLinearSolverEvent.java 1416643 2012-12-03 19:37:14Z tn $
    027     * @since 3.0
    028     */
    029    public abstract class IterativeLinearSolverEvent
    030        extends IterationEvent {
    031        /** Serialization identifier. */
    032        private static final long serialVersionUID = 20120129L;
    033
    034        /**
    035         * Creates a new instance of this class.
    036         *
    037         * @param source the iterative algorithm on which the event initially
    038         * occurred
    039         * @param iterations the number of iterations performed at the time
    040         * {@code this} event is created
    041         */
    042        public IterativeLinearSolverEvent(final Object source, final int iterations) {
    043            super(source, iterations);
    044        }
    045
    046        /**
    047         * Returns the current right-hand side of the linear system to be solved.
    048         * This method should return an unmodifiable view, or a deep copy of the
    049         * actual right-hand side vector, in order not to compromise subsequent
    050         * iterations of the source {@link IterativeLinearSolver}.
    051         *
    052         * @return the right-hand side vector, b
    053         */
    054        public abstract RealVector getRightHandSideVector();
    055
    056        /**
    057         * Returns the norm of the residual. The returned value is not required to
    058         * be <em>exact</em>. Instead, the norm of the so-called <em>updated</em>
    059         * residual (if available) should be returned. For example, the
    060         * {@link ConjugateGradient conjugate gradient} method computes a sequence
    061         * of residuals, the norm of which is cheap to compute. However, due to
    062         * accumulation of round-off errors, this residual might differ from the
    063         * true residual after some iterations. See e.g. A. Greenbaum and
    064         * Z. Strakos, <em>Predicting the Behavior of Finite Precision Lanzos and
    065         * Conjugate Gradient Computations</em>, Technical Report 538, Department of
    066         * Computer Science, New York University, 1991 (available
    067         * <a href="http://www.archive.org/details/predictingbehavi00gree">here</a>).
    068         *
    069         * @return the norm of the residual, ||r||
    070         */
    071        public abstract double getNormOfResidual();
    072
    073        /**
    074         * <p>
    075         * Returns the residual. This is an optional operation, as all iterative
    076         * linear solvers do not provide cheap estimate of the updated residual
    077         * vector, in which case
    078         * </p>
    079         * <ul>
    080         * <li>this method should throw a
    081         * {@link MathUnsupportedOperationException},</li>
    082         * <li>{@link #providesResidual()} returns {@code false}.</li>
    083         * </ul>
    084         * <p>
    085         * The default implementation throws a
    086         * {@link MathUnsupportedOperationException}. If this method is overriden,
    087         * then {@link #providesResidual()} should be overriden as well.
    088         * </p>
    089         *
    090         * @return the updated residual, r
    091         */
    092        public RealVector getResidual() {
    093            throw new MathUnsupportedOperationException();
    094        }
    095
    096        /**
    097         * Returns the current estimate of the solution to the linear system to be
    098         * solved. This method should return an unmodifiable view, or a deep copy of
    099         * the actual current solution, in order not to compromise subsequent
    100         * iterations of the source {@link IterativeLinearSolver}.
    101         *
    102         * @return the solution, x
    103         */
    104        public abstract RealVector getSolution();
    105
    106        /**
    107         * Returns {@code true} if {@link #getResidual()} is supported. The default
    108         * implementation returns {@code false}.
    109         *
    110         * @return {@code false} if {@link #getResidual()} throws a
    111         * {@link MathUnsupportedOperationException}
    112         */
    113        public boolean providesResidual() {
    114            return false;
    115        }
    116    }