Skip to content
Symi Docs
Swift
On this page

Optimization

Local symbolic optimization finds critical points of an objective and classifies them by second-order conditions. The layer is local and exact — it finds and classifies critical / Lagrange / KKT points, deciding every classification from exact minor signs (never numerically) and declining whenever a sign is undecidable or the underlying system solver cannot close the stationarity equations. These local operations do not claim a global optimum. The separate global_optimum_on_semialgebraic operation handles its documented CAD-backed polynomial semialgebraic domain.

Each function returns a structured outcome: a verdict of "points" or "declined", a complete flag (true only when the critical-point enumeration was certified exhaustive — typically a quadratic objective whose gradient system is linear), and a list of points. Each point carries its coordinate assignment, the introduced Lagrange / KKT multipliers (empty for the unconstrained case), and a classification string: "local_minimum", "local_maximum", "saddle_point", or "inconclusive".

Notes on the result shape: Python returns a dict with keys verdict (str), complete (bool), and points (a list of dicts, each with assignment, multipliers, and classification); WASM returns an OptimizationOutcome object whose getters expose the same data.

unconstrained_critical_points#

Explicit context

func unconstrainedCriticalPoints(
    objective: UniffiExpression,
    variables: [String],
) -> UniffiOptimizationOutcome

The critical points of objective as the solutions of ∇f=0\nabla f = 0, each classified by the definiteness of the Hessian (Sylvester's criterion on the leading principal minors). A quadratic objective yields a complete outcome; a degenerate Hessian (det H = 0) classifies as inconclusive.

classify_unconstrained#

Explicit context

func classifyUnconstrained(
    objective: UniffiExpression,
    variables: [String],
    pointVariables: [String],
    pointValues: [UniffiExpression],
) -> UniffiExtremumClassification

Classify one given interior point — supplied as the parallel point_variables / point_values lists — by Hessian definiteness, returning the verdict string.

lagrange_critical_points#

Explicit context

func lagrangeCriticalPoints(
    objective: UniffiExpression,
    constraints: [UniffiExpression],
    variables: [String],
) -> UniffiOptimizationOutcome

The equality-constrained critical points via Lagrange multipliers: stationarity of L=f+∑iλigiL = f + \sum_i \lambda_i g_i together with each constraint = 0, classified by the bordered Hessian. The solved multiplier values appear in each point's multipliers.

karush_kuhn_tucker_points#

Explicit context

func karushKuhnTuckerPoints(
    objective: UniffiExpression,
    inequalityConstraints: [UniffiExpression],
    equalityConstraints: [UniffiExpression],
    variables: [String],
) -> UniffiOptimizationOutcome

The Karush–Kuhn–Tucker points found by active-set enumeration. Each inequality is read as inequality⁡≤0\operatorname{inequality} \le 0 and each equality as equality = 0. Only primal- and dual-feasible candidates are kept; a candidate whose feasibility a sign cannot settle is retained but classified inconclusive. The enumeration is bounded by a documented cap on the number of inequalities, above which the layer declines.

Result accessors (WASM)#

On WASM the outcome and its points are objects with the following getters; on Python the same data is returned as plain dicts.

points#

The list of CriticalPoint objects in an OptimizationOutcome (WASM).

UniffiOptimizationOutcome method

func points() -> [UniffiCriticalPoint]

The list of critical_point objects in an optimization_outcome (WASM).

classification#

UniffiCriticalPoint method

func classification() -> UniffiExtremumClassification

The verdict string of a critical point: "local_minimum", "local_maximum", "saddle_point", or "inconclusive".

multiplier_variables#

The names of the introduced Lagrange / KKT multipliers at a constrained critical point (empty for the unconstrained case).

UniffiCriticalPoint method

func multiplierVariables() -> [String]

The names of the introduced Lagrange / KKT multipliers at a constrained critical point (empty for the unconstrained case).

multiplier_values#

The solved values of those multipliers, in the same order as multiplier_variables.

UniffiCriticalPoint method

func multiplierValues() -> [UniffiExpression]

The solved values of those multipliers, in the same order as multiplier_variables.

Global optimization on semialgebraic sets#

global_optimum_on_semialgebraic#

Explicit context

func globalOptimumOnSemialgebraic(
    objective: UniffiExpression,
    constraints: UniffiExpression,
    variables: [String],
    direction: UniffiOptimizationDirection,
) -> UniffiOptimizationOutcome

context.global_optimum_on_semialgebraic(objective, constraints, variables: list[VariableLike], direction: str)

Global optimum of a polynomial objective over the semialgebraic feasible set described by constraints (a Boolean combination of polynomial relations), with direction either "minimize" or "maximize". Builds the objective-gradient-adapted cylindrical algebraic decomposition, ranks the objective exactly over the feasible cell sample points, and certifies the candidate by quantifier elimination (∀x. feasible⁡(x)→objective⁡(x)⋛value⁡\forall x.\ \operatorname{feasible}(x) \rightarrow \operatorname{objective}(x) \gtreqless \operatorname{value}). Returns the same OptimizationOutcome shape (on Python a dict, on WASM an object): a "points" verdict with one point and complete = true carries the attained global optimum; a "declined" verdict reports an unbounded objective or an extremum that is approached but not attained. This closes the global-optimum-on-semialgebraic-set problem; the returned point and value are exact rationals (an irrational-algebraic optimum declines).

Example#

Additional API#

CriticalPoint#

CriticalPoint.values#

UniffiCriticalPoint method

func values() -> [UniffiExpression]

Getter on system_assignment: the assigned value expressions, aligned with variables.

CriticalPoint.variables#

UniffiCriticalPoint method

func variables() -> [String]

Getter on system_assignment: the unknown names, in order.

OptimizationOutcome#

OptimizationOutcome.complete#

UniffiOptimizationOutcome method

func complete() -> Bool

Getter on polynomial_system_solution: whether the solver certified it found every solution.

OptimizationOutcome.verdict#

UniffiOptimizationOutcome method

func verdict() -> UniffiOptimizationVerdict

The optimization result classification.

Symi documentation · Swift