usrfun must define the nonlinear portion fx of the problem functions Fx=fx+Ax, along with its gradient elements Gijx=fixxj. (A dummy method is needed even if f0 and all functions are linear.)
In general, usrfun should return all function and gradient values on every entry except perhaps the last. This provides maximum reliability and corresponds to the default option setting, Derivative Option=1.
The elements of Gx are stored in the array g1:usrfun_leng in the order specified by the input arrays igfun and jgvar.
In practice it is often convenient not to code gradients. e04vh is able to estimate them by finite differences, using a call to usrfun for each variable xj for which some fixxj needs to be estimated. However, this reduces the reliability of the optimization algorithm, and it can be very expensive if there are many such variables xj.
As a compromise, e04vh allows you to code as many gradients as you like. This option is implemented as follows. Just before usrfun is called, each element of the derivative array g is initialized to a specific value. On exit, any element retaining that value must be estimated by finite differences.
Some rules of thumb follow:
(i) for maximum reliability, compute all gradients;
(ii) if the gradients are expensive to compute, specify optional parameter Nonderivative Linesearch and use the value of the input parameter needg to avoid computing them on certain entries. (There is no need to compute gradients if needg=0 on entry to usrfun.);
(iii) if not all gradients are known, you must specify Derivative Option=0. You should still compute as many gradients as you can. (It often happens that some of them are constant or zero.);
(iv) again, if the known gradients are expensive, don't compute them if needg=0 on entry to usrfun;
(v) use the input parameter status to test for special actions on the first or last entries;
(vi) while usrfun is being developed, use the optional parameter Verify Level to check the computation of gradients that are supposedly known;
(vii) usrfun is not called until the linear constraints and bounds on x are satisfied. This helps confine x to regions where the functions fix are likely to be defined. However, be aware of the optional parameter Minor Feasibility Tolerance if the functions have singularities on the constraint boundaries;
(viii) set status=-1 if some of the functions are undefined. The linesearch will shorten the step and try again;
(ix) set status-2 if you want e04vh to stop.

Syntax

C#
public delegate void E04VH_USRFUN(
	ref int status,
	int n,
	double[] x,
	int needf,
	int nf,
	double[] f,
	int needg,
	double[] g
)
Visual Basic
Public Delegate Sub E04VH_USRFUN ( _
	ByRef status As Integer, _
	n As Integer, _
	x As Double(), _
	needf As Integer, _
	nf As Integer, _
	f As Double(), _
	needg As Integer, _
	g As Double() _
)
Visual C++
public delegate void E04VH_USRFUN(
	int% status, 
	int n, 
	array<double>^ x, 
	int needf, 
	int nf, 
	array<double>^ f, 
	int needg, 
	array<double>^ g
)
F#
type E04VH_USRFUN = 
    delegate of 
        status : int byref * 
        n : int * 
        x : float[] * 
        needf : int * 
        nf : int * 
        f : float[] * 
        needg : int * 
        g : float[] -> unit

Parameters

status
Type: System..::..Int32%
On entry: indicates the first and last calls to usrfun.
status=0
There is nothing special about the current call to usrfun.
status=1
e04vh is calling your method for the first time. You may wish to do something special such as read data from a file.
status2
e04vh is calling your method for the last time. This parameter setting allows you to perform some additional computation on the final solution.
status=2
The current x is optimal.
status=3
The problem appears to be infeasible.
status=4
The problem appears to be unbounded.
status=5
An iterations limit was reached.
If the functions are expensive to evaluate, it may be desirable to do nothing on the last call. The first executable statement could be
On exit: may be used to indicate that you are unable to evaluate f or its gradients at the current x. (For example, the problem functions may not be defined there.)
During the linesearch, fx is evaluated at points x=xk+αpk for various step lengths α, where fxk has already been evaluated satisfactorily. For any such x, if you set status=-1, e04vh will reduce α and evaluate f again (closer to xk, where fxk is more likely to be defined).
If for some reason you wish to terminate the current problem, set status-2.
n
Type: System..::..Int32
On entry: n, the number of variables, as defined in the call to e04vh.
x
Type: array<System..::..Double>[]()[][]
On entry: the variables x at which the problem functions are to be calculated. The array x must not be altered.
needf
Type: System..::..Int32
On entry: indicates whether f must be assigned during this call of usrfun.
needf=0
f is not required and is ignored.
needf>0
The components of fx corresponding to the nonlinear part of Fx must be calculated and assigned to f.
If Fix is linear and completely defined by the ith row of A, Ai, then the associated value fix is ignored and need not be assigned. However, if Fix has a nonlinear portion fix that happens to be zero at x, then it is still necessary to set fix=0. If the linear part Ai of a nonlinear Fix is provided using the arrays iafunjavar and a, then it must not be computed again as part of fix.
To simplify the code, you may ignore the value of needf and compute fx on every entry to usrfun.
needf may also be ignored with Derivative Linesearch and Derivative Option=1. In this case, needf is always 1, and f must always be assigned.
nf
Type: System..::..Int32
On entry: is the length of the full vector Fx=fx+Ax as defined in the call to e04vh.
f
Type: array<System..::..Double>[]()[][]
On entry: concerns the calculation of fx.
On exit: f contains the computed functions fx (except perhaps if needf=0).
needg
Type: System..::..Int32
On entry: indicates whether g must be assigned during this call of usrfun.
needg=0
g is not required and is ignored.
needg>0
The partial derivatives of fx must be calculated and assigned to g. The value of g[k-1] should be fixxj, where i=igfun[k-1], j=jgvar[k-1] and k=1,2,,leng.
g
Type: array<System..::..Double>[]()[][]
On entry: concerns the calculations of the derivatives of the function fx.
On exit: contains the computed derivatives Gx (unless needg=0).
These derivative elements must be stored in g in exactly the same positions as implied by the definitions of arrays igfun and jgvar. There is no internal check for consistency (except indirectly via the optional parameter Verify Level), so great care is essential.

See Also