%N dpolyzr %F $MIR/src/subs/poly.for
%D Roots of a real polynomial.
%: polynomials
%B
      subroutine dpolyzr(a,nn,roots,ifail)

      implicit none
      integer nn,ifail
      complex roots(nn)
      double precision a(0:nn)

  This procedure attempts to solve a real polynomial equation in degree nn
  using the technique suggested by Grant and Hitchins (1971) to limiting
  machine precision. On entry, the coefficients of the polynomial are
  held in the array a(0:nn), with a(0) holding the coefficient of the
  highest power. On normal entry, the parameter ifail has value zero,
  and will remain zero on successful exit, with the calculated estimates
  of the roots held in roots(1:nn), in approximately decreasing order
  of magnitude. The parameter "tol" givers the precision of the floating
  binary arithmetic used, normally 2**(-t), where "t" is the number
  of bits in the mantissa.

  Abnormal exits will be indicated by ifail having a value 1 or 2. The
  former implieds that either a(0) = 0 or nn < 1. For ifail=2, a
  possible saddle point has been detected. The degree of the reduced poly
  is stored in nn and its coefficients are held in a(0:nn), the roots
  obtained thus far are held in roots(nn+1) onwards. An immediate
  re-entry is possible with ind unchanged and with a new starting
  point for the search held in roots(1).

  The algorithm has been copies from:
    Grant J.A., Hitchins G.D., (1973 or 1974) "Two algorithms for the
    solution of polynomial equations to limiting machine precision"
    The Computer Journal, vol 18, n3, pp 258-264

  Apart from cosmetic changes, it is an FORTRAN equivalent of the
  ALGOL program they present.

  Input/Output:
    nn         The degree of the poly. 
    a          The poly coefficients.  Destroyed by the algorithm.
    ifail      Should be zero on normal entry and exit, but see above.

  Output:
    roots      The roots of the polynomial.
