001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.math3.analysis.solvers;
018
019import org.apache.commons.math3.analysis.UnivariateFunction;
020import org.apache.commons.math3.exception.MathIllegalArgumentException;
021import org.apache.commons.math3.exception.TooManyEvaluationsException;
022
023
024/**
025 * Interface for (univariate real) rootfinding algorithms.
026 * Implementations will search for only one zero in the given interval.
027 *
028 * This class is not intended for use outside of the Apache Commons Math
029 * library, regular user should rely on more specific interfaces like
030 * {@link UnivariateSolver}, {@link PolynomialSolver} or {@link
031 * DifferentiableUnivariateSolver}.
032 * @param <FUNC> Type of function to solve.
033 *
034 * @since 3.0
035 * @see UnivariateSolver
036 * @see PolynomialSolver
037 * @see DifferentiableUnivariateSolver
038 */
039public interface BaseUnivariateSolver<FUNC extends UnivariateFunction> {
040    /**
041     * Get the maximum number of function evaluations.
042     *
043     * @return the maximum number of function evaluations.
044     */
045    int getMaxEvaluations();
046
047    /**
048     * Get the number of evaluations of the objective function.
049     * The number of evaluations corresponds to the last call to the
050     * {@code optimize} method. It is 0 if the method has not been
051     * called yet.
052     *
053     * @return the number of evaluations of the objective function.
054     */
055    int getEvaluations();
056
057    /**
058     * Get the absolute accuracy of the solver.  Solutions returned by the
059     * solver should be accurate to this tolerance, i.e., if &epsilon; is the
060     * absolute accuracy of the solver and {@code v} is a value returned by
061     * one of the {@code solve} methods, then a root of the function should
062     * exist somewhere in the interval ({@code v} - &epsilon;, {@code v} + &epsilon;).
063     *
064     * @return the absolute accuracy.
065     */
066    double getAbsoluteAccuracy();
067
068    /**
069     * Get the relative accuracy of the solver.  The contract for relative
070     * accuracy is the same as {@link #getAbsoluteAccuracy()}, but using
071     * relative, rather than absolute error.  If &rho; is the relative accuracy
072     * configured for a solver and {@code v} is a value returned, then a root
073     * of the function should exist somewhere in the interval
074     * ({@code v} - &rho; {@code v}, {@code v} + &rho; {@code v}).
075     *
076     * @return the relative accuracy.
077     */
078    double getRelativeAccuracy();
079
080    /**
081     * Get the function value accuracy of the solver.  If {@code v} is
082     * a value returned by the solver for a function {@code f},
083     * then by contract, {@code |f(v)|} should be less than or equal to
084     * the function value accuracy configured for the solver.
085     *
086     * @return the function value accuracy.
087     */
088    double getFunctionValueAccuracy();
089
090    /**
091     * Solve for a zero root in the given interval.
092     * A solver may require that the interval brackets a single zero root.
093     * Solvers that do require bracketing should be able to handle the case
094     * where one of the endpoints is itself a root.
095     *
096     * @param maxEval Maximum number of evaluations.
097     * @param f Function to solve.
098     * @param min Lower bound for the interval.
099     * @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.math3.exception.MathIllegalArgumentException
137     * if the arguments do not satisfy the requirements specified by the solver.
138     * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if
139     * the allowed number of evaluations is exceeded.
140     */
141    double solve(int maxEval, FUNC f, double startValue);
142}