    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
    018    package org.apache.commons.math3.analysis.solvers;
    019
    020    /**
    021     * Implements the <em>Regula Falsi</em> or <em>False position</em> method for
    022     * root-finding (approximating a zero of a univariate real function). It is a
    023     * modified {@link SecantSolver <em>Secant</em>} method.
    024     *
    025     * <p>The <em>Regula Falsi</em> method is included for completeness, for
    026     * testing purposes, for educational purposes, for comparison to other
    027     * algorithms, etc. It is however <strong>not</strong> intended to be used
    028     * for actual problems, as one of the bounds often remains fixed, resulting
    029     * in very slow convergence. Instead, one of the well-known modified
    030     * <em>Regula Falsi</em> algorithms can be used ({@link IllinoisSolver
    031     * <em>Illinois</em>} or {@link PegasusSolver <em>Pegasus</em>}). These two
    032     * algorithms solve the fundamental issues of the original <em>Regula
    033     * Falsi</em> algorithm, and greatly out-performs it for most, if not all,
    034     * (practical) functions.
    035     *
    036     * <p>Unlike the <em>Secant</em> method, the <em>Regula Falsi</em> guarantees
    037     * convergence, by maintaining a bracketed solution. Note however, that due to
    038     * the finite/limited precision of Java's {@link Double double} type, which is
    039     * used in this implementation, the algorithm may get stuck in a situation
    040     * where it no longer makes any progress. Such cases are detected and result
    041     * in a {@code ConvergenceException} exception being thrown. In other words,
    042     * the algorithm theoretically guarantees convergence, but the implementation
    043     * does not.</p>
    044     *
    045     * <p>The <em>Regula Falsi</em> method assumes that the function is continuous,
    046     * but not necessarily smooth.</p>
    047     *
    048     * <p>Implementation based on the following article: M. Dowell and P. Jarratt,
    049     * <em>A modified regula falsi method for computing the root of an
    050     * equation</em>, BIT Numerical Mathematics, volume 11, number 2,
    051     * pages 168-174, Springer, 1971.</p>
    052     *
    053     * @since 3.0
    054     * @version $Id: RegulaFalsiSolver.java 1364387 2012-07-22 18:14:11Z tn $
    055     */
    056    public class RegulaFalsiSolver extends BaseSecantSolver {
    057
    058        /** Construct a solver with default accuracy (1e-6). */
    059        public RegulaFalsiSolver() {
    060            super(DEFAULT_ABSOLUTE_ACCURACY, Method.REGULA_FALSI);
    061        }
    062
    063        /**
    064         * Construct a solver.
    065         *
    066         * @param absoluteAccuracy Absolute accuracy.
    067         */
    068        public RegulaFalsiSolver(final double absoluteAccuracy) {
    069            super(absoluteAccuracy, Method.REGULA_FALSI);
    070        }
    071
    072        /**
    073         * Construct a solver.
    074         *
    075         * @param relativeAccuracy Relative accuracy.
    076         * @param absoluteAccuracy Absolute accuracy.
    077         */
    078        public RegulaFalsiSolver(final double relativeAccuracy,
    079                                 final double absoluteAccuracy) {
    080            super(relativeAccuracy, absoluteAccuracy, Method.REGULA_FALSI);
    081        }
    082
    083        /**
    084         * Construct a solver.
    085         *
    086         * @param relativeAccuracy Relative accuracy.
    087         * @param absoluteAccuracy Absolute accuracy.
    088         * @param functionValueAccuracy Maximum function value error.
    089         */
    090        public RegulaFalsiSolver(final double relativeAccuracy,
    091                                 final double absoluteAccuracy,
    092                                 final double functionValueAccuracy) {
    093            super(relativeAccuracy, absoluteAccuracy, functionValueAccuracy, Method.REGULA_FALSI);
    094        }
    095    }