ipyopt

https://ipyopt-devs.gitlab.io/ipyopt/
Admin
ipyopt is a Python library that extends optimization capabilities, integrating with SciPy's optimize...
Tokens:9,160
Snippets:31
Trust Score:7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Import ipyopt and numpy

Source: https://ipyopt-devs.gitlab.io/ipyopt/_sources/getting_started

Imports the ipyopt library for optimization and numpy for numerical operations. These are the fundamental libraries required to start using ipyopt.

```python
import numpy as np
import ipyopt
```

--------------------------------

### Create and Solve ipyopt Problem

Source: https://ipyopt-devs.gitlab.io/ipyopt/_sources/getting_started

Initializes an ipyopt.Problem instance with the defined functions and bounds, then solves the optimization problem using an initial guess for x.

```python
nlp = ipyopt.Problem(
    n=3,
    m=1,
    f=f,
    grad_f=grad_f,
    g=g,
    jac_g=jac_g,
    hess_g=hess_g,
    bounds=([-10]*3, [10]*3),
    constraints_upper_bounds=[4],
)
x, obj, status = nlp.solve(
    x=[0.1, 0.1, 0.1]
)
```

--------------------------------

### Import ipyopt and numpy

Source: https://ipyopt-devs.gitlab.io/ipyopt/getting_started

Imports necessary libraries for numerical operations and the ipyopt solver.

```python
import numpy as np
import ipyopt

```

--------------------------------

### Initialize and Solve ipyopt Problem in Python

Source: https://ipyopt-devs.gitlab.io/ipyopt/getting_started

Initializes an ipyopt Problem object with problem dimensions, bounds, sparsity information, and evaluation functions. Then, it solves the problem using a specified initial guess.

```python
nlp = ipyopt.Problem(
    n=3,
    x_l=np.array([-10.0, -10.0, -10.0]),
    x_u=np.array([10.0, 10.0, 10.0]),
    m=1,
    g_l=np.array([0.0]),
    g_u=np.array([4.0]),
    sparsity_indices_jac_g=(np.array([0, 0, 0]), np.array([0, 1, 2])),
    sparsity_indices_h=(np.array([0, 1, 2]), np.array([0, 1, 2])),
    eval_f=f,
    eval_grad_f=grad_f,
    eval_g=g,
    eval_jac_g=jac_g,
    eval_h=hess_g,
)

```

```python
x, obj, status = nlp.solve(x0=np.array([0.1, 0.1, 0.1]))

```

--------------------------------

### Define Objective Function f(x) and its Gradient

Source: https://ipyopt-devs.gitlab.io/ipyopt/_sources/getting_started

Defines the objective function f(x) and its gradient function grad_f(x). The gradient must be written into the 'out' argument for performance, as ipyopt avoids memory allocation.

```python
def f(x):
    return (x[0]**2 + x[1]**2 + x[2]**2)

def grad_f(x, out):
    out[0] = 2*x[0]
    out[1] = 2*x[1]
    out[2] = 2*x[2]
```

--------------------------------

### Define Objective Function (f) and its Gradient (grad_f) in Python

Source: https://ipyopt-devs.gitlab.io/ipyopt/getting_started

Defines the objective function f(x) and its gradient grad_f(x). The gradient function is optimized to write its output directly into the 'out' argument for performance.

```python
def f(x: NDArray[np.float64]) -> float:
    """Objective value."""
    out: float = np.sum(x**2)
    return out

```

```python
def grad_f(x: NDArray[np.float64], out: NDArray[np.float64]) -> NDArray[np.float64]:
    """Gradient of the objective."""
    out[()] = 2.0 * x
    return out

```

--------------------------------

### Install Cython and Import PyCapsules

Source: https://ipyopt-devs.gitlab.io/ipyopt/_sources/capsules

This code demonstrates how to install Cython's dynamic compilation and import the compiled PyCapsules from a Cython module. This is essential for using C callbacks with ipyopt.

```python
import pyximport
pyximport.install(language_level=3)

from hs071_capsules import __pyx_capi__ as capsules

# Example usage with ipyopt.Problem (details omitted for brevity)
# nlp = ipyopt.Problem(
#     ...
#     capsules["f"],
#     capsules["grad_f"],
#     capsules["g"],
#     capsules["jac_g"],
#     capsules["h"],
# )
```

--------------------------------

### Define Constraint Function (g) and its Jacobian (jac_g) in Python

Source: https://ipyopt-devs.gitlab.io/ipyopt/getting_started

Defines the constraint function g(x) and its Jacobian jac_g(x). The Jacobian is implemented to efficiently calculate its values and store them in the 'out' argument.

```python
def g(x: NDArray[np.float64], out: NDArray[np.float64]) -> NDArray[np.float64]:
    """Constraint function: squared distance to (1, 0, ..., 0)."""
    out[0] = (x[0] - 1.0) ** 2 + np.sum(x[1:] ** 2)
    return out

```

