# dcov.f

          SUBROUTINE DCOV (FCN, IOPT, M, N, X, FVEC, R, LDR, INFO, WA1, WA2,
         +   WA3, WA4)
    C***BEGIN PROLOGUE  DCOV
    C***PURPOSE  Calculate the covariance matrix for a nonlinear data
    C            fitting problem.  It is intended to be used after a
    C            successful return from either DNLS1 or DNLS1E.
    C***LIBRARY   SLATEC
    C***CATEGORY  K1B1
    C***TYPE      DOUBLE PRECISION (SCOV-S, DCOV-D)
    C***KEYWORDS  COVARIANCE MATRIX, NONLINEAR DATA FITTING,
    C             NONLINEAR LEAST SQUARES
    C***AUTHOR  Hiebert, K. L., (SNLA)
    C***DESCRIPTION
    C
    C  1. Purpose.
    C
    C     DCOV calculates the covariance matrix for a nonlinear data
    C     fitting problem.  It is intended to be used after a
    C     successful return from either DNLS1 or DNLS1E. DCOV
    C     and DNLS1 (and DNLS1E) have compatible parameters.  The
    C     required external subroutine, FCN, is the same
    C     for all three codes, DCOV, DNLS1, and DNLS1E.
    C
    C  2. Subroutine and Type Statements.
    C
    C     SUBROUTINE DCOV(FCN,IOPT,M,N,X,FVEC,R,LDR,INFO,
    C                     WA1,WA2,WA3,WA4)
    C     INTEGER IOPT,M,N,LDR,INFO
    C     DOUBLE PRECISION X(N),FVEC(M),R(LDR,N),WA1(N),WA2(N),WA3(N),WA4(M)
    C     EXTERNAL FCN
    C
    C  3. Parameters. All TYPE REAL parameters are DOUBLE PRECISION
    C
    C      FCN is the name of the user-supplied subroutine which calculates
    C         the functions.  If the user wants to supply the Jacobian
    C         (IOPT=2 or 3), then FCN must be written to calculate the
    C         Jacobian, as well as the functions.  See the explanation
    C         of the IOPT argument below.
    C         If the user wants the iterates printed in DNLS1 or DNLS1E,
    C         then FCN must do the printing.  See the explanation of NPRINT
    C         in DNLS1 or DNLS1E.  FCN must be declared in an EXTERNAL
    C         statement in the calling program and should be written as
    C         follows.
    C
    C         SUBROUTINE FCN(IFLAG,M,N,X,FVEC,FJAC,LDFJAC)
    C         INTEGER IFLAG,LDFJAC,M,N
    C         DOUBLE PRECISION X(N),FVEC(M)
    C         ----------
    C         FJAC and LDFJAC may be ignored       , if IOPT=1.
    C         DOUBLE PRECISION FJAC(LDFJAC,N)      , if IOPT=2.
    C         DOUBLE PRECISION FJAC(N)             , if IOPT=3.
    C         ----------
    C           If IFLAG=0, the values in X and FVEC are available
    C           for printing in DNLS1 or DNLS1E.
    C           IFLAG will never be zero when FCN is called by DCOV.
    C           The values of X and FVEC must not be changed.
    C         RETURN
    C         ----------
    C           If IFLAG=1, calculate the functions at X and return
    C           this vector in FVEC.
    C         RETURN
    C         ----------
    C           If IFLAG=2, calculate the full Jacobian at X and return
    C           this matrix in FJAC.  Note that IFLAG will never be 2 unless
    C           IOPT=2.  FVEC contains the function values at X and must
    C           not be altered.  FJAC(I,J) must be set to the derivative
    C           of FVEC(I) with respect to X(J).
    C         RETURN
    C         ----------
    C           If IFLAG=3, calculate the LDFJAC-th row of the Jacobian
    C           and return this vector in FJAC.  Note that IFLAG will
    C           never be 3 unless IOPT=3.  FJAC(J) must be set to
    C           the derivative of FVEC(LDFJAC) with respect to X(J).
    C         RETURN
    C         ----------
    C         END
    C
    C
    C         The value of IFLAG should not be changed by FCN unless the
    C         user wants to terminate execution of DCOV.  In this case, set
    C         IFLAG to a negative integer.
    C
    C
    C       IOPT is an input variable which specifies how the Jacobian will
    C         be calculated.  If IOPT=2 or 3, then the user must supply the
    C         Jacobian, as well as the function values, through the
    C         subroutine FCN.  If IOPT=2, the user supplies the full
    C         Jacobian with one call to FCN.  If IOPT=3, the user supplies
    C         one row of the Jacobian with each call.  (In this manner,
    C         storage can be saved because the full Jacobian is not stored.)
    C         If IOPT=1, the code will approximate the Jacobian by forward
    C         differencing.
    C
    C       M is a positive integer input variable set to the number of
    C         functions.
    C
    C       N is a positive integer input variable set to the number of
    C         variables.  N must not exceed M.
    C
    C       X is an array of length N.  On input X must contain the value
    C         at which the covariance matrix is to be evaluated.  This is
    C         usually the value for X returned from a successful run of
    C         DNLS1 (or DNLS1E).  The value of X will not be changed.
    C
    C    FVEC is an output array of length M which contains the functions
    C         evaluated at X.
    C
    C       R is an output array.  For IOPT=1 and 2, R is an M by N array.
    C         For IOPT=3, R is an N by N array.  On output, if INFO=1,
    C         the upper N by N submatrix of R contains the covariance
    C         matrix evaluated at X.
    C
    C     LDR is a positive integer input variable which specifies
    C         the leading dimension of the array R.  For IOPT=1 and 2,
    C         LDR must not be less than M.  For IOPT=3, LDR must not
    C         be less than N.
    C
    C    INFO is an integer output variable.  If the user has terminated
    C         execution, INFO is set to the (negative) value of IFLAG.  See
    C         description of FCN. Otherwise, INFO is set as follows.
    C
    C         INFO = 0 Improper input parameters (M.LE.0 or N.LE.0).
    C
    C         INFO = 1 Successful return.  The covariance matrix has been
    C                  calculated and stored in the upper N by N
    C                  submatrix of R.
    C
    C         INFO = 2 The Jacobian matrix is singular for the input value
    C                  of X.  The covariance matrix cannot be calculated.
    C                  The upper N by N submatrix of R contains the QR
    C                  factorization of the Jacobian (probably not of
    C                  interest to the user).
    C
    C WA1,WA2 are work arrays of length N.
    C and WA3
    C
    C     WA4 is a work array of length M.
    C
    C***REFERENCES  (NONE)
    C***ROUTINES CALLED  DENORM, DFDJC3, DQRFAC, DWUPDT, XERMSG
    C***REVISION HISTORY  (YYMMDD)
    C   810522  DATE WRITTEN
    C   890831  Modified array declarations.  (WRB)
    C   891006  Cosmetic changes to prologue.  (WRB)
    C   891006  REVISION DATE from Version 3.2
    C   891214  Prologue converted to Version 4.0 format.  (BAB)
    C   900315  CALLs to XERROR changed to CALLs to XERMSG.  (THJ)
    C   900510  Fixed an error message.  (RWC)
    C***END PROLOGUE  DCOV