Reference

This is the class and function reference of cyipopt. Please refer to the tutorial for further details, as the class and function raw specifications may not be enough to give full guidelines on their uses.

class cyipopt.Problem

Wrapper class for solving optimization problems using the C interface of the Ipopt package.

It can be used to solve general nonlinear programming problems of the form:

\[\min_ {x \in R^n} f(x)\]

subject to

\[ \begin{align}\begin{aligned}g_L \leq g(x) \leq g_U\\x_L \leq x \leq x_U\end{aligned}\end{align} \]

Where \(x\) are the optimization variables (possibly with upper an lower bounds), \(f(x)\) is the objective function and \(g(x)\) are the general nonlinear constraints. The constraints, \(g(x)\), have lower and upper bounds. Note that equality constraints can be specified by setting \(g^i_L = g^i_U\).

Parameters:

• n (int) – Number of primal variables.

• m (int) – Number of constraints.

• problem_obj (object, optional (default=None)) –

  An object holding the problem’s callbacks. If None, cyipopt will use self, this is useful when subclassing Problem. The object is required to have the following attributes and methods (some are optional):

  • objective(x)

    Callback function for evaluating objective function at the given point x.

    Parameters

    xnumpy.ndarray, shape (n, )

    Value of the optimization variables at which the objective is to be evaluated.

    Returns

    float

    Objective function value at the point x.

  • constraints(x)

    Callback function for evaluating constraint functions at the given point x.

    Parameters

    xnumpy.ndarray, shape (n, )

    Value of the optimization variables at which the constraints are to be evaluated.

    Returns

    numpy.ndarray, shape (m, )

    Constraint values at the point x.

  • gradient(x)

    Callback function for evaluating gradient of objective function at the given point x.

    Parameters

    xnumpy.ndarray, shape (n, )

    Value of the optimization variables at which the gradient is to be evaluated.

    Returns

    numpy.ndarray, shape (n, )

    Gradient of the objective function at the point x.

  • jacobian(x)

    Callback function for evaluating Jacobian of constraint functions at the given point x. The values should be returned as a 1-dim numpy array (using the same order as you used when specifying the sparsity structure)

    Parameters

    xnumpy.ndarray, shape (n, )

    Value of the optimization variables at which the Jacobian is to be evaluated.

    Returns

    numpy.ndarray, shape (jac_nnz, )

    Jacobian of the constraint functions at the point x.

  • jacobianstructure()

    Optional callback function that returns the sparsity structure of the Jacobian of the constraints. The function should return a tuple of two numpy.ndarrays of integers, the first array contains the row indices and the second array contains the column indices of the non-zero elements of the Jacobian. Both arrays should have the same length of jac_nnz, and indexing is zero-based.

    If this callback is not provided, the Jacobian is assumed to be dense (jac_nnz = m * n) using row-major (C-style) order.

    Returns

    tuple

    Tuple containing two numpy arrays, the first array contains the row indices and the second array contains the column indices of the non-zero elements of the Jacobian.

  • hessian(x, lambda, objective_factor)

    Optional callback function for evaluating the Hessian of the Lagrangian function with respect to the primal variables \(x\). The Lagrangian is given by

    \[\mathcal{L}(x, \lambda) = \lambda_0 f(x) + \sum_{i=1}^{m} \lambda_i g_i(x)\]

    where \(\lambda_1, \ldots, \lambda_m\) are the Lagrange multipliers and \(\lambda_0\) is the objective factor. The function should return the values of the Hessian as calculated using x, lambda and objective_factor. The values should be returned as a 1-dimensional array-like structure (using the same order as you used when specifying the sparsity structure).

    If this callback is not provided, the Hessian is calculated numerically.

    Parameters

    xnumpy.ndarray, shape (n, )

    Value of the optimization variables at which the Hessian is to be evaluated.

    lambdanumpy.ndarray, shape (m, )

    Values for the Lagrange multipliers.

    objective_factorfloat

    Factor for the objective term of the Hessian (usually 1).

    Returns

    numpy.ndarray, shape (hess_nnz, )

    Hessian of the Lagrangian function at the point x.

  • hessianstructure()

    Optional callback function that returns the sparsity structure of the Hessian of the Lagrangian. The function should return a tuple of two numpy.ndarrays, the first array contains the row indices and the second array contains the column indices of the non-zero elements of the Hessian. Both arrays should have the same length of hess_nnz, and indexing is zero-based. Furthermore, since the Hessian is symmetric, the indices must only correspond to the lower triangular part of the Hessian (i.e., row >= col).

    If this callback is not provided, the Hessian is assumed to be dense (hess_nnz = n * (n + 1) / 2) using row-major (C-style) order.

    Returns

    tuple

    Tuple containing two numpy arrays, the first array contains the row indices and the second array contains the column indices of the non-zero elements of the Hessian.

  • intermediatefunction pointer, optional (default=None)

    Optional. Callback function that is called once per iteration (during the convergence check), and can be used to obtain information about the optimization status while Ipopt solves the problem. If this callback returns False, Ipopt will terminate with the User_Requested_Stop status. The information below corresponeds to the argument list passed to this callback:

    alg_mod:

    Algorithm phase: 0 is for regular, 1 is restoration.

    iter_count:

    The current iteration count.

    obj_value:

    The unscaled objective value at the current point

    inf_pr:

    The scaled primal infeasibility at the current point.

    inf_du:

    The scaled dual infeasibility at the current point.

    mu:

    The value of the barrier parameter.

    d_norm:

    The infinity norm (max) of the primal step.

    regularization_size:

    The value of the regularization term for the Hessian of the Lagrangian in the augmented system.

    alpha_du:

    The stepsize for the dual variables.

    alpha_pr:

    The stepsize for the primal variables.

    ls_trials:

    The number of backtracking line search steps.

    more information can be found in the following link: https://coin-or.github.io/Ipopt/OUTPUT.html