```python
def jac_g(x: NDArray[np.float64], out: NDArray[np.float64]) -> NDArray[np.float64]:
    """Jacobian of the constraint function."""
    out[()] = 2.0 * x
    out[0] -= 2.0
    return out

```

--------------------------------

### hs071 Example using Symbolic Compilation - Python

Source: https://ipyopt-devs.gitlab.io/ipyopt/_sources/sym_diff

This Python code demonstrates the `ipyopt.sym_compile` module to automatically generate symbolic derivatives and C code for the `hs071` optimization problem. It requires `numpy` and defines symbolic variables and objective/constraint functions.

```python
import numpy
from ipyopt import Problem
from ipyopt.sym_compile import sym_compile

# Define symbolic variables
x = sym_compile.array_sym(2, "x")

# Define objective function and constraint residuals
def f(x):
    return x[0] * x[1]

def g(x):
    return x[0] + x[1]

# Compile symbolic expressions to C code and load as Python extension
# This function generates C code, compiles it, and loads it as a Python extension.
# The compiled functions for objective and constraints are returned.
# The compiled_code is a dictionary containing PyCapsule objects for the compiled functions.
compiled_code = sym_compile([f, g])

# Create an ipyopt problem instance using the compiled code
# The compiled_code dictionary is passed to the Problem constructor,
# which expects PyCapsule objects for the objective and constraint functions.
problem = Problem(compiled_code["f"], compiled_code["g"])

# Define initial point and bounds (example values)
x0 = [1.5, 1.5]
lb = [-10.0, -10.0]
ub = [10.0, 10.0]
clb = [1.0, 1.0]
cub = [1.0, 1.0]

# Set bounds and constraints
problem.set_lower_bounds(lb)
problem.set_upper_bounds(ub)
problem.set_constraint_lower_bounds(clb)
problem.set_constraint_upper_bounds(cub)

# Solve the problem
# The solution is stored in the problem object after calling solve()
# x, obj, mult_g, mult_x = problem.solve(x0)

# print("Solution:", x)
# print("Objective value:", obj)
```

--------------------------------

### Define Constraint g(x) and its Jacobian

Source: https://ipyopt-devs.gitlab.io/ipyopt/_sources/getting_started

Defines the constraint function g(x) and its Jacobian function jac_g(x). The Jacobian provides information about the non-zero elements of the constraint's derivative. The sparsity pattern is provided as pairs of row and column indices.

```python
def g(x):
    return np.array([(x[0] - 1)**2 + x[1]**2 + x[2]**2])

def jac_g(x, out):
    out[0] = 2*(x[0] - 1)
    out[1] = 2*x[1]
    out[2] = 2*x[2]
```

--------------------------------

### Define NLP problem with symbolic derivatives using ipyopt

Source: https://ipyopt-devs.gitlab.io/ipyopt/sym_diff

This example demonstrates how to define a Non-Linear Programming (NLP) problem using ipyopt's symbolic compilation. It uses `sympy` to create symbolic variables and expressions for the objective function and constraints, then compiles them into C code and loads them into an ipyopt Problem.

```python
import numpy as np

import ipyopt
from ipyopt.sym_compile import SymNlp, array_sym

n = 4
m = 2

x = array_sym("x", n)

f = x[0] * x[3] * (x[0] + x[1] + x[2]) + x[2]
g = [x[0] * x[1] * x[2] * x[3], x[0] * x[0] + x[1] * x[1] + x[2] * x[2] + x[3] * x[3]]

c_api = SymNlp(f, g).compile()

nlp = ipyopt.Problem(
    n=n,
    x_l=np.ones(n),
    x_u=np.full(n, 5.0),
    m=m,
    g_l=np.array([25.0, 40.0]),
    g_u=np.array([2.0e19, 40.0]),
    **c_api,
)

```

--------------------------------

### Define Hessian of the Lagrangian (hess_g) in Python

Source: https://ipyopt-devs.gitlab.io/ipyopt/getting_started

Defines the Hessian of the Lagrangian function, hess_g. This function calculates the non-zero entries of the Hessian, which can be used for performance optimization. If not provided, Ipopt will approximate it.

```python
def hess_g(
    x: NDArray[np.float64],
    lagrange: NDArray[np.float64],
    obj_factor: float,
    out: NDArray[np.float64],
) -> NDArray[np.float64]:
    """Hessian of the constraint function."""
    out[()] = np.full_like(x, 2.0 * (obj_factor + lagrange[0]))
    return out

```

--------------------------------

### Define Hessian of the Lagrangian

Source: https://ipyopt-devs.gitlab.io/ipyopt/_sources/getting_started

Defines the Hessian of the Lagrangian function. This function calculates the second derivatives of the objective and constraints with respect to x. Providing the Hessian can significantly improve performance compared to numerical approximation.

