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    *      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 &epsilon; 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} - &epsilon;, {@code v} + &epsilon;).
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 &rho; 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} - &rho; {@code v}, {@code v} + &rho; {@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 }