naginterfaces.library.opt.handle_​solve_​ipopt

naginterfaces.library.opt.handle_solve_ipopt(handle, x, objfun=None, objgrd=None, confun=None, congrd=None, hess=None, monit=None, u=None, data=None, io_manager=None)[source]

handle_solve_ipopt is a solver from the NAG optimization modelling suite for constrained large-scale Nonlinear Programming (NLP) problems. It is an interior point method optimization solver based on the IPOPT software package.

Note: this function uses optional algorithmic parameters, see also: handle_opt_set(), handle_opt_get().

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

https://www.nag.com/numeric/nl/nagdoc_28.5/flhtml/e04/e04stf.html

Parameters
handleHandle

The handle to the problem. It needs to be initialized (e.g., by handle_init()) and to hold a problem formulation compatible with handle_solve_ipopt. It must not be changed between calls to the NAG optimization modelling suite.

xfloat, array-like, shape

, the initial estimates of the variables .

objfunNone or callable (fx, inform) = objfun(x, inform, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

must calculate the value of the nonlinear objective function at a specified value of the -element vector of variables.

If there is no nonlinear objective (e.g., handle_set_linobj(), handle_set_quadobj(), handle_set_qconstr() or handle_set_qconstr_fac() was called to define a linear or quadratic objective function), will never be called by handle_solve_ipopt and may be None.

Parameters
xfloat, ndarray, shape

The vector of variable values at which the objective function is to be evaluated.

informint

A non-negative value.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
fxfloat

The value of the objective function at .

informint

Must be set to a value describing the action to be taken by the solver on return from . Specifically, if the value is negative, then the value of will be discarded and the solver will either attempt to find a different trial point or terminate immediately with = 25; otherwise, the solver will proceed normally.

objgrdNone or callable inform = objgrd(x, fdx, inform, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

must calculate the values of the nonlinear objective function gradients at a specified value of the -element vector of variables.

If there is no nonlinear objective (e.g., handle_set_linobj(), handle_set_quadobj(), handle_set_qconstr() or handle_set_qconstr_fac() was called to define a linear or quadratic objective function), will never be called by handle_solve_ipopt and may be None.

Parameters
xfloat, ndarray, shape

The vector of variable values at which the objective function gradient is to be evaluated.

fdxfloat, ndarray, shape , to be modified in place

On entry: the elements should only be assigned and not referenced.

On exit: the values of the nonzero elements in the sparse gradient vector of the objective function, in the order specified by in a previous call to handle_set_nlnobj(). will be the gradient .

informint

A non-negative value.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
informint

Must be set to a value describing the action to be taken by the solver on return from . Specifically, if the value is negative then the value of will be discarded and the solver will either attempt to find a different trial point or will terminate immediately with = 25; otherwise, computations will continue.

confunNone or callable (gx, inform) = confun(x, ncnln, inform, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

must calculate the values of the -element vector of nonlinear constraint functions at a specified value of the -element vector of variables.

If there are no nonlinear constraints then will never be called by handle_solve_ipopt and it may be None.

Parameters
xfloat, ndarray, shape

The vector of variable values at which the constraint functions are to be evaluated.

ncnlnint

, the number of nonlinear constraints, as specified in an earlier call to handle_set_nlnconstr().

informint

A non-negative value.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
gxfloat, array-like, shape

The values of the nonlinear constraint functions at .

informint

Must be set to a value describing the action to be taken by the solver on return from . Specifically, if the value is negative, then the value of will be discarded and the solver will either attempt to find a different trial point or terminate immediately with = 25; otherwise, the solver will proceed normally.

congrdNone or callable inform = congrd(x, gdx, inform, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

must calculate the nonzero values of the sparse Jacobian of the nonlinear constraint functions at a specified value of the -element vector of variables.

If there are no nonlinear constraints, will never be called by handle_solve_ipopt and may be None.

Parameters
xfloat, ndarray, shape

The vector of variable values at which the Jacobian of the constraint functions is to be evaluated.

gdxfloat, ndarray, shape , to be modified in place

On entry: the elements should only be assigned and not referenced.

On exit: the nonzero values of the Jacobian of the nonlinear constraints, in the order specified by and in an earlier call to handle_set_nlnconstr(). will be the gradient , where and .

informint

A non-negative value.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
informint

Must be set to a value describing the action to be taken by the solver on return from . Specifically, if the value is negative the solution of the current problem will terminate immediately with = 25; otherwise, computations will continue.

hessNone or callable inform = hess(x, idf, sigma, lamda, hx, inform, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

must calculate the nonzero values of one of a set of second derivative quantities:

the Hessian of the Lagrangian function ,

the Hessian of the objective function ,

the Hessian of the th constraint function .

The value of argument determines which one of these is to be computed and this, in turn, is determined by earlier calls to handle_set_nlnhess(), when the nonzero sparsity structure of these Hessians was registered.

Please note that it is not possible to only supply a subset of the Hessians (see = 6).

If there were no calls to handle_set_nlnhess(), will never be called by handle_solve_ipopt and may be None. In this case, the Hessian of the Lagrangian will be approximated by a limited-memory quasi-Newton method (L-BFGS).

Parameters
xfloat, ndarray, shape

The vector of variable values at which the Hessian functions are to be evaluated.

idfint

Specifies the quantities to be computed in .

The values of the Hessian of the Lagrangian will be computed in . This will be the case if handle_set_nlnhess() has been called with of the same value.

The values of the Hessian of the objective function will be computed in . This will be the case if handle_set_nlnhess() has been called with of the same value.

The values of the Hessian of the constraint function with index will be computed in . This will be the case if handle_set_nlnhess() has been called with of the same value.

sigmafloat

If , the value of the quantity in the definition of the Hessian of the Lagrangian. Otherwise, should not be referenced.

lamdafloat, ndarray, shape

If , the values of the quantities in the definition of the Hessian of the Lagrangian. Otherwise, should not be referenced.

hxfloat, ndarray, shape , to be modified in place

On entry: the elements should only be assigned and not referenced.

On exit: the nonzero values of the requested Hessian evaluated at . For each value of , the ordering of nonzeros must follow the sparsity structure registered in the by earlier calls to handle_set_nlnhess() through the arguments and .

informint

A non-negative value.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

Returns
informint

Must be set to a value describing the action to be taken by the solver on return from . Specifically, if the value is negative the solution of the current problem will terminate immediately with = 25; otherwise, computations will continue.

monitNone or callable monit(x, u, rinfo, stats, data=None), optional

Note: if this argument is None then a NAG-supplied facility will be used.

is provided to enable you to monitor the progress of the optimization.

may be None.

Parameters
xfloat, ndarray, shape

, the values of the decision variables at the current iteration.

ufloat, ndarray, shape

If , holds the values of Lagrange multipliers (dual variables) for the constraints at the current iteration. See Structure of the Lagrange Multipliers for layout information.

rinfofloat, ndarray, shape

Error measures and various indicators at the end of the current iteration as described in Description of the Printed Output.

statsfloat, ndarray, shape

Solver statistics at the end of the current iteration. It reports only the iteration count and the number of backtracking trial steps taken. See Description of the Printed Output.

dataarbitrary, optional, modifiable in place

User-communication data for callback functions.

uNone or float, array-like, shape , optional

The input of is reserved for future releases of the NAG Library and it is ignored at the moment.

Note: if , holds Lagrange multipliers (dual variables) for the constraints. See Structure of the Lagrange Multipliers for layout information. If , will not be referenced.

dataarbitrary, optional

User-communication data for callback functions.

io_managerFileObjManager, optional

Manager for I/O in this routine.

Returns
xfloat, ndarray, shape

The final values of the variables .

ufloat, ndarray, shape

The final value of Lagrange multipliers .

rinfofloat, ndarray, shape

Error measures and various indicators at the end of the final iteration as given in the list below:

Objective function value .

Constraint violation (primal infeasibility), see [equation].

Dual infeasibility, see [equation].

Complementarity.

Karush–Kuhn–Tucker error.

Regularization term for the Hessian of the Lagrangian. This value is only available in , see Iteration log in Description of the Printed Output.

Step size for the dual variables. This value is only available in , see Iteration log in Description of the Printed Output.

Step size for the primal variables. This value is only available in , see Iteration log in Description of the Printed Output.

Reserved for future use.

statsfloat, ndarray, shape

Solver statistics at the end of the final iteration as given in the list below:

Number of the iterations.

Reserved for future use.

Number of backtracking trial steps.

Number of Hessian evaluations.

Number of objective gradient evaluations.

,

Reserved for future use.

Total wall clock time elapsed.

Reserved for future use.

Number of objective function evaluations.

Number of constraint function evaluations.

Number of constraint Jacobian evaluations.

Reserved for future use.

Other Parameters
‘Defaults’valueless

This special keyword may be used to reset all options to their default values. Any value given with this keyword will be ignored.

‘Hessian Mode’str

Default

This argument specifies whether the Hessian will be user-supplied (in ) or approximated by handle_solve_ipopt using a limited-memory quasi-Newton L-BFGS method. In the ‘AUTO’ setting, if no Hessian structure has been registered in the problem with a call to handle_set_nlnhess() and there are general nonlinear objective or constraints, then the Hessian will be approximated. Otherwise will be called if and only if any of handle_set_nlnobj() or handle_set_nlnconstr() have been used to define the problem. Approximating the Hessian is likely to require more iterations to achieve convergence but will reduce the time spent in user-supplied functions.

Constraint: , or .

‘Infinite Bound Size’float

Default

This defines the ‘infinite’ bound in the definition of the problem constraints. Any upper bound greater than or equal to will be regarded as (and similarly any lower bound less than or equal to will be regarded as ). Note that a modification of this option does not influence constraints which have already been defined; only the constraints formulated after the change will be affected.

It also serves as a limit for the objective function to be considered unbounded ( = 54).

Constraint: .

‘Monitoring File’int

Default

If , the unit number for the secondary (monitoring) output. If set to , no secondary output is provided. The information output to this unit is controlled by ‘Monitoring Level’.

Constraint: .

‘Monitoring Level’int

Default

This argument sets the amount of information detail that will be printed by the solver to the secondary output. The meaning of the levels is the same as with ‘Print Level’.

Constraint: .

‘Matrix Ordering’str

Default

This argument specifies the ordering to be used by the internal sparse linear algebra solver. It affects the number of nonzeros in the factorized matrix and thus influences the cost per iteration.

A heuristic is used to choose automatically between METIS and AMD orderings.

Both AMD and METIS orderings are computed at the beginning of the solve and the one with the fewest nonzeros in the factorized matrix is selected.

An approximate minimum degree (AMD) ordering is used.

METIS ordering is used.

Constraint: , , or .

‘Outer Iteration Limit’int

Default

The maximum number of iterations to be performed by handle_solve_ipopt. Setting the option too low might lead to = 22.

Constraint: .

‘Print File’int

Default

If , the unit number for the primary output of the solver. If , the primary output is completely turned off independently of other settings. The default value is the advisory message unit number at the time of the options initialization, e.g., at the initialization of the handle. The information output to this unit is controlled by ‘Print Level’.

Constraint: .

‘Print Level’int

Default

This argument defines how detailed information should be printed by the solver to the primary output.

Output

No output from the solver

Additionally, derivative check information, the Header and Summary.

Additionally, the Iteration log.

,

Additionally, details of each iteration with scalar quantities printed.

Additionally, individual components of arrays are printed resulting in large output.

Constraint: .

‘Print Options’str

Default

If , a listing of options will be printed to the primary output.

Constraint: or .

‘Print Solution’str

Default

If , the final values of the primal variables are printed on the primary and secondary outputs.

If or , in addition to the primal variables, the final values of the dual variables are printed on the primary and secondary outputs.

Constraint: , , or .

‘Stats Time’str

Default

This argument allows you to turn on timings of various parts of the algorithm to give a better overview of where most of the time is spent. This might be helpful for a choice of different solving approaches.

Constraint: or .

‘Stop Tolerance 1’float

Default

This option sets the value of (5) which is used for optimality and complementarity tests from KKT conditions. See Stopping Criteria.

Constraint: .

‘Task’str

Default

This argument specifies the required direction of the optimization. If , the objective function (if set) is ignored and the algorithm stops as soon as a feasible point is found with respect to the given tolerance. If no objective function is set, ‘Task’ reverts to ‘FEASIBLE POINT’ automatically.

Constraint: , or .

‘Time Limit’float

Default

A limit to the number of seconds that the solver can use to solve one problem. If during the convergence check this limit is exceeded, the solver will terminate with a corresponding error message.

Constraint: .

‘Verify Derivatives’str

Default

This argument specifies whether the function should perform numerical checks on the consistency of the user-supplied functions. It is recommended that such checks are enabled when first developing the formulation of the problem, however, the derivative check results in a significant increase of the number of the function evaluations and thus it shouldn’t be used in production code.

Constraint: or .

Raises
NagValueError
(errno )

handle_solve_ipopt is not available in this implementation.

(errno )

has not been initialized.

(errno )

does not belong to the NAG optimization modelling suite, has not been initialized properly or is corrupted.

(errno )

has not been initialized properly or is corrupted.

(errno )

The problem is already being solved.

(errno )

This solver does not support the model defined in the handle.

(errno )

On entry, , expected .

Constraint: must match the current number of variables of the model in the .

(errno )

On entry, .

Constraint: or .

(errno )

On entry, .

Constraint: no constraints present, so must be .

(errno )

On entry, a nonlinear objective function has been defined but no objective Hessian sparsity structure has been defined through handle_set_nlnhess().

(errno )

On entry, a nonlinear constraint function has been defined but no constraint Hessian sparsity structure has been defined through handle_set_nlnhess(), for constraint number .

(errno )

Either change the option ‘Hessian Mode’ or provide a proper function.

(errno )

Please provide a proper function.

(errno )

Please provide a proper function.

(errno )

Please provide a proper function.

(errno )

Please provide a proper function.

(errno )

The solver terminated with not enough degrees of freedom.

(errno )

The solver terminated due to an invalid problem definition.

(errno )

The solver terminated due to an invalid option.

(errno )

The solver detected an infeasible problem.

(errno )

The solver terminated due to diverging iterates.

Warns
NagAlgorithmicWarning
(errno )

Maximum number of iterations exceeded.

(errno )

The solver reports NLP solved to acceptable level.

NagAlgorithmicMajorWarning
(errno )

The solver terminated after failure in the restoration phase.

(errno )

The solver terminated after an error in the step computation.

(errno )

The solver terminated after the maximum time allowed was exceeded.

(errno )

The solver terminated after the search direction became too small.

(errno )

Invalid number detected in user function.

NagCallbackTerminateWarning
(errno )

User requested termination during a monitoring step.

Notes

handle_solve_ipopt is typically used to solve the following nonlinear programming problem

where

is the number of the decision variables,

is the number of the nonlinear constraints and , and are -dimensional vectors,

is the number of the quadratic constraints,

is the number of the linear constraints and is a matrix, and are -dimensional vectors,

there are box constraints and and are -dimensional vectors.

The objective can be specified in a number of ways: handle_set_linobj() for a dense linear function, handle_set_quadobj() (and handle_set_qconstr() or handle_set_qconstr_fac()) for a sparse linear or quadratic function, handle_set_qconstr_fac() is used to provide the quadratic function in factorized form, and handle_set_nlnobj() for a general nonlinear function. In the last case, and will be used to compute values and gradients of the objective function. Variable box bounds can be specified with handle_set_simplebounds(). The special case of linear constraints is handled by handle_set_linconstr(), quadratic constraints are handled by handle_set_qconstr() and handle_set_qconstr_fac() while general nonlinear constraints are specified by handle_set_nlnconstr() (all can be specified). Again, in the last case, and will be used to compute values and gradients of the nonlinear constraint functions.

Finally, if it is viable to calculate second derivatives, the sparsity structure of the second partial derivatives of a general nonlinear objective and/or of any general nonlinear constraints is specified by handle_set_nlnhess() and the values of these derivatives themselves will be computed by user-supplied . While there is an option (see ‘Hessian Mode’) that forces internal approximation of second derivatives, no such option exists for first derivatives which must be computed accurately. If handle_set_nlnhess() has been called and is used to calculate values for second derivatives, both the nonlinear objective and all the nonlinear constraints must be included; it is not possible to provide a subset of these. If the problem has only linear or quadratic objective and constraints, then is never called since the required Hessian information is already provided by the calls to handle_set_linobj(), handle_set_quadobj(), handle_set_linconstr(), handle_set_qconstr_fac() and handle_set_qconstr(). If handle_set_nlnhess() is not called, then internal approximation of second derivatives will take place.

See the E04 Introduction for more details about the NAG optimization modelling suite.

Structure of the Lagrange Multipliers

For a problem consisting of variable bounds, linear constraints, quadratic constraints, and nonlinear constraints, the number of Lagrange multipliers, and consequently the correct value for , will be . The order these will be found in the array is

where the and subscripts refer to lower and upper bounds, respectively, and the variable bound constraint multipliers come first (if present, i.e., if handle_set_simplebounds() was called), followed by the linear constraint multipliers (if present, i.e., if handle_set_linconstr() was called), followed by the quadratic constraint multipliers (if present, i.e., if handle_set_qconstr() or handle_set_qconstr_fac() were called), and the nonlinear constraint multipliers (if present, i.e., if handle_set_nlnconstr() was called).

Significantly nonzero values for any of these, after the solver has terminated, indicates that the corresponding constraint is active. Significance is judged in the first instance by the relative scale of any value compared to the smallest among them.

References

Byrd, R H, Gilbert, J Ch and Nocedal, J, 2000, A trust region method based on interior point techniques for nonlinear programming, Mathematical Programming (89), 149–185

Byrd, R H, Liu, G and Nocedal, J, 1997, On the local behavior of an interior point method for nonlinear programming, Numerical Analysis, (eds D F Griffiths and D J Higham), Addison–Wesley

Conn, A R, Gould, N I M, Orban, D and Toint, Ph L, 2000, A primal-dual trust-region algorithm for non-convex nonlinear programming, Mathematical Programming (87 (2)), 215–249

Conn, A R, Gould, N I M and Toint, Ph L, 2000, Trust Region Methods, SIAM, Philadephia

Fiacco, A V and McCormick, G P, 1990, Nonlinear Programming: Sequential Unconstrained Minimization Techniques, SIAM, Philadelphia

Gould, N I M, Orban, D, Sartenaer, A and Toint, Ph L, 2001, Superlinear convergence of primal-dual interior point algorithms for nonlinear programming, SIAM Journal on Optimization (11 (4)), 974–1002

Hock, W and Schittkowski, K, 1981, Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems (187), Springer–Verlag

Hogg, J D and Scott, J A, 2011, HSL MA97: a bit-compatible multifrontal code for sparse symmetric systems, RAL Technical Report. RAL-TR-2011-024

Wächter, A and Biegler, L T, 2006, On the implementation of a primal-dual interior point filter line search algorithm for large-scale nonlinear programming, Mathematical Programming (106(1)), 25–57

Williams, P and Lang, B, 2013, A framework for the Algorithm: theory and implementation, SIAM J. Sci. Comput. (35), 740–766

Yamashita, H, 1998, A globally convergent primal-dual interior-point method for constrained optimization, Optimization Methods and Software (10), 443–469