```python
def hess_g(x, lagrange, obj_factor, out):
    out[0, 0] = 2 * (obj_factor + lagrange[0])
    out[1, 1] = 2 * (obj_factor + lagrange[0])
    out[2, 2] = 2 * (obj_factor + lagrange[0])
```

--------------------------------

### Using ipyopt with scipy.optimize.minimize

Source: https://ipyopt-devs.gitlab.io/ipyopt/_sources/scipy

Demonstrates how to call the minimize function from SciPy's optimize module, specifying 'ipyopt.optimize.ipopt' as the method. This function requires specific arguments for objective function, initial guess, Jacobian, and constraints.

```python
result = scipy.optimize.minimize(
    fun=...,
    x0=...,
    jac=...,
    constraints=...,
    method=ipyopt.optimize.ipopt,
    ...
    )
```

--------------------------------

### Use Ipopt for Optimization with scipy.optimize.minimize

Source: https://ipyopt-devs.gitlab.io/ipyopt/reference

The ipyopt.optimize.ipopt function serves as a 'method' argument for scipy.optimize.minimize, enabling the use of the Ipopt solver. It requires the objective function, initial guess, and crucially, the gradient (or a wrapper for scipy.LowLevelCallable/PyCapsule via JacEnvelope). Optional arguments include Hessians, bounds, constraints, tolerances, callbacks, and various IPOpt-specific scaling and option parameters.

```python
ipyopt.optimize.ipopt(_fun : Callable[[NDArray[np.float64]], float]_, _x0 : NDArray[np.float64]_, _args : tuple[()]_, _*_ , _jac : Callable[[NDArray[np.float64], NDArray[np.float64]], Any] | JacEnvelope[Any]_, _hess : Callable[[NDArray[np.float64], NDArray[np.float64], float, NDArray[np.float64]], Any] | None = None_, _bounds : Sequence[tuple[float, float]] | None = None_, _constraints : Constraint_, _tol : float | None = None_, _callback : Callable[[int, int, float, float, float, float, float, float, float, float], Any] | None = None_, _maxiter : int | None = None_, _disp : bool = False_, _obj_scaling : float = 1.0_, _x_scaling : NDArray[np.float64] | None = None_, _constraint_scaling : NDArray[np.float64] | None = None_, _hess_sparsity_indices : tuple[Sequence[int] | NDArray[np.int64], Sequence[int] | NDArray[np.int64]] | None = None_, _** kwargs: Any_) → OptimizeResult
    
    Ipopt Method for scipy.optimize.minimize (to be used as `method` argument). 

    Parameters:
        
      * **fun** – Function to optimize.
      * **x0** – same as in scipy.optimize.minimize
      * **args** – must be `()`
      * **jac** – Gradient of `fun`. If you want to pass a scipy.LowLevelCallable or a PyCapsule, you have to wrap it with `JacEnvelope` (see its documentation). In contrast to standard scipy.optimize.minimize this argument is mandatory. Use scipy.optimize.approx_fprime to numerically approximate the derivative for pure python callables. This wont work for scipy.LowLevelCallable / PyCapsule.
      * **hess** – 
    Hessian of the Lagrangian L. `hess(x, lag, obj_fac, out)` should write into `out` the value of the Hessian of:
    ```
    L = obj_fac*fun + <lag, constraint.fun>,

    ```

    where `<.,.>` denotes the euclidean inner product.
      * **bounds** – Bounds for the x variable space
      * **constraints** – See doc of `Constraint`
      * **tol** – According to scipy.optimize.minimize
      * **callback** – Will be called after each iteration. Must have the same signature as the `intermediate_callback` argument for `ipyopt.Problem`. See the Ipopt documentation for the meaning of the arguments.
      * **maxiter** – According to scipy.optimize.minimize.
      * **disp** – According to scipy.optimize.minimize.
      * **obj_scaling** – Scaling factor for the objective value.
      * **x_scaling** – Scaling factors for the x space.
      * **constraint_scaling** – Scaling factors for the constraint space.
      * **hess_sparsity_indices** – Sparsity indices for `hess`. Must be given in the form `((i[0], ..., i[n-1]), (j[0], ..., j[n-1]))`, where `(i[k], j[k]), k=0,...,n-1` are the non zero entries of `hess`.
      * **kwargs** – Options which will be forwarded to the call of IPOpt.


    Returns:
        
    An scipy.optimize.OptimizeResult instance
```

--------------------------------

### Ipopt Optimization Method

Source: https://ipyopt-devs.gitlab.io/ipyopt/reference

Provides the Ipopt optimization algorithm as a method for `scipy.optimize.minimize`. This function allows users to leverage the power of Ipopt for solving optimization problems within the familiar scipy framework.

