usrfun must define the nonlinear portion

f (x)

of the problem functions

F (x) = f (x) + A x

, along with its gradient elements

G_{i j} (x) = \frac{\partial f_{i} (x)}{\partial x_{j}}

. (A dummy method is needed even if

f \equiv 0

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

G (x)

are stored in the array

g (1 : 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

x_{j}

for which some

\frac{\partial f_{i} (x)}{\partial x_{j}}

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

x_{j}

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 $f_{i} (x)$ 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 \leq - 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.

$status \geq 2$

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,

f (x)

is evaluated at points

x = x_{k} + α p_{k}

for various step lengths

α

, where

f (x_{k})

has already been evaluated satisfactorily. For any such

x

, if you set

status = - 1

, e04vh will reduce

α

and evaluate

f

again (closer to

x_{k}

, where

f (x_{k})

is more likely to be defined).

If for some reason you wish to terminate the current problem, set

status \leq - 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 $f (x)$ corresponding to the nonlinear part of $F (x)$ must be calculated and assigned to f.
If $F_{i} (x)$ is linear and completely defined by the $i$ th row of $A$ , $A_{i}^{'}$ , then the associated value $f_{i} (x)$ is ignored and need not be assigned. However, if $F_{i} (x)$ has a nonlinear portion $f_{i} (x)$ that happens to be zero at $x$ , then it is still necessary to set $f_{i} (x) = 0$ . If the linear part $A_{i}^{'}$ of a nonlinear $F_{i} (x)$ is provided using the arrays iafun, javar and a, then it must not be computed again as part of $f_{i} (x)$ .

To simplify the code, you may ignore the value of needf and compute

f (x)

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 $F (x) = f (x) + A x$ as defined in the call to e04vh.

f: Type: array<System..::..Double>[]()[][]
On entry: concerns the calculation of $f (x)$ .
On exit: f contains the computed functions $f (x)$ (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 $f (x)$ must be calculated and assigned to g. The value of $g [k - 1]$ should be $\frac{\partial f_{i} (x)}{\partial x_{j}}$ , where $i = igfun [k - 1]$ , $j = jgvar [k - 1]$ and $k = 1, 2, \dots, leng$ .

g: Type: array<System..::..Double>[]()[][]
On entry: concerns the calculations of the derivatives of the function $f (x)$ .
On exit: contains the computed derivatives $G (x)$ (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.

Syntax

Parameters

See Also