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.math.analysis.solvers;
18  
19  import org.apache.commons.math.ConvergenceException;
20  import org.apache.commons.math.ConvergingAlgorithm;
21  import org.apache.commons.math.FunctionEvaluationException;
22  import org.apache.commons.math.analysis.UnivariateRealFunction;
23  
24  
25  /**
26   * Interface for (univariate real) rootfinding algorithms.
27   * <p>
28   * Implementations will search for only one zero in the given interval.</p>
29   *  
30   * @version $Revision: 799857 $ $Date: 2009-08-01 09:07:12 -0400 (Sat, 01 Aug 2009) $
31   */
32  public interface UnivariateRealSolver extends ConvergingAlgorithm {
33  
34      /**
35       * Set the function value accuracy.
36       * <p>
37       * This is used to determine when an evaluated function value or some other
38       * value which is used as divisor is zero.</p>
39       * <p>
40       * This is a safety guard and it shouldn't be necessary to change this in
41       * general.</p>
42       * 
43       * @param accuracy the accuracy.
44       * @throws IllegalArgumentException if the accuracy can't be achieved by
45       * the solver or is otherwise deemed unreasonable. 
46       */
47      void setFunctionValueAccuracy(double accuracy);
48  
49      /**
50       * Get the actual function value accuracy.
51       * @return the accuracy
52       */
53      double getFunctionValueAccuracy();
54  
55      /**
56       * Reset the actual function accuracy to the default.
57       * The default value is provided by the solver implementation.
58       */
59      void resetFunctionValueAccuracy();
60  
61      /**
62       * Solve for a zero root in the given interval.
63       * <p>A solver may require that the interval brackets a single zero root.
64       * Solvers that do require bracketing should be able to handle the case
65       * where one of the endpoints is itself a root.</p>
66       * 
67       * @param min the lower bound for the interval.
68       * @param max the upper bound for the interval.
69       * @return a value where the function is zero
70       * @throws ConvergenceException if the maximum iteration count is exceeded
71       * or the solver detects convergence problems otherwise.
72       * @throws FunctionEvaluationException if an error occurs evaluating the
73       * function
74       * @throws IllegalArgumentException if min > max or the endpoints do not
75       * satisfy the requirements specified by the solver
76       * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)}
77       * since 2.0
78       */
79      @Deprecated
80      double solve(double min, double max) throws ConvergenceException, 
81          FunctionEvaluationException;
82  
83      /**
84       * Solve for a zero root in the given interval.
85       * <p>A solver may require that the interval brackets a single zero root.
86       * Solvers that do require bracketing should be able to handle the case
87       * where one of the endpoints is itself a root.</p>
88       * 
89       * @param f the function to solve.
90       * @param min the lower bound for the interval.
91       * @param max the upper bound for the interval.
92       * @return a value where the function is zero
93       * @throws ConvergenceException if the maximum iteration count is exceeded
94       * or the solver detects convergence problems otherwise.
95       * @throws FunctionEvaluationException if an error occurs evaluating the
96       * function
97       * @throws IllegalArgumentException if min > max or the endpoints do not
98       * satisfy the requirements specified by the solver
99       * @since 2.0
100      */
101     double solve(UnivariateRealFunction f, double min, double max)
102         throws ConvergenceException, 
103         FunctionEvaluationException;
104 
105     /**
106      * Solve for a zero in the given interval, start at startValue.
107      * <p>A solver may require that the interval brackets a single zero root.
108      * Solvers that do require bracketing should be able to handle the case
109      * where one of the endpoints is itself a root.</p>
110      * 
111      * @param min the lower bound for the interval.
112      * @param max the upper bound for the interval.
113      * @param startValue the start value to use
114      * @return a value where the function is zero
115      * @throws ConvergenceException if the maximum iteration count is exceeded
116      * or the solver detects convergence problems otherwise.
117      * @throws FunctionEvaluationException if an error occurs evaluating the
118      * function
119      * @throws IllegalArgumentException if min > max or the arguments do not
120      * satisfy the requirements specified by the solver
121      * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double, double)}
122      * since 2.0
123      */
124     @Deprecated
125     double solve(double min, double max, double startValue)
126         throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException;
127 
128     /**
129      * Solve for a zero in the given interval, start at startValue.
130      * <p>A solver may require that the interval brackets a single zero root.
131      * Solvers that do require bracketing should be able to handle the case
132      * where one of the endpoints is itself a root.</p>
133      * 
134      * @param f the function to solve.
135      * @param min the lower bound for the interval.
136      * @param max the upper bound for the interval.
137      * @param startValue the start value to use
138      * @return a value where the function is zero
139      * @throws ConvergenceException if the maximum iteration count is exceeded
140      * or the solver detects convergence problems otherwise.
141      * @throws FunctionEvaluationException if an error occurs evaluating the
142      * function
143      * @throws IllegalArgumentException if min > max or the arguments do not
144      * satisfy the requirements specified by the solver
145      * @since 2.0
146      */
147     double solve(UnivariateRealFunction f, double min, double max, double startValue)
148         throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException;
149 
150     /**
151      * Get the result of the last run of the solver.
152      * 
153      * @return the last result.
154      * @throws IllegalStateException if there is no result available, either
155      * because no result was yet computed or the last attempt failed.
156      */
157     double getResult();
158 
159     /**
160      * Get the result of the last run of the solver.
161      * 
162      * @return the value of the function at the last result.
163      * @throws IllegalStateException if there is no result available, either
164      * because no result was yet computed or the last attempt failed.
165      */
166     double getFunctionValue();
167 }