Skip to content
Symi Docs
Rust

The Rust manual covers the recommended facade. The complete native crate is documented in the native Rust API reference.

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#

api::solving::Session method

pub fn unconstrained_critical_points<'a, IteratorType, VariableType>(
    &self,
    objective: &Expression,
    variables: IteratorType,
) -> Result<OptimizationOutcome, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

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#

api::solving::Session method

pub fn classify_unconstrained< 'a, 'b, IteratorType, PointIteratorType, VariableType, PointVariableType, >(
    &self,
    objective: &Expression,
    variables: IteratorType,
    point_variables: PointIteratorType,
    point_values: &[Expression],
) -> Result<ExtremumClassification, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,
    PointIteratorType: IntoIterator<Item = PointVariableType>,
    PointVariableType: Into<VariableLike<'b>>,

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

lagrange_critical_points#

api::solving::Session method

pub fn lagrange_critical_points<'a, IteratorType, VariableType>(
    &self,
    objective: &Expression,
    constraints: &[Expression],
    variables: IteratorType,
) -> Result<OptimizationOutcome, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

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#

api::solving::Session method

pub fn karush_kuhn_tucker_points<'a, IteratorType, VariableType>(
    &self,
    objective: &Expression,
    inequality_constraints: &[Expression],
    equality_constraints: &[Expression],
    variables: IteratorType,
) -> Result<OptimizationOutcome, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

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

api::results::OptimizationOutcome method

pub fn points(&self) -> Vec<CriticalPoint>

The classified critical points, empty on a decline.

classification#

api::results::CriticalPoint method

pub fn classification(&self) -> ExtremumClassification

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

api::results::CriticalPoint method

pub fn multiplier_variables(&self) -> Vec<String>

The names of the introduced Lagrange or Karush-Kuhn-Tucker multipliers.

multiplier_values#

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

api::results::CriticalPoint method

pub fn multiplier_values(&self) -> Vec<Expression>

The value taken by each multiplier, parallel to multiplier_variables.

Global optimization on semialgebraic sets#

global_optimum_on_semialgebraic#

api::solving::Session method

pub fn global_optimum_on_semialgebraic<'a, IteratorType, VariableType>(
    &self,
    objective: &Expression,
    constraints: &Expression,
    variables: IteratorType,
    direction: OptimizationDirection,
) -> Result<OptimizationOutcome, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

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#

This family is not part of the recommended symi::api facade in this release. Call it through the native modules in the native Rust API reference.

Additional API#

CriticalPoint#

api re_export

pub use results::CriticalPoint;

One classified critical point of an optimization problem.

Calling forms

Type: api::results::CriticalPoint

pub struct CriticalPoint

CriticalPoint.values#

api::results::CriticalPoint method

pub fn values(&self) -> Vec<Expression>

The coordinate attained by each unknown, parallel to variables.

CriticalPoint.variables#

api::results::CriticalPoint method

pub fn variables(&self) -> Vec<String>

The unknown names of this point's assignment, in order.

ExtremumClassification#

api re_export

pub use results::ExtremumClassification;

The classification a critical point received from the second-order test.

Calling forms

Type: api::results::ExtremumClassification

pub enum ExtremumClassification

ExtremumClassification.Inconclusive#

api::results::ExtremumClassification variant

Inconclusive,

The second-order test did not settle the point.

ExtremumClassification.LocalMaximum#

api::results::ExtremumClassification variant

LocalMaximum,

The point is a local maximum.

ExtremumClassification.LocalMinimum#

api::results::ExtremumClassification variant

LocalMinimum,

The point is a local minimum.

ExtremumClassification.SaddlePoint#

api::results::ExtremumClassification variant

SaddlePoint,

The point is a saddle point.

ExtremumClassification.name#

api::results::ExtremumClassification method

pub fn name(&self) -> &'static str

The stable lowercase spelling shared by every binding.

OptimizationDirection#

Type

pub enum OptimizationDirection

Whether a global optimum is sought at the minimum or the maximum.

OptimizationDirection.Maximize#

api::solving::OptimizationDirection variant

Maximize,

Seek the global maximum.

OptimizationDirection.Minimize#

api::solving::OptimizationDirection variant

Minimize,

Seek the global minimum.

OptimizationDirection.from_name#

api::solving::OptimizationDirection method

pub fn from_name(name: &str) -> Result<Self, ApiError>

Resolve the stable spelling a binding passes across the boundary.

OptimizationDirection.name#

api::solving::OptimizationDirection method

pub fn name(&self) -> &'static str

The stable spelling of this direction.

OptimizationOutcome#

api re_export

pub use results::OptimizationOutcome;

The outcome of a critical-point or optimum enumeration.

Calling forms

Type: api::results::OptimizationOutcome

pub struct OptimizationOutcome

OptimizationOutcome.complete#

api::results::OptimizationOutcome method

pub fn complete(&self) -> bool

True only when the enumeration was certified exhaustive.

OptimizationOutcome.verdict#

api::results::OptimizationOutcome method

pub fn verdict(&self) -> OptimizationVerdict

Whether the enumeration produced points or declined.

OptimizationVerdict#

api re_export

pub use results::OptimizationVerdict;

The verdict an optimization enumeration reached.

Calling forms

Type: api::results::OptimizationVerdict

pub enum OptimizationVerdict

OptimizationVerdict.Declined#

api::results::OptimizationVerdict variant

Declined,

The enumeration declined.

OptimizationVerdict.Points#

api::results::OptimizationVerdict variant

Points,

The enumeration produced critical points.

OptimizationVerdict.name#

api::results::OptimizationVerdict method

pub fn name(&self) -> &'static str

The stable lowercase spelling shared by every binding.