﻿ c05av Method
c05av attempts to locate an interval containing a simple zero of a continuous function using a binary search. It uses reverse communication for evaluating the function.

# Syntax

C#
```public static void c05av(
ref double x,
double fx,
ref double h,
double boundl,
double boundu,
ref double y,
double[] c,
ref int ind,
out int ifail
)```
Visual Basic
```Public Shared Sub c05av ( _
ByRef x As Double, _
fx As Double, _
ByRef h As Double, _
boundl As Double, _
boundu As Double, _
ByRef y As Double, _
c As Double(), _
ByRef ind As Integer, _
<OutAttribute> ByRef ifail As Integer _
)```
Visual C++
```public:
static void c05av(
double% x,
double fx,
double% h,
double boundl,
double boundu,
double% y,
array<double>^ c,
int% ind,
[OutAttribute] int% ifail
)```
F#
```static member c05av :
x : float byref *
fx : float *
h : float byref *
boundl : float *
boundu : float *
y : float byref *
c : float[] *
ind : int byref *
ifail : int byref -> unit
```

#### Parameters

x
Type: System..::..Double%
On initial entry: the best available approximation to the zero.
Constraint: x must lie in the closed interval $\left[{\mathbf{boundl}},{\mathbf{boundu}}\right]$ (see below).
On intermediate exit: contains the point at which $f$ must be evaluated before re-entry to the method.
On final exit: contains one end of an interval containing the zero, the other end being in y, unless an error has occurred. If ${\mathbf{ifail}}={4}$, x and y are the end points of the largest interval searched. If a zero is located exactly, its value is returned in x (and in y).
fx
Type: System..::..Double
On initial entry: if ${\mathbf{ind}}=1$, fx need not be set.
If ${\mathbf{ind}}=-1$, fx must contain $f\left({\mathbf{x}}\right)$ for the initial value of x.
On intermediate re-entry: must contain $f\left({\mathbf{x}}\right)$ for the current value of x.
h
Type: System..::..Double%
On initial entry: a basic step size which is used in the binary search for an interval containing a zero. The basic step sizes ${\mathbf{h}},0.1×{\mathbf{h}}$, $0.01×{\mathbf{h}}$ and $0.001×{\mathbf{h}}$ are used in turn when searching for the zero.
Constraint: either ${\mathbf{x}}+{\mathbf{h}}$ or ${\mathbf{x}}-{\mathbf{h}}$ must lie inside the closed interval $\left[{\mathbf{boundl}},{\mathbf{boundu}}\right]$.
h must be sufficiently large that ${\mathbf{x}}+{\mathbf{h}}\ne {\mathbf{x}}$ on the computer.
On final exit: is undefined.
boundl
Type: System..::..Double
On initial entry: boundl and boundu must contain respectively lower and upper bounds for the interval of search for the zero.
Constraint: ${\mathbf{boundl}}<{\mathbf{boundu}}$.
boundu
Type: System..::..Double
On initial entry: boundl and boundu must contain respectively lower and upper bounds for the interval of search for the zero.
Constraint: ${\mathbf{boundl}}<{\mathbf{boundu}}$.
y
Type: System..::..Double%
On initial entry: need not be set.
On final exit: contains the closest point found to the final value of x, such that $f\left({\mathbf{x}}\right)×f\left({\mathbf{y}}\right)\le 0.0$. If a value x is found such that $f\left({\mathbf{x}}\right)=0$, then ${\mathbf{y}}={\mathbf{x}}$. On final exit with ${\mathbf{ifail}}={4}$, x and y are the end points of the largest interval searched.
c
Type: array<System..::..Double>[]()[][]
An array of size [$11$]
On initial entry: need not be set.
On final exit: if ${\mathbf{ifail}}={0}$ or ${4}$, ${\mathbf{c}}\left[0\right]$ contains $f\left({\mathbf{y}}\right)$.
ind
Type: System..::..Int32%
On initial entry: must be set to $1$ or $-1$.
${\mathbf{ind}}=1$
fx need not be set.
${\mathbf{ind}}=-1$
fx must contain $f\left({\mathbf{x}}\right)$.
On intermediate exit: contains $2$ or $3$. The calling program must evaluate $f$ at x, storing the result in fx, and re-enter c05av with all other parameters unchanged.
On final exit: contains $0$.
Constraint: on entry ${\mathbf{ind}}=-1$, $1$, $2$ or $3$.
ifail
Type: System..::..Int32%
On initial entry: ifail must be set to $0$, $-1\text{​ or ​}1$. If you are unfamiliar with this parameter you should refer to Library Overview for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value $-1\text{​ or ​}1$ is recommended. If the output of error messages is undesirable, then the value $1$ is recommended. Otherwise, because for this method the values of the output parameters may be useful even if ${\mathbf{ifail}}\ne {0}$ on exit, the recommended value is $-1$. When the value $-\mathbf{1}\text{​ or ​}1$ is used it is essential to test the value of ifail on exit.
On final exit: ${\mathbf{ifail}}={0}$ unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

# Description

