Man page - hybrj1_(3)

Packages contains this manual

Manual

HYBRJ_

NAME
SYNOPSIS
DESCRIPTION
Language notes
Parameters for both functions
Parameters for hybrj1_
Parameters for hybrj_
SEE ALSO
AUTHORS

NAME

hybrj_, hybrj1_ - find a zero of a system of nonlinear function

SYNOPSIS

#include <minpack.h>

void hybrj1_ (void (* fcn )(int * n , double * x , double * fvec , double * fjac , int * ldfjac , int * iflag ),

int * n , double * x , double * fvec , double * fjac ,
int * ldfjac ,
double * tol , int * info , double * wa , int * lwa );

void hybrj_ (void (* fcn )(int * n , double * x , double * fvec , double * fjac , int * ldfjac , int * iflag ),

int * n , double * x , double * fvec , double * fjac ,
int * ldfjac ,
double * xtol , int * maxfev , double * diag , int * mode , double * factor , int * nprint , int * info , int * nfev ,
int * njev , double * r , int * lr , double * qtf ,
double * wa1 , double * wa2 , double * wa3 , double * wa4 );

DESCRIPTION

The purpose of hybrj_ 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 and a subroutine which calculates the Jacobian.

hybrj1_ serves the same function but has a simplified calling sequence.

Language notes

hybrj_ and hybrj1_ 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,fjac,ldfjac,iflag)
integer n,ldfjac,iflag
double precision x(n),fvec(n),fjac(ldfjac,n)
----------
if iflag = 1 calculate the functions at x and
return this vector in fvec. do not alter fjac.
if iflag = 2 calculate the jacobian at x and
return this matrix in fjac. do not alter fvec.
---------
return
end

In C, fcn should be written as follows:

void fcn(int *n, double *x, double *fvec, double *fjac,
int *ldfjac, int *iflag)
{
/* if iflag = 1 calculate the functions at x and
return this vector in fvec. do not alter fjac.
if iflag = 2 calculate the jacobian at x and
return this matrix in fjac. do not alter fvec. */
}

The value of iflag should not be changed by fcn unless the user wants to terminate execution of hybrj_. 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.

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 .

fvec is an output array of length n which contains the functions evaluated at the output x .

Parameters for hybrj1_

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 hybrj_

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.

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

hybrd (3), hybrd1 (3).

AUTHORS

Burton S. Garbow, Kenneth E. Hillstrom, Jorge J. More.
This manual page was written by Jim Van Zandt <jrv@debian.org>, for the Debian GNU/Linux system (but may be used by others).