PyVMCON

pyvmcon.vmcon module

pyvmcon.vmcon.calculate_new_B(result: Result, new_result: Result, B: ndarray, x_jm1: ndarray, x_j: ndarray, lamda_equality: ndarray, lamda_inequality: ndarray) → ndarray
pyvmcon.vmcon.convergence_value(result: Result, delta_j: ndarray, lamda_equality: ndarray, lamda_inequality: ndarray) → float

Test if the convergence criteria of VMCON have been met. Equation 11 of the VMCON paper. Note this tests convergence at the point (j-1)th evaluation point.

Parameters:

  • result (Result) – Contains the data for the (j-1)th evaluation point.

  • delta_j (ndarray) – The search direction for the jth evaluation point.

  • lambda_equality (ndarray) – The Lagrange multipliers for equality constraints for the jth evaluation point.

  • lambda_inequality (ndarray) – The Lagrange multipliers for inequality constraints for the jth evaluation point.

pyvmcon.vmcon.perform_linesearch(problem: AbstractProblem, result: Result, mu_equality: ndarray | None, mu_inequality: ndarray | None, lamda_equality: ndarray, lamda_inequality: ndarray, delta: ndarray, x_jm1: ndarray) → Tuple[float, ndarray, ndarray, Result]

Performs the line search on equation 6 (to minimise phi).

Parameters:

  • problem (AbstractProblem) – The current minimisation problem being solved.

  • result (Result) – Contains the data for the (j-1)th evaluation point.

  • mu_equality (ndarray) – The mu values for the equality constraints.

  • mu_inequality (ndarray) – The mu values for the inequality constraints.

pyvmcon.vmcon.solve_qsp(problem: AbstractProblem, result: Result, x: ndarray, B: ndarray, lbs: ndarray | None, ubs: ndarray | None, options: Dict[str, Any]) → Tuple[ndarray, ...]

Solves the quadratic programming problem detailed in equation 4 and 5 of the VMCON paper.

The QSP is solved using cvxpy. cvxpy requires the problem be convex, which is ensured by equation 9 of the VMCON paper.

Parameters:

  • problem (AbstractProblem) – The current minimisation problem being solved.

  • result (Result) – Contains the data for the (j-1)th evaluation point.

  • x (ndarray) – The (j-1)th evaluation point.

  • B (ndarray) – The current approximation of the Hessian matrix.

  • lbs (ndarray) – The lower bounds of x.

  • ubs (ndarray) – The upper bounds of x.

  • options (Dict[str, Any]) – Dictionary of keyword arguments that are passed to the CVXPY Problem.solve method.

Notes

the solve method however this can be changed by specifying a different solver in the options dictionary.

Module contents

class pyvmcon.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
property has_inequality: bool
abstract property num_equality: int

Returns the number of equality constraints this problem has

abstract property num_inequality: int

Returns the number of inequality constraints this problem has

property total_constraints: int

Returns the total number of constraints m

exception pyvmcon.LineSearchConvergenceException(*args: object, x: ndarray | None = None, result: Result | None = None, lamda_equality: ndarray | None = None, lamda_inequality: ndarray | None = None)

Bases: VMCONConvergenceException

Indicates the line search portion of VMCON was unable to solve within a pre-defined number of iterations

class pyvmcon.Problem(f: Callable[[ndarray], T], df: Callable[[ndarray], ndarray], equality_constraints: List[Callable[[ndarray], T]], inequality_constraints: List[Callable[[ndarray], T]], dequality_constraints: List[Callable[[ndarray], ndarray]], dinequality_constraints: List[Callable[[ndarray], ndarray]])

Bases: AbstractProblem

Provides a simple implementation of an AbstractProblem that essentially acts as a caller to equations to gather all of the various data.

property num_equality: int

Returns the number of equality constraints this problem has

property num_inequality: int

Returns the number of inequality constraints this problem has

exception pyvmcon.QSPSolverException(*args: object, x: ndarray | None = None, result: Result | None = None, lamda_equality: ndarray | None = None, lamda_inequality: ndarray | None = None)

Bases: VMCONConvergenceException

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

class pyvmcon.Result(f: T, df: T, eq: ndarray, deq: ndarray, ie: ndarray, die: ndarray)

Bases: NamedTuple

The data from calling a problem

deq: ndarray

2D array of the derivatives of the equality constraints wrt each component of x

df: T

Derivative of the objective function

die: ndarray

2D array of the derivatives of the inequality constraints wrt each component of x

eq: ndarray

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

f: T

Value of the objective function

ie: ndarray

1D array of the values of the inequality constraints

exception pyvmcon.VMCONConvergenceException(*args: object, x: ndarray | None = None, result: Result | None = None, lamda_equality: ndarray | None = None, lamda_inequality: ndarray | None = None)

Bases: Exception

Base class for an exception that indicates VMCON has failed to converge. This exception allows certain diagnostics to be passed and propagated with the exception.

pyvmcon.solve(problem: AbstractProblem, x: ndarray, lbs: ndarray | None = None, ubs: ndarray | 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, float], None] | None = None, additional_convergence: Callable[[Result, ndarray, ndarray, ndarray, ndarray], None] | None = None, overwrite_convergence_criteria: bool = False) → Tuple[ndarray, ndarray, ndarray, Result]

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

Parameters:

  • problem (AbstractProblem) – Defines the system to be minimised

  • 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.