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 * @version $Id: BaseUnivariateSolver.java 1455194 2013-03-11 15:45:54Z luc $
036 * @see UnivariateSolver
037 * @see PolynomialSolver
038 * @see DifferentiableUnivariateSolver
039 */
040public interface BaseUnivariateSolver<FUNC extends UnivariateFunction> {
041    /**
042     * Get the maximum number of function evaluations.
043     *
044     * @return the maximum number of function evaluations.
045     */
046    int getMaxEvaluations();
047
048    /**
049     * Get the number of evaluations of the objective function.
050     * The number of evaluations corresponds to the last call to the
051     * {@code optimize} method. It is 0 if the method has not been
052     * called yet.
053     *
054     * @return the number of evaluations of the objective function.
055     */
056    int getEvaluations();
057
058    /**
059     * Get the absolute accuracy of the solver.  Solutions returned by the
060     * solver should be accurate to this tolerance, i.e., if &epsilon; is the
061     * absolute accuracy of the solver and {@code v} is a value returned by
062     * one of the {@code solve} methods, then a root of the function should
063     * exist somewhere in the interval ({@code v} - &epsilon;, {@code v} + &epsilon;).
064     *
065     * @return the absolute accuracy.
066     */
067    double getAbsoluteAccuracy();
068
069    /**
070     * Get the relative accuracy of the solver.  The contract for relative
071     * accuracy is the same as {@link #getAbsoluteAccuracy()}, but using
072     * relative, rather than absolute error.  If &rho; is the relative accuracy
073     * configured for a solver and {@code v} is a value returned, then a root
074     * of the function should exist somewhere in the interval
075     * ({@code v} - &rho; {@code v}, {@code v} + &rho; {@code v}).
076     *
077     * @return the relative accuracy.
078     */
079    double getRelativeAccuracy();
080
081    /**
082     * Get the function value accuracy of the solver.  If {@code v} is
083     * a value returned by the solver for a function {@code f},
084     * then by contract, {@code |f(v)|} should be less than or equal to
085     * the function value accuracy configured for the solver.
086     *
087     * @return the function value accuracy.
088     */
089    double getFunctionValueAccuracy();
090
091    /**
092     * Solve for a zero root in the given interval.
093     * A solver may require that the interval brackets a single zero root.
094     * Solvers that do require bracketing should be able to handle the case
095     * where one of the endpoints is itself a root.
096     *
097     * @param maxEval Maximum number of evaluations.
098     * @param f Function to solve.
099     * @param min Lower bound for the interval.
100     * @param max Upper bound for the interval.
101     * @return a value where the function is zero.
102     * @throws MathIllegalArgumentException
103     * if the arguments do not satisfy the requirements specified by the solver.
104     * @throws TooManyEvaluationsException if
105     * the allowed number of evaluations is exceeded.
106     */
107    double solve(int maxEval, FUNC f, double min, double max)
108        throws MathIllegalArgumentException, TooManyEvaluationsException;
109
110    /**
111     * Solve for a zero in the given interval, start at {@code startValue}.
112     * A solver may require that the interval brackets a single zero root.
113     * Solvers that do require bracketing should be able to handle the case
114     * where one of the endpoints is itself a root.
115     *
116     * @param maxEval Maximum number of evaluations.
117     * @param f Function to solve.
118     * @param min Lower bound for the interval.
119     * @param max Upper bound for the interval.
120     * @param startValue Start value to use.
121     * @return a value where the function is zero.
122     * @throws MathIllegalArgumentException
123     * if the arguments do not satisfy the requirements specified by the solver.
124     * @throws TooManyEvaluationsException if
125     * the allowed number of evaluations is exceeded.
126     */
127    double solve(int maxEval, FUNC f, double min, double max, double startValue)
128        throws MathIllegalArgumentException, TooManyEvaluationsException;
129
130    /**
131     * Solve for a zero in the vicinity of {@code startValue}.
132     *
133     * @param f Function to solve.
134     * @param startValue Start value to use.
135     * @return a value where the function is zero.
136     * @param maxEval Maximum number of evaluations.
137     * @throws org.apache.commons.math3.exception.MathIllegalArgumentException
138     * if the arguments do not satisfy the requirements specified by the solver.
139     * @throws org.apache.commons.math3.exception.TooManyEvaluationsException if
140     * the allowed number of evaluations is exceeded.
141     */
142    double solve(int maxEval, FUNC f, double startValue);
143}