You must supply an initial point x and a step h. c05av attempts to locate a short interval $\left[{\mathbf{x}},{\mathbf{y}}\right]\subset \left[{\mathbf{boundl}},{\mathbf{boundu}}\right]$ containing a simple zero of $f\left(x\right)$.
(On exit we may have ${\mathbf{x}}>{\mathbf{y}}$; x is determined as the first point encountered in a binary search where the sign of $f\left(x\right)$ differs from the sign of $f\left(x\right)$ at the initial input point x.) The method attempts to locate a zero of $f\left(x\right)$ using h, $0.1×{\mathbf{h}}$, $0.01×{\mathbf{h}}$ and $0.001×{\mathbf{h}}$ in turn as its basic step before quitting with an error exit if unsuccessful.
c05av returns to the calling program for each evaluation of $f\left(x\right)$. On each return you should set ${\mathbf{fx}}=f\left({\mathbf{x}}\right)$ and call c05av again.

None.

# Error Indicators and Warnings

Errors or warnings detected by the method:
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{boundu}}\le {\mathbf{boundl}}$, or ${\mathbf{x}}\notin \left[{\mathbf{boundl}},{\mathbf{boundu}}\right]$, or both ${\mathbf{x}}+{\mathbf{h}}$ and ${\mathbf{x}}-{\mathbf{h}}\notin \left[{\mathbf{boundl}},{\mathbf{boundu}}\right]$.
${\mathbf{ifail}}=2$
On initial entry, h is too small to be used to perturb the initial value of x in the search.
${\mathbf{ifail}}=3$
The parameter ind is incorrectly set on initial or intermediate entry.
${\mathbf{ifail}}=4$
c05av has been unable to determine an interval containing a simple zero starting from the initial value of x and using the step h. If you have prior knowledge that a simple zero lies in the interval $\left[{\mathbf{boundl}},{\mathbf{boundu}}\right]$, you should vary x and h in an attempt to find it. (See also [Further Comments].)
${\mathbf{ifail}}=-9000$
An error occured, see message report.
${\mathbf{ifail}}=-8000$
Negative dimension for array $〈\mathit{\text{value}}〉$
${\mathbf{ifail}}=-6000$
Invalid Parameters $〈\mathit{\text{value}}〉$

# Accuracy

c05av is not intended to be used to obtain accurate approximations to the zero of $f\left(x\right)$ but rather to locate an interval containing a zero. This interval can then be used as input to an accurate rootfinder such as c05ay or c05az. The size of the interval determined depends somewhat unpredictably on the choice of x and h. The closer x is to the root and the smaller the initial value of h, then, in general, the smaller (more accurate) the interval determined; however, the accuracy of this statement depends to some extent on the behaviour of $f\left(x\right)$ near $x={\mathbf{x}}$ and on the size of h.

# Parallelism and Performance

None.

For most problems, the time taken on each call to c05av will be negligible compared with the time spent evaluating $f\left(x\right)$ between calls to c05av. However, the initial value of x and h will clearly affect the timing. The closer x is to the root, and the larger the initial value of h then the less time taken. (However taking a large h can affect the accuracy and reliability of the method, see below.)
You are expected to choose boundl and boundu as physically (or mathematically) realistic limits on the interval of search. For example, it may be known, from physical arguments, that no zero of $f\left(x\right)$ of interest will lie outside $\left[{\mathbf{boundl}},{\mathbf{boundu}}\right]$. Alternatively, $f\left(x\right)$ may be more expensive to evaluate for some values of x than for others and such expensive evaluations can sometimes be avoided by careful choice of boundl and boundu.
The choice of boundl and boundu affects the search only in that these values provide physical limitations on the search values and that the search is terminated if it seems, from the available information about $f\left(x\right)$, that the zero lies outside $\left[{\mathbf{boundl}},{\mathbf{boundu}}\right]$. In this case (${\mathbf{ifail}}={4}$ on exit), only one of $f\left({\mathbf{boundl}}\right)$ and $f\left({\mathbf{boundu}}\right)$ may have been evaluated and a zero close to the other end of the interval could be missed. The actual interval searched is returned in the parameters x and y and you can call c05av again to search the remainder of the original interval.
Though c05av is intended primarily for determining an interval containing a zero of $f\left(x\right)$, it may be used to shorten a known interval. This could be useful if, for example, a large interval containing the zero is known and it is also known that the root lies close to one end of the interval; by setting x to this end of the interval and h small, a short interval will usually be determined. However, it is worth noting that once any interval containing a zero has been determined, a call to c05az will usually be the most efficient way to calculate an interval of specified length containing the zero. To assist in this determination, the information in fx and in x, y and ${\mathbf{c}}\left[0\right]$ on successful exit from c05av is in the correct form for a call to method c05az with ${\mathbf{ind}}=-1$.
If the calculation terminates because $f\left({\mathbf{x}}\right)=0.0$, then on return y is set to x. (In fact, ${\mathbf{y}}={\mathbf{x}}$ on return only in this case.) In this case, there is no guarantee that the value in x corresponds to a simple zero and you should check whether it does.
One way to check this is to compute the derivative of $f$ at the point x, preferably analytically, or, if this is not possible, numerically, perhaps by using a central difference estimate. If ${f}^{\prime }\left({\mathbf{x}}\right)=0.0$, then x must correspond to a multiple zero of $f$ rather than a simple zero.

# Example

This example finds a sub-interval of $\left[0.0,4.0\right]$ containing a simple zero of ${x}^{2}-3x+2$. The zero nearest to $3.0$ is required and so we set ${\mathbf{x}}=3.0$ initially.

Example program (C#): c05ave.cs

Example program results: c05ave.r