naginterfaces.library.opt.uncon_​conjgrd_​comp

naginterfaces.library.opt.uncon_conjgrd_comp(objfun, x, comm, data=None, io_manager=None)

uncon_conjgrd_comp minimizes an unconstrained nonlinear function of several variables using a pre-conditioned, limited memory quasi-Newton conjugate gradient method. First derivatives (or an ‘acceptable’ finite difference approximation to them) are required. It is intended for use on large scale problems.

Note: this function uses optional algorithmic parameters, see also: uncon_conjgrd_option_file(), uncon_conjgrd_option_string(), nlp1_init().

Deprecated since version 27.0.0.0: uncon_conjgrd_comp is deprecated. Please use handle_solve_bounds_foas() instead. See also the Replacement Calls document.

For full information please refer to the NAG Library document for e04dg

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/e04/e04dgf.html

Parameters

objfuncallable (objf, objgrd) = objfun(mode, x, nstate, data=None)

$objfun$ must calculate the objective function $F\left(x\right)$ and possibly its gradient as well for a specified $n$-element vector $x$.

Parameters

modeint

Indicates which values must be assigned during each call of $objfun$. Only the following values need be assigned:

$mode=0$

$objf$.

$mode=2$

$objf$ and $objgrd$.

xfloat, ndarray, shape $\left(n\right)$

$x$, the vector of variables at which the objective function and its gradient are to be evaluated.

nstateint

Will be $1$ on the first call of $objfun$ by uncon_conjgrd_comp, and $0$ for all subsequent calls. Thus, you may wish to test, $nstate$ within $objfun$ in order to perform certain calculations once only. For example, you may read data or initialize global variables when $nstate=1$.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns

objffloat

The value of the objective function at $x$.

objgrdfloat, array-like, shape $\left(n\right)$

If $mode=2$, $objgrd[\text{i}-1]$ must contain the value of $\frac{\partial F}{\partial x_{\text{i}}}$ evaluated at $x$, for $\text{i}=1,2,\dots ,n$.

xfloat, array-like, shape $\left(n\right)$

An initial estimate of the solution.

commdict, communication object, modified in place

Communication structure.

This argument must have been initialized by a prior call to nlp1_init().

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns

iteraint

The total number of iterations performed.

objffloat

The value of the objective function at the final iterate.

objgrdfloat, ndarray, shape $\left(n\right)$

The gradient of the objective function at the final iterate (or its finite difference approximation).

xfloat, ndarray, shape $\left(n\right)$

The final estimate of the solution.

Other Parameters

‘Defaults’valueless

This special keyword may be used to reset all options to their default values.

‘Estimated Optimal Function Value’float

This value of $r$ specifies the user-supplied guess of the optimum objective function value $F_{est}$. This value is used to calculate an initial step length ${\alpha }_0$ (see Algorithmic Details). If the value of $r$ is not specified (the default), then this has the effect of setting ${\alpha }_0$ to unity. It should be noted that for badly scaled functions a unit step along the steepest descent direction will often compute the objective function at very large values of $x$.

‘Function Precision’float

Default $={ϵ}^{0.9}$

The argument defines ${ϵ}_r$, which is intended to be a measure of the accuracy with which the problem function $F\left(x\right)$ can be computed. If $r<ϵ$ or $r\ge 1$, the default value is used.

The value of ${ϵ}_r$ should reflect the relative precision of $1+\left|F\left(x\right)\right|$; i.e., ${ϵ}_r$ acts as a relative precision when $\left|F\right|$ is large, and as an absolute precision when $\left|F\right|$ is small. For example, if $F\left(x\right)$ is typically of order $1000$ and the first six significant digits are known to be correct, an appropriate value for ${ϵ}_r$ would be ${10}^{-6}$. In contrast, if $F\left(x\right)$ is typically of order ${10}^{-4}$ and the first six significant digits are known to be correct, an appropriate value for ${ϵ}_r$ would be ${10}^{-10}$. The choice of ${ϵ}_r$ can be quite complicated for badly scaled problems; see Module 8 of Gill et al. (1981) for a discussion of scaling techniques. The default value is appropriate for most simple functions that are computed with full accuracy. However when the accuracy of the computed function values is known to be significantly worse than full precision, the value of ${ϵ}_r$ should be large enough so that no attempt will be made to distinguish between function values that differ by less than the error inherent in the calculation.

