| Description |
[x,fVal,ExitFlag] = BISECTION(f,LB,UB,target,options) finds x +/- TolX (LB < x < UB) such that f(x) = target +/- TolFun.
Any or all of f(scalar), f(array), LB, UB, target, TolX, or TolFun may be scalar or n-dim arrays. All non-scalar arrays must be the same size. All outputs will be this size.
x = BISECTION(f,LB,UB) finds the root(s) of function f on the interval [LB, UB], i.e. finds x such that f(x) = 0 where LB <= x <= UB. f will never be evaluated outside of the interval specified by LB and UB. f should have only one root and f(UB) and f(LB) must bound it. elements of x are NaN for instances where a solution could not be found.
x = BISECTION(f,LB,UB,target) finds x such that f(x) = target.
x = BISECTION(f,LB,UB,target,TolX) will terminate the search when the search interval is smaller than TolX.
x = BISECTION(f,LB,UB,target,options) solves with the default parameters replaced by values in the structure OPTIONS, an argument created with the OPTIMSET function. Used options are TolX and TolFun. Note that OPTIMSET will not allow arrays for tolerances, so set the fields of the options structure manually for non-scalar TolX or TolFun.
Default values are target = 0, TolX = 1e-6, and TolFun = 0.
[x,fVal] = BISECTION(f,...) returns the value of f evaluated at x.
[x,fVal,ExitFlag] = BISECTION(...) returns an ExitFlag that describes the exit condition of BISECTION. Possible values of elements of ExitFlag and the corresponding exit conditions are
1 Search interval smaller than TolX.
2 Function value within TolFun of target.
3 Search interval smaller than TolX AND function value within TolFun of target.
-1 No solutions found.
Note that there is no iteration limit. This is because BISECTION (with a TolX that won't introduce numerical issues) is guaranteed to converge if f is a continuous function on the interval [UB, LB] and f(x) - target changes sign on the interval. The absolute error is halved at each step so the method converges linearly. BISECTION is a very robust root-finding method. However, Brent's method (such as implemented in FZERO) can converge superlinearly and is as robust. FZERO also has more features and input checking, so use BISECTION in cases where either the optimization toolbox is unavailable or if FZERO would have to be implemented in a loop to solve multiple cases, in which case BISECTION will be much faster because of vectorization.
The user should define LB, UB, target, TolX, and TolFun for each specific application using great care for the following reasons:
-There is no iteration limit, so given an unsolvable task, such as TolX = TolFun = 0, BISECTION remains in an unending loop.
-Spacing between very large floating point numbers is likely to be greater than TolX.
-There is no initial check to make sure that f(x) - target changes sign between LB and UB.
-Very large or very small numbers can introduce numerical issues.
Examples included in help:
Example 1: find cube root of array 'target' without using NTHROOT and compare speed to using FZERO.
Example 2: find roots for varying function coefficients. |
