View Javadoc
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    *      http://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  package org.apache.commons.math3.dfp;
18  
19  
20  import org.apache.commons.math3.analysis.RealFieldUnivariateFunction;
21  import org.apache.commons.math3.analysis.solvers.AllowedSolution;
22  import org.apache.commons.math3.analysis.solvers.FieldBracketingNthOrderBrentSolver;
23  import org.apache.commons.math3.exception.NoBracketingException;
24  import org.apache.commons.math3.exception.NullArgumentException;
25  import org.apache.commons.math3.exception.NumberIsTooSmallException;
26  import org.apache.commons.math3.util.MathUtils;
27  
28  /**
29   * This class implements a modification of the <a
30   * href="http://mathworld.wolfram.com/BrentsMethod.html"> Brent algorithm</a>.
31   * <p>
32   * The changes with respect to the original Brent algorithm are:
33   * <ul>
34   *   <li>the returned value is chosen in the current interval according
35   *   to user specified {@link AllowedSolution},</li>
36   *   <li>the maximal order for the invert polynomial root search is
37   *   user-specified instead of being invert quadratic only</li>
38   * </ul>
39   * </p>
40   * The given interval must bracket the root.
41   * @deprecated as of 3.6 replaced with {@link FieldBracketingNthOrderBrentSolver}
42   */
43  @Deprecated
44  public class BracketingNthOrderBrentSolverDFP extends FieldBracketingNthOrderBrentSolver<Dfp> {
45  
46      /**
47       * Construct a solver.
48       *
49       * @param relativeAccuracy Relative accuracy.
50       * @param absoluteAccuracy Absolute accuracy.
51       * @param functionValueAccuracy Function value accuracy.
52       * @param maximalOrder maximal order.
53       * @exception NumberIsTooSmallException if maximal order is lower than 2
54       */
55      public BracketingNthOrderBrentSolverDFP(final Dfp relativeAccuracy,
56                                              final Dfp absoluteAccuracy,
57                                              final Dfp functionValueAccuracy,
58                                              final int maximalOrder)
59          throws NumberIsTooSmallException {
60          super(relativeAccuracy, absoluteAccuracy, functionValueAccuracy, maximalOrder);
61      }
62  
63      /**
64       * Get the absolute accuracy.
65       * @return absolute accuracy
66       */
67      @Override
68      public Dfp getAbsoluteAccuracy() {
69          return super.getAbsoluteAccuracy();
70      }
71  
72      /**
73       * Get the relative accuracy.
74       * @return relative accuracy
75       */
76      @Override
77      public Dfp getRelativeAccuracy() {
78          return super.getRelativeAccuracy();
79      }
80  
81      /**
82       * Get the function accuracy.
83       * @return function accuracy
84       */
85      @Override
86      public Dfp getFunctionValueAccuracy() {
87          return super.getFunctionValueAccuracy();
88      }
89  
90      /**
91       * Solve for a zero in the given interval.
92       * A solver may require that the interval brackets a single zero root.
93       * Solvers that do require bracketing should be able to handle the case
94       * where one of the endpoints is itself a root.
95       *
96       * @param maxEval Maximum number of evaluations.
97       * @param f Function to solve.
98       * @param min Lower bound for the interval.
99       * @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 }