‘Iteration Limit’int

Default $=max(50,5n)$

The value of $i$ specifies the maximum number of iterations allowed before termination. If $i<0$, the default value is used.

Problems whose Hessian matrices at the solution contain sets of clustered eigenvalues are likely to be minimized in significantly fewer than $n$ iterations. Problems without this property may require anything between $n$ and $5n$ iterations, with approximately $2n$ iterations being a common figure for moderately difficult problems.

‘Iters’int

Default $=max(50,5n)$

The value of $i$ specifies the maximum number of iterations allowed before termination. If $i<0$, the default value is used.

Problems whose Hessian matrices at the solution contain sets of clustered eigenvalues are likely to be minimized in significantly fewer than $n$ iterations. Problems without this property may require anything between $n$ and $5n$ iterations, with approximately $2n$ iterations being a common figure for moderately difficult problems.

‘Itns’int

Default $=max(50,5n)$

The value of $i$ specifies the maximum number of iterations allowed before termination. If $i<0$, the default value is used.

Problems whose Hessian matrices at the solution contain sets of clustered eigenvalues are likely to be minimized in significantly fewer than $n$ iterations. Problems without this property may require anything between $n$ and $5n$ iterations, with approximately $2n$ iterations being a common figure for moderately difficult problems.

‘Linesearch Tolerance’float

Default $=0.9$

The value $r$ controls the accuracy with which the step $\alpha$ taken during each iteration approximates a minimum of the function along the search direction (the smaller the value of $r$, the more accurate the linesearch). The default value $r=0.9$ requests an inaccurate search, and is appropriate for most problems. A more accurate search may be appropriate when it is desirable to reduce the number of iterations – for example, if the objective function is cheap to evaluate. If $r<0$ or $r\ge 1$, the default value is used.

‘List’valueless

Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.

‘Nolist’valueless

