We can categorically state that we have not released man-eating badgers into the area
Synopsis
#include <maxmod.h>
extern int maxmod_d( |
const double complex *coeffs, |
| size_t order, | |
| maxmod_opt_t options, | |
maxmod_results_t *results); |
extern double maxmod( |
const double complex *coeffs, |
size_t order); |
DESCRIPTION
The maxmod and maxmod_d
functions calculate the maximum modulus of a complex polynomial on the unit disc. The
maxmod function offers a simplified interface while maxmod_d gives access to a detailed interface.
For both functions the first two parameters are the coefficients and order of the polynomial. Thus
the coefficients varname is an array of order + 1 complex values.
For the maxmod_d function the third parameter is a structure
maxmod_opt_t discussed below. The final argument is a pointer
to a maxmod_results_t structure.
OPTIONS
The detailed interface uses a maxmod_opt_t structure to pass options to the function. The fields are:
- double
relerror -
The required relative accuracy in the result;
- size_t
max.evaluations -
The maximum number of polynomial evaluations to be used in calculating the maximum modulus. If this number is exceeded then the function terminates early and returns MAXMOD_INACCURATE;
Use a value of zero for unlimited evaluations.
- size_t
max.intervals -
An upper bound on the size of the interval table, behaving as
max.evaluations.
RESULTS
The detailed interface returns its results in the maxmod_results_t passed to the function by reference. The fields are:
- double
maxmod -
The maximum modulus;
- double
relerror -
The relative error in the maximum modulus;
- double
width -
The width of each interval at the end of the processing;
- size_t
evaluations -
The number of polynomial evaluation used.
RETURN VALUE
The simplified interface returns the estimate of the maximum modulus.
The detailed interface return an integer errorcode defined by the symbols:
- MAXMOD_OK
-
Success;
- MAXMOD_INACCURATE
-
The function terminated before the requested accuracy could be achieved. The results structure is modified to give the (inaccurate) estimate found;
- MAXMOD_ERROR
-
An error occurred, the results structure is not modified.
ACCURACY
If the polynomial evaluation is exact then the algorithm should be able to obtain arbitrary accuracy. However, for floating point arithmetic the relative error in evaluating a polynomial is of the order of the relative error in representing a floating point value: around machine epsilon.
If the user specifies a required relative accuracy which of the order (or smaller) than machine epsilon then, in the closing stages of the algorithm, the polynomial evaluates as constant. This can lead to an exponential explosion in the number of intervals used eventually exhausting memory.
Consequently we would recommend the the relative accuracy requested is larger than machine epsilon by a factor of 100.
If this advice is not followed then one can mitigate the effects of the explosion by setting
the max.evaluations or max.intervals fields of the maxmod_opt_t structure.