PyVMCON

pyvmcon.vmcon module

The Python implementation of the VMCON algorithm.

pyvmcon.vmcon.solve(problem: AbstractProblem, x: ndarray[tuple[int, ...], dtype[_ScalarType_co]], lbs: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, ubs: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, *, max_iter: int = 10, epsilon: float = 1e-08, qsp_options: dict[str, Any] | None = None, initial_B: ndarray | None = None, callback: Callable[[int, Result, ndarray[tuple[int, ...], dtype[_ScalarType_co]], float], None] | None = None, additional_convergence: Callable[[Result, ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]], None] | None = None, overwrite_convergence_criteria: bool = False) → tuple[ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], ndarray[tuple[int, ...], dtype[_ScalarType_co]], Result]

The main solving loop of the VMCON non-linear constrained optimiser.

Parameters:

  • problem (AbstractProblem) – Defines the system to be minimised optionally subject to constraints. Inequality constraints are feasible when >= 0.

  • x (ndarray) – The initial starting x of VMCON

  • lbs (ndarray) – Lower bounds of x. If None, no lower bounds are applied

  • ubs (ndarray) – Upper bounds of x. If None, no upper bounds are applied

  • max_iter (int) – The maximum iterations of VMCON before an exception is raised

  • epsilon (float) – The tolerance used to test if VMCON has converged

  • qsp_options (Optional[Dict[str, Any]]) – Dictionary of keyword arguments that are passed to the CVXPY Probelem.solve method. None will pass no additional arguments to the solver.

  • initial_B (ndarray) – Initial estimate of the Hessian matrix B. If None, B is the identity matrix of shape (n, n).

  • callback (Optional[Callable[[int, ndarray, Result], None]]) – A callable which takes the current iteration, the Result of the current design point, current design point, and the convergence parameter as arguments and returns None. This callable is called each iteration after the QSP is solved but before the convergence test.

  • additional_convergence (Optional[Callable[[Result, ndarray, ndarray, ndarray, ndarray], None]]) – A callabale which takes: the Result of the current design point, the current design point, the proposed search direction for the next design point, the equality Lagrange multipliers, and the inequality Lagrange multipliers. The callable returns a boolean indicating whether VMCON should be allowed to converge. Note that the original VMCON convergence criteria being False will stop convergence even if this callable returns True unless we overwrite_convergence_criteria.

  • overwrite_convergence_criteria (bool) – Ignore original VMCON convergence criteria and only evaluate convergence using additional_convergence.

Returns:

  • x (ndarray) – The solution vector which VMCON converges to.

  • lamda_equality (ndarray) – The Lagrange multipliers for the equality constraints at the solution vector.

  • lamda_inequality (ndarray) – The Lagrange multipliers for the inequality constraints at the solution vector.

  • result (Result) – The result from running the solution vector through the problem.

pyvmcon.problem module

Defines the interface for VMCON to exchange data with external software.

class pyvmcon.problem.AbstractProblem

Bases: ABC

A problem defines how VMCON gets data about your specific constrained system.

The problem class is required to provide several properties and data gathering methods but the implementation of these is not prescribed.

Note that when defining a problem, VMCON will minimise an objective function f(x) subject to some equality constraints e(x) = 0 and some inequality constraints i(x) >= 0.

property has_equality: bool

Indicates whether or not this problem has equality constraints.

property has_inequality: bool

Indicates whether or not this problem has inequality constraints.

abstract property num_equality: int

The number of equality constraints this problem has.

abstract property num_inequality: int

The number of inequality constraints this problem has.

property total_constraints: int

The total number of constraints m.

class pyvmcon.problem.Problem(f: ~collections.abc.Callable[[~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]]], ~pyvmcon.problem.ScalarType], df: ~collections.abc.Callable[[~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]]], ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]]], equality_constraints: list[~collections.abc.Callable[[~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]]], ~pyvmcon.problem.ScalarType]] = <factory>, inequality_constraints: list[~collections.abc.Callable[[~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]]], ~pyvmcon.problem.ScalarType]] = <factory>, dequality_constraints: list[~collections.abc.Callable[[~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]]], ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]]]] = <factory>, dinequality_constraints: list[~collections.abc.Callable[[~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]]], ~numpy.ndarray[tuple[int, ...], ~numpy.dtype[~numpy._typing._array_like._ScalarType_co]]]] = <factory>)

Bases: AbstractProblem

A simple implementation of an AbstractProblem.

It essentially acts as a caller to equations to gather all of the various data.

Note that VMCON assumes minimisation of f and that inequality constraints are feasible when they return a value >= 0.

dequality_constraints: list[Callable[[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]]]
df: Callable[[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]]
dinequality_constraints: list[Callable[[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], ndarray[tuple[int, ...], dtype[_ScalarType_co]]]]
equality_constraints: list[Callable[[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], ScalarType]]
f: Callable[[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], ScalarType]
inequality_constraints: list[Callable[[ndarray[tuple[int, ...], dtype[_ScalarType_co]]], ScalarType]]
property num_equality: int

The number of equality constraints this problem has.

property num_inequality: int

The number of inequality constraints this problem has.

class pyvmcon.problem.Result(f: ScalarType, df: ndarray[tuple[int, ...], dtype[_ScalarType_co]], eq: ndarray[tuple[int, ...], dtype[_ScalarType_co]], deq: ndarray[tuple[int, ...], dtype[_ScalarType_co]], ie: ndarray[tuple[int, ...], dtype[_ScalarType_co]], die: ndarray[tuple[int, ...], dtype[_ScalarType_co]])

Bases: object

The data from calling a problem.

deq: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

2D array of the derivatives of the equality constraints wrt each input variable.

df: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

Derivative of the objective function wrt to each input variable.

die: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

2D array of the derivatives of the inequality constraints wrt each input variable.

eq: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

1D array of the values of the equality constraints with shape.

f: ScalarType

Value of the objective function.

ie: ndarray[tuple[int, ...], dtype[_ScalarType_co]]

1D array of the values of the inequality constraints.

pyvmcon.exceptions module

Exceptions and errors raised within VMCON.

exception pyvmcon.exceptions.LineSearchConvergenceException(*args: object, x: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, result: Result | None = None, lamda_equality: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, lamda_inequality: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None)

Bases: VMCONConvergenceException

Indicates the line search was unable to converge.

exception pyvmcon.exceptions.QSPSolverException(*args: object, x: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, result: Result | None = None, lamda_equality: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, lamda_inequality: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None)

Bases: VMCONConvergenceException

Indicates VMCON failed to solve because the QSP Solver was unable to solve.

exception pyvmcon.exceptions.VMCONConvergenceException(*args: object, x: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, result: Result | None = None, lamda_equality: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None, lamda_inequality: ndarray[tuple[int, ...], dtype[_ScalarType_co]] | None = None)

Bases: Exception

Base error for VMCON errors.

This exception allows certain diagnostics to be passed and propagated with the exception.