```APIDOC
## ipyopt.optimize.ipopt

### Description
Ipopt optimization method for `scipy.optimize.minimize`. This function serves as the 'method' argument, enabling the use of the Ipopt solver for minimization tasks.

### Method

`ipopt`

### Parameters

*   **fun** (`Callable[[NDArray[np.float64]], float]`) - The objective function to be minimized.
*   **x0** (`NDArray[np.float64]`) - The initial guess for the optimization variables.
*   **args** (`tuple[()]`) - Must be an empty tuple `()`.
*   **jac** (`Callable[[NDArray[np.float64], NDArray[np.float64]], Any] | JacEnvelope[Any]`) - The gradient of the objective function. Can be a callable or a `JacEnvelope` wrapper for `scipy.LowLevelCallable` or PyCapsule objects. This argument is mandatory.
*   **hess** (`Callable[[NDArray[np.float64], NDArray[np.float64], float, NDArray[np.float64]], Any] | None`) - The Hessian of the Lagrangian. Signature: `hess(x, lag, obj_fac, out)`. `out` should be updated with the Hessian value.
*   **bounds** (`Sequence[tuple[float, float]] | None`) - Bounds for the variables (e.g., `[(low1, high1), (low2, high2), ...]`).
*   **constraints** (`Constraint`) - Constraint definitions using the `Constraint` class.
*   **tol** (`float | None`) - Tolerance for termination criteria.
*   **callback** (`Callable[[int, int, float, float, float, float, float, float, float, float], Any] | None`) - A callback function called after each iteration.
*   **maxiter** (`int | None`) - Maximum number of iterations.
*   **disp** (`bool`) - If True, prints convergence messages.
*   **obj_scaling** (`float`) - Scaling factor for the objective function.
*   **x_scaling** (`NDArray[np.float64] | None`) - Scaling factors for the optimization variables.
*   **constraint_scaling** (`NDArray[np.float64] | None`) - Scaling factors for the constraints.
*   **hess_sparsity_indices** (`tuple[Sequence[int] | NDArray[np.int64], Sequence[int] | NDArray[np.int64]] | None`) - Sparsity structure for the Hessian.
*   **kwargs** - Additional keyword arguments passed directly to the Ipopt solver.

### Returns

*   `OptimizeResult` - An `scipy.optimize.OptimizeResult` instance containing the optimization results.
```

--------------------------------

### Ipopt Optimization Method for Scipy

Source: https://ipyopt-devs.gitlab.io/ipyopt/scipy

Provides the Ipopt solver as a method for scipy.optimize.minimize. It accepts the objective function, initial guess, and optionally Jacobian, Hessian, bounds, constraints, and various solver options for IPOpt.

```python
def ipopt(_fun : Callable[[NDArray[np.float64]], float]_, _x0 : NDArray[np.float64], _args : tuple[()]_, _* , _jac : Callable[[NDArray[np.float64], NDArray[np.float64]], Any] | JacEnvelope[Any]_, _hess : Callable[[NDArray[np.float64], NDArray[np.float64], float, NDArray[np.float64]], Any] | None = None_, _bounds : Sequence[tuple[float, float]] | None = None_, _constraints : Constraint_, _tol : float | None = None_, _callback : Callable[[int, int, float, float, float, float, float, float, float, float], Any] | None = None_, _maxiter : int | None = None_, _disp : bool = False_, _obj_scaling : float = 1.0_, _x_scaling : NDArray[np.float64] | None = None_, _constraint_scaling : NDArray[np.float64] | None = None_, _hess_sparsity_indices : tuple[Sequence[int] | NDArray[np.int64], Sequence[int] | NDArray[np.int64]] | None = None_, _** kwargs: Any_) → OptimizeResult:
    """Ipopt Method for scipy.optimize.minimize (to be used as `method` argument).

    Parameters:
        
      * **fun** – Function to optimize.
      * **x0** – same as in scipy.optimize.minimize
      * **args** – must be `()`
      * **jac** – Gradient of `fun`. If you want to pass a scipy.LowLevelCallable or a PyCapsule, you have to wrap it with `JacEnvelope` (see its documentation). In contrast to standard scipy.optimize.minimize this argument is mandatory. Use scipy.optimize.approx_fprime to numerically approximate the derivative for pure python callables. This wont work for scipy.LowLevelCallable / PyCapsule.
      * **hess** – 
Hessian of the Lagrangian L. `hess(x, lag, obj_fac, out)` should write into `out` the value of the Hessian of:
    ```
    L = obj_fac*fun + <lag, constraint.fun>,

    ```

    where `<.,.>` denotes the euclidean inner product.
      * **bounds** – Bounds for the x variable space
      * **constraints** – See doc of `Constraint`
      * **tol** – According to scipy.optimize.minimize
      * **callback** – Will be called after each iteration. Must have the same signature as the `intermediate_callback` argument for `ipyopt.Problem`. See the Ipopt documentation for the meaning of the arguments.
      * **maxiter** – According to scipy.optimize.minimize.
      * **disp** – According to scipy.optimize.minimize.
      * **obj_scaling** – Scaling factor for the objective value.
      * **x_scaling** – Scaling factors for the x space.
      * **constraint_scaling** – Scaling factors for the constraint space.
      * **hess_sparsity_indices** – Sparsity indices for `hess`. Must be given in the form `((i[0], ..., i[n-1]), (j[0], ..., j[n-1]))`, where `(i[k], j[k]), k=0,...,n-1` are the non zero entries of `hess`.
      * **kwargs** – Options which will be forwarded to the call of IPOpt.

    Returns:
        
    An scipy.optimize.OptimizeResult instance
      *[*]: Keyword-only parameters separator (PEP 3102) 
    """
    pass

```

