org.apache.commons.math.analysis.solvers.UnivariateRealSolver Maven / Gradle / Ivy
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.math.analysis.solvers;
import org.apache.commons.math.ConvergenceException;
import org.apache.commons.math.ConvergingAlgorithm;
import org.apache.commons.math.FunctionEvaluationException;
import org.apache.commons.math.analysis.UnivariateRealFunction;
/**
* Interface for (univariate real) rootfinding algorithms.
*
* Implementations will search for only one zero in the given interval.
*
* @version $Revision: 1070725 $ $Date: 2011-02-15 02:31:12 +0100 (mar. 15 févr. 2011) $
*/
public interface UnivariateRealSolver extends ConvergingAlgorithm {
/**
* Set the function value accuracy.
*
* This is used to determine when an evaluated function value or some other
* value which is used as divisor is zero.
*
* This is a safety guard and it shouldn't be necessary to change this in
* general.
*
* @param accuracy the accuracy.
* @throws IllegalArgumentException if the accuracy can't be achieved by
* the solver or is otherwise deemed unreasonable.
*/
void setFunctionValueAccuracy(double accuracy);
/**
* Get the actual function value accuracy.
* @return the accuracy
*/
double getFunctionValueAccuracy();
/**
* Reset the actual function accuracy to the default.
* The default value is provided by the solver implementation.
*/
void resetFunctionValueAccuracy();
/**
* Solve for a zero root in the given interval.
* A solver may require that the interval brackets a single zero root.
* Solvers that do require bracketing should be able to handle the case
* where one of the endpoints is itself a root.
*
* @param min the lower bound for the interval.
* @param max the upper bound for the interval.
* @return a value where the function is zero
* @throws ConvergenceException if the maximum iteration count is exceeded
* or the solver detects convergence problems otherwise.
* @throws FunctionEvaluationException if an error occurs evaluating the function
* @throws IllegalArgumentException if min > max or the endpoints do not
* satisfy the requirements specified by the solver
* @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double)}
* since 2.0
*/
@Deprecated
double solve(double min, double max) throws ConvergenceException, FunctionEvaluationException;
/**
* Solve for a zero root in the given interval.
* A solver may require that the interval brackets a single zero root.
* Solvers that do require bracketing should be able to handle the case
* where one of the endpoints is itself a root.
*
* @param f the function to solve.
* @param min the lower bound for the interval.
* @param max the upper bound for the interval.
* @return a value where the function is zero
* @throws ConvergenceException if the maximum iteration count is exceeded
* or the solver detects convergence problems otherwise.
* @throws FunctionEvaluationException if an error occurs evaluating the function
* @throws IllegalArgumentException if min > max or the endpoints do not
* satisfy the requirements specified by the solver
* @since 2.0
* @deprecated in 2.2 (to be removed in 3.0).
*/
@Deprecated
double solve(UnivariateRealFunction f, double min, double max)
throws ConvergenceException, FunctionEvaluationException;
/**
* Solve for a zero in the given interval, start at startValue.
* A solver may require that the interval brackets a single zero root.
* Solvers that do require bracketing should be able to handle the case
* where one of the endpoints is itself a root.
*
* @param min the lower bound for the interval.
* @param max the upper bound for the interval.
* @param startValue the start value to use
* @return a value where the function is zero
* @throws ConvergenceException if the maximum iteration count is exceeded
* or the solver detects convergence problems otherwise.
* @throws FunctionEvaluationException if an error occurs evaluating the function
* @throws IllegalArgumentException if min > max or the arguments do not
* satisfy the requirements specified by the solver
* @deprecated replaced by {@link #solve(UnivariateRealFunction, double, double, double)}
* since 2.0
*/
@Deprecated
double solve(double min, double max, double startValue)
throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException;
/**
* Solve for a zero in the given interval, start at startValue.
* A solver may require that the interval brackets a single zero root.
* Solvers that do require bracketing should be able to handle the case
* where one of the endpoints is itself a root.
*
* @param f the function to solve.
* @param min the lower bound for the interval.
* @param max the upper bound for the interval.
* @param startValue the start value to use
* @return a value where the function is zero
* @throws ConvergenceException if the maximum iteration count is exceeded
* or the solver detects convergence problems otherwise.
* @throws FunctionEvaluationException if an error occurs evaluating the function
* @throws IllegalArgumentException if min > max or the arguments do not
* satisfy the requirements specified by the solver
* @since 2.0
* @deprecated in 2.2 (to be removed in 3.0).
*/
@Deprecated
double solve(UnivariateRealFunction f, double min, double max, double startValue)
throws ConvergenceException, FunctionEvaluationException, IllegalArgumentException;
/**
* Get the result of the last run of the solver.
*
* @return the last result.
* @throws IllegalStateException if there is no result available, either
* because no result was yet computed or the last attempt failed.
*/
double getResult();
/**
* Get the result of the last run of the solver.
*
* @return the value of the function at the last result.
* @throws IllegalStateException if there is no result available, either
* because no result was yet computed or the last attempt failed.
*/
double getFunctionValue();
}