    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.math.analysis.solvers;
    019
    020    import org.apache.commons.math.FunctionEvaluationException;
    021    import org.apache.commons.math.MathRuntimeException;
    022    import org.apache.commons.math.MaxIterationsExceededException;
    023    import org.apache.commons.math.analysis.DifferentiableUnivariateRealFunction;
    024    import org.apache.commons.math.analysis.UnivariateRealFunction;
    025    import org.apache.commons.math.exception.util.LocalizedFormats;
    026    import org.apache.commons.math.util.FastMath;
    027
    028    /**
    029     * Implements <a href="http://mathworld.wolfram.com/NewtonsMethod.html">
    030     * Newton's Method</a> for finding zeros of real univariate functions.
    031     * <p>
    032     * The function should be continuous but not necessarily smooth.</p>
    033     *
    034     * @version $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 f??vr. 2011) $
    035     */
    036    public class NewtonSolver extends UnivariateRealSolverImpl {
    037
    038        /**
    039         * Construct a solver for the given function.
    040         * @param f function to solve.
    041         * @deprecated as of 2.0 the function to solve is passed as an argument
    042         * to the {@link #solve(UnivariateRealFunction, double, double)} or
    043         * {@link UnivariateRealSolverImpl#solve(UnivariateRealFunction, double, double, double)}
    044         * method.
    045         */
    046        @Deprecated
    047        public NewtonSolver(DifferentiableUnivariateRealFunction f) {
    048            super(f, 100, 1E-6);
    049        }
    050
    051        /**
    052         * Construct a solver.
    053         * @deprecated in 2.2 (to be removed in 3.0).
    054         */
    055        @Deprecated
    056        public NewtonSolver() {
    057            super(100, 1E-6);
    058        }
    059
    060        /** {@inheritDoc} */
    061        @Deprecated
    062        public double solve(final double min, final double max)
    063            throws MaxIterationsExceededException, FunctionEvaluationException  {
    064            return solve(f, min, max);
    065        }
    066
    067        /** {@inheritDoc} */
    068        @Deprecated
    069        public double solve(final double min, final double max, final double startValue)
    070            throws MaxIterationsExceededException, FunctionEvaluationException  {
    071            return solve(f, min, max, startValue);
    072        }
    073
    074        /**
    075         * Find a zero near the midpoint of <code>min</code> and <code>max</code>.
    076         *
    077         * @param f the function to solve
    078         * @param min the lower bound for the interval
    079         * @param max the upper bound for the interval
    080         * @param maxEval Maximum number of evaluations.
    081         * @return the value where the function is zero
    082         * @throws MaxIterationsExceededException if the maximum iteration count is exceeded
    083         * @throws FunctionEvaluationException if an error occurs evaluating the function or derivative
    084         * @throws IllegalArgumentException if min is not less than max
    085         */
    086        @Override
    087        public double solve(int maxEval, final UnivariateRealFunction f,
    088                            final double min, final double max)
    089            throws MaxIterationsExceededException, FunctionEvaluationException  {
    090            setMaximalIterationCount(maxEval);
    091            return solve(f, min, max);
    092        }
    093
    094        /**
    095         * Find a zero near the midpoint of <code>min</code> and <code>max</code>.
    096         *
    097         * @param f the function to solve
    098         * @param min the lower bound for the interval
    099         * @param max the upper bound for the interval
    100         * @return the value where the function is zero
    101         * @throws MaxIterationsExceededException if the maximum iteration count is exceeded
    102         * @throws FunctionEvaluationException if an error occurs evaluating the function or derivative
    103         * @throws IllegalArgumentException if min is not less than max
    104         * @deprecated in 2.2 (to be removed in 3.0).
    105         */
    106        @Deprecated
    107        public double solve(final UnivariateRealFunction f,
    108                            final double min, final double max)
    109            throws MaxIterationsExceededException, FunctionEvaluationException  {
    110            return solve(f, min, max, UnivariateRealSolverUtils.midpoint(min, max));
    111        }
    112
    113        /**
    114         * Find a zero near the value <code>startValue</code>.
    115         *
    116         * @param f the function to solve
    117         * @param min the lower bound for the interval (ignored).
    118         * @param max the upper bound for the interval (ignored).
    119         * @param startValue the start value to use.
    120         * @param maxEval Maximum number of evaluations.
    121         * @return the value where the function is zero
    122         * @throws MaxIterationsExceededException if the maximum iteration count is exceeded
    123         * @throws FunctionEvaluationException if an error occurs evaluating the function or derivative
    124         * @throws IllegalArgumentException if startValue is not between min and max or
    125         * if function is not a {@link DifferentiableUnivariateRealFunction} instance
    126         */
    127        @Override
    128        public double solve(int maxEval, final UnivariateRealFunction f,
    129                            final double min, final double max, final double startValue)
    130            throws MaxIterationsExceededException, FunctionEvaluationException {
    131            setMaximalIterationCount(maxEval);
    132            return solve(f, min, max, startValue);
    133        }
    134
    135        /**
    136         * Find a zero near the value <code>startValue</code>.
    137         *
    138         * @param f the function to solve
    139         * @param min the lower bound for the interval (ignored).
    140         * @param max the upper bound for the interval (ignored).
    141         * @param startValue the start value to use.
    142         * @return the value where the function is zero
    143         * @throws MaxIterationsExceededException if the maximum iteration count is exceeded
    144         * @throws FunctionEvaluationException if an error occurs evaluating the function or derivative
    145         * @throws IllegalArgumentException if startValue is not between min and max or
    146         * if function is not a {@link DifferentiableUnivariateRealFunction} instance
    147         * @deprecated in 2.2 (to be removed in 3.0).
    148         */
    149        @Deprecated
    150        public double solve(final UnivariateRealFunction f,
    151                            final double min, final double max, final double startValue)
    152            throws MaxIterationsExceededException, FunctionEvaluationException {
    153
    154            try {
    155
    156                final UnivariateRealFunction derivative =
    157                    ((DifferentiableUnivariateRealFunction) f).derivative();
    158                clearResult();
    159                verifySequence(min, startValue, max);
    160
    161                double x0 = startValue;
    162                double x1;
    163
    164                int i = 0;
    165                while (i < maximalIterationCount) {
    166
    167                    x1 = x0 - (f.value(x0) / derivative.value(x0));
    168                    if (FastMath.abs(x1 - x0) <= absoluteAccuracy) {
    169                        setResult(x1, i);
    170                        return x1;
    171                    }
    172
    173                    x0 = x1;
    174                    ++i;
    175                }
    176
    177                throw new MaxIterationsExceededException(maximalIterationCount);
    178            } catch (ClassCastException cce) {
    179                throw MathRuntimeException.createIllegalArgumentException(LocalizedFormats.FUNCTION_NOT_DIFFERENTIABLE);
    180            }
    181        }
    182
    183    }