--------------------------------

### Enable Cython's Just-In-Time Compilation

Source: https://ipyopt-devs.gitlab.io/ipyopt/capsules

This Python code snippet demonstrates how to use Cython's `pyximport` to enable just-in-time compilation of Cython files (`.pyx`). It sets the language level to 3, which is necessary for modern Python syntax within Cython.

```Python
import pyximport
pyximport.install(language_level=3)

```

--------------------------------

### Define Objective and Constraints using Cython

Source: https://ipyopt-devs.gitlab.io/ipyopt/_sources/capsules

This snippet defines the objective function, constraint residuals, and their derivatives using Cython syntax. It's a common pattern for integrating C-level performance with Python's ease of use.

```python
import cython

@cython.ccall
def f(x):
    # Objective function implementation
    pass

@cython.ccall
def grad_f(x):
    # Gradient of objective function implementation
    pass

@cython.ccall
def g(x):
    # Constraint residuals implementation
    pass

@cython.ccall
def jac_g(x):
    # Jacobian of constraint residuals implementation
    pass

@cython.ccall
def h(x, lambda_):
    # Hessian of Lagrangian implementation
    pass
```

--------------------------------

### ipopt Method

Source: https://ipyopt-devs.gitlab.io/ipyopt/scipy

IPOPT method for scipy.optimize.minimize. This function serves as the 'method' argument for the minimize function, providing an interface to the IPOPT solver.

```APIDOC
## Function ipyopt.optimize.ipopt

### Description
Ipopt Method for scipy.optimize.minimize (to be used as `method` argument).

### Method
Any (Used as a method argument for `scipy.optimize.minimize`)

### Endpoint
N/A (Function within a library)

### Parameters
#### Positional Arguments
* **_fun** (Callable[[NDArray[np.float64]], float]) - Function to optimize.
* **_x0** (NDArray[np.float64]) - Initial guess for the solution.
* **_args** (tuple[()]) - Must be an empty tuple `()`.

#### Keyword Arguments
* **jac** (Callable[[NDArray[np.float64], NDArray[np.float64]], Any] | JacEnvelope[Any]) - Gradient of `_fun`. If passing a scipy.LowLevelCallable or PyCapsule, wrap it with `JacEnvelope`. Use `scipy.optimize.approx_fprime` for numerical approximation with pure Python callables.
* **hess** (Callable[[NDArray[np.float64], NDArray[np.float64], float, NDArray[np.float64]], Any] | None) - Hessian of the Lagrangian L. Signature: `hess(x, lag, obj_fac, out)` should write the Hessian value into `out`. L = obj_fac*fun + <lag, constraint.fun>.
* **bounds** (Sequence[tuple[float, float]] | None) - Bounds for the x variable space.
* **constraints** (Constraint_) - Constraints definition, created using the `Constraint` class.
* **tol** (float | None) - Tolerance for termination, as per `scipy.optimize.minimize`.
* **callback** (Callable[[int, int, float, float, float, float, float, float, float, float], Any] | None) - Called after each iteration. Signature matches `ipyopt.Problem.intermediate_callback`.
* **maxiter** (int | None) - Maximum number of iterations, as per `scipy.optimize.minimize`.
* **disp** (bool) - If True, prints convergence messages, as per `scipy.optimize.minimize`.
* **obj_scaling** (float) - Scaling factor for the objective value.
* **x_scaling** (NDArray[np.float64] | None) - Scaling factors for the x space.
* **constraint_scaling** (NDArray[np.float64] | None) - Scaling factors for the constraint space.
* **hess_sparsity_indices** (tuple[Sequence[int] | NDArray[np.int64], Sequence[int] | NDArray[np.int64]] | None) - Sparsity indices for `hess`. Format: `((i[0], ..., i[n-1]), (j[0], ..., j[n-1]))`.
* **kwargs** (Any) - Additional options to be forwarded to the IPOpt call.

### Returns
* **OptimizeResult** - An `scipy.optimize.OptimizeResult` instance containing the optimization results.
```

