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 */
17package org.apache.commons.math.analysis.solvers;
18
19import org.apache.commons.math.ConvergenceException;
20import org.apache.commons.math.ConvergingAlgorithm;
21import org.apache.commons.math.FunctionEvaluationException;
22import 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: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 févr. 2011) $
31 */
32public 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 function
73     * @throws IllegalArgumentException if min > max or the endpoints do not
74     * satisfy the requirements specified by the solver
75     * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)}
76     * since 2.0
77     */
78    @Deprecated
79    double solve(double min, double max) throws ConvergenceException, FunctionEvaluationException;
80
81    /**
82     * Solve for a zero root in the given interval.
83     * <p>A solver may require that the interval brackets a single zero root.
84     * Solvers that do require bracketing should be able to handle the case
85     * where one of the endpoints is itself a root.</p>
86     *
87     * @param f the function to solve.
88     * @param min the lower bound for the interval.
89     * @param max the upper bound for the interval.
90     * @return a value where the function is zero
91     * @throws ConvergenceException if the maximum iteration count is exceeded
92     * or the solver detects convergence problems otherwise.
93     * @throws FunctionEvaluationException if an error occurs evaluating the function
94     * @throws IllegalArgumentException if min > max or the endpoints do not
95     * satisfy the requirements specified by the solver
96     * @since 2.0
97     * @deprecated in 2.2 (to be removed in 3.0).
98     */
99    @Deprecated
100    double solve(UnivariateRealFunction f, double min, double max)
101        throws ConvergenceException, FunctionEvaluationException;
102
103    /**
104     * Solve for a zero in the given interval, start at startValue.
105     * <p>A solver may require that the interval brackets a single zero root.
106     * Solvers that do require bracketing should be able to handle the case
107     * where one of the endpoints is itself a root.</p>
108     *
109     * @param min the lower bound for the interval.
110     * @param max the upper bound for the interval.
111     * @param startValue the start value to use
112     * @return a value where the function is zero
113     * @throws ConvergenceException if the maximum iteration count is exceeded
114     * or the solver detects convergence problems otherwise.
115     * @throws FunctionEvaluationException if an error occurs evaluating the function
116     * @throws IllegalArgumentException if min > max or the arguments do not
117     * satisfy the requirements specified by the solver
118     * @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double, double)}
119     * since 2.0
120     */
121    @Deprecated
122    double solve(double min, double max, double startValue)
123        throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException;
124
125    /**
126     * Solve for a zero in the given interval, start at startValue.
127     * <p>A solver may require that the interval brackets a single zero root.
128     * Solvers that do require bracketing should be able to handle the case
129     * where one of the endpoints is itself a root.</p>
130     *
131     * @param f the function to solve.
132     * @param min the lower bound for the interval.
133     * @param max the upper bound for the interval.
134     * @param startValue the start value to use
135     * @return a value where the function is zero
136     * @throws ConvergenceException if the maximum iteration count is exceeded
137     * or the solver detects convergence problems otherwise.
138     * @throws FunctionEvaluationException if an error occurs evaluating the function
139     * @throws IllegalArgumentException if min > max or the arguments do not
140     * satisfy the requirements specified by the solver
141     * @since 2.0
142     * @deprecated in 2.2 (to be removed in 3.0).
143     */
144    @Deprecated
145    double solve(UnivariateRealFunction f, double min, double max, double startValue)
146        throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException;
147
148    /**
149     * Get the result of the last run of the solver.
150     *
151     * @return the last result.
152     * @throws IllegalStateException if there is no result available, either
153     * because no result was yet computed or the last attempt failed.
154     */
155    double getResult();
156
157    /**
158     * Get the result of the last run of the solver.
159     *
160     * @return the value of the function at the last result.
161     * @throws IllegalStateException if there is no result available, either
162     * because no result was yet computed or the last attempt failed.
163     */
164    double getFunctionValue();
165}
166