NAG Library Routine Document
c05avf
(contfn_interval_rcomm)
1
Purpose
c05avf 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.
2
Specification
Fortran Interface
| Integer, Intent (Inout) | :: |
ind,
ifail | | Real (Kind=nag_wp), Intent (In) | :: |
fx,
boundl,
boundu | | Real (Kind=nag_wp), Intent (Inout) | :: |
x,
h,
y,
c(11) |
|
C Header Interface
|
#include nagmk26.h
| void |
c05avf_ (
double *x,
const double *fx,
double *h,
const double *boundl,
const double *boundu,
double *y,
double c[],
Integer *ind,
Integer *ifail) |
|
3
Description
You must supply an initial point
x and a step
h.
c05avf attempts to locate a short interval
containing a simple zero of
.
(On exit we may have
;
x is determined as the first point encountered in a binary search where the sign of
differs from the sign of
at the initial input point
x.) The routine attempts to locate a zero of
using
h,
,
and
in turn as its basic step before quitting with an error exit if unsuccessful.
c05avf returns to the calling program for each evaluation of . On each return you should set and call c05avf again.
4
References
None.
5
Arguments
Note: this routine uses
reverse communication. Its use involves an initial entry, intermediate exits and re-entries, and a final exit, as indicated by the argument
ind. Between intermediate exits and re-entries,
all arguments other than fx must remain unchanged.
- 1: – Real (Kind=nag_wp)Input/Output
-
On initial entry: the best available approximation to the zero.
Constraint:
x must lie in the closed interval
(see below).
On intermediate exit:
contains the point at which must be evaluated before re-entry to the routine.
On final exit: contains one end of an interval containing the zero, the other end being in
y, unless an error has occurred. If
,
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).
- 2: – Real (Kind=nag_wp)Input
-
On initial entry: if
,
fx need not be set.
If
,
fx must contain
for the initial value of
x.
On intermediate re-entry: must contain
for the current value of
x.
- 3: – Real (Kind=nag_wp)Input/Output
-
On initial entry: a basic step size which is used in the binary search for an interval containing a zero. The basic step sizes , and are used in turn when searching for the zero.
Constraint:
either
or
must lie inside the closed interval
.
h must be sufficiently large that
on the computer.
On final exit: is undefined.
- 4: – Real (Kind=nag_wp)Input
- 5: – Real (Kind=nag_wp)Input
-
On initial entry:
boundl and
boundu must contain respectively lower and upper bounds for the interval of search for the zero.
Constraint:
.
- 6: – Real (Kind=nag_wp)Input/Output
-
On initial entry: need not be set.
On final exit: contains the closest point found to the final value of
x, such that
. If a value
x is found such that
,
. On final exit with
,
x and
y are the end points of the largest interval searched.
- 7: – Real (Kind=nag_wp) arrayCommunication Array
-
On initial entry: need not be set.
On final exit: if or , contains .
- 8: – IntegerInput/Output
-
On initial entry: must be set to
or
.
- fx need not be set.
- fx must contain .
On intermediate exit:
contains
or
. The calling program must evaluate
at
x, storing the result in
fx, and re-enter
c05avf with all other arguments unchanged.
On final exit: contains .
Constraint:
on entry , , or .
Note: any values you return to c05avf as part of the reverse communication procedure should not include floating-point NaN (Not a Number) or infinity values, since these are not handled by c05avf. If your code inadvertently does return any NaNs or infinities, c05avf is likely to produce unexpected results.
- 9: – IntegerInput/Output
-
On initial entry:
ifail must be set to
,
. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
is recommended. If the output of error messages is undesirable, then the value
is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if
on exit, the recommended value is
.
When the value is used it is essential to test the value of ifail on exit.
On final exit:
unless the routine detects an error or a warning has been flagged (see
Section 6).
6
Error Indicators and Warnings
If on entry
or
, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Errors or warnings detected by the routine:
-
| On entry, | , |
| or | , |
| or | both and . |
-
On initial entry,
h is too small to be used to perturb the initial value of
x in the search.
-
The argument
ind is incorrectly set on initial or intermediate entry.
-
c05avf 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
, you should vary
x and
h in an attempt to find it. (See also
Section 9.)
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
c05avf is not intended to be used to obtain accurate approximations to the zero of
but rather to locate an interval containing a zero. This interval can then be used as input to an accurate rootfinder such as
c05ayf or
c05azf. 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
near
and on the size of
h.
8
Parallelism and Performance
c05avf is not threaded in any implementation.
For most problems, the time taken on each call to
c05avf will be negligible compared with the time spent evaluating
between calls to
c05avf. 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 routine, 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
of interest will lie outside
. Alternatively,
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
, that the zero lies outside
. In this case (
on exit), only one of
and
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 arguments
x and
y and you can call
c05avf again to search the remainder of the original interval.
Though
c05avf is intended primarily for determining an interval containing a zero of
, 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
c05azf 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
on successful exit from
c05avf is in the correct form for a call to routine
c05azf with
.
If the calculation terminates because
, then on return
y is set to
x. (In fact,
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
at the point
x, preferably analytically, or, if this is not possible, numerically, perhaps by using a central difference estimate. If
, then
x must correspond to a multiple zero of
rather than a simple zero.
10
Example
This example finds a sub-interval of containing a simple zero of . The zero nearest to is required and so we set initially.
10.1
Program Text
Program Text (c05avfe.f90)
10.2
Program Data
None.
10.3
Program Results
Program Results (c05avfe.r)