--------------------------------

### Define Constraints for scipy.optimize.minimize using ipyopt

Source: https://ipyopt-devs.gitlab.io/ipyopt/reference

Defines a Constraint class to structure optimization constraints for scipy.optimize.minimize. Supports defining the constraint function, its Jacobian, lower/upper bounds, and sparsity structure.

```python
class _ipyopt.optimize.Constraint(_fun : Callable[[NDArray[np.float64], NDArray[np.float64]], Any]_, _jac : Callable[[NDArray[np.float64], NDArray[np.float64]], Any]_, _lb : NDArray[np.float64]_, _ub : NDArray[np.float64]_, _jac_sparsity_indices : tuple[Sequence[int] | NDArray[np.int64], Sequence[int] | NDArray[np.int64]] | None = None_)
    
    Bases: `NamedTuple`
    Constraints definition.
    To be passed to scipy.optimize.minimize as its `constraints` argument when using the ipopt method.
    The constraints are defined by:
    ```
    lb <= fun(x) <= ub

    ```


    fun _: Callable[[NDArray[np.float64], NDArray[np.float64]], Any]_
        
        Constraint function.
        Signature is `fun(x: NDArray[np.float64], out: NDArray[np.float64]) -> Any` 

    jac _: Callable[[NDArray[np.float64], NDArray[np.float64]], Any]_
        
        Jacobian of `fun`.
        Signature is `jac(x: NDArray[np.float64], out: NDArray[np.float64]) -> Any` 

    jac_sparsity_indices _: tuple[Sequence[int] | NDArray[np.int64], Sequence[int] | NDArray[np.int64]] | None_
        
        Sparsity structure of `jac`.
        Must be given in the form `((i[0], ..., i[m-1]), (j[0], ..., j[m-1]))`, where `(i[k], j[k]), k=0,...,m-1` are the non zero entries of `jac` 

    lb _: NDArray[np.float64]_
        
        Lower bounds 

    ub _: NDArray[np.float64]_
        
        Upper bounds 

```

--------------------------------

### Define Objective, Gradient, Constraints, Jacobian, and Hessian using Cython

Source: https://ipyopt-devs.gitlab.io/ipyopt/capsules

This Cython code defines C-level functions for the objective function, its gradient, constraint residuals, their Jacobian, and the Hessian. These functions are designed to be encapsulated as PyCapsules for use with ipyopt. The code includes necessary C type definitions and function signatures.

```Cython
import cython
cdef extern from "stdbool.h":
    ctypedef bint bool 

cdef api:
    bool f(int n, const double *x, double *obj_value, void*userdata):
        obj_value[0] = x[0] * x[3] * (x[0] + x[1] + x[2]) + x[2]
        return True

    bool grad_f(int n, const double *x, double *out, void *userdata):
        out[0] = x[0] * x[3] + x[3] * (x[0] + x[1] + x[2])
        out[1] = x[0] * x[3]
        out[2] = x[0] * x[3] + 1.0
        out[3] = x[0] * (x[0] + x[1] + x[2])
        return True

    bool g(int n, const double *x, int m, double *out, void *userdata):
        out[0] = x[0] * x[1] * x[2] * x[3]
        out[1] = x[0] * x[0] + x[1] * x[1] + x[2] * x[2] + x[3] * x[3]
        return True

    bool jac_g(int n, const double *x, int m, int n_out, double *out,
                      void *userdata):
        out[0] = x[1] * x[2] * x[3]
        out[1] = x[0] * x[2] * x[3]
        out[2] = x[0] * x[1] * x[3]
        out[3] = x[0] * x[1] * x[2]
        out[4] = 2.0 * x[0]
        out[5] = 2.0 * x[1]
        out[6] = 2.0 * x[2]
        out[7] = 2.0 * x[3]
        out[8] = x[0] * x[1] * x[2] * x[3]
        return True

    bool h(int n, const double *x, double obj_factor, int m,
                  const double *lagrange, int n_out, double *out, void *userdata):
        out[0] = obj_factor * (2 * x[3])
        out[1] = obj_factor * (x[3])
        out[2] = 0
        out[3] = obj_factor * (x[3])
        out[4] = 0
        out[5] = 0
        out[6] = obj_factor * (2 * x[0] + x[1] + x[2])
        out[7] = obj_factor * (x[0])
        out[8] = obj_factor * (x[0])
        out[9] = 0
        out[1] += lagrange[0] * (x[2] * x[3])

        out[3] += lagrange[0] * (x[1] * x[3])
        out[4] += lagrange[0] * (x[0] * x[3])

        out[6] += lagrange[0] * (x[1] * x[2])
        out[7] += lagrange[0] * (x[0] * x[2])
        out[8] += lagrange[0] * (x[0] * x[1])
        out[0] += lagrange[1] * 2
        out[2] += lagrange[1] * 2
        out[5] += lagrange[1] * 2
        out[9] += lagrange[1] * 2
        return True

```