• lb (array-like, shape(n, )) – Lower bounds on variables, where n is the dimension of x. To assume no lower bounds pass values lower then 10^-19.

• ub (array-like, shape(n, )) – Upper bounds on variables, where n is the dimension of x. To assume no upper bounds pass values higher then 10^-19.

• cl (array-like, shape(m, )) – Lower bounds on constraints, where m is the number of constraints. Equality constraints can be specified by setting cl[i] = cu[i].

• cu (array-like, shape(m, )) – Upper bounds on constraints, where m is the number of constraints. Equality constraints can be specified by setting cl[i] = cu[i].

add_option(keyword, val)

Add a keyword/value option pair to the problem.

See the Ipopt documentaion for details on available options.

Parameters:

• keyword (str) – Option name.

• val (str, int or float) – Value of the option. The type of val should match the option definition as described in the Ipopt documentation.

close()

Deallocate memory resources used by the Ipopt package.

Called implicitly by the Problem class destructor.

get_current_iterate(scaled=False)

Return the current iterate vectors during an Ipopt solve

The iterate contains vectors for primal variables, bound multipliers, constraint function values, and constraint multipliers. Here, the constraints are treated as a single function rather than separating equality and inequality constraints. This method can only be called during an intermediate callback.

Only supports Ipopt >=3.14.0

Parameters:

scaled (bool) – Whether the scaled iterate vectors should be returned

Returns:

A dict containing the iterate vector with keys "x", "mult_x_L", "mult_x_U", "g", and "mult_g". If iterate vectors cannot be obtained, None is returned.

Return type:

dict or None

get_current_violations(scaled=False)

Return the current violation vectors during an Ipopt solve

Violations returned are primal variable bound violations, bound complementarities, the gradient of the Lagrangian, constraint violation, and constraint complementarity. Here, the constraints are treated as a single function rather than separating equality and inequality constraints. This method can only be called during an intermediate callback.

Only supports Ipopt >=3.14.0

Parameters:

scaled (bool) – Whether to scale the returned violations

Returns:

A dict containing the violation vector with keys "x_L_violation", "x_U_violation", "compl_x_L", "compl_x_U", "grad_lag_x", "g_violation", and "compl_g". If violation vectors cannot be obtained, None is returned.

Return type:

dict or None

set_problem_scaling(obj_scaling=1.0, x_scaling=None, g_scaling=None)

Optional function for setting scaling parameters for the problem.

To use the scaling parameters set the option nlp_scaling_method to user-scaling.

Parameters:

