The Rust manual covers the recommended facade. The complete native crate is documented in the native Rust API reference.
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, 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λigi 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 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). 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
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
The second-order test did not settle the point.
ExtremumClassification.LocalMaximum#
api::results::ExtremumClassification variant
The point is a local maximum.
ExtremumClassification.LocalMinimum#
api::results::ExtremumClassification variant
The point is a local minimum.
ExtremumClassification.SaddlePoint#
api::results::ExtremumClassification variant
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
Seek the global maximum.
OptimizationDirection.Minimize#
api::solving::OptimizationDirection variant
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
The enumeration declined.
OptimizationVerdict.Points#
api::results::OptimizationVerdict variant
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.