--------------------------------

### JacEnvelope Wrapper

Source: https://ipyopt-devs.gitlab.io/ipyopt/reference

A utility to wrap PyCapsule or scipy.LowLevelCallable objects for use as the Jacobian argument in `scipy.optimize.minimize`. This ensures compatibility when the callable is not directly recognized.

```APIDOC
## ipyopt.optimize.JacEnvelope

### Description
A wrapper for PyCapsule / scipy.LowLevelCallable objects to be passed as the `jac` argument to `scipy.optimize.minimize`. This wrapper circumvents issues where non-callablejac arguments are treated as booleans.

### Parameters

*   **inner** (`T`) - The PyCapsule or scipy.LowLevelCallable object to wrap.
```

--------------------------------

### JacEnvelope Class

Source: https://ipyopt-devs.gitlab.io/ipyopt/scipy

A wrapper for PyCapsule / scipy.LowLevelCallable objects to be used as the `jac` argument in scipy.optimize.minimize.

```APIDOC
## Class ipyopt.optimize.JacEnvelope

### Description
A wrapper for PyCapsule / scipy.LowLevelCallable objects. This allows those kind of objects to passed as the `jac` argument of scipy.optimize.minimize. If the `jac` argument is not callable, then scipy.optimize.minimize will assume that it is a `bool`. It will be evaluated to a `bool` and `None` will be passed to the method. To circumvent this, wrap your PyCapsule / scipy.LowLevelCallable objects with this wrapper and pass it to scipy.optimize.minimize as the `jac` argument.

### Parameters
#### Path Parameters
* **_inner** (T_) - The object to wrap (e.g., PyCapsule or scipy.LowLevelCallable).
```

--------------------------------

### Define Constraints for Scipy Optimize

Source: https://ipyopt-devs.gitlab.io/ipyopt/scipy

Defines a constraint for use with scipy.optimize.minimize using the Ipopt method. It requires a callable function for the constraint, its Jacobian, and lower/upper bounds. Optionally, sparsity indices for the Jacobian can be provided.

```python
class Constraint:
    """Constraints definition.

    To be passed to scipy.optimize.minimize as its `constraints` argument when using the ipopt method.
    The constraints are defined by:
    ```
    lb <= fun(x) <= ub
    ```
    """
    def __init__(self, _fun : Callable[[NDArray[np.float64], NDArray[np.float64]], Any]_, _jac : Callable[[NDArray[np.float64], NDArray[np.float64]], Any]_, _lb : NDArray[np.float64]_, _ub : NDArray[np.float64]_, _jac_sparsity_indices : tuple[Sequence[int] | NDArray[np.int64], Sequence[int] | NDArray[np.int64]] | None = None_) -> None:
        # Constraint function.
        # Signature is `fun(x: NDArray[np.float64], out: NDArray[np.float64]) -> Any` 
        self.fun = _fun
        # Jacobian of `fun`.
        # Signature is `jac(x: NDArray[np.float64], out: NDArray[np.float64]) -> Any`
        self.jac = _jac
        # Lower bounds 
        self.lb = _lb
        # Upper bounds 
        self.ub = _ub
        # Sparsity structure of `jac`.
        # Must be given in the form `((i[0], ..., i[m-1]), (j[0], ..., j[m-1]))`, where `(i[k], j[k]), k=0,...,m-1` are the non zero entries of `jac` 
        self.jac_sparsity_indices = _jac_sparsity_indices

```

--------------------------------

### Constraint Definition

Source: https://ipyopt-devs.gitlab.io/ipyopt/reference

Defines the structure for constraints in the optimization problem, including the constraint function, its Jacobian, and bounds. This is used when passing constraints to `scipy.optimize.minimize` with the 'ipopt' method.

```APIDOC
## ipyopt.optimize.Constraint

### Description
Represents a single constraint defined by `lb <= fun(x) <= ub`. This structure is used to define constraints for the Ipopt solver via `scipy.optimize.minimize`.

### Fields

*   **fun** (`Callable[[NDArray[np.float64], NDArray[np.float64]], Any]`) - The constraint function. Signature: `fun(x: NDArray[np.float64], out: NDArray[np.float64]) -> Any`.
*   **jac** (`Callable[[NDArray[np.float64], NDArray[np.float64]], Any]`) - The Jacobian of the constraint function. Signature: `jac(x: NDArray[np.float64], out: NDArray[np.float64]) -> Any`.
*   **jac_sparsity_indices** (`tuple[Sequence[int] | NDArray[np.int64], Sequence[int] | NDArray[np.int64]] | None`) - Sparsity structure of the Jacobian. Format: `((i[0], ..., i[m-1]), (j[0], ..., j[m-1]))`.
*   **lb** (`NDArray[np.float64]`) - Lower bounds for the constraint function's output.
*   **ub** (`NDArray[np.float64]`) - Upper bounds for the constraint function's output.
```