• obj_scaling (float) – Determines, how Ipopt should internally scale the objective function. For example, if this number is chosen to be 10, then Ipopt solves internally an optimization problem that has 10 times the value of the original objective. In particular, if this value is negative, then Ipopt will maximize the objective function instead of minimizing it.

• x_scaling (array-like, shape(n, )) – The scaling factors for the variables. If None, no scaling is done.

• g_scaling (array-like, shape(m, )) – The scaling factors for the constrains. If None, no scaling is done.

solve(x, lagrange=[], zl=[], zu=[])

Returns the optimal solution and an info dictionary.

Solves the posed optimization problem starting at point x.

Parameters:

• x (array-like, shape(n, )) – Initial guess.

• lagrange (array-like, shape(m, ), optional (default=[])) – Initial values for the constraint multipliers (only if warm start option is chosen).

• zl (array-like, shape(n, ), optional (default=[])) – Initial values for the multipliers for lower variable bounds (only if warm start option is chosen).

• zu (array-like, shape(n, ), optional (default=[])) – Initial values for the multipliers for upper variable bounds (only if warm start option is chosen).

Returns:

• x (numpy.ndarray, shape (n, )) – Optimal solution.

• info (dict with the following entries) –

  x: numpy.ndarray, shape (n, )

  optimal solution

  g: numpy.ndarray, shape (m, )

  constraints at the optimal solution

  obj_val: float

  objective value at optimal solution

  mult_g: numpy.ndarray, shape (m, )

  final values of the constraint multipliers

  mult_x_L: numpy.ndarray, shape (n, )

  bound multipliers at the solution

  mult_x_U: numpy.ndarray, shape (n, )

  bound multipliers at the solution

  status: int

  gives the status of the algorithm

  status_msg: str

  gives the status of the algorithm as a message

cyipopt.minimize_ipopt(fun, x0, args=(), kwargs=None, method=None, jac=None, hess=None, hessp=None, bounds=None, constraints=(), tol=None, callback=None, options=None)

Minimization using Ipopt with an interface like scipy.optimize.minimize().

Differences compared to scipy.optimize.minimize() include:

• A different default method: when method is not provided, Ipopt is used to solve the problem.

• Support for parameter kwargs: additional keyword arguments to be passed to the objective function, constraints, and their derivatives.

• Lack of support for callback and hessp with the default method.

This function can be used to solve general nonlinear programming problems of the form:

\[\min_ {x \in R^n} f(x)\]

subject to

\[ \begin{align}\begin{aligned}g_L \leq g(x) \leq g_U\\x_L \leq x \leq x_U\end{aligned}\end{align} \]

where \(x\) are the optimization variables, \(f(x)\) is the objective function, \(g(x)\) are the general nonlinear constraints, and \(x_L\) and \(x_U\) are the upper and lower bounds (respectively) on the decision variables. The constraints, \(g(x)\), have lower and upper bounds \(g_L\) and \(g_U\). Note that equality constraints can be specified by setting \(g^i_L = g^i_U\).

Parameters:

• fun (callable) – The objective function to be minimized: fun(x, *args, **kwargs) -> float.

• x0 (array-like, shape(n, )) – Initial guess. Array of real elements of shape (n,), where n is the number of independent variables.

• args (tuple, optional) – Extra arguments passed to the objective function and its derivatives (fun, jac, and hess).

• kwargs (dict, optional) – Extra keyword arguments passed to the objective function and its derivatives (fun, jac, hess).

• method (str, optional) – If unspecified (default), Ipopt is used. scipy.optimize.minimize() methods can also be used.

• jac (callable, optional) – The Jacobian (gradient) of the objective function: jac(x, *args, **kwargs) -> ndarray, shape(n, ). If None, SciPy’s approx_fprime is used.

• hess (callable, optional) – The Hessian of the objective function: hess(x) -> ndarray, shape(n, ). If None, the Hessian is computed using IPOPT’s numerical methods.

• hessp (callable, optional) – If method is one of the SciPy methods, this is a callable that produces the inner product of the Hessian and a vector. Otherwise, an error will be raised if a value other than None is provided.

