
          E01 -- Interpolation                          Introduction -- E01
                                    Chapter E01
                                   Interpolation

          1. Scope of the Chapter

          This chapter is concerned with the interpolation of a function of
          one or two variables. When provided with the value of the
          function (and possibly one or more of its lowest-order
          derivatives) at each of a number of values of the variable(s),
          the routines provide either an interpolating function or an
          interpolated value. For some of the interpolating functions,
          there are supporting routines to evaluate, differentiate or
          integrate them.

          2. Background to the Problems

          In motivation and in some of its numerical processes, this
          chapter has much in common with Chapter E02 (Curve and Surface
          Fitting). For this reason, we shall adopt the same terminology
          and refer to dependent variable and independent variable(s)
          instead of function and variable(s). Where there is only one
          independent variable, we shall denote it by x and the dependent
          variable by y. Thus, in the basic problem considered in this
          chapter, we are given a set of distinct values x ,x ,...,x  of x
                                                          1  2      m
          and a corresponding set of values y ,y ,...,y  of y, and we shall
                                             1  2      m
          describe the problem as being one of interpolating the data
          points (x ,y ), rather than interpolating a function. In modern
                   r  r
          usage, however, interpolation can have either of two rather
          different meanings, both relevant to routines in this chapter.
          They are

          (a) the determination of a function of x which takes the value y
                                                                          r
              at x=x , for r=1,2,...,m (an interpolating function or
                    r
              interpolant),

          (b) the determination of the value (interpolated value or
              interpolate) of an interpolating function at any given value,
                  ^
              say x, of x within the range of the x  (so as to estimate the
                                                   r
                       ^
              value at x of the function underlying the data).

          The latter is the older meaning, associated particularly with the
          use of mathematical tables. The term 'function underlying the
          data', like the other terminology described above, is used so as
          to cover situations additional to those in which the data points
          have been computed from a known function, as with a mathematical
          table. In some contexts, the function may be unknown, perhaps
          representing the dependency of one physical variable on another,
          say temperature upon time.

          Whether the underlying function is known or unknown, the object
          of interpolation will usually be to approximate it to acceptable
          accuracy by a function which is easy to evaluate anywhere in some
          range of interest. Piecewise polynomials such as cubic splines
          (see Section 2.2 of the E02 Chapter Introduction for definitions
          of terms in this case), being easy to evaluate and also capable
          of approximating a wide variety of functions, are the types of
          function mostly used in this chapter as interpolating functions.

          Piecewise polynomials also, to a large extent, avoid the well-
          known problem of large unwanted fluctuations which can arise when
          interpolating a data set with a simple polynomial. Fluctuations
          can still arise but much less frequently and much less severely
          than with simple polynomials. Unwanted fluctuations are avoided
          altogether by a routine using piecewise cubic polynomials having
          only first derivative continuity. It is designed especially for
          monotonic data, but for other data still provides an interpolant
          which increases, or decreases, over the same intervals as the
          data.

          The concept of interpolation can be generalised in a number of
          ways. For example, we may be required to estimate the value of
                                             ^
          the underlying function at a value x outside the range of the
          data. This is the process of extrapolation. In general, it is a
          good deal less accurate than interpolation and is to be avoided
          whenever possible.

          Interpolation can also be extended to the case of two independent
          variables. We shall denote these by x and y, and the dependent
          variable by f. Methods used depend markedly on whether or not the
          data values of f are given at the intersections of a rectangular
          mesh in the (x,y)-plane. If they are, bicubic splines (see
          Section 2.3.2 of the E02 Chapter Introduction) are very suitable
          and usually very effective for the problem. For other cases,
          perhaps where the f values are quite arbitrarily scattered in the
          (x,y)-plane, polynomials and splines are not at all appropriate
          and special forms of interpolating function have to be employed.
          Many such forms have been devised and two of the most successful
          are in routines in this chapter. They both have continuity in
          first, but not higher, derivatives.

          2.1. References

          [1]   Froberg C E (1970) Introduction to Numerical Analysis.
                Addison-Wesley (2nd Edition).

          [2]   Dahlquist G and Bjork A (1974) Numerical Methods. Prentice-
                Hall.

          3. Recommendations on Choice and Use of Routines

          3.1. General

          Before undertaking interpolation, in other than the simplest
          cases, the user should seriously consider the alternative of
          using a routine from Chapter E02 to approximate the data by a
          polynomial or spline containing significantly fewer coefficients
          than the corresponding interpolating function. This approach is
          much less liable to produce unwanted fluctuations and so can
          often provide a better approximation to the function underlying
          the data.

          When interpolation is employed to approximate either an
          underlying function or its values, the user will need to be
          satisfied that the accuracy of approximation achieved is
          adequate. There may be a means for doing this which is particular
          to the application, or the routine used may itself provide a
          means. In other cases, one possibility is to repeat the
          interpolation using one or more extra data points, if they are
          available, or otherwise one or more fewer, and to compare the
          results. Other possibilities, if it is an interpolating function
          which is determined, are to examine the function graphically, if
          that gives sufficient accuracy, or to observe the behaviour of
          the differences in a finite-difference table, formed from
          evaluations of the interpolating function at equally-spaced
          values of x over the range of interest. The spacing should be
          small enough to cause the typical size of the differences to
          decrease as the order of difference increases.

          3.2. One Independent Variable

          E01BAF computes an interpolating cubic spline, using a particular
          choice for the set of knots which has proved generally
          satisfactory in practice. If the user wishes to choose a
          different set, a cubic spline routine from Chapter E02, namely
          E02BAF, may be used in its interpolating mode, setting NCAP7 = M+
          4 and all elements of the parameter W to unity. These routines
          provide the interpolating function in B-spline form (see Section
          2.2.2 in the E02 Chapter Introduction). Routines for evaluating,
          differentiating and integrating this form are discussed in
          Section 3.7 of the E02 Chapter Introduction.

          The cubic spline does not always avoid unwanted fluctuations,
          especially when the data show a steep slope close to a region of
          small slope, or when the data inadequately represent the
          underlying curve. In such cases, E01BEF can be very useful. It
          derives a piecewise cubic polynomial (with first derivative
          continuity) which, between any adjacent pair of data points,
          either increases all the way, or decreases all the way (or stays
          constant). It is especially suited to data which are monotonic
          over their whole range.

          In this routine, the interpolating function is represented simply
          by its value and first derivative at the data points. Supporting
          routines compute its value and first derivative elsewhere, as
          well as its definite integral over an arbitary interval.

          3.3. Two Independent Variables

          3.3.1.  Data on a rectangular mesh

          Given the value f   of the dependent variable f at the point
                           qr
          (x ,y ) in the plane of the independent variables x and y, for
            q  r
          each q=1,2,...,m and r=1,2,...,n (so that the points (x ,y ) lie
                                                                 q  r
          at the m*n intersections of a rectangular mesh), E01DAF computes
          an interpolating bicubic spline, using a particular choice for
          each of the spline's knot-set. This choice, the same as in E01BAF
          , has proved generally satisfactory in practice. If, instead, the
          user wishes to specify his own knots, a routine from Chapter E02,
          namely E02DAF, may be adapted (it is more cumbersome for the
          purpose, however, and much slower for larger problems). Using m
          and n in the above sense, the parameter M must be set to m*n, PX
          and PY must be set to m+4 and n+4 respectively and all elements
          of W should be set to unity. The recommended value for EPS is
          zero.

          3.3.2.  Arbitrary data

          As remarked at the end of Section 2, special types of
          interpolating are required for this problem, which can often be
          difficult to solve satisfactorily. Two of the most successful are
          employed in E01SAF and E01SEF, the two routines which (with their
          respective evaluation routines E01SBF and E01SFF) are provided
          for the problem. Definitions can be found in the routine
          documents. Both interpolants have first derivative continuity and
          are 'local', in that their value at any point depends only on
          data in the immediate neighbourhood of the point. This latter
          feature is necessary for large sets of data to avoid prohibitive
          computing time.

          The relative merits of the two methods vary with the data and it
          is not possible to predict which will be the better in any
          particular case.

          3.4. Index

          Derivative, of interpolant from E01BEF                     E01BGF

          Evaluation, of interpolant
               from E01BEF                                           E01BFF
               from E01SAF                                           E01SBF
               from E01SEF                                           E01SFF
          Extrapolation, one variable                                E01BEF
          Integration (definite) of interpolant from E01BEF          E01BHF
          Interpolated values, one variable, from interpolant from   E01BFF
          E01BEF
                                                                     E01BGF
          Interpolated values, two variables,
               from interpolant from E01SAF                          E01SBF
               from interpolant from E01SEF                          E01SFF
          Interpolating function, one variable,
               cubic spline                                          E01BAF
               other piecewise polynomial                            E01BEF
          Interpolating function, two variables
               bicubic spline                                        E01DAF
               other piecewise polynomial                            E01SAF
               modified Shepard method                               E01SEF


          E01 -- Interpolation                              Contents -- E01
          Chapter E01

          Interpolation

          E01BAF  Interpolating functions, cubic spline interpolant, one
                  variable

          E01BEF  Interpolating functions, monotonicity-preserving,
                  piecewise cubic Hermite, one variable

          E01BFF  Interpolated values, interpolant computed by E01BEF,
                  function only, one variable,

          E01BGF  Interpolated values, interpolant computed by E01BEF,
                  function and 1st derivative, one variable

          E01BHF  Interpolated values, interpolant computed by E01BEF,
                  definite integral, one variable

          E01DAF  Interpolating functions, fitting bicubic spline, data on
                  rectangular grid

          E01SAF  Interpolating functions, method of Renka and Cline, two
                  variables

          E01SBF  Interpolated values, evaluate interpolant computed by
                  E01SAF, two variables

          E01SEF  Interpolating functions, modified Shepard's method, two
                  variables

          E01SFF  Interpolated values, evaluate interpolant computed by
                  E01SEF, two variables

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          E01 -- Interpolation                                       E01BAF
                  E01BAF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          E01BAF determines a cubic spline interpolant to a given set of
          data.

          2. Specification

                 SUBROUTINE E01BAF (M, X, Y, LAMDA, C, LCK, WRK, LWRK,
                1                   IFAIL)
                 INTEGER          M, LCK, LWRK, IFAIL
                 DOUBLE PRECISION X(M), Y(M), LAMDA(LCK), C(LCK), WRK(LWRK)

          3. Description

          This routine determines a cubic spline s(x), defined in the range
          x <=x<=x , which interpolates (passes exactly through) the set of
           1      m
          data points (x ,y ), for i=1,2,...,m, where m>=4 and x <x <...<x
                        i  i                                    1  2      m
          end conditions are not imposed. The spline interpolant chosen has
          m-4 interior knots (lambda) ,(lambda) ,...,(lambda) , which are
                                     5         6             m
          set to the values of x ,x ,...,x    respectively. This spline is
                                3  4      m-2
          represented in its B-spline form (see Cox [1]):

                                        m
                                        --
                                  s(x)= >  c N (x),
                                        --  i i
                                        i=1

          where N (x) denotes the normalised B-Spline of degree 3, defined
                 i
          upon the knots (lambda) ,(lambda)   ,...,(lambda)   , and c
                                 i         i+1             i+4       i
          denotes its coefficient, whose value is to be determined by the
          routine.

          The use of B-splines requires eight additional knots (lambda) ,
                                                                       1
          (lambda) , (lambda) , (lambda) , (lambda)   , (lambda)   ,
                  2          3          4          m+1          m+2
          (lambda)    and (lambda)    to be specified; the routine sets the
                  m+3             m+4
          first four of these to x  and the last four to x .
                                  1                       m

          The algorithm for determining the coefficients is as described in
          [1] except that QR factorization is used instead of LU
          decomposition. The implementation of the algorithm involves
          setting up appropriate information for the related routine E02BAF
          followed by a call of that routine. (For further details of
          E02BAF, see the routine document.)

          Values of the spline interpolant, or of its derivatives or
          definite integral, can subsequently be computed as detailed in
          Section 8.

          4. References

          [1]   Cox M G (1975) An Algorithm for Spline Interpolation. J.
                Inst. Math. Appl. 15 95--108.

          [2]   Cox M G (1977) A Survey of Numerical Methods for Data and
                Function Approximation. The State of the Art in Numerical
                Analysis. (ed D A H Jacobs) Academic Press. 627--668.

          5. Parameters

           1:  M -- INTEGER                                           Input
               On entry: m, the number of data points. Constraint: M >= 4.

           2:  X(M) -- DOUBLE PRECISION array                         Input
               On entry: X(i) must be set to x , the ith data value of the
                                              i
               independent variable x, for i=1,2,...,m. Constraint: X(i) <
               X(i+1), for i=1,2,...,M-1.

           3:  Y(M) -- DOUBLE PRECISION array                         Input
               On entry: Y(i) must be set to y , the ith data value of the
                                              i
               dependent variable y, for i=1,2,...,m.

           4:  LAMDA(LCK) -- DOUBLE PRECISION array                  Output
               On exit: the value of (lambda) , the ith knot, for
                                             i
               i=1,2,...,m+4.

           5:  C(LCK) -- DOUBLE PRECISION array                      Output
               On exit: the coefficient c  of the B-spline N (x), for
                                         i                  i
               i=1,2,...,m. The remaining elements of the array are not
               used.

           6:  LCK -- INTEGER                                         Input
               On entry:
               the dimension of the arrays LAMDA and C as declared in the
               (sub)program from which E01BAF is called.
               Constraint: LCK >= M + 4.

           7:  WRK(LWRK) -- DOUBLE PRECISION array                Workspace

           8:  LWRK -- INTEGER                                        Input
               On entry:
               the dimension of the array WRK as declared in the
               (sub)program from which E01BAF is called.
               Constraint: LWRK>=6*M+16.

           9:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               On entry M < 4,

               or       LCK<M+4,

               or       LWRK<6*M+16.

          IFAIL= 2
               The X-values fail to satisfy the condition

               X(1) < X(2) < X(3) <... < X(M).

          7. Accuracy

          The rounding errors incurred are such that the computed spline is
          an exact interpolant for a slightly perturbed set of ordinates
          y +(delta)y . The ratio of the root-mean-square value of the
           i         i
          (delta)y  to that of the y  is no greater than a small multiple
                  i                 i
          of the relative machine precision.

          8. Further Comments

          The time taken by the routine is approximately proportional to m.

          All the x  are used as knot positions except x  and x   . This
                   i                                    2      m-1
          choice of knots (see Cox [2]) means that s(x) is composed of m-3
          cubic arcs as follows. If m=4, there is just a single arc space
          spanning the whole interval x  to x . If m>=5, the first and last
                                       1     4
          arcs span the intervals x  to x  and x    to x  respectively.
                                   1     3      m-2     m
          Additionally if m>=6, the ith arc, for i=2,3,...,m-4 spans the
          interval x    to x   .
                    i+1     i+2

          After the call

                 CALL E01BAF (M, X, Y, LAMDA, C, LCK, WRK, LWRK, IFAIL)

          the following operations may be carried out on the interpolant
          s(x).

          The value of s(x) at x = XVAL can be provided in the real
          variable SVAL by the call

                 CALL E02BBF (M+4, LAMDA, C, XVAL, SVAL, IFAIL)

          The values of s(x) and its first three derivatives at x = XVAL
          can be provided in the real array SDIF of dimension 4, by the
          call

                 CALL E02BCF (M+4, LAMDA, C, XVAL, LEFT, SDIF, IFAIL)

          Here LEFT must specify whether the left- or right-hand value of
          the third derivative is required (see E02BCF for details).

          The value of the integral of s(x) over the range x  to x  can be
                                                            1     m
          provided in the real variable SINT by

                 CALL E02BDF (M+4, LAMDA, C, SINT, IFAIL)

          9. Example

          The example program sets up data from 7 values of the exponential
          function in the interval 0 to 1. E01BAF is then called to compute
          a spline interpolant to these data.

          The spline is evaluated by E02BBF, at the data points and at
          points halfway between each adjacent pair of data points, and the
                                           x
          spline values and the values of e  are printed out.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          E01 -- Interpolation                                       E01BEF
                  E01BEF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          E01BEF computes a monotonicity-preserving piecewise cubic Hermite
          interpolant to a set of data points.

          2. Specification

                 SUBROUTINE E01BEF (N, X, F, D, IFAIL)
                 INTEGER          N, IFAIL
                 DOUBLE PRECISION X(N), F(N), D(N)

          3. Description

          This routine estimates first derivatives at the set of data
          points (x ,f ), for r=1,2,...,n, which determine a piecewise
                   r  r
          cubic Hermite interpolant to the data, that preserves
          monotonicity over ranges where the data points are monotonic. If
          the data points are only piecewise monotonic, the interpolant
          will have an extremum at each point where monotonicity switches
          direction. The estimates of the derivatives are computed by a
          formula due to Brodlie, which is described in Fritsch and Butland
          [1], with suitable changes at the boundary points.

          The routine is derived from routine PCHIM in Fritsch [2].

          Values of the computed interpolant, and of its first derivative
          and definite integral, can subsequently be computed by calling
          E01BFF, E01BGF and E01BHF, as described in Section 8

          4. References

          [1]   Fritsch F N and Butland J (1984) A Method for Constructing
                Local Monotone Piecewise Cubic Interpolants. SIAM J. Sci.
                Statist. Comput. 5 300--304.

          [2]   Fritsch F N (1982) PCHIP Final Specifications. Report UCID-
                30194. Lawrence Livermore National Laboratory.

          5. Parameters

           1:  N -- INTEGER                                           Input
               On entry: n, the number of data points. Constraint: N >= 2.

           2:  X(N) -- DOUBLE PRECISION array                         Input
               On entry: X(r) must be set to x , the rth value of the
                                              r
               independent variable (abscissa), for r=1,2,...,n.
               Constraint: X(r) < X(r+1).

           3:  F(N) -- DOUBLE PRECISION array                         Input
               On entry: F(r) must be set to f , the rth value of the
                                              r
               dependent variable (ordinate), for r=1,2,...,n.

           4:  D(N) -- DOUBLE PRECISION array                        Output
               On exit: estimates of derivatives at the data points. D(r)
               contains the derivative at X(r).

           5:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry N < 2.

          IFAIL= 2
               The values of X(r), for r=1,2,...,N, are not in strictly
               increasing order.

          7. Accuracy

          The computational errors in the array D should be negligible in
          most practical situations.

          8. Further Comments

          The time taken by the routine is approximately proportional to n.

          The values of the computed interpolant at the points PX(i), for
          i=1,2,...,M, may be obtained in the real array PF, of length at
          least M, by the call:


                  CALL E01BFF(N,X,F,D,M,PX,PF,IFAIL)

          where N, X and F are the input parameters to E01BEF and D is the
          output parameter from E01BEF.

          The values of the computed interpolant at the points PX(i), for i
          = 1,2,...,M, together with its first derivatives, may be obtained
          in the real arrays PF and PD, both of length at least M, by the
          call:

                  CALL E01BGF(N,X,F,D,M,PX,PF,PD,IFAIL)

          where N, X, F and D are as described above.

          The value of the definite integral of the interpolant over the
          interval A to B can be obtained in the real variable PINT by the
          call:

                  CALL E01BHF(N,X,F,D,A,B,PINT,IFAIL)

          where N, X, F and D are as described above.

          9. Example

          This example program reads in a set of data points, calls E01BEF
          to compute a piecewise monotonic interpolant, and then calls
          E01BFF to evaluate the interpolant at equally spaced points.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          E01 -- Interpolation                                       E01BFF
                  E01BFF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          E01BFF evaluates a piecewise cubic Hermite interpolant at a set
          of points.

          2. Specification

                 SUBROUTINE E01BFF (N, X, F, D, M, PX, PF, IFAIL)
                 INTEGER          N, M, IFAIL
                 DOUBLE PRECISION X(N), F(N), D(N), PX(M), PF(M)

          3. Description

          This routine evaluates a piecewise cubic Hermite interpolant, as
          computed by E01BEF, at the points PX(i), for i=1,2,...,m. If any
          point lies outside the interval from X(1) to X(N), a value is
          extrapolated from the nearest extreme cubic, and a warning is
          returned.

          The routine is derived from routine PCHFE in Fritsch [1].

          4. References

          [1]   Fritsch F N (1982) PCHIP Final Specifications. Report UCID-
                30194. Lawrence Livermore National Laboratory.

          5. Parameters

           1:  N -- INTEGER                                           Input

           2:  X(N) -- DOUBLE PRECISION array                         Input

           3:  F(N) -- DOUBLE PRECISION array                         Input

           4:  D(N) -- DOUBLE PRECISION array                         Input
               On entry: N, X, F and D must be unchanged from the previous
               call of E01BEF.

           5:  M -- INTEGER                                           Input
               On entry: m, the number of points at which the interpolant
               is to be evaluated. Constraint: M >= 1.

           6:  PX(M) -- DOUBLE PRECISION array                        Input
               On entry: the m values of x at which the interpolant is to
               be evaluated.

           7:  PF(M) -- DOUBLE PRECISION array                       Output
               On exit: PF(i) contains the value of the interpolant
               evaluated at the point PX(i), for i=1,2,...,m.

           8:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry N < 2.

          IFAIL= 2
               The values of X(r), for r = 1,2,...,N, are not in strictly
               increasing order.

          IFAIL= 3
               On entry M < 1.

          IFAIL= 4
               At least one of the points PX(i), for i = 1,2,...,M, lies
               outside the interval [X(1),X(N)], and extrapolation was
               performed at all such points. Values computed at such points
               may be very unreliable.

          7. Accuracy

          The computational errors in the array PF should be negligible in
          most practical situations.

          8. Further Comments

          The time taken by the routine is approximately proportional to
          the number of evaluation points, m. The evaluation will be most
          efficient if the elements of PX are in non-decreasing order (or,
          more generally, if they are grouped in increasing order of the
          intervals [X(r-1),X(r)]). A single call of E01BFF with m>1 is
          more efficient than several calls with m=1.

          9. Example

          This example program reads in values of N, X, F and D, and then
          calls E01BFF to evaluate the interpolant at equally spaced
          points.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          E01 -- Interpolation                                       E01BGF
                  E01BGF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          E01BGF evaluates a piecewise cubic Hermite interpolant and its
          first derivative at a set of points.

          2. Specification

                 SUBROUTINE E01BGF (N, X, F, D, M, PX, PF, PD, IFAIL)
                 INTEGER          N, M, IFAIL
                 DOUBLE PRECISION X(N), F(N), D(N), PX(M), PF(M), PD(M)

          3. Description

          This routine evaluates a piecewise cubic Hermite interpolant, as
          computed by E01BEF, at the points PX(i), for i=1,2,...,m. The
          first derivatives at the points are also computed. If any point
          lies outside the interval from X(1) to X(N), values of the
          interpolant and its derivative are extrapolated from the nearest
          extreme cubic, and a warning is returned.

          If values of the interpolant only, and not of its derivative, are
          required, E01BFF should be used.

          The routine is derived from routine PCHFD in Fritsch [1].

          4. References

          [1]   Fritsch F N (1982) PCHIP Final Specifications. Report UCID-
                30194. Lawrence Livermore National Laboratory.

          5. Parameters

           1:  N -- INTEGER                                           Input

           2:  X(N) -- DOUBLE PRECISION array                         Input

           3:  F(N) -- DOUBLE PRECISION array                         Input

           4:  D(N) -- DOUBLE PRECISION array                         Input
               On entry: N, X, F and D must be unchanged from the previous
               call of E01BEF.

           5:  M -- INTEGER                                           Input
               On entry: m, the number of points at which the interpolant
               is to be evaluated. Constraint: M >= 1.

           6:  PX(M) -- DOUBLE PRECISION array                        Input
               On entry: the m values of x at which the interpolant is to
               be evaluated.

           7:  PF(M) -- DOUBLE PRECISION array                       Output
               On exit: PF(i) contains the value of the interpolant
               evaluated at the point PX(i), for i=1,2,...,m.

           8:  PD(M) -- DOUBLE PRECISION array                       Output
               On exit: PD(i) contains the first derivative of the
               interpolant evaluated at the point PX(i), for i=1,2,...,m.

           9:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry N < 2.

          IFAIL= 2
               The values of X(r), for r = 1,2,...,N, are not in strictly
               increasing order.

          IFAIL= 3
               On entry M < 1.

          IFAIL= 4
               At least one of the points PX(i), for i = 1,2,...,M, lies
               outside the interval [X(1),X(N)], and extrapolation was
               performed at all such points. Values computed at these
               points may be very unreliable.

          7. Accuracy

          The computational errors in the arrays PF and PD should be
          negligible in most practical situations.

          8. Further Comments

          The time taken by the routine is approximately proportional to
          the number of evaluation points, m. The evaluation will be most
          efficient if the elements of PX are in non-decreasing order (or,
          more generally, if they are grouped in increasing order of the
          intervals [X(r-1),X(r)]). A single call of E01BGF with m>1 is
          more efficient than several calls with m=1.

          9. Example

          This example program reads in values of N, X, F and D, and calls
          E01BGF to compute the values of the interpolant and its
          derivative at equally spaced points.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          E01 -- Interpolation                                       E01BHF
                  E01BHF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          E01BHF evaluates the definite integral of a piecewise cubic
          Hermite interpolant over the interval [a,b].

          2. Specification

                 SUBROUTINE E01BHF (N, X, F, D, A, B, PINT, IFAIL)
                 INTEGER          N, IFAIL
                 DOUBLE PRECISION X(N), F(N), D(N), A, B, PINT

          3. Description

          This routine evaluates the definite integral of a piecewise cubic
          Hermite interpolant, as computed by E01BEF, over the interval
          [a,b].

          If either a or b lies outside the interval from X(1) to X(N)
          computation of the integral involves extrapolation and a warning
          is returned.

          The routine is derived from routine PCHIA in Fritsch [1].

          4. References

          [1]   Fritsch F N (1982) PCHIP Final Specifications. Report UCID-
                30194. Lawrence Livermore National Laboratory .

          5. Parameters

           1:  N -- INTEGER                                           Input

           2:  X(N) -- DOUBLE PRECISION array                         Input

           3:  F(N) -- DOUBLE PRECISION array                         Input

           4:  D(N) -- DOUBLE PRECISION array                         Input
               On entry: N, X, F and D must be unchanged from the previous
               call of E01BEF.

           5:  A -- DOUBLE PRECISION                                  Input

           6:  B -- DOUBLE PRECISION                                  Input
               On entry: the interval [a,b] over which integration is to
               be performed.

           7:  PINT -- DOUBLE PRECISION                              Output
               On exit: the value of the definite integral of the
               interpolant over the interval [a,b].

           8:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry N < 2.

          IFAIL= 2
               The values of X(r), for r = 1,2,...,N, are not in strictly
               increasing order.

          IFAIL= 3
               On entry at least one of A or B lies outside the interval [X
               (1),X(N)], and extrapolation was performed to compute the
               integral. The value returned is therefore unreliable.

          7. Accuracy

          The computational error in the value returned for PINT should be
          negligible in most practical situations.

          8. Further Comments

          The time taken by the routine is approximately proportional to
          the number of data points included within the interval [a,b].

          9. Example

          This example program reads in values of N, X, F and D. It then
          reads in pairs of values for A and B, and evaluates the definite
          integral of the interpolant over the interval [A,B] until end-of-
          file is reached.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          E01 -- Interpolation                                       E01DAF
                  E01DAF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          E01DAF computes a bicubic spline interpolating surface through a
          set of data values, given on a rectangular grid in the x-y plane.

          2. Specification

                 SUBROUTINE E01DAF (MX, MY, X, Y, F, PX, PY, LAMDA, MU, C,
                1                   WRK, IFAIL)
                 INTEGER          MX, MY, PX, PY, IFAIL
                 DOUBLE PRECISION X(MX), Y(MY), F(MX*MY), LAMDA(MX+4), MU(MX
                1                 +4), C(MX*MY), WRK((MX+6)*(MY+6))

          3. Description

          This routine determines a bicubic spline interpolant to the set
          of data points (x ,y ,f   ), for q=1,2,...,m ; r=1,2,...,m . The
                           q  r  q,r                  x             y
          spline is given in the B-spline representation

                                    m   m
                                     x   y
                                    --  --
                            s(x,y)= >   >  c  M (x)N (y),
                                    --  --  ij i    j
                                    i=1 j=1

          such that

                                   s(x ,y )=f   ,
                                      q  r   q,r

          where M (x) and N (y) denote normalised cubic B-splines, the
                 i         j
          former defined on the knots (lambda)  to (lambda)    and the
                                              i            i+4
          latter on the knots (mu)  to (mu)   , and the c   are the spline
                                  j        j+4           ij
          coefficients. These knots, as well as the coefficients, are
          determined by the routine, which is derived from the routine
          B2IRE in Anthony et al[1]. The method used is described in
          Section 8.2.

          For further information on splines, see Hayes and Halliday [4]
          for bicubic splines and de Boor [3] for normalised B-splines.

          Values of the computed spline can subsequently be obtained by
          calling E02DEF or E02DFF as described in Section 8.3.

          4. References

          [1]   Anthony G T, Cox M G and Hayes J G (1982) DASL - Data
                Approximation Subroutine Library. National Physical
                Laboratory.

          [2]   Cox M G (1975) An Algorithm for Spline Interpolation. J.
                Inst. Math. Appl. 15 95--108.

          [3]   De Boor C (1972) On Calculating with B-splines. J. Approx.
                Theory. 6 50--62.

          [4]   Hayes J G and Halliday J (1974) The Least-squares Fitting of
                Cubic Spline Surfaces to General Data Sets. J. Inst. Math.
                Appl. 14 89--103.

          5. Parameters

           1:  MX -- INTEGER                                          Input

           2:  MY -- INTEGER                                          Input
               On entry: MX and MY must specify m  and m  respectively,
                                                 x      y
               the number of points along the x and y axis that define the
               rectangular grid. Constraint: MX >= 4 and MY >= 4.

           3:  X(MX) -- DOUBLE PRECISION array                        Input

           4:  Y(MY) -- DOUBLE PRECISION array                        Input
               On entry: X(q) and Y(r) must contain x , for q=1,2,...,m ,
                                                     q                 x
               and y , for r=1,2,...,m , respectively. Constraints:
                    r                 y
                    X(q) < X(q+1), for q=1,2,...,m -1,
                                                  x

                    Y(r) < Y(r+1), for r=1,2,...,m -1.
                                                  y

           5:  F(MX*MY) -- DOUBLE PRECISION array                     Input
               On entry: F(m *(q-1)+r) must contain f   , for q=1,2,...,m ;
                            y                        q,r                 x
               r=1,2,...,m .
                          y

           6:  PX -- INTEGER                                         Output

           7:  PY -- INTEGER                                         Output
               On exit: PX and PY contain m +4 and m +4, the total number
                                           x        y
               of knots of the computed spline with respect to the x and y
               variables, respectively.

           8:  LAMDA(MX+4) -- DOUBLE PRECISION array                 Output

           9:  MU(MY+4) -- DOUBLE PRECISION array                    Output
               On exit: LAMDA contains the complete set of knots (lambda)
                                                                         i
               associated with the x variable, i.e., the interior knots
               LAMDA(5), LAMDA(6), ..., LAMDA(PX-4), as well as the
               additional knots LAMDA(1) = LAMDA(2) = LAMDA(3) = LAMDA(4) =
               X(1) and LAMDA(PX-3) = LAMDA(PX-2) = LAMDA(PX-1) = LAMDA(PX)
               = X(MX) needed for the B-spline representation. MU contains
               the corresponding complete set of knots (mu)  associated
                                                           i
               with the y variable.

          10:  C(MX*MY) -- DOUBLE PRECISION array                    Output
               On exit: the coefficients of the spline interpolant. C(
               m *(i-1)+j) contains the coefficient c   described in
                y                                    ij
               Section 3.

          11:  WRK((MX+6)*(MY+6)) -- DOUBLE PRECISION array       Workspace

          12:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry MX < 4,

               or       MY < 4.

          IFAIL= 2
               On entry either the values in the X array or the values in
               the Y array are not in increasing order.

          IFAIL= 3
               A system of linear equations defining the B-spline
               coefficients was singular; the problem is too ill-
               conditioned to permit solution.

          7. Accuracy

          The main sources of rounding errors are in steps (2), (3), (6)
          and (7) of the algorithm described in Section 8.2. It can be
          shown (Cox [2]) that the matrix A  formed in step (2) has
                                           x
          elements differing relatively from their true values by at most a
          small multiple of 3(epsilon), where (epsilon) is the machine
          precision. A  is 'totally positive', and a linear system with
                      x
          such a coefficient matrix can be solved quite safely by
          elimination without pivoting. Similar comments apply to steps (6)
          and (7). Thus the complete process is numerically stable.

          8. Further Comments

          8.1. Timing

          The time taken by this routine is approximately proportional to
          m m .
           x y

          8.2. Outline of method used

          The process of computing the spline consists of the following
          steps:

          (1)   choice of the interior x-knots (lambda) , (lambda) ,...,
                                                       5          6
                (lambda)   as (lambda) =x   , for i=5,6,...,m ,
                        m             i  i-2                 x
                         x

          (2)   formation of the system
                                          A E=F,
                                           x
                where A  is a band matrix of order m  and bandwidth 4,
                       x                            x
                containing in its qth row the values at x  of the B-splines
                                                         q
                in x, F is the m  by m  rectangular matrix of values f   ,
                                x     y                               q,r
                and E denotes an m  by m  rectangular matrix of
                                  x     y
                intermediate coefficients,

          (3)   use of Gaussian elimination to reduce this system to band
                triangular form,

          (4)   solution of this triangular system for E,

          (5)   choice of the interior y knots (mu) , (mu) ,...,(mu)   as
                                                   5      6         m
                                                                     y
                (mu) =y   , for i=5,6,...,m ,
                    i  i-2                 y

          (6)   formation of the system
                                            T  T
                                         A C =E ,
                                          y
                where A  is the counterpart of A  for the y variable, and C
                       y                        x
                denotes the m  by m  rectangular matrix of values of c  ,
                             x     y                                  ij

          (7)   use of Gaussian elimination to reduce this system to band
                triangular form,

                                                        T
          (8)   solution of this triangular system for C  and hence C.

          For computational convenience, steps (2) and (3), and likewise
          steps (6) and (7), are combined so that the formation of A  and
                                                                    x
          A  and the reductions to triangular form are carried out one row
           y
          at a time.

          8.3. Evaluation of Computed Spline

          The values of the computed spline at the points (TX(r),TY(r)),
          for r = 1,2,...,N, may be obtained in the double precision array
          FF, of length at least N, by the following call:


                IFAIL = 0
                CALL E02DEF(N,PX,PY,TX,TY,LAMDA,MU,C,FF,WRK,IWRK,IFAIL)

          where PX, PY, LAMDA, MU and C are the output parameters of E01DAF
          , WRK is a double precision workspace array of length at least
          PY-4, and IWRK is an integer workspace array of length at least
          PY-4.

          To evaluate the computed spline on an NX by NY rectangular grid
          of points in the x-y plane, which is defined by the x co-
          ordinates stored in TX(q), for q = 1,2,...,NX, and the y co-
          ordinates stored in TY(r), for r = 1,2,...,NY, returning the
          results in the double precision array FG which is of length at
          least NX*NY, the following call may be used:


                 IFAIL = 0
                 CALL E02DFF(NX,NY,PX,PY,TX,TY,LAMDA,MU,C,FG,WRK,LWRK,
                *            IWRK,LIWRK,IFAIL)

          where PX, PY, LAMDA, MU and C are the output parameters of E01DAF
          , WRK is a double precision workspace array of length at least
          LWRK = min(NWRK1,NWRK2), NWRK1 = NX*4+PX, NWRK2 = NY*4+PY, and
          IWRK is an integer workspace array of length at least LIWRK = NY
          + PY - 4 if NWRK1 > NWRK2, or NX + PX - 4 otherwise. The result
          of the spline evaluated at grid point (q,r) is returned in
          element (NY*(q-1)+r) of the array FG.

          9. Example

          This program reads in values of m , x  for q=1,2,...,m , m  and
                                           x   q                x   y
          y  for r=1,2,...,m , followed by values of the ordinates f
           r                y                                       q,r
          defined at the grid points (x ,y ). It then calls E01DAF to
                                       q  r
          compute a bicubic spline interpolant of the data values, and
          prints the values of the knots and B-spline coefficients. Finally
          it evaluates the spline at a small sample of points on a
          rectangular grid.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          E01 -- Interpolation                                       E01SAF
                  E01SAF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          E01SAF generates a two-dimensional surface interpolating a set of
          scattered data points, using the method of Renka and Cline.

          2. Specification

                 SUBROUTINE E01SAF (M, X, Y, F, TRIANG, GRADS, IFAIL)
                 INTEGER          M, TRIANG(7*M), IFAIL
                 DOUBLE PRECISION X(M), Y(M), F(M), GRADS(2,M)

          3. Description

          This routine constructs an interpolating surface F(x,y) through a
          set of m scattered data points (x ,y ,f ), for r=1,2,...,m, using
                                           r  r  r
          a method due to Renka and Cline. In the (x,y) plane, the data
          points must be distinct. The constructed surface is continuous
          and has continuous first derivatives.

          The method involves firstly creating a triangulation with all the
          (x,y) data points as nodes, the triangulation being as nearly
          equiangular as possible (see Cline and Renka [1]). Then gradients
          in the x- and y-directions are estimated at node r, for
          r=1,2,...,m, as the partial derivatives of a quadratic function
          of x and y which interpolates the data value f , and which fits
                                                        r
          the data values at nearby nodes (those within a certain distance
          chosen by the algorithm) in a weighted least-squares sense. The
          weights are chosen such that closer nodes have more influence
          than more distant nodes on derivative estimates at node r. The
          computed partial derivatives, with the f  values, at the three
                                                  r
          nodes of each triangle define a piecewise polynomial surface of a
          certain form which is the interpolant on that triangle. See Renka
          and Cline [4] for more detailed information on the algorithm, a
          development of that by Lawson [2]. The code is derived from Renka
          [3].

          The interpolant F(x,y) can subsequently be evaluated at any point
          (x,y) inside or outside the domain of the data by a call to
          E01SBF. Points outside the domain are evaluated by extrapolation.

          4. References

          [1]   Cline A K and Renka R L (1984) A Storage-efficient Method
                for Construction of a Thiessen Triangulation. Rocky Mountain
                J. Math. 14 119--139.

                                                1
          [2]   Lawson C L (1977) Software for C  Surface Interpolation.
                Mathematical Software III. (ed J R Rice) Academic Press.
                161--194.

          [3]   Renka R L (1984) Algorithm 624: Triangulation and
                Interpolation of Arbitrarily Distributed Points in the
                Plane. ACM Trans. Math. Softw. 10 440--442.

                                                                 1
          [4]   Renka R L and Cline A K (1984) A Triangle-based C
                Interpolation Method. Rocky Mountain J. Math. 14 223--237.

          5. Parameters

           1:  M -- INTEGER                                           Input
               On entry: m, the number of data points. Constraint: M >= 3.

           2:  X(M) -- DOUBLE PRECISION array                         Input

           3:  Y(M) -- DOUBLE PRECISION array                         Input

           4:  F(M) -- DOUBLE PRECISION array                         Input
               On entry: the co-ordinates of the rth data point, for
               r=1,2,...,m. The data points are accepted in any order, but
               see Section 8. Constraint: The (x,y) nodes must not all be
               collinear, and each node must be unique.

           5:  TRIANG(7*M) -- INTEGER array                          Output
               On exit: a data structure defining the computed
               triangulation, in a form suitable for passing to E01SBF.

           6:  GRADS(2,M) -- DOUBLE PRECISION array                  Output
               On exit: the estimated partial derivatives at the nodes, in
               a form suitable for passing to E01SBF. The derivatives at
               node r with respect to x and y are contained in GRADS(1,r)
               and GRADS(2,r) respectively, for r=1,2,...,m.

           7:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry M < 3.

          IFAIL= 2
               On entry all the (X,Y) pairs are collinear.

          IFAIL= 3
               On entry (X(i),Y(i)) = (X(j),Y(j)) for some i/=j.

          7. Accuracy

          On successful exit, the computational errors should be negligible
          in most situations but the user should always check the computed
          surface for acceptability, by drawing contours for instance. The
          surface always interpolates the input data exactly.

          8. Further Comments

          The time taken for a call of E01SAF is approximately proportional
          to the number of data points, m. The routine is more efficient
          if, before entry, the values in X, Y, F are arranged so that the
          X array is in ascending order.

          9. Example

          This program reads in a set of 30 data points and calls E01SAF to
          construct an interpolating surface. It then calls E01SBF to
          evaluate the interpolant at a sample of points on a rectangular
          grid.

          Note that this example is not typical of a realistic problem: the
          number of data points would normally be larger, and the
          interpolant would need to be evaluated on a finer grid to obtain
          an accurate plot, say.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          E01 -- Interpolation                                       E01SBF
                  E01SBF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          E01SBF evaluates at a given point the two-dimensional interpolant
          function computed by E01SAF.

          2. Specification

                 SUBROUTINE E01SBF (M, X, Y, F, TRIANG, GRADS, PX, PY, PF,
                1                   IFAIL)
                 INTEGER          M, TRIANG(7*M), IFAIL
                 DOUBLE PRECISION X(M), Y(M), F(M), GRADS(2,M), PX, PY, PF

          3. Description

          This routine takes as input the parameters defining the
          interpolant F(x,y) of a set of scattered data points (x ,y ,f ),
                                                                 r  r  r
          for r=1,2,...,m, as computed by E01SAF, and evaluates the
          interpolant at the point (px,py).

          If (px,py) is equal to (x ,y ) for some value of r, the returned
                                   r  r
          value will be equal to f .
                                  r

          If (px,py) is not equal to (x ,y ) for any r, the derivatives in
                                       r  r
          GRADS will be used to compute the interpolant. A triangle is
          sought which contains the point (px,py), and the vertices of the
          triangle along with the partial derivatives and f  values at the
                                                           r
          vertices are used to compute the value F(px,py). If the point
          (px,py) lies outside the triangulation defined by the input
          parameters, the returned value is obtained by extrapolation. In
          this case, the interpolating function F is extended linearly
          beyond the triangulation boundary. The method is described in
          more detail in Renka and Cline [2] and the code is derived from
          Renka [1].

          E01SBF must only be called after a call to E01SAF.

          4. References

          [1]   Renka R L (1984) Algorithm 624: Triangulation and
                Interpolation of Arbitrarily Distributed Points in the
                Plane. ACM Trans. Math. Softw. 10 440--442.

                                                                 1
          [2]   Renka R L and Cline A K (1984) A Triangle-based C
                Interpolation Method. Rocky Mountain J. Math. 14 223--237.

          5. Parameters

           1:  M -- INTEGER                                           Input

           2:  X(M) -- DOUBLE PRECISION array                         Input

           3:  Y(M) -- DOUBLE PRECISION array                         Input

           4:  F(M) -- DOUBLE PRECISION array                         Input

           5:  TRIANG(7*M) -- INTEGER array                           Input

           6:  GRADS(2,M) -- DOUBLE PRECISION array                   Input
               On entry: M, X, Y, F, TRIANG and GRADS must be unchanged
               from the previous call of E01SAF.

           7:  PX -- DOUBLE PRECISION                                 Input

           8:  PY -- DOUBLE PRECISION                                 Input
               On entry: the point (px,py) at which the interpolant is to
               be evaluated.

           9:  PF -- DOUBLE PRECISION                                Output
               On exit: the value of the interpolant evaluated at the
               point (px,py).

          10:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry M < 3.

          IFAIL= 2
               On entry the triangulation information held in the array
               TRIANG does not specify a valid triangulation of the data
               points. TRIANG may have been corrupted since the call to
               E01SAF.

          IFAIL= 3
               The evaluation point (PX,PY) lies outside the nodal
               triangulation, and the value returned in PF is computed by
               extrapolation.

          7. Accuracy

          Computational errors should be negligible in most practical
          situations.

          8. Further Comments

          The time taken for a call of E01SBF is approximately proportional
          to the number of data points, m.

          The results returned by this routine are particularly suitable
          for applications such as graph plotting, producing a smooth
          surface from a number of scattered points.

          9. Example

          See the example for E01SAF.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          E01 -- Interpolation                                       E01SEF
                  E01SEF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          E01SEF generates a two-dimensional surface interpolating a set of
          scattered data points, using a modified Shepard method.

          2. Specification

                 SUBROUTINE E01SEF (M, X, Y, F, RNW, RNQ, NW, NQ, FNODES,
                1                   MINNQ, WRK, IFAIL)
                 INTEGER          M, NW, NQ, MINNQ, IFAIL
                 DOUBLE PRECISION X(M), Y(M), F(M), RNW, RNQ, FNODES(5*M),
                1                 WRK(6*M)

          3. Description

          This routine constructs an interpolating surface F(x,y) through a
          set of m scattered data points (x ,y ,f ), for r=1,2,...,m, using
                                           r  r  r
          a modification of Shepard's method. The surface is continuous and
          has continuous first derivatives.

          The basic Shepard method, described in [2], interpolates the
          input data with the weighted mean

                                        m
                                        --
                                        >  w (x,y)f
                                        --  r      r
                                        r=1
                               F(x,y)= -------------,
                                         m
                                         --
                                         >  w (x,y)
                                         --  r
                                         r=1

                                    1         2       2       2
                     where w (x,y)= --  and  d =(x-x ) +(y-y ) .
                            r        2        r     r       r
                                    d
                                     r

          The basic method is global in that the interpolated value at any
          point depends on all the data, but this routine uses a
          modification due to Franke and Nielson described in [1], whereby
          the method becomes local by adjusting each w (x,y) to be zero
                                                      r
          outside a circle with centre (x ,y ) and some radius R . Also, to
                                         r  r                   w
          improve the performance of the basic method, each f  above is
                                                             r
          replaced by a function f (x,y), which is a quadratic fitted by
                                  r
          weighted least-squares to data local to (x ,y ) and forced to
                                                    r  r
          interpolate (x ,y ,f ). In this context, a point (x,y) is defined
                        r  r  r
          to be local to another point if it lies within some distance R
                                                                        q
          of it. Computation of these quadratics constitutes the main work
          done by this routine. If there are less than 5 other points
          within distance R  from (x ,y ), the quadratic is replaced by a
                           q        r  r
          linear function. In cases of rank-deficiency, the minimum norm
          solution is computed.

          The user may specify values for R  and R , but it is usually
                                           w      q
          easier to choose instead two integers N  and N , from which the
                                                 w      q
          routine will compute R  and R . These integers can be thought of
                                w      q
          as the average numbers of data points lying within distances R
                                                                        w
          and R  respectively from each node. Default values are provided,
               q
          and advice on alternatives is given in Section 8.2.

          The interpolant F(x,y) generated by this routine can subsequently
          be evaluated for any point (x,y) in the domain of the data by a
          call to E01SFF.

          4. References

          [1]   Franke R and Nielson G (1980) Smooth Interpolation of Large
                Sets of Scattered Data. Internat. J. Num. Methods Engrg. 15
                1691--1704.

          [2]   Shepard D (1968) A Two-dimensional Interpolation Function
                for Irregularly Spaced Data. Proc. 23rd Nat. Conf. ACM.
                Brandon/Systems Press Inc., Princeton. 517--523.

          5. Parameters

           1:  M -- INTEGER                                           Input
               On entry: m, the number of data points. Constraint: M >= 3.

           2:  X(M) -- DOUBLE PRECISION array                         Input

           3:  Y(M) -- DOUBLE PRECISION array                         Input

           4:  F(M) -- DOUBLE PRECISION array                         Input
               On entry: the co-ordinates of the rth data point, for
               r=1,2,...,m. The order of the data points is immaterial.
               Constraint: each of the (X(r),Y(r)) pairs must be unique.

           5:  RNW -- DOUBLE PRECISION                         Input/Output

           6:  RNQ -- DOUBLE PRECISION                         Input/Output
               On entry: suitable values for the radii R  and R ,
                                                         w      q
               described in Section 3. Constraint: RNQ <= 0 or 0 < RNW <=
               RNQ. On exit: if RNQ is set less than or equal to zero on
               entry, then default values for both of them will be computed
               from the parameters NW and NQ, and RNW and RNQ will contain
               these values on exit.

           7:  NW -- INTEGER                                          Input

           8:  NQ -- INTEGER                                          Input
               On entry: if RNQ > 0.0 and RNW > 0.0 then NW and NQ are not
               referenced by the routine. Otherwise, NW and NQ must specify
               suitable values for the integers N  and N  described in
                                                 w      q
               Section 3.

               If NQ is less than or equal to zero on entry, then default
               values for both of them, namely NW = 9 and NQ = 18, will be
               used. Constraint: NQ <= 0 or 0 < NW <= NQ.

           9:  FNODES(5*M) -- DOUBLE PRECISION array                 Output
               On exit: the coefficients of the constructed quadratic
               nodal functions. These are in a form suitable for passing to
               E01SFF.

          10:  MINNQ -- INTEGER                                      Output
               On exit: the minimum number of data points that lie within
               radius RNQ of any node, and thus define a nodal function. If
               MINNQ is very small (say, less than 5), then the interpolant
               may be unsatisfactory in regions where the data points are
               sparse.

          11:  WRK(6*M) -- DOUBLE PRECISION array                 Workspace

          12:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry M < 3.

          IFAIL= 2
               On entry RNQ > 0 and either RNW > RNQ or RNW <= 0.

          IFAIL= 3
               On entry NQ > 0 and either NW > NQ or NW <= 0.

          IFAIL= 4
               On entry (X(i),Y(i)) is equal to (X(j),Y(j)) for some i/=j.

          7. Accuracy

          On successful exit, the computational errors should be negligible
          in most situations but the user should always check the computed
          surface for acceptability, by drawing contours for instance. The
          surface always interpolates the input data exactly.

          8. Further Comments

          8.1. Timing

          The time taken for a call of E01SEF is approximately proportional
          to the number of data points, m, provided that N  is of the same
                                                          q
          order as its default value (18). However if N  is increased so
                                                       q
          that the method becomes more global, the time taken becomes
                                         2
          approximately proportional to m .
                            m N} {{\rm w}}$ and ${\rm N} {{\rm q}}$
          8.2. Choice of ${\
          Note first that the radii R  and R , described in Section 3, are
                                     w      q
                                            

                            / N            / N
                       D   /   w      D   /   q
          computed as  -  /   -- and  -  /   -- respectively, where D is
                       2\/    m       2/    m
          the maximum distance between any pair of data points.
          Default values N =9 and N =18 work quite well when the data
                          w        q
          points are fairly uniformly distributed. However, for data having
          some regions with relatively few points or for small data sets
          (m<25), a larger value of N  may be needed. This is to ensure a
                                    w
          reasonable number of data points within a distance R  of each
                                                              w
          node, and to avoid some regions in the data area being left
          outside all the discs of radius R  on which the weights w (x,y)
                                           w                       r
          are non-zero. Maintaining N  approximately equal to 2N  is
                                     q                          w
          usually an advantage.

          Note however that increasing N  and N  does not improve the
                                        w      q
          quality of the interpolant in all cases. It does increase the
          computational cost and makes the method less local.

          9. Example

          This program reads in a set of 30 data points and calls E01SEF to
          construct an interpolating surface. It then calls E01SFF to
          evaluate the interpolant at a sample of points on a rectangular
          grid.

          Note that this example is not typical of a realistic problem: the
          number of data points would normally be larger, and the
          interpolant would need to be evaluated on a finer grid to obtain
          an accurate plot, say.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

          E01 -- Interpolation                                       E01SFF
                  E01SFF -- NAG Foundation Library Routine Document

          Note: Before using this routine, please read the Users' Note for
          your implementation to check implementation-dependent details.
          The symbol (*) after a NAG routine name denotes a routine that is
          not included in the Foundation Library.

          1. Purpose

          E01SFF evaluates at a given point the two-dimensional
          interpolating function computed by E01SEF.

          2. Specification

                 SUBROUTINE E01SFF (M, X, Y, F, RNW, FNODES, PX, PY, PF,
                1                   IFAIL)
                 INTEGER          M, IFAIL
                 DOUBLE PRECISION X(M), Y(M), F(M), RNW, FNODES(5*M), PX,
                1                 PY, PF

          3. Description

          This routine takes as input the interpolant F(x,y) of a set of
          scattered data points (x ,y ,f ), for r=1,2,...,m, as computed by
                                  r  r  r
          E01SEF, and evaluates the interpolant at the point (px,py).

          If (px,py) is equal to (x ,y ) for some value of r, the returned
                                   r  r
          value will be equal to f .
                                  r

          If (px,py) is not equal to (x ,y ) for any r, all points that are
                                       r  r
          within distance RNW of (px,py), along with the corresponding
          nodal functions given by FNODES, will be used to compute a value
          of the interpolant.

          E01SFF must only be called after a call to E01SEF.

          4. References

          [1]   Franke R and Nielson G (1980) Smooth Interpolation of Large
                Sets of Scattered Data. Internat. J. Num. Methods Engrg. 15
                1691--1704.

          [2]   Shepard D (1968) A Two-dimensional Interpolation Function
                for Irregularly Spaced Data. Proc. 23rd Nat. Conf. ACM.
                Brandon/Systems Press Inc., Princeton. 517--523.

          5. Parameters

           1:  M -- INTEGER                                           Input

           2:  X(M) -- DOUBLE PRECISION array                         Input

           3:  Y(M) -- DOUBLE PRECISION array                         Input

           4:  F(M) -- DOUBLE PRECISION array                         Input

           5:  RNW -- DOUBLE PRECISION                                Input

           6:  FNODES(5*M) -- DOUBLE PRECISION array                  Input
               On entry: M, X, Y, F, RNW and FNODES must be unchanged from
               the previous call of E01SEF.

           7:  PX -- DOUBLE PRECISION                                 Input

           8:  PY -- DOUBLE PRECISION                                 Input
               On entry: the point (px,py) at which the interpolant is to
               be evaluated.

           9:  PF -- DOUBLE PRECISION                                Output
               On exit: the value of the interpolant evaluated at the
               point (px,py).

          10:  IFAIL -- INTEGER                                Input/Output
               On entry: IFAIL must be set to 0, -1 or 1. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               On exit: IFAIL = 0 unless the routine detects an error (see
               Section 6).

          6. Error Indicators and Warnings

          Errors detected by the routine:

          If on entry IFAIL = 0 or -1, explanatory error messages are
          output on the current error message unit (as defined by X04AAF).

          IFAIL= 1
               On entry M < 3.

          IFAIL= 2
               The interpolant cannot be evaluated because the evaluation
               point (PX,PY) lies outside the support region of the data
               supplied in X, Y and F. This error exit will occur if
               (PX,PY) lies at a distance greater than or equal to RNW from
               every point given by arrays X and Y.

               The value 0.0 is returned in PF. This value will not provide
               continuity with values obtained at other points (PX,PY),
               i.e., values obtained when IFAIL = 0 on exit.

          7. Accuracy

          Computational errors should be negligible in most practical
          situations.

          8. Further Comments

          The time taken for a call of E01SFF is approximately proportional
          to the number of data points, m.

          The results returned by this routine are particularly suitable
          for applications such as graph plotting, producing a smooth
          surface from a number of scattered points.

          9. Example

          See the example for E01SEF.

          The example program is not reproduced here. The source code for
          all example programs is distributed with the NAG Foundation
          Library software and should be available on-line.

