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