Default for uncon_conjgrd_comp $=\text{‘Nolist'}$

Option ‘List’ enables printing of each option specification as it is supplied. ‘Nolist’ suppresses this printing.

‘Maximum Step Length’float

Default $={10}^{20}$

If $r>0$, the maximum allowable step length for the linesearch is taken as $min(\frac{1}{\text{machine.real\_safe}\left(\right)},\frac{r}{\parallel p_k\parallel })$. If $r\le 0$, the default value is used.

‘Optimality Tolerance’float

Default $={ϵ}_R^{0.8}$

The argument $r$ specifies the accuracy to which you wish the final iterate to approximate a solution of the problem. Broadly speaking, $r$ indicates the number of correct figures desired in the objective function at the solution. For example, if $r$ is ${10}^{-6}$ and termination occurs with no exception or warning is raised (see Parameters), then the final point satisfies the termination criteria, where ${\tau }_F$ represents ‘Optimality Tolerance’. If $r<{ϵ}_r$ or $r\ge 1$, the default value is used. If ‘Optimality Tolerance’ is chosen below a certain threshold, it will automatically be reset to another value.

‘Print Level’int

The value $i$ controls the amount of printout produced by uncon_conjgrd_comp, as indicated below. A detailed description of the printout is given in Description of Printed Output (summary output at each iteration and the final solution).

$i$	Output
$0$	No output.
$1$	The final solution only.
$5$	One line of summary output ($<80$ characters; see Description of Printed Output) for each iteration (no printout of the final solution).
$10$	The final solution and one line of summary output for each iteration.

‘Start Objective Check at Variable’int

Default $=1$

These keywords take effect only if $\text{‘Verify Level'}>0$. They may be used to control the verification of gradient elements computed by $objfun$. For example, if the first $30$ elements of the objective gradient appeared to be correct in an earlier run, so that only element $31$ remains questionable, it is reasonable to specify $\text{‘Start Objective Check at Variable'}=31$. If the first $30$ variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.

If $i_1\le 0$ or $i_1>max(1,min(n,i_2))$, the default value is used. If $i_2\le 0$ or $i_2>n$, the default value is used.

‘Stop Objective Check at Variable’int

Default $=n$

These keywords take effect only if $\text{‘Verify Level'}>0$. They may be used to control the verification of gradient elements computed by $objfun$. For example, if the first $30$ elements of the objective gradient appeared to be correct in an earlier run, so that only element $31$ remains questionable, it is reasonable to specify $\text{‘Start Objective Check at Variable'}=31$. If the first $30$ variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.

If $i_1\le 0$ or $i_1>max(1,min(n,i_2))$, the default value is used. If $i_2\le 0$ or $i_2>n$, the default value is used.

‘Verify Level’int

Default $=0$

These keywords refer to finite difference checks on the gradient elements computed by $objfun$. Gradients are verified at the user-supplied initial estimate of the solution. The possible choices for $i$ are as follows:

$i$	Meaning
$-1$	No checks are performed.
$0$	Only a ‘cheap’ test will be performed, requiring one call to $objfun$.
$1$	In addition to the ‘cheap’ test, individual gradient elements will also be checked using a reliable (but more expensive) test.

For example, the objective gradient will be verified if ‘Verify’, $\text{‘Verify'}=\text{'YES'}$, ‘Verify Gradients’, ‘Verify Objective Gradients’ or $\text{‘Verify Level'}=1$ is specified.

‘Verify’valueless

These keywords refer to finite difference checks on the gradient elements computed by $objfun$. Gradients are verified at the user-supplied initial estimate of the solution. The possible choices for $i$ are as follows:

$i$	Meaning
$-1$	No checks are performed.
$0$	Only a ‘cheap’ test will be performed, requiring one call to $objfun$.
$1$	In addition to the ‘cheap’ test, individual gradient elements will also be checked using a reliable (but more expensive) test.

For example, the objective gradient will be verified if ‘Verify’, $\text{‘Verify'}=\text{'YES'}$, ‘Verify Gradients’, ‘Verify Objective Gradients’ or $\text{‘Verify Level'}=1$ is specified.

‘Verify Gradients’valueless

These keywords refer to finite difference checks on the gradient elements computed by $objfun$. Gradients are verified at the user-supplied initial estimate of the solution. The possible choices for $i$ are as follows:

$i$	Meaning
$-1$	No checks are performed.
$0$	Only a ‘cheap’ test will be performed, requiring one call to $objfun$.
$1$	In addition to the ‘cheap’ test, individual gradient elements will also be checked using a reliable (but more expensive) test.

For example, the objective gradient will be verified if ‘Verify’, $\text{‘Verify'}=\text{'YES'}$, ‘Verify Gradients’, ‘Verify Objective Gradients’ or $\text{‘Verify Level'}=1$ is specified.

‘Verify Objective Gradients’valueless

These keywords refer to finite difference checks on the gradient elements computed by $objfun$. Gradients are verified at the user-supplied initial estimate of the solution. The possible choices for $i$ are as follows:

$i$	Meaning
$-1$	No checks are performed.
$0$	Only a ‘cheap’ test will be performed, requiring one call to $objfun$.
$1$	In addition to the ‘cheap’ test, individual gradient elements will also be checked using a reliable (but more expensive) test.

For example, the objective gradient will be verified if ‘Verify’, $\text{‘Verify'}=\text{'YES'}$, ‘Verify Gradients’, ‘Verify Objective Gradients’ or $\text{‘Verify Level'}=1$ is specified.

Raises

NagValueError

(errno $8$)

Gradient at the starting point is too small.

(errno $9$)

On entry, $n=⟨value⟩$.

Constraint: $n>0$.

Warns

NagAlgorithmicWarning

(errno $6$)

Current point cannot be improved upon.

(errno $7$)

Large errors found in the derivatives.

NagAlgorithmicMajorWarning

(errno $3$)

Too many iterations.

(errno $4$)

Computed upper bound on step length is too small.

NagCallbackTerminateWarning

(errno $i<0$)

User requested termination.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

uncon_conjgrd_comp is designed to solve unconstrained minimization problems of the form

$${minimize}_{x\in R^n}F\left(x\right)\text{subject to}-\infty \le x\le \infty \text{,}$$

where $x$ is an $n$-element vector.

You must supply an initial estimate of the solution.

For maximum reliability, it is preferable to provide all first partial derivatives. If all of the derivatives cannot be provided, you are recommended to obtain approximate values (using finite differences) by calling estimate_deriv() from within $objfun$.

The method used by uncon_conjgrd_comp is described in Algorithmic Details.

References

Gill, P E and Murray, W, 1979, Conjugate-gradient methods for large-scale nonlinear optimization, Technical Report SOL 79-15, Department of Operations Research, Stanford University

Gill, P E, Murray, W and Wright, M H, 1981, Practical Optimization, Academic Press