Skip to content
Symi Docs
Python
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#

Default context

unconstrained_critical_points(
    objective: ExpressionLike,
    variables: Iterable[VariableLike],
) -> Any
Calling forms

Explicit context: Context.unconstrained_critical_points

unconstrained_critical_points(
    objective: ExpressionLike,
    variables: Iterable[VariableLike],
) -> Any

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#

Default context

classify_unconstrained(
    objective: ExpressionLike,
    variables: Iterable[VariableLike],
    point_variables: Iterable[VariableLike],
    point_values: Iterable[ExpressionLike],
) -> str
Calling forms

Explicit context: Context.classify_unconstrained

classify_unconstrained(
    objective: ExpressionLike,
    variables: Iterable[VariableLike],
    point_variables: Iterable[VariableLike],
    point_values: Iterable[ExpressionLike],
) -> str

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

lagrange_critical_points#

Default context

lagrange_critical_points(
    objective: ExpressionLike,
    constraints: Iterable[ExpressionLike],
    variables: Iterable[VariableLike],
) -> Any
Calling forms

Explicit context: Context.lagrange_critical_points

lagrange_critical_points(
    objective: ExpressionLike,
    constraints: Iterable[ExpressionLike],
    variables: Iterable[VariableLike],
) -> Any

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#

Default context

karush_kuhn_tucker_points(
    objective: ExpressionLike,
    inequality_constraints: Iterable[ExpressionLike],
    equality_constraints: Iterable[ExpressionLike],
    variables: Iterable[VariableLike],
) -> Any
Calling forms

Explicit context: Context.karush_kuhn_tucker_points

karush_kuhn_tucker_points(
    objective: ExpressionLike,
    inequality_constraints: Iterable[ExpressionLike],
    equality_constraints: Iterable[ExpressionLike],
    variables: Iterable[VariableLike],
) -> Any

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#

Not exposed by the Python bindings. Available as UniffiOptimizationOutcome.points in Kotlin, UniffiOptimizationOutcome.points in Swift, api::results::OptimizationOutcome::points in Rust.

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

classification#

Not exposed by the Python bindings. Available as UniffiCriticalPoint.classification in Kotlin, UniffiCriticalPoint.classification in Swift, api::results::CriticalPoint::classification in Rust.

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

multiplier_variables#

Not exposed by the Python bindings. Available as UniffiCriticalPoint.multiplierVariables in Kotlin, UniffiCriticalPoint.multiplierVariables in Swift, api::results::CriticalPoint::multiplier_variables in Rust.

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

multiplier_values#

Not exposed by the Python bindings. Available as UniffiCriticalPoint.multiplierValues in Kotlin, UniffiCriticalPoint.multiplierValues in Swift, api::results::CriticalPoint::multiplier_values in Rust.

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

Global optimization on semialgebraic sets#

global_optimum_on_semialgebraic#

Default context

global_optimum_on_semialgebraic(
    objective: ExpressionLike,
    constraints: ExpressionLike,
    variables: Iterable[VariableLike],
    direction: str,
) -> Any
Calling forms

Explicit context: Context.global_optimum_on_semialgebraic

global_optimum_on_semialgebraic(
    objective: ExpressionLike,
    constraints: ExpressionLike,
    variables: Iterable[VariableLike],
    direction: str,
) -> Any

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#

Critical points and their classification.

Python
import symi

x = symi.symbol("x")
y = symi.symbol("y")
objective = x**2 + y**2

print(symi.unconstrained_critical_points(objective, ["x", "y"]))
print(symi.lagrange_critical_points(objective, [x + y - 1], ["x", "y"]))

Symi documentation · Python