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_29/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 withhandle_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()
orhandle_set_qconstr_fac()
was called to define a linear or quadratic objective function), will never be called byhandle_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()
orhandle_set_qconstr_fac()
was called to define a linear or quadratic objective function), will never be called byhandle_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 byhandle_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 tohandle_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 ofhandle_set_nlnobj()
orhandle_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 problemwhere
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()
(andhandle_set_qconstr()
orhandle_set_qconstr_fac()
) for a sparse linear or quadratic function,handle_set_qconstr_fac()
is used to provide the quadratic function in factorized form, andhandle_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 withhandle_set_simplebounds()
. The special case of linear constraints is handled byhandle_set_linconstr()
, quadratic constraints are handled byhandle_set_qconstr()
andhandle_set_qconstr_fac()
while general nonlinear constraints are specified byhandle_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. Ifhandle_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 tohandle_set_linobj()
,handle_set_quadobj()
,handle_set_linconstr()
,handle_set_qconstr_fac()
andhandle_set_qconstr()
. Ifhandle_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., ifhandle_set_linconstr()
was called), followed by the quadratic constraint multipliers (if present, i.e., ifhandle_set_qconstr()
orhandle_set_qconstr_fac()
were called), and the nonlinear constraint multipliers (if present, i.e., ifhandle_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