
     C05(3NAG)         Foundation Library (12/10/92)         C05(3NAG)

          C05 -- Roots of One or More Transcendental Equations
                                                         Introduction -- C05
                                    Chapter C05
                   Roots of One or More Transcendental Equations

          1. Scope of the Chapter

          This chapter is concerned with the calculation of real zeros of
          continuous real functions of one or more variables. (Complex
          equations must be expressed in terms of the equivalent larger
          system of real equations.)

          2. Background to the Problems

          The chapter divides naturally into two parts.

          2.1. A Single Equation

          The first deals with the real zeros of a real function of a
          single variable f(x).

          At present, there is only one routine with a simple calling
          sequence. This routine assumes that the user can determine an
          initial interval [a,b] within which the desired zero lies, that
          is f(a)*f(b)<0, and outside which all other zeros lie. The
          routine then systematically subdivides the interval to produce a
          final interval containing the zero. This final interval has a
          length bounded by the user's specified error requirements; the
          end of the interval where the function has smallest magnitude is
          returned as the zero. This routine is guaranteed to converge to a
          simple zero of the function. (Here we define a simple zero as a
          zero corresponding to a sign-change of the function.) The
          algorithm used is due to Bus and Dekker.

          2.2. Systems of Equations

          The routines in the second part of this chapter are designed to
          solve a set of nonlinear equations in n unknowns


                                                           T
                   f (x)=0,  i=1,2,...,n,  x=(x ,x ,...,x )             (1)
                    i                          1  2      n

          where T stands for transpose.

          It is assumed that the functions are continuous and
          differentiable so that the matrix of first partial derivatives of
          the functions, the Jacobian matrix J  (x)=ddf /ddx  evaluated at
                                              ij       i    j
          the point x, exists, though it may not be possible to calculate
          it directly.

          The functions f  must be independent, otherwise there will be an
                         i
          infinity of solutions and the methods will fail. However, even
          when the functions are independent the solutions may not be
          unique. Since the methods are iterative, an initial guess at the
          solution has to be supplied, and the solution located will
          usually be the one closest to this initial guess.

          2.3. References

          [1]   Gill P E and Murray W (1976) Algorithms for the Solution of
                the Nonlinear Least-squares Problem. NAC 71 National
                Physical Laboratory.

          [2]   More J J, Garbow B S and Hillstrom K E (1974) User Guide for
                Minpack-1. ANL-80-74 Argonne National Laboratory.

          [3]   Ortega J M and Rheinboldt W C (1970) Iterative Solution of
                Nonlinear Equations in Several Variables. Academic Press.

          [4]   Rabinowitz P (1970) Numerical Methods for Nonlinear
                Algebraic Equations. Gordon and Breach.

          3. Recommendations on Choice and Use of Routines

          3.1. Zeros of Functions of One Variable

          There is only one routine (C05ADF) for solving a single nonlinear
          equation. This routine is designed for solving problems where the
          function f(x) whose zero is to be calculated, can be coded as a
          user-supplied routine.

          C05ADF may only be used when the user can supply an interval
          [a,b] containing the zero, that is f(a)*f(b)<0.

          3.2. Solution of Sets of Nonlinear Equations

          The solution of a set of nonlinear equations

                        f (x ,x ,...,x )=0,  i=1,2,...,n                (2)
                         i  1  2      n

          can be regarded as a special case of the problem of finding a
          minimum of a sum of squares

                           m
                           /                    2
                     s(x)= |  [f (x ,x ,...,x )]   (m>=n).              (3)
                           /    i  1  2      n
                           i=1

          So the routines in Chapter E04 of the Library are relevant as
          well as the special nonlinear equations routines.

          There are two routines (C05NBF and C05PBF) for solving a set of
          nonlinear equations. These routines require the f  (and possibly
                                                           i
          their derivatives) to be calculated in user-supplied routines.
          These should be set up carefully so the Library routines can work
          as efficiently as possible.

          The main decision which has to be made by the user is whether to
                                  ddf
                                     i
          supply the derivatives  ----. It is advisable to do so if
                                  ddx
                                     j
          possible, since the results obtained by algorithms which use
          derivatives are generally more reliable than those obtained by
          algorithms which do not use derivatives.

          C05PBF requires the user to provide the derivatives, whilst
          C05NBF does not. C05NBF and C05PBF are easy-to-use routines. A
          routine, C05ZAF, is provided for use in conjunction with C05PBF
          to check the user-provided derivatives for consistency with the
          functions themselves. The user is strongly advised to make use of
          this routine whenever C05PBF is used.

          Firstly, the calculation of the functions and their derivatives
          should be ordered so that cancellation errors are avoided. This
          is particularly important in a routine that uses these quantities
          to build up estimates of higher derivatives.

          Secondly, scaling of the variables has a considerable effect on
          the efficiency of a routine. The problem should be designed so
          that the elements of x are of similar magnitude. The same comment
          applies to the functions, all the f  should be of comparable
                                             i
          size.

          The accuracy is usually determined by the accuracy parameters of
          the routines, but the following points may be useful:

          (i)   Greater accuracy in the solution may be requested by
                choosing smaller input values for the accuracy parameters.
                However, if unreasonable accuracy is demanded, rounding
                errors may become important and cause a failure.

          (ii)  Some idea of the accuracies of the x  may be obtained by
                                                    i
                monitoring the progress of the routine to see how many
                figures remain unchanged during the last few iterations.

          (iii) An approximation to the error in the solution x, given by e
                where e is the solution to the set of linear equations

                J(x)e=-f(x)

                                                  T
                where f(x)=(f (x),f (x),...,f (x))  (see Chapter F04).
                             1     2         n

          (iv)  If the functions f (x) are changed by small amounts
                                  i
                (epsilon) , for i=1,2,...,n, then the corresponding change
                         i
                in the solution x is given approximately by (sigma), where
                (sigma) is the solution of the set of linear equations

                J(x)(sigma)=-(epsilon), (see Chapter F04).

                Thus one can estimate the sensitivity of x to any
                uncertainties in the specification of f (x), for
                                                       i
                i=1,2,...,n.

          3.3. Index

          Zeros of functions of one variable:
               Bus and Dekker algorithm                              C05ADF
          Zeros of functions of several variables:
               easy-to-use                                           C05NBF
               easy-to-use, derivatives required                     C05PBF
          Checking Routine:
               Checks user-supplied Jacobian                         C05ZAF


          C05 -- Roots of One or More Transcendental Equations
                                                             Contents -- C05
          Chapter C05

          Roots of One or More Transcendental Equations

          C05ADF  Zero of continuous function in given interval, Bus and
                  Dekker algorithm

          C05NBF  Solution of system of nonlinear equations using function
                  values only

          C05PBF  Solution of system of nonlinear equations using 1st
                  derivatives

          C05ZAF  Check user's routine for calculating 1st derivatives

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

     C05ADF(3NAG)      Foundation Library (12/10/92)      C05ADF(3NAG)

          C05 -- Roots of One or More Transcendental Equations       C05ADF
                  C05ADF -- 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

          C05ADF locates a zero of a continuous function in a given
          interval by a combination of the methods of linear interpolation,
          extrapolation and bisection.

          2. Specification

                 SUBROUTINE C05ADF (A, B, EPS, ETA, F, X, IFAIL)
                 INTEGER          IFAIL
                 DOUBLE PRECISION A, B, EPS, ETA, F, X
                 EXTERNAL         F

          3. Description

          The routine attempts to obtain an approximation to a simple zero
          of the function f(x) given an initial interval [a,b] such that
          f(a)*f(b)<=0. The zero is found by calls to C05AZF(*) whose
          specification should be consulted for details of the method used.

          The approximation x to the zero (alpha) is determined so that one
          or both of the following criteria are satisfied:

               (i) |x-(alpha)|<EPS,

               (ii) |f(x)|<ETA.

          4. References

          None.

          5. Parameters

           1:  A -- DOUBLE PRECISION                                  Input
               On entry: the lower bound of the interval, a.

           2:  B -- DOUBLE PRECISION                                  Input
               On entry: the upper bound of the interval, b. Constraint: B
               /= A.

           3:  EPS -- DOUBLE PRECISION                                Input
               On entry: the absolute tolerance to which the zero is
               required (see Section 3). Constraint: EPS > 0.0.

           4:  ETA -- DOUBLE PRECISION                                Input
               On entry: a value such that if |f(x)|<ETA, x is accepted as
               the zero. ETA may be specified as 0.0 (see Section 7).

           5:  F -- DOUBLE PRECISION FUNCTION, supplied by the user.
                                                    External Procedure
               F must evaluate the function f whose zero is to be
               determined.

               Its specification is:

                      DOUBLE PRECISION FUNCTION F (XX)
                      DOUBLE PRECISION XX

                1:  XX -- DOUBLE PRECISION                            Input
                    On entry: the point at which the function must be
                    evaluated.
               F must be declared as EXTERNAL in the (sub)program from
               which C05ADF is called. Parameters denoted as Input
               must not be changed by this procedure.

           6:  X -- DOUBLE PRECISION                                 Output
               On exit: the approximation to the zero.

           7:  IFAIL -- INTEGER                                Input/Output
               Before entry, IFAIL must be assigned a value. For users not
               familiar with this parameter (described in the Essential
               Introduction) the recommended value is 0.

               Unless the routine detects an error (see Section 6), IFAIL
               contains 0 on exit.

          6. Error Indicators and Warnings

          Errors detected by the routine:

          IFAIL= 1
               On entry EPS <= 0.0,

               or       A = B,

               or       F(A)*F(B)>0.0.

          IFAIL= 2
               Too much accuracy has been requested in the computation,
               that is, EPS is too small for the computer being used. The
               final value of X is an accurate approximation to the zero.

          IFAIL= 3
               A change in sign of f(x) has been determined as occurring
               near the point defined by the final value of X. However,
               there is some evidence that this sign-change corresponds to
               a pole of f(x).

          IFAIL= 4
               Indicates that a serious error has occurred in C05AZF(*).
               Check all routine calls. Seek expert help.

          7. Accuracy

          This depends on the value of EPS and ETA. If full machine
          accuracy is required, they may be set very small, resulting in an
          error exit with IFAIL = 2, although this may involve more
          iterations than a lesser accuracy. The user is recommended to set
          ETA = 0.0 and to use EPS to control the accuracy, unless he has
          considerable knowledge of the size of f(x) for values of x near
          the zero.

          8. Further Comments

          The time taken by the routine depends primarily on the time spent
          evaluating F (see Section 5).

          If it is important to determine an interval of length less than
          EPS containing the zero, or if the function F is expensive to
          evaluate and the number of calls to F is to be restricted, then
          use of C05AZF(*) is recommended. Use of C05AZF(*) is also
          recommended when the structure of the problem to be solved does
          not permit a simple function F to be written: the reverse
          communication facilities of C05AZF(*) are more flexible than the
          direct communication of F required by C05ADF.

          9. Example

                                                            -x
          The example program below calculates the zero of e  -x within the
          interval [0,1] to approximately 5 decimal places.

          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.

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

     C05NBF(3NAG)      Foundation Library (12/10/92)      C05NBF(3NAG)

          C05 -- Roots of One or More Transcendental Equations       C05NBF
                  C05NBF -- 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

          C05NBF is an easy-to-use routine to find a solution of a system
          of nonlinear equations by a modification of the Powell hybrid
          method.

          2. Specification

                 SUBROUTINE C05NBF (FCN, N, X, FVEC, XTOL, WA, LWA, IFAIL)
                 INTEGER          N, LWA, IFAIL
                 DOUBLE PRECISION X(N), FVEC(N), XTOL, WA(LWA)
                 EXTERNAL         FCN

          3. Description

          The system of equations is defined as:

                        f (x ,x ,...,x )=0, for i=1,2,...,n.
                         i  1  2      n

          C05NBF is based upon the MINPACK routine HYBRD1 (More et al [1]).
          It chooses the correction at each step as a convex combination of
          the Newton and scaled gradient directions. Under reasonable
          conditions this guarantees global convergence for starting points
          far from the solution and a fast rate of convergence. The
          Jacobian is updated by the rank-1 method of Broyden. At the
          starting point the Jacobian is approximated by forward
          differences, but these are not used again until the rank-1 method
          fails to produce satisfactory progress. For more details see
          Powell [2].

          4. References

          [1]   More J J, Garbow B S and Hillstrom K E User Guide for
                MINPACK-1. Technical Report ANL-80-74. Argonne National
                Laboratory.

          [2]   Powell M J D (1970) A Hybrid Method for Nonlinear Algebraic
                Equations. Numerical Methods for Nonlinear Algebraic
                Equations. (ed P Rabinowitz) Gordon and Breach.

          5. Parameters

           1:  FCN -- SUBROUTINE, supplied by the user.
                                                    External Procedure
               FCN must return the values of the functions f  at a point x.
                                                            i

               Its specification is:

                      SUBROUTINE FCN (N, X, FVEC, IFLAG)
                      INTEGER          N, IFLAG
                      DOUBLE PRECISION X(N), FVEC(N)

                1:  N -- INTEGER                                      Input
                    On entry: the number of equations, n.

                2:  X(N) -- DOUBLE PRECISION array                    Input
                    On entry: the components of the point x at which the
                    functions must be evaluated.

                3:  FVEC(N) -- DOUBLE PRECISION array                Output
                    On exit: the function values f (x) (unless IFLAG is
                                                  i
                    set to a negative value by FCN).

                4:  IFLAG -- INTEGER                           Input/Output
                    On entry: IFLAG > 0. On exit: in general, IFLAG should
                    not be reset by FCN. If, however, the user wishes to
                    terminate execution (perhaps because some illegal point
                    X has been reached), then IFLAG should be set to a
                    negative integer. This value will be returned through
                    IFAIL.
               FCN must be declared as EXTERNAL in the (sub)program
               from which C05NBF is called. Parameters denoted as
               Input must not be changed by this procedure.

           2:  N -- INTEGER                                           Input
               On entry: the number of equations, n. Constraint: N > 0.

           3:  X(N) -- DOUBLE PRECISION array                  Input/Output
               On entry: an initial guess at the solution vector. On
               exit: the final estimate of the solution vector.

           4:  FVEC(N) -- DOUBLE PRECISION array                     Output
               On exit: the function values at the final point, X.

           5:  XTOL -- DOUBLE PRECISION                               Input
               On entry: the accuracy in X to which the solution is
               required. Suggested value: the square root of the machine
               precision. Constraint: XTOL >= 0.0.

           6:  WA(LWA) -- DOUBLE PRECISION array                  Workspace

           7:  LWA -- INTEGER                                         Input
               On entry: the dimension of the array WA. Constraint:
               LWA>=N*(3*N+13)/2.

           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< 0
               The user has set IFLAG negative in FCN. The value of IFAIL
               will be the same as the user's setting of IFLAG.

          IFAIL= 1
               On entry N <= 0,

               or       XTOL < 0.0,

               or       LWA<N*(3*N+13)/2.

          IFAIL= 2
               There have been at least 200*(N+1) evaluations of FCN.
               Consider restarting the calculation from the final point
               held in X.

          IFAIL= 3
               No further improvement in the approximate solution X is
               possible; XTOL is too small.

          IFAIL= 4
               The iteration is not making good progress. This failure exit
               may indicate that the system does not have a zero, or that
               the solution is very close to the origin (see Section 7).
               Otherwise, rerunning C05NBF from a different starting point
               may avoid the region of difficulty.

          7. Accuracy

             ^
          If x is the true solution, C05NBF tries to ensure that

                                   ^             ^
                              ||x-x||<=XTOL*||x||.

                                                     -k
          If this condition is satisfied with XTOL=10  , then the larger
          components of x have k significant decimal digits. There is a
          danger that the smaller components of x may have large relative
          errors, but the fast rate of convergence of C05NBF usually avoids
          this possibility.

          If XTOL is less than machine precision, and the above test is
          satisfied with the machine precision in place of XTOL, then the
          routine exits with IFAIL = 3.

          Note: this convergence test is based purely on relative error,
          and may not indicate convergence if the solution is very close to
          the origin.

          The test assumes that the functions are reasonably well behaved.
          If this condition is not satisfied, then C05NBF may incorrectly
          indicate convergence. The validity of the answer can be checked,
          for example, by rerunning C05NBF with a tighter tolerance.

          8. Further Comments

          The time required by C05NBF to solve a given problem depends on n
          , the behaviour of the functions, the accuracy requested and the
          starting point. The number of arithmetic operations executed by
                                                            2
          C05NBF to process each call of FCN is about 11.5*n . Unless FCN
          can be evaluated quickly, the timing of C05NBF will be strongly
          influenced by the time spent in FCN.

          Ideally the problem should be scaled so that at the solution the
          function values are of comparable magnitude.

          9. Example

          To determine the values x ,..., x  which satisfy the tridiagonal
                                   1       9
          equations:

                                  (3-2x )x -2x =-1
                                       1  1   2

                       -x -1+(3-2x )x -2x   =-1,  i=2,3,...,8
                         i        i  i   i+1

                                  -x +(3-2x )x =-1.
                                    8      9  9

          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.

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

     C05PBF(3NAG)      Foundation Library (12/10/92)      C05PBF(3NAG)

          C05 -- Roots of One or More Transcendental Equations       C05PBF
                  C05PBF -- 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

          C05PBF is an easy-to-use routine to find a solution of a system
          of nonlinear equations by a modification of the Powell hybrid
          method. The user must provide the Jacobian.

          2. Specification

                 SUBROUTINE C05PBF (FCN, N, X, FVEC, FJAC, LDFJAC, XTOL,
                1                   WA, LWA, IFAIL)
                 INTEGER          N, LDFJAC, LWA, IFAIL
                 DOUBLE PRECISION X(N), FVEC(N), FJAC(LDFJAC,N), XTOL, WA
                1                 (LWA)
                 EXTERNAL         FCN

          3. Description

          The system of equations is defined as:

                          f (x ,x ,...,x )=0, i=1,2,...,n.
                           i  1  2      n

          C05PBF is based upon the MINPACK routine HYBRJ1 (More et al [1]).
          It chooses the correction at each step as a convex combination of
          the Newton and scaled gradient directions. Under reasonable
          conditions this guarantees global convergence for starting points
          far from the solution and a fast rate of convergence. The
          Jacobian is updated by the rank-1 method of Broyden. At the
          starting point the Jacobian is calculated, but it is not
          recalculated until the rank-1 method fails to produce
          satisfactory progress. For more details see Powell [2].

          4. References

          [1]   More J J, Garbow B S and Hillstrom K E User Guide for
                MINPACK-1. Technical Report ANL-80-74. Argonne National
                Laboratory.

          [2]   Powell M J D (1970) A Hybrid Method for Nonlinear Algebraic
                Equations. Numerical Methods for Nonlinear Algebraic
                Equations. (ed P Rabinowitz) Gordon and Breach.

          5. Parameters

           1:  FCN -- SUBROUTINE, supplied by the user.
                                                    External Procedure
               Depending upon the value of IFLAG, FCN must either return
               the values of the functions f  at a point x or return the
                                            i
               Jacobian at x.

               Its specification is:

                      SUBROUTINE FCN (N, X, FVEC, FJAC, LDFJAC, IFLAG)
                      INTEGER          N, LDFJAC, IFLAG
                      DOUBLE PRECISION X(N), FVEC(N), FJAC(LDFJAC,N)

                1:  N -- INTEGER                                      Input
                    On entry: the number of equations, n.

                2:  X(N) -- DOUBLE PRECISION array                    Input
                    On entry: the components of the point x at which the
                    functions or the Jacobian must be evaluated.

                3:  FVEC(N) -- DOUBLE PRECISION array                Output
                    On exit: if IFLAG = 1 on entry, FVEC must contain the
                    function values f (x) (unless IFLAG is set to a
                                     i
                    negative value by FCN). If IFLAG = 2 on entry, FVEC
                    must not be changed.

                4:  FJAC(LDFJAC,N) -- DOUBLE PRECISION array         Output
                    On exit: if IFLAG = 2 on entry, FJAC(i,j) must contain
                                  ddf
                                     i
                    the value of  ---- at the point x, for i,j=1,2,...,n
                                  ddx
                                     j
                    (unless IFLAG is set to a negative value by FCN).

                    If IFLAG = 1 on entry, FJAC must not be changed.

                5:  LDFJAC -- INTEGER                                 Input
                    On entry: the first dimension of FJAC.

                6:  IFLAG -- INTEGER                           Input/Output
                    On entry: IFLAG = 1 or 2:
                         if IFLAG = 1, FVEC is to be updated;

                         if IFLAG = 2, FJAC is to be updated.
                    On exit: in general, IFLAG should not be reset by FCN.
                    If, however, the user wishes to terminate execution
                    (perhaps because some illegal point x has been reached)
                    then IFLAG should be set to a negative integer. This
                    value will be returned through IFAIL.
               FCN must be declared as EXTERNAL in the (sub)program
               from which C05PBF is called. Parameters denoted as
               Input must not be changed by this procedure.

           2:  N -- INTEGER                                           Input
               On entry: the number of equations, n. Constraint: N > 0.

           3:  X(N) -- DOUBLE PRECISION array                  Input/Output
               On entry: an initial guess at the solution vector. On
               exit: the final estimate of the solution vector.

           4:  FVEC(N) -- DOUBLE PRECISION array                     Output
               On exit: the function values at the final point, X.

           5:  FJAC(LDFJAC,N) -- DOUBLE PRECISION array              Output
               On exit: the orthogonal matrix Q produced by the QR
               factorization of the final approximate Jacobian.

           6:  LDFJAC -- INTEGER                                      Input
               On entry:
               the first dimension of the array FJAC as declared in the
               (sub)program from which C05PBF is called.
               Constraint: LDFJAC >= N.

           7:  XTOL -- DOUBLE PRECISION                               Input
               On entry: the accuracy in X to which the solution is
               required. Suggested value: the square root of the machine
               precision. Constraint: XTOL >= 0.0.

           8:  WA(LWA) -- DOUBLE PRECISION array                  Workspace

           9:  LWA -- INTEGER                                         Input
               On entry: the dimension of the array WA. Constraint:
               LWA>=N*(N+13)/2.

          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< 0
               A negative value of IFAIL indicates an exit from C05PBF
               because the user has set IFLAG negative in FCN. The value of
               IFAIL will be the same as the user's setting of IFLAG.

          IFAIL= 1
               On entry N <= 0,

               or       LDFJAC < N,

               or       XTOL < 0.0,

               or       LWA<N*(N+13)/2.

          IFAIL= 2
               There have been 100*(N+1) evaluations of the functions.
               Consider restarting the calculation from the final point
               held in X.

          IFAIL= 3
               No further improvement in the approximate solution X is
               possible; XTOL is too small.

          IFAIL= 4
               The iteration is not making good progress. This failure exit
               may indicate that the system does not have a zero or that
               the solution is very close to the origin (see Section 7).
               Otherwise, rerunning C05PBF from a different starting point
               may avoid the region of difficulty.

          7. Accuracy

             ^
          If x is the true solution, C05PBF tries to ensure that

                                  ^              ^
                             ||x-x|| <=XTOL*||x|| .
                                    2            2

                                                     -k
          If this condition is satisfied with XTOL=10  , then the larger
          components of x have k significant decimal digits. There is a
          danger that the smaller components of x may have large relative
          errors, but the fast rate of convergence of C05PBF usually avoids
          the possibility.

          If XTOL is less than machine precision and the above test is
          satisfied with the machine precision in place of XTOL, then the
          routine exits with IFAIL = 3.

          Note: this convergence test is based purely on relative error,
          and may not indicate convergence if the solution is very close to
          the origin.

          The test assumes that the functions and Jacobian are coded
          consistently and that the functions are reasonably well behaved.
          If these conditions are not satisfied then C05PBF may incorrectly
          indicate convergence. The coding of the Jacobian can be checked
          using C05ZAF. If the Jacobian is coded correctly, then the
          validity of the answer can be checked by rerunning C05PBF with a
          tighter tolerance.

          8. Further Comments

          The time required by C05PBF to solve a given problem depends on n
          , the behaviour of the functions, the accuracy requested and the
          starting point. The number of arithmetic operations executed by
                                2
          C05PBF is about 11.5*n  to process each evaluation of the
                                   3
          functions and about 1.3*n  to process each evaluation of the
          Jacobian. Unless FCN can be evaluated quickly, the timing of
          C05PBF will be strongly influenced by the time spent in FCN.

          Ideally the problem should be scaled so that, at the solution,
          the function values are of comparable magnitude.

          9. Example

          To determine the values x ,..., x  which satisfy the tridiagonal
                                   1       9
          equations:

                                  (3-2x )x -2x =-1
                                       1  1   2

                        -x   +(3-2x )x -2x   =-1,  i=2,3,...,8.
                          i-1      i  i   i+1

                                  -x +(3-2x )x =-1.
                                    8      9  9

          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.