• bounds (sequence of array-like shape(n, ) or scipy.optimize.Bounds, optional) –

  Simple bounds on decision variables. There are two ways to specify the bounds:

  1. Instance of scipy.optimize.Bounds class.

  2. Sequence of (min, max) pairs for each element in x. Use None to specify an infinite bound (i.e., no bound).

• constraints ({Constraint, dict}, optional) – Linear or nonlinear constraint specified by a dictionary, scipy.optimize.LinearConstraint, or scipy.optimize.NonlinearConstraint. See scipy.optimize.minimize() for more information. Note that the Jacobian of each constraint corresponds to the 'jac' key and must be a callable function with signature jac(x) -> {ndarray, coo_array}. If the constraint’s value of 'jac' is True, the constraint function fun must return a tuple (con_val, con_jac) consisting of the evaluated constraint con_val and the evaluated Jacobian con_jac.

• tol (float, optional (default=1e-8)) – The desired relative convergence tolerance, passed as an option to Ipopt. See [1] for details.

• options (dict, optional) –

  A dictionary of solver options.

  When method is unspecified (default: Ipopt), the options disp and maxiter are automatically mapped to their Ipopt equivalents print_level and max_iter, and eps is used to control the step size of finite difference gradient and constraint Jacobian approximations. All other options are passed directly to Ipopt. See [1] for details.

  For other values of method, options is passed to the SciPy solver. See [2] for details.

• callback (callable, optional) – This argument is ignored by the default method (Ipopt). If method is one of the SciPy methods, this is a callable that is called once per iteration. See [2] for details.

References

[1] (1,2)

COIN-OR Project. “Ipopt: Ipopt Options”. https://coin-or.github.io/Ipopt/OPTIONS.html

[2] (1,2)

The SciPy Developers. “scipy.optimize.minimize”. https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html

Examples

Consider the problem of minimizing the Rosenbrock function. The Rosenbrock function and its derivatives are implemented in scipy.optimize.rosen(), scipy.optimize.rosen_der(), and scipy.optimize.rosen_hess().

>>> from cyipopt import minimize_ipopt
>>> from scipy.optimize import rosen, rosen_der, rosen_hess
>>> x0 = [1.3, 0.7, 0.8, 1.9, 1.2]  # initial guess

If we provide the objective function but no derivatives, Ipopt finds the correct minimizer ([1, 1, 1, 1, 1]) with a minimum objective value of 0. However, it does not report success, and it requires many iterations and function evaluations before termination. This is because SciPy’s approx_fprime requires many objective function evaluations to approximate the gradient, and still the approximation is not very accurate, delaying convergence.

>>> res = minimize_ipopt(rosen, x0)
>>> res.success
False
>>> res.x
array([1., 1., 1., 1., 1.])
>>> res.nit, res.nfev, res.njev
(46, 528, 48)

To improve performance, provide the gradient using the jac keyword. In this case, Ipopt recognizes its own success, and requires fewer function evaluations to do so.

>>> res = minimize_ipopt(rosen, x0, jac=rosen_der)
>>> res.success
True
>>> res.nit, res.nfev, res.njev
(37, 200, 39)

For best results, provide the Hessian, too.

>>> res = minimize_ipopt(rosen, x0, jac=rosen_der, hess=rosen_hess)
>>> res.success
True
>>> res.nit, res.nfev, res.njev
(17, 29, 19)

cyipopt.set_logging_level(level=None)

Set the logger verbosity to the specified level.

Parameters:

level (int) – The verbosity of the logger. This threshold is used to determine which logging messages are logged by this module’s log() function.

class cyipopt.CyIpoptEvaluationError

An exception that should be raised in evaluation callbacks to signal to CyIpopt that a numerical error occured during function evaluation.

Whereas most exceptions that occur in callbacks are re-raised, exceptions of this type are ignored other than to communicate to Ipopt that an error occurred.

Ipopt handles evaluation errors differently depending on where they are raised (which evaluation callback returns false to Ipopt). When evaluation errors are raised in the following callbacks, Ipopt attempts to recover by cutting the step size. This is usually the desired behavior when an undefined value is encountered.

• objective

• constraints

When raised in the following callbacks, Ipopt fails with an “Invalid number” return status.

• gradient

• jacobian

• hessian

Raising an evaluation error in the following callbacks results is not supported.

• jacobianstructure

• hessianstructure

• intermediate