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.math4.legacy.analysis.solvers;
18
19 import org.apache.commons.math4.legacy.analysis.UnivariateFunction;
20 import org.apache.commons.math4.legacy.exception.MathIllegalArgumentException;
21 import org.apache.commons.math4.legacy.exception.TooManyEvaluationsException;
22
23
24 /**
25 * Interface for (univariate real) rootfinding algorithms.
26 * Implementations will search for only one zero in the given interval.
27 *
28 * This class is not intended for use outside of the Apache Commons Math
29 * library, regular user should rely on more specific interfaces like
30 * {@link UnivariateSolver}, {@link PolynomialSolver} or {@link
31 * UnivariateDifferentiableSolver}.
32 * @param <FUNC> Type of function to solve.
33 *
34 * @since 3.0
35 * @see UnivariateSolver
36 * @see PolynomialSolver
37 * @see UnivariateDifferentiableSolver
38 */
39 public interface BaseUnivariateSolver<FUNC extends UnivariateFunction> {
40 /**
41 * Get the maximum number of function evaluations.
42 *
43 * @return the maximum number of function evaluations.
44 */
45 int getMaxEvaluations();
46
47 /**
48 * Get the number of evaluations of the objective function.
49 * The number of evaluations corresponds to the last call to the
50 * {@code optimize} method. It is 0 if the method has not been
51 * called yet.
52 *
53 * @return the number of evaluations of the objective function.
54 */
55 int getEvaluations();
56
57 /**
58 * Get the absolute accuracy of the solver. Solutions returned by the
59 * solver should be accurate to this tolerance, i.e., if ε is the
60 * absolute accuracy of the solver and {@code v} is a value returned by
61 * one of the {@code solve} methods, then a root of the function should
62 * exist somewhere in the interval ({@code v} - ε, {@code v} + ε).
63 *
64 * @return the absolute accuracy.
65 */
66 double getAbsoluteAccuracy();
67
68 /**
69 * Get the relative accuracy of the solver. The contract for relative
70 * accuracy is the same as {@link #getAbsoluteAccuracy()}, but using
71 * relative, rather than absolute error. If ρ is the relative accuracy
72 * configured for a solver and {@code v} is a value returned, then a root
73 * of the function should exist somewhere in the interval
74 * ({@code v} - ρ {@code v}, {@code v} + ρ {@code v}).
75 *
76 * @return the relative accuracy.
77 */
78 double getRelativeAccuracy();
79
80 /**
81 * Get the function value accuracy of the solver. If {@code v} is
82 * a value returned by the solver for a function {@code f},
83 * then by contract, {@code |f(v)|} should be less than or equal to
84 * the function value accuracy configured for the solver.
85 *
86 * @return the function value accuracy.
87 */
88 double getFunctionValueAccuracy();
89
90 /**
91 * Solve for a zero root 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 * @return a value where the function is zero.
101 * @throws MathIllegalArgumentException
102 * if the arguments do not satisfy the requirements specified by the solver.
103 * @throws TooManyEvaluationsException if
104 * the allowed number of evaluations is exceeded.
105 */
106 double solve(int maxEval, FUNC f, double min, double max)
107 throws MathIllegalArgumentException, TooManyEvaluationsException;
108
109 /**
110 * Solve for a zero in the given interval, start at {@code startValue}.
111 * A solver may require that the interval brackets a single zero root.
112 * Solvers that do require bracketing should be able to handle the case
113 * where one of the endpoints is itself a root.
114 *
115 * @param maxEval Maximum number of evaluations.
116 * @param f Function to solve.
117 * @param min Lower bound for the interval.
118 * @param max Upper bound for the interval.
119 * @param startValue Start value to use.
120 * @return a value where the function is zero.
121 * @throws MathIllegalArgumentException
122 * if the arguments do not satisfy the requirements specified by the solver.
123 * @throws TooManyEvaluationsException if
124 * the allowed number of evaluations is exceeded.
125 */
126 double solve(int maxEval, FUNC f, double min, double max, double startValue)
127 throws MathIllegalArgumentException, TooManyEvaluationsException;
128
129 /**
130 * Solve for a zero in the vicinity of {@code startValue}.
131 *
132 * @param f Function to solve.
133 * @param startValue Start value to use.
134 * @return a value where the function is zero.
135 * @param maxEval Maximum number of evaluations.
136 * @throws org.apache.commons.math4.legacy.exception.MathIllegalArgumentException
137 * if the arguments do not satisfy the requirements specified by the solver.
138 * @throws org.apache.commons.math4.legacy.exception.TooManyEvaluationsException if
139 * the allowed number of evaluations is exceeded.
140 */
141 double solve(int maxEval, FUNC f, double startValue);
142 }