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 */
017package org.apache.commons.math3.dfp;
018
019
020import org.apache.commons.math3.analysis.RealFieldUnivariateFunction;
021import org.apache.commons.math3.analysis.solvers.AllowedSolution;
022import org.apache.commons.math3.analysis.solvers.FieldBracketingNthOrderBrentSolver;
023import org.apache.commons.math3.exception.NoBracketingException;
024import org.apache.commons.math3.exception.NullArgumentException;
025import org.apache.commons.math3.exception.NumberIsTooSmallException;
026import org.apache.commons.math3.util.MathUtils;
027
028/**
029 * This class implements a modification of the <a
030 * href="http://mathworld.wolfram.com/BrentsMethod.html"> Brent algorithm</a>.
031 * <p>
032 * The changes with respect to the original Brent algorithm are:
033 * <ul>
034 *   <li>the returned value is chosen in the current interval according
035 *   to user specified {@link AllowedSolution},</li>
036 *   <li>the maximal order for the invert polynomial root search is
037 *   user-specified instead of being invert quadratic only</li>
038 * </ul>
039 * </p>
040 * The given interval must bracket the root.
041 * @deprecated as of 3.6 replaced with {@link FieldBracketingNthOrderBrentSolver}
042 */
043@Deprecated
044public class BracketingNthOrderBrentSolverDFP extends FieldBracketingNthOrderBrentSolver<Dfp> {
045
046    /**
047     * Construct a solver.
048     *
049     * @param relativeAccuracy Relative accuracy.
050     * @param absoluteAccuracy Absolute accuracy.
051     * @param functionValueAccuracy Function value accuracy.
052     * @param maximalOrder maximal order.
053     * @exception NumberIsTooSmallException if maximal order is lower than 2
054     */
055    public BracketingNthOrderBrentSolverDFP(final Dfp relativeAccuracy,
056                                            final Dfp absoluteAccuracy,
057                                            final Dfp functionValueAccuracy,
058                                            final int maximalOrder)
059        throws NumberIsTooSmallException {
060        super(relativeAccuracy, absoluteAccuracy, functionValueAccuracy, maximalOrder);
061    }
062
063    /**
064     * Get the absolute accuracy.
065     * @return absolute accuracy
066     */
067    @Override
068    public Dfp getAbsoluteAccuracy() {
069        return super.getAbsoluteAccuracy();
070    }
071
072    /**
073     * Get the relative accuracy.
074     * @return relative accuracy
075     */
076    @Override
077    public Dfp getRelativeAccuracy() {
078        return super.getRelativeAccuracy();
079    }
080
081    /**
082     * Get the function accuracy.
083     * @return function accuracy
084     */
085    @Override
086    public Dfp getFunctionValueAccuracy() {
087        return super.getFunctionValueAccuracy();
088    }
089
090    /**
091     * Solve for a zero in the given interval.
092     * A solver may require that the interval brackets a single zero root.
093     * Solvers that do require bracketing should be able to handle the case
094     * where one of the endpoints is itself a root.
095     *
096     * @param maxEval Maximum number of evaluations.
097     * @param f Function to solve.
098     * @param min Lower bound for the interval.
099     * @param max Upper bound for the interval.
100     * @param allowedSolution The kind of solutions that the root-finding algorithm may
101     * accept as solutions.
102     * @return a value where the function is zero.
103     * @exception NullArgumentException if f is null.
104     * @exception NoBracketingException if root cannot be bracketed
105     */
106    public Dfp solve(final int maxEval, final UnivariateDfpFunction f,
107                     final Dfp min, final Dfp max, final AllowedSolution allowedSolution)
108        throws NullArgumentException, NoBracketingException {
109        return solve(maxEval, f, min, max, min.add(max).divide(2), allowedSolution);
110    }
111
112    /**
113     * Solve for a zero in the given interval, start at {@code startValue}.
114     * A solver may require that the interval brackets a single zero root.
115     * Solvers that do require bracketing should be able to handle the case
116     * where one of the endpoints is itself a root.
117     *
118     * @param maxEval Maximum number of evaluations.
119     * @param f Function to solve.
120     * @param min Lower bound for the interval.
121     * @param max Upper bound for the interval.
122     * @param startValue Start value to use.
123     * @param allowedSolution The kind of solutions that the root-finding algorithm may
124     * accept as solutions.
125     * @return a value where the function is zero.
126     * @exception NullArgumentException if f is null.
127     * @exception NoBracketingException if root cannot be bracketed
128     */
129    public Dfp solve(final int maxEval, final UnivariateDfpFunction f,
130                     final Dfp min, final Dfp max, final Dfp startValue,
131                     final AllowedSolution allowedSolution)
132        throws NullArgumentException, NoBracketingException {
133
134        // checks
135        MathUtils.checkNotNull(f);
136
137        // wrap the function
138        RealFieldUnivariateFunction<Dfp> fieldF = new RealFieldUnivariateFunction<Dfp>() {
139
140            /** {@inheritDoc} */
141            public Dfp value(final Dfp x) {
142                return f.value(x);
143            }
144        };
145
146        // delegate to general field solver
147        return solve(maxEval, fieldF, min, max, startValue, allowedSolution);
148
149    }
150
151}