------------------------------------------------------------------------ IMSL Name: NEQBJ/DNEQBJ (Single/Double precision version) Revised: June 10, 1991 Purpose: Solve a system of nonlinear equations using factored secant update with a user-supplied Jacobian. Usage: CALL NEQBJ (FCN, JAC, N, XGUESS, XSCALE, FSCALE, IPARAM, RPARAM, X, FVEC) Arguments: FCN - User-supplied SUBROUTINE to evaluate the system of equations to be solved. The usage is CALL FCN (N, X, F), where N - Length of X and F. (Input) X - The point at which the functions are evaluated. (Input) X should not be changed by FCN. F - The computed function values at the point X. (Output) FCN must be declared EXTERNAL in the calling program. JAC - User-supplied SUBROUTINE to evaluate the Jacobian at a point X. The usage is CALL JAC (N, X, FJAC, LDFJAC), where N - Length of X. (Input) X - Vector of length N at which point the Jacobian is evaluated. (Input) X should not be changed by JAC. FJAC - The computed N by N Jacobian at the point X. (Output) LDFJAC - Leading dimension of FJAC. (Input) JAC must be declared EXTERNAL in the calling program. N - Dimension of the problem. (Input) XGUESS - Vector of length N containing initial guess of the root. (Input) XSCALE - Vector of length N containing the diagonal scaling matrix for the variables. (Input) XSCALE is used mainly in scaling the distance between two points. In the absence of other information, set all entries to 1.0. If internal scaling is desired for XSCALE, set IPARAM (6) to 1. FSCALE - Vector of length N containing the diagonal scaling matrix for the functions. (Input) FSCALE is used mainly in scaling the function residuals. In the absence of other information, set all entries to 1.0. IPARAM - Parameter vector of length 6. (Input/Output) Set IPARAM (1) to zero for default values of IPARAM and RPARAM. See Remark 4. RPARAM - Parameter vector of length 5. (Input/Output) See Remark 4. X - Vector of length N containing the approximate solution. (Output) FVEC - Vector of length N containing the values of the functions at the approximate solution. (Output) Remarks: 1. Automatic workspace usage is NEQBJ 2*N**2+11*N units, or DNEQBJ 4*N**2+22*N units. Workspace may be explicitly provided, if desired, by use of N2QBJ/DN2QBJ. The reference is CALL N2QBJ (FCN, JAC, N, XGUESS, XSCALE, FSCALE, IPARAM, RPARAM, X, FVEC, WK, LWK) The additional arguments are as follows: WK - A work vector of length LWK. On output WK contains the following information: The third N locations contain the last step taken. The fourth N locations contain the last Newton step. The final N**2 locations contain an estimate of the Jacobian at the solution. LWK - Length of WK, which must be at least 2*N**2+11*N. (Input) 2. Informational errors Type Code 3 1 The last global step failed to decrease the 2-norm of F(X) sufficiently; either the current point is close to a root of F(X) and no more accuracy is possible, or the secant approximation to the Jacobian is inaccurate, or the step tolerance is too large. 3 3 The scaled distance between the last two steps is less than the step tolerance; the current point is probably an approximate root of F(X) (unless STEPTL is too large). 3 4 Maximum number of iterations exceeded. 3 5 Maximum number of function evaluations exceeded. 3 7 Five consecutive steps of length STEPMX have been taken; either the 2-norm of F(X) asymptotes from above to a finite value in some direction or the maximum allowable stepsize STEPMX is too small. 3. The stopping criterion for NEQBJ occurs when the scaled norm of the functions is less than the scaled function tolerance (RPARAM(1)). 4. If the default parameters are desired for NEQBJ, then set IPARAM(1) to zero and call routine NEQBJ. Otherwise, if any nondefault parameters are desired for IPARAM or RPARAM, then the following steps should be taken before calling NEQBJ. CALL N4QBJ (IPARAM, RPARAM). Set nondefault values for desired IPARAM, RPARAM elements. Note that the call to N4QBJ will set IPARAM and RPARAM to their default values, so only nondefault values need to be set above. The following is a list of the parameters and the default values: IPARAM - Integer vector of length 6. IPARAM(1) = Initialization flag. IPARAM(2) = Number of good digits in the function. Default: Machine dependent. IPARAM(3) = Maximum number of iterations. Default: 100. IPARAM(4) = Maximum number of function evaluations. Default: 400. IPARAM(5) = Maximum number of Jacobian evaluations. Default: not used in NEQBJ. IPARAM(6) = Internal variable scaling flag. If IPARAM(6) = 1, then the values of XSCALE are set internally. Default: 0. RPARAM - Real vector of length 5. RPARAM(1) = Scaled function tolerance. Default: SQRT(eps), where eps is the machine precision. RPARAM(2) = Scaled step tolerance. (STEPTL) Default: eps**(2/3), where eps is the machine precision. RPARAM(3) = False convergence tolerance. Default: not used in NEQBJ. RPARAM(4) = Maximum allowable step size. (STEPMX) Default: 1000*MAX(TOL1,TOL2), where TOL1 = SQRT(sum of (XSCALE(I)*XGUESS(I))**2) for I=1,..,N, TOL2 = 2-norm of XSCALE. RPARAM(5) = Size of initial trust region. Default: based on the initial scaled Cauchy step. If double precision is desired, then DN4QBJ is called and RPARAM is declared double precision. 5. Users wishing to override the default print/stop attributes associated with error messages issued by this routine are referred to ERROR HANDLING in the Introduction. Keywords: Factored Broyden update; double dogleg step; trust region GAMS: F2 Chapter: MATH/LIBRARY Nonlinear Equations Page No.: MATH/LIBRARY User's Manual page 958 ------------------------------------------------------------------------ IMSL Name: NEQBJ/DNEQBJ (Single/Double precision version) Revised: June 10, 1991 Purpose: Solve a system of nonlinear equations using factored secant update with a user-supplied Jacobian. Usage: CALL NEQBJ (FCN, JAC, N, XGUESS, XSCALE, FSCALE, IPARAM, RPARAM, X, FVEC) Arguments: FCN - User-supplied SUBROUTINE to evaluate the system of equations to be solved. The usage is CALL FCN (N, X, F), where N - Length of X and F. (Input) X - The point at which the functions are evaluated. (Input) X should not be changed by FCN. F - The computed function values at the point X. (Output) FCN must be declared EXTERNAL in the calling program. JAC - User-supplied SUBROUTINE to evaluate the Jacobian at a point X. The usage is CALL JAC (N, X, FJAC, LDFJAC), where N - Length of X. (Input) X - Vector of length N at which point the Jacobian is evaluated. (Input) X should not be changed by JAC. FJAC - The computed N by N Jacobian at the point X. (Output) LDFJAC - Leading dimension of FJAC. (Input) JAC must be declared EXTERNAL in the calling program. N - Dimension of the problem. (Input) XGUESS - Vector of length N containing initial guess of the root. (Input) XSCALE - Vector of length N containing the diagonal scaling matrix for the variables. (Input) XSCALE is used mainly in scaling the distance between two points. In the absence of other information, set all entries to 1.0. If internal scaling is desired for XSCALE, set IPARAM (6) to 1. FSCALE - Vector of length N containing the diagonal scaling matrix for the functions. (Input) FSCALE is used mainly in scaling the function residuals. In the absence of other information, set all entries to 1.0. IPARAM - Parameter vector of length 6. (Input/Output) Set IPARAM (1) to zero for default values of IPARAM and RPARAM. See Remark 4. RPARAM - Parameter vector of length 5. (Input/Output) See Remark 4. X - Vector of length N containing the approximate solution. (Output) FVEC - Vector of length N containing the values of the functions at the approximate solution. (Output) Remarks: 1. Automatic workspace usage is NEQBJ 2*N**2+11*N units, or DNEQBJ 4*N**2+22*N units. Workspace may be explicitly provided, if desired, by use of N2QBJ/DN2QBJ. The reference is CALL N2QBJ (FCN, JAC, N, XGUESS, XSCALE, FSCALE, IPARAM, RPARAM, X, FVEC, WK, LWK) The additional arguments are as follows: WK - A work vector of length LWK. On output WK contains the following information: The third N locations contain the last step taken. The fourth N locations contain the last Newton step. The final N**2 locations contain an estimate of the Jacobian at the solution. LWK - Length of WK, which must be at least 2*N**2+11*N. (Input) 2. Informational errors Type Code 3 1 The last global step failed to decrease the 2-norm of F(X) sufficiently; either the current point is close to a root of F(X) and no more accuracy is possible, or the secant approximation to the Jacobian is inaccurate, or the step tolerance is too large. 3 3 The scaled distance between the last two steps is less than the step tolerance; the current point is probably an approximate root of F(X) (unless STEPTL is too large). 3 4 Maximum number of iterations exceeded. 3 5 Maximum number of function evaluations exceeded. 3 7 Five consecutive steps of length STEPMX have been taken; either the 2-norm of F(X) asymptotes from above to a finite value in some direction or the maximum allowable stepsize STEPMX is too small. 3. The stopping criterion for NEQBJ occurs when the scaled norm of the functions is less than the scaled function tolerance (RPARAM(1)). 4. If the default parameters are desired for NEQBJ, then set IPARAM(1) to zero and call routine NEQBJ. Otherwise, if any nondefault parameters are desired for IPARAM or RPARAM, then the following steps should be taken before calling NEQBJ. CALL N4QBJ (IPARAM, RPARAM). Set nondefault values for desired IPARAM, RPARAM elements. Note that the call to N4QBJ will set IPARAM and RPARAM to their default values, so only nondefault values need to be set above. The following is a list of the parameters and the default values: IPARAM - Integer vector of length 6. IPARAM(1) = Initialization flag. IPARAM(2) = Number of good digits in the function. Default: Machine dependent. IPARAM(3) = Maximum number of iterations. Default: 100. IPARAM(4) = Maximum number of function evaluations. Default: 400. IPARAM(5) = Maximum number of Jacobian evaluations. Default: not used in NEQBJ. IPARAM(6) = Internal variable scaling flag. If IPARAM(6) = 1, then the values of XSCALE are set internally. Default: 0. RPARAM - Real vector of length 5. RPARAM(1) = Scaled function tolerance. Default: SQRT(eps), where eps is the machine precision. RPARAM(2) = Scaled step tolerance. (STEPTL) Default: eps**(2/3), where eps is the machine precision. RPARAM(3) = False convergence tolerance. Default: not used in NEQBJ. RPARAM(4) = Maximum allowable step size. (STEPMX) Default: 1000*MAX(TOL1,TOL2), where TOL1 = SQRT(sum of (XSCALE(I)*XGUESS(I))**2) for I=1,..,N, TOL2 = 2-norm of XSCALE. RPARAM(5) = Size of initial trust region. Default: based on the initial scaled Cauchy step. If double precision is desired, then DN4QBJ is called and RPARAM is declared double precision. 5. Users wishing to override the default print/stop attributes associated with error messages issued by this routine are referred to ERROR HANDLING in the Introduction. Keywords: Factored Broyden update; double dogleg step; trust region GAMS: F2 Chapter: MATH/LIBRARY Nonlinear Equations Page No.: MATH/LIBRARY User's Manual page 958