--------------------------------

### Wrap PyCapsule/scipy.LowLevelCallable for ipyopt's jac argument

Source: https://ipyopt-devs.gitlab.io/ipyopt/reference

Provides a JacEnvelope wrapper for PyCapsule or scipy.LowLevelCallable objects, ensuring they are correctly passed as the `jac` argument to scipy.optimize.minimize when using the ipyopt method. This overcomes issues where non-callable jac arguments are misinterpreted.

```python
class _ipyopt.optimize.JacEnvelope(_inner : T_)
    
    Bases: `Generic`[`T`]
A wrapper for PyCapsule / scipy.LowLevelCallable objects.
This allows those kind of objects to passed as the `jac` argument of scipy.optimize.minimize.
If the `jac` argument is not callable, then scipy.optimize.minimize will assume that it is a `bool`. It will be evaluated to a `bool` and `None` will be passed to the method. To circumwent this, wrap your PyCapsule / scipy.LowLevelCallable objects with this wrapper and pass it to scipy.optimize.minimize as the `jac` argument. 
```

--------------------------------

### Constraint Class

Source: https://ipyopt-devs.gitlab.io/ipyopt/scipy

Defines constraints for optimization problems in the form lb <= fun(x) <= ub. Used with scipy.optimize.minimize when the 'ipopt' method is specified.

```APIDOC
## Class ipyopt.optimize.Constraint

### Description
Constraints definition. To be passed to scipy.optimize.minimize as its `constraints` argument when using the ipopt method. The constraints are defined by: `lb <= fun(x) <= ub`.

### Parameters
#### Path Parameters
* **_fun** (Callable[[NDArray[np.float64], NDArray[np.float64]], Any]) - The constraint function.
* **_jac** (Callable[[NDArray[np.float64], NDArray[np.float64]], Any]) - The Jacobian of `_fun`.
* **_lb** (NDArray[np.float64]) - Lower bounds for the constraint function.
* **_ub** (NDArray[np.float64]) - Upper bounds for the constraint function.
* **_jac_sparsity_indices** (tuple[Sequence[int] | NDArray[np.int64], Sequence[int] | NDArray[np.int64]] | None) - Sparsity structure of `_jac`. Must be given in the form `((i[0], ..., i[m-1]), (j[0], ..., j[m-1]))`, where `(i[k], j[k]), k=0,...,m-1` are the non zero entries of `_jac`.

### Attributes
* **fun** (Callable[[NDArray[np.float64], NDArray[np.float64]], Any]) - Constraint function.
* **jac** (Callable[[NDArray[np.float64], NDArray[np.float64]], Any]) - Jacobian of `fun`.
* **lb** (NDArray[np.float64]) - Lower bounds.
* **ub** (NDArray[np.float64]) - Upper bounds.
* **jac_sparsity_indices** (tuple[Sequence[int] | NDArray[np.int64], Sequence[int] | NDArray[np.int64]] | None) - Sparsity structure of `jac`.
```

--------------------------------

### Import PyCapsules from Compiled Cython Extension

Source: https://ipyopt-devs.gitlab.io/ipyopt/capsules

This Python code shows how to import the compiled PyCapsules from a Cython extension (e.g., `hs071_capsules`). The `__pyx_capi__` attribute of the compiled module contains the PyCapsule objects, which can then be passed to the `ipyopt.Problem` constructor.

```Python
from hs071_capsules import __pyx_capi__ as capsules

nlp = ipyopt.Problem(
    ...
    capsules["f"],
    capsules["grad_f"],
    capsules["g"],
    capsules["jac_g"],
    capsules["h"],
)

```

--------------------------------

### Wrap Jacobian for Scipy Minimize

Source: https://ipyopt-devs.gitlab.io/ipyopt/scipy

Wraps PyCapsule or scipy.LowLevelCallable objects to be passed as the `jac` argument to scipy.optimize.minimize. This ensures that these objects are correctly evaluated by the optimizer when they are not directly callable.

```python
class JacEnvelope:
    """A wrapper for PyCapsule / scipy.LowLevelCallable objects.

    This allows those kind of objects to passed as the `jac` argument of scipy.optimize.minimize.
    If the `jac` argument is not callable, then scipy.optimize.minimize will assume that it is a `bool`. It will be evaluated to a `bool` and `None` will be passed to the method. To circumwent this, wrap your PyCapsule / scipy.LowLevelCallable objects with this wrapper and pass it to scipy.optimize.minimize as the `jac` argument.
    """
    def __init__(self, _inner : T_) -> None:
        self._inner = _inner

```
Tokens:
Raw