NAG CL Interface
e02cac (dim2_cheb_lines)
1
Purpose
e02cac forms an approximation to the weighted, least squares Chebyshev series surface fit to data arbitrarily distributed on lines parallel to one independent coordinate axis.
2
Specification
void |
e02cac (const Integer m[],
Integer n,
Integer k,
Integer l,
const double x[],
const double y[],
const double f[],
const double w[],
double a[],
const double xmin[],
const double xmax[],
const double nux[],
Integer inuxp1,
const double nuy[],
Integer inuyp1,
NagError *fail) |
|
The function may be called by the names: e02cac, nag_fit_dim2_cheb_lines or nag_2d_cheb_fit_lines.
3
Description
e02cac determines a bivariate polynomial approximation of degree
in
and
in
to the set of data points
, with weights
, for
and
. That is, the data points are on lines
, but the
values may be different on each line. The values of
and
are prescribed by you (for guidance on their choice, see
Section 9). The function is based on the method described in Sections 5 and 6 of
Clenshaw and Hayes (1965).
The polynomial is represented in double Chebyshev series form with arguments
and
. The arguments lie in the range
to
and are related to the original variables
and
by the transformations
Here
and
are set by the function to, respectively, the largest and smallest value of
, but
and
are functions of
prescribed by you (see
Section 9). For this function, only their values
and
at each
are required. For each
,
must not be less than the largest
on the line
, and, similarly,
must not be greater than the smallest
.
The double Chebyshev series can be written as
where
is the Chebyshev polynomial of the first kind of degree
with argument
, and
is similarly defined. However, the standard convention, followed in this function, is that coefficients in the above expression which have either
or
zero are written as
, instead of simply
, and the coefficient with both
and
equal to zero is written as
. The series with coefficients output by the function should be summed using this convention.
e02cbc is available to compute values of the fitted function from these coefficients.
The function first obtains Chebyshev series coefficients , for , of the weighted least squares polynomial curve fit of degree in to the data on each line , for , in turn, using an auxiliary function. The same function is then called times to fit , for , by a polynomial of degree in , for each . The resulting coefficients are the required .
You can force the fit to contain a given polynomial factor. This allows for the surface fit to be constrained to have specified values and derivatives along the boundaries
,
,
and
or indeed along any lines
constant or
constant (see Section 8 of
Clenshaw and Hayes (1965)).
4
References
Clenshaw C W and Hayes J G (1965) Curve and surface fitting J. Inst. Math. Appl. 1 164–183
Hayes J G (ed.) (1970) Numerical Approximation to Functions and Data Athlone Press, London
5
Arguments
-
1:
– const Integer
Input
-
On entry: must be set to , the number of data values on the line , for .
Constraint:
, for .
-
2:
– Integer
Input
-
On entry: the number of lines constant on which data points are given.
Constraint:
.
-
3:
– Integer
Input
-
On entry: , the required degree of in the fit.
Constraint:
for
,
, where
is the number of distinct
values with nonzero weight on the line
. See
Section 9.
-
4:
– Integer
Input
-
On entry: , the required degree of in the fit.
Constraints:
- ;
- .
-
5:
– const double
Input
-
Note: the dimension,
dim, of the array
x
must be at least
.
On entry: the
values of the data points. The sequence must be
- all points on , followed by
- all points on , followed by
- all points on .
Constraint:
for each , the values must be in nondecreasing order.
-
6:
– const double
Input
-
On entry: must contain the value of line , for , on which data is given.
Constraint:
the values must be in strictly increasing order.
-
7:
– const double
Input
-
Note: the dimension,
dim, of the array
f
must be at least
.
On entry: , the data values of the dependent variable in the same sequence as the values.
-
8:
– const double
Input
-
Note: the dimension,
dim, of the array
w
must be at least
.
On entry: the weights to be assigned to the data points, in the same sequence as the values. These weights should be calculated from estimates of the absolute accuracies of the , expressed as standard deviations, probable errors or some other measure which is of the same dimensions as . Specifically, each should be inversely proportional to the accuracy estimate of . Often weights all equal to unity will be satisfactory. If a particular weight is zero, the corresponding data point is omitted from the fit.
-
9:
– double
Output
-
Note: the dimension,
dim, of the array
a
must be at least
.
On exit: contains the Chebyshev coefficients of the fit.
is the coefficient
of
Section 3 defined according to the standard convention. These coefficients are used by
e02cbc to calculate values of the fitted function.
-
10:
– const double
Input
-
On entry:
must contain
, the lower end of the range of
on the line
, for
. It must not be greater than the lowest data value of
on the line. Each
is scaled to
in the fit. (See also
Section 9.)
-
11:
– const double
Input
-
On entry:
must contain
, the upper end of the range of
on the line
, for
. It must not be less than the highest data value of
on the line. Each
is scaled to
in the fit. (See also
Section 9.)
Constraint:
.
-
12:
– const double
Input
-
On entry:
must contain the coefficient of the Chebyshev polynomial of degree
in
, in the Chebyshev series representation of the polynomial factor in
which you require the fit to contain, for
. These coefficients are defined according to the standard convention of
Section 3.
Constraint:
must be nonzero, unless
, in which case
nux is ignored.
-
13:
– Integer
Input
-
On entry:
, where
is the degree of a polynomial factor in
which you require the fit to contain. (See
Section 3, last paragraph.)
If this option is not required,
inuxp1 should be set equal to
.
Constraint:
.
-
14:
– const double
Input
-
On entry:
must contain the coefficient of the Chebyshev polynomial of degree
in
, in the Chebyshev series representation of the polynomial factor which you require the fit to contain, for
. These coefficients are defined according to the standard convention of
Section 3.
Constraint:
must be nonzero, unless
, in which case
nuy is ignored.
-
15:
– Integer
Input
-
On entry:
, where
is the degree of a polynomial factor in
which you require the fit to contain. (See
Section 3, last paragraph.) If this option is not required,
inuyp1 should be set equal to
.
-
16:
– NagError *
Input/Output
-
The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
6
Error Indicators and Warnings
- NE_ALLOC_FAIL
-
Dynamic memory allocation failed.
See
Section 3.1.2 in the Introduction to the NAG Library CL Interface for further information.
- NE_BAD_PARAM
-
On entry, argument had an illegal value.
- NE_INT
-
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
On entry, .
Constraint: .
- NE_INT_2
-
On entry, and .
Constraint: .
On entry, and .
Constraint: .
- NE_INT_3
-
On entry, , and .
Constraint: .
On entry, , and .
Constraint: and
On entry, , and .
Constraint: .
- NE_INT_ARRAY
-
On entry, , , and .
Constraint: .
On entry, , , and .
Constraint: if , ; if , .
- NE_INTERNAL_ERROR
-
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact
NAG for assistance.
See
Section 7.5 in the Introduction to the NAG Library CL Interface for further information.
- NE_NO_LICENCE
-
Your licence key may have expired or may not have been installed correctly.
See
Section 8 in the Introduction to the NAG Library CL Interface for further information.
- NE_NON_ZERO_WEIGHTS
-
On entry, the number of distinct
x values with nonzero weight on
is less than
:
,
,
and
.
- NE_NOT_NON_DECREASING
-
On entry, the data
x values are not nondecreasing for
:
and
.
- NE_NOT_STRICTLY_INCREASING
-
On entry, , and .
Constraint: .
- NE_REAL_ARRAY
-
On entry,
and
do not span the data
x values on
:
,
,
and
.
7
Accuracy
No error analysis for this method has been published. Practical experience with the method, however, is generally extremely satisfactory.
8
Parallelism and Performance
e02cac is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the
Users' Note for your implementation for any additional implementation-specific information.
The time taken is approximately proportional to .
The reason for allowing
and
(which are used to normalize the range of
) to vary with
is that unsatisfactory fits can result if the highest (or lowest) data values of the normalized
on each line
are not approximately the same. (For an explanation of this phenomenon, see page 176 of
Clenshaw and Hayes (1965).) Commonly in practice, the lowest (for example) data values
, while not being approximately constant, do lie close to some smooth curve in the
plane. Using values from this curve as the values of
, different in general on each line, causes the lowest transformed data values
to be approximately constant. Sometimes, appropriate curves for
and
will be clear from the context of the problem (they need not be polynomials). If this is not the case, suitable curves can often be obtained by fitting to the lowest data values
and to the corresponding highest data values of
, low degree polynomials in
, using function
e02adc, and then shifting the two curves outwards by a small amount so that they just contain all the data between them. The complete curves are not in fact supplied to the present function, only their values at each
; and the values simply need to lie on smooth curves. More values on the complete curves will be required subsequently, when computing values of the fitted surface at arbitrary
values.
Naturally, a satisfactory approximation to the surface underlying the data cannot be expected if the character of the surface is not adequately represented by the data. Also, as always with polynomials, the approximating function may exhibit unwanted oscillations (particularly near the ends of the ranges) if the degrees and are taken greater than certain values, generally unknown but depending on the total number of coefficients should be significantly smaller than, say not more than half, the total number of data points. Similarly, should be significantly smaller than most (preferably all) the , and significantly smaller than . Closer spacing of the data near the ends of the and ranges is an advantage. In particular, if , for and , for , (thus for all ), then the values and (so that the polynomial passes exactly through all the data points) should not give unwanted oscillations. Other datasets should be similarly satisfactory if they are everywhere at least as closely spaced as the above cosine values with replaced by and by (more precisely, if for every the largest interval between consecutive values of , for , is not greater than , and similarly for the ). The polynomial obtained should always be examined graphically before acceptance. Note that, for this purpose it is not sufficient to plot the polynomial only at the data values of and : intermediate values should also be plotted, preferably via a graphics facility.
Provided the data are adequate, and the surface underlying the data is of a form that can be represented by a polynomial of the chosen degrees, the function should produce a good approximation to this surface. It is not, however, the true least squares surface fit nor even a polynomial in
and
, the original variables (see Section 6 of
Clenshaw and Hayes (1965), ), except in certain special cases. The most important of these is where the data values of
are the same on each line
, (i.e., the data points lie on a rectangular mesh in the
plane), the weights of the data points are all equal, and
and
are both constants (in this case they should be set to the largest and smallest data values of
, respectively).
If the dataset is such that it can be satisfactorily approximated by a polynomial of degrees
and
, say, then if higher values are used for
and
in the function, all the coefficients
for
or
will take apparently random values within a range bounded by the size of the data errors, or rather less. (This behaviour of the Chebyshev coefficients, most readily observed if they are set out in a rectangular array, closely parallels that in curve-fitting, examples of which are given in Section 8 of
Hayes (1970).) In practice, therefore, to establish suitable values of
and
, you should first be seeking (within the limitations discussed above) values for
and
which are large enough to exhibit the behaviour described. Values for
and
should then be chosen as the smallest which do not exclude any coefficients significantly larger than the random ones. A polynomial of degrees
and
should then be fitted to the data.
If the option to force the fit to contain a given polynomial factor in is used and if zeros of the chosen factor coincide with data values on any line, then the effective number of data points on that line is reduced by the number of such coincidences. A similar consideration applies when forcing the -direction. No account is taken of this by the function when testing that the degrees and have not been chosen too large.
10
Example
This example reads data in the following order, using the notation of the argument list for
e02cac above:
The data points are fitted using
e02cac, and then the fitting polynomial is evaluated at the data points using
e02cbc.
The output is:
- the data points and their fitted values;
- the Chebyshev coefficients of the fit.
10.1
Program Text
10.2
Program Data
10.3
Program Results