--- name: "hybrd_" section: "3" platform: "linux" package: "minpack-dev" version: "19961126+dfsg1-5+b2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/hybrd_" --- # hybrd\_(3) find a zero of a system of nonlinear function ## NAME hybrd\_, hybrd1\_ - find a zero of a system of nonlinear function ## SYNOPSIS **#include \** **void hybrd1\_ (** **void (\****fcn***)(** **int \****n***,** **double \****x***,**\ **double \****fvec***,** **int \****iflag***),** **int \****n***,** **double \****x***,** **double \****fvec***,**\ **double \****tol***,** **int \****info***,** **double \****wa***,**\ **int \****lwa***);** **void hybrd\_** **( void (\****fcn***)(** **int \*** *n***,** **double \****x***,**\ **double \****fvec***,** **int \****iflag***),** **int \****n***,** **double \****x***,** **double \****fvec***,**\ **double \****xtol***,** **int \****maxfev***,** **int \****ml***,** **int \****mu***,**\ **double \****epsfcn***,** **double \****diag***,** **int \****mode***,** **double \****factor***,** **int \****nprint***,** **int \****info***,**\ **int \****nfev***,** **double \****fjac***,** **int \****ldfjac***,**\ **double \****r***,** **int \****lr***,** **double \****qtf***,**\ **double \****wa1***,** **double \****wa2***,** **double \****wa3***,** **double \****wa4***);** ## DESCRIPTION The purpose of **hybrd\_** is to find a zero of a system of *n* nonlinear functions in *n* variables by a modification of the Powell hybrid method. The user must provide a subroutine which calculates the functions. The Jacobian is then calculated by a forward-difference approximation. **hybrd1\_** serves the same function but has a simplified calling sequence.\ ### Language notes **hybrd\_** and **hybrd1\_** are written in FORTRAN. If calling from C, keep these points in mind: - Name mangling. With **gfortran**, all the function names end in an underscore. - Compile with **gfortran**. Even if your program is all C code, you should link with **gfortran** so it will pull in the FORTRAN libraries automatically. It's easiest just to use **gfortran** to do all the compiling. (It handles C just fine.) - Call by reference. All function parameters must be pointers. - Column-major arrays. Suppose a function returns an array with 5 rows and 3 columns in an array *z* and in the call you have declared a leading dimension of 7. The FORTRAN and equivalent C references are: ``` z(1,1) z[0] z(2,1) z[1] z(5,1) z[4] z(1,2) z[7] z(1,3) z[14] z(i,j) z[(i-1) + (j-1)*7] ``` ### Parameters for both functions *fcn* is the name of the user-supplied subroutine which calculates the functions. In FORTRAN, *fcn* must be declared in an external statement in the user calling program, and should be written as follows: ``` subroutine fcn(n,x,fvec,iflag) integer n,iflag double precision x(n),fvec(n) ---------- calculate the functions at x and return this vector in fvec. --------- return end ``` In C, *fcn* should be written as follows: ``` void fcn(int *n, double *x, double *fvec, int *iflag) { /* calculate the functions at x and return this vector in fvec. */ } ``` The value of *iflag* should not be changed by *fcn* unless the user wants to terminate execution of **hybrd\_**. In this case set *iflag* to a negative integer. *n* is a positive integer input variable set to the number of functions and variables. *x* is an array of length *n*. On input *x* must contain an initial estimate of the solution vector. On output *x* contains the final estimate of the solution vector. *fvec* is an output array of length *n* which contains the functions evaluated at the output *x*.\ ### Parameters for hybrd1\_ *tol* is a nonnegative input variable. Termination occurs when the algorithm estimates that the relative error between *x* and the solution is at most *tol*. *info* is an integer output variable. If the user has terminated execution, *info* is set to the (negative) value of *iflag*. See description of *fcn*. Otherwise, *info* is set as follows. *info* = 0 improper input parameters. *info* = 1 algorithm estimates that the relative error\ between *x* and the solution is at most *tol*. *info* = 2 number of calls to fcn has reached or exceeded\ 200\*(*n*+1). *info* = 3 *tol* is too small. No further improvement in\ the approximate solution *x* is possible. *info* = 4 iteration is not making good progress. *wa* is a work array of length *lwa*. *lwa* is a positive integer input variable not less than (*n*\*(3\**n*+13))/2.\ ### Parameters for hybrd\_ *xtol* is a nonnegative input variable. Termination occurs when the relative error between two consecutive iterates is at most *xtol*. *maxfev* is a positive integer input variable. Termination occurs when the number of calls to *fcn* is at least *maxfev* by the end of an iteration. *ml* is a nonnegative integer input variable which specifies the number of subdiagonals within the band of the jacobian matrix. If the Jacobian is not banded, set *ml* to at least *n* - 1. *mu* is a nonnegative integer input variable which specifies the number of superdiagonals within the band of the jacobian matrix. If the jacobian is not banded, set mu to at least *n* - 1. *epsfcn* is an input variable used in determining a suitable step length for the forward-difference approximation. This approximation assumes that the relative errors in the functions are of the order of *epsfcn*. If *epsfcn* is less than the machine precision, it is assumed that the relative errors in the functions are of the order of the machine precision. *diag* is an array of length *n*. If *mode* = 1 (see below), *diag* is internally set. If *mode* = 2, *diag* must contain positive entries that serve as multiplicative scale factors for the variables. *mode* is an integer input variable. If *mode* = 1, the variables will be scaled internally. If *mode* = 2, the scaling is specified by the input *diag*. Other values of mode are equivalent to *mode* = 1. *factor* is a positive input variable used in determining the initial step bound. This bound is set to the product of *factor* and the euclidean norm of diag\*x if nonzero, or else to *factor* itself. In most cases factor should lie in the interval (.1,100.). 100. Is a generally recommended value. *nprint* is an integer input variable that enables controlled printing of iterates if it is positive. In this case, *fcn* is called with *iflag* = 0 at the beginning of the first iteration and every nprint iterations thereafter and immediately prior to return, with *x* and *fvec* available for printing. If *nprint* is not positive, no special calls of *fcn* with *iflag* = 0 are made. *info* is an integer output variable. If the user has terminated execution, *info* is set to the (negative) value of *iflag*. See description of *fcn*. Otherwise, *info* is set as follows. *info* = 0 improper input parameters. *info* = 1 relative error between two consecutive iterates\ is at most *xtol*. *info* = 2 number of calls to *fcn* has reached or exceeded\ *maxfev*. *info* = 3 *xtol* is too small. No further improvement in\ the approximate solution *x* is possible. *info* = 4 iteration is not making good progress, as\ measured by the improvement from the last\ five jacobian evaluations. *info* = 5 iteration is not making good progress, as\ measured by the improvement from the last\ ten iterations. *nfev* is an integer output variable set to the number of calls to *fcn*. *fjac* is an output *n* by *n* array which contains the orthogonal matrix *q* produced by the *qr* factorization of the final approximate jacobian. *ldfjac* is a positive integer input variable not less than *n* which specifies the leading dimension of the array *fjac*. *r* is an output array of length *lr* which contains the upper triangular matrix produced by the *qr* factorization of the final approximate Jacobian, stored rowwise. *lr* is a positive integer input variable not less than (*n*\*(*n*+1))/2. *qtf* is an output array of length *n* which contains the vector (q transpose)\**fvec*. *wa1*, *wa2*, *wa3*, and *wa4* are work arrays of length *n*. ## SEE ALSO **hybrj**(3), **hybrj1**(3).\ ## AUTHORS Burton S. Garbow, Kenneth E. Hillstrom, Jorge J. More.\ This manual page was written by Jim Van Zandt \, for the Debian GNU/Linux system (but may be used by others).