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

Polynomial queries

These take ordinary expressions plus a variable name; the named variable becomes the main polynomial variable and every other free variable rides along symbolically in the coefficients. An expression that is not polynomial in the variable (a transcendental call of it, a non-integer power of it) makes the query decline — None for degree, an error for the others.

degree#

api::algebra::Session method

pub fn degree<'a, VariableType>(
    &self,
    input_expression: &Expression,
    variable: VariableType,
) -> Result<Option<usize>, ApiError>
where
    VariableType: Into<VariableLike<'a>>,

Degree in variable. None when the expression is not polynomial in variable or is identically zero (the zero polynomial has no degree under the core convention).

leading_coefficient#

api::algebra::Session method

pub fn leading_coefficient<'a, VariableType>(
    &self,
    input_expression: &Expression,
    variable: VariableType,
) -> Result<Expression, ApiError>
where
    VariableType: Into<VariableLike<'a>>,

Coefficient of the highest power of variable; may contain the other free variables. Errors on non-polynomial or zero input.

coefficient#

api::algebra::Session method

pub fn coefficient<'a, VariableType>(
    &self,
    input_expression: &Expression,
    variable: VariableType,
    power: usize,
) -> Result<Expression, ApiError>
where
    VariableType: Into<VariableLike<'a>>,

Coefficient of variable^power; integer 0 when the term is absent. Errors on non-polynomial input.

polynomial_gcd#

api::algebra::Session method

pub fn polynomial_gcd<'a, VariableType>(
    &self,
    left: &Expression,
    right: &Expression,
    variable: VariableType,
) -> Result<Expression, ApiError>
where
    VariableType: Into<VariableLike<'a>>,

Greatest common divisor of the two expressions as polynomials in variable (primitive, with the core's sign normalisation). Errors when either input is not polynomial in variable.

resultant#

api::algebra::Session method

pub fn resultant<'a, VariableType>(
    &self,
    left: &Expression,
    right: &Expression,
    variable: VariableType,
) -> Result<Expression, ApiError>
where
    VariableType: Into<VariableLike<'a>>,

Resultant with respect to variable; zero exactly when the two polynomials share a root (over the algebraic closure). Errors on non-polynomial input.

isolate_real_roots#

api::solving::Session method

pub fn isolate_real_roots<'a, VariableType>(
    &self,
    input_expression: &Expression,
    variable: VariableType,
) -> Result<Vec<IsolatingInterval>, ApiError>
where
    VariableType: Into<VariableLike<'a>>,
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::isolate_real_roots

pub fn isolate_real_roots<'a, VariableType>(
    &self,
    variable: VariableType,
) -> Result<Vec<IsolatingInterval>, ApiError>
where
    VariableType: Into<VariableLike<'a>>,

One (lower, upper) rational isolating interval per distinct real root, sorted ascending; a collapsed pair (r, r) marks an exact rational root. Requires a non-zero univariate polynomial with rational coefficients. Notes: WASM returns IsolatingInterval objects with lower/upper getters.

isolating_interval (WASM result class)#

lower#

api::results::IsolatingInterval method

pub fn lower(&self) -> Expression

The lower endpoint.

upper#

api::results::IsolatingInterval method

pub fn upper(&self) -> Expression

The upper endpoint.

Gröbner bases and ideals#

These operate over the polynomial ring Q[variables]\mathbb{Q}[\text{variables}]. Generators are passed as an expression list; the ring variables are named by a string list; the monomial order is named by a string ("lexicographic" / "lex", "degree_lexicographic" / "deglex", or "degree_reverse_lexicographic" / "degrevlex", the computational default). Any generator that is not a polynomial over Q\mathbb{Q} in the named variables — a transcendental call, a non-integer power, an unnamed symbol, or an irrational coefficient — makes the operation decline cleanly (Python None, WASM null); it never returns a wrong or partial answer. Within Q[variables]\mathbb{Q}[\text{variables}] the results are exact and complete: a returned basis is the canonical reduced Gröbner basis, membership is a genuine decision, and elimination is exact by the Elimination Theorem.

Performance. The basis is computed by F4 (Faugère's batched Macaulay-matrix reduction), with a signature-based engine (F5 / GVW) available internally; the reference Buchberger algorithm is retained as the differential oracle these are checked against. The choice of engine is an internal acceleration only: the result is identical to the reference Buchberger basis for every input, and the monomial-order argument and the whole binding surface are unchanged. These entry points simply run faster — there is no new method to call.

groebner_basis#

api::algebra::Session method

pub fn groebner_basis<'a, IteratorType, VariableType>(
    &self,
    generators: &[Expression],
    variables: IteratorType,
    order: MonomialOrdering,
) -> Result<Option<Vec<Expression>>, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

The canonical reduced Gröbner basis of the ideal <generators> under the named monomial order — monic, autoreduced, and sorted, so it is unique for the (ideal, order) pair. None when any generator is outside Q[variables]\mathbb{Q}[\text{variables}].

ideal_membership#

api::algebra::Session method

pub fn ideal_membership<'a, IteratorType, VariableType>(
    &self,
    element: &Expression,
    generators: &[Expression],
    variables: IteratorType,
    order: MonomialOrdering,
) -> Result<Option<bool>, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

Whether element lies in the ideal <generators>, decided by reducing it to its normal form modulo the Gröbner basis (zero exactly when it is a member). The verdict is independent of the order. None when the element or a generator is outside Q[variables]\mathbb{Q}[\text{variables}].

ideal_sum#

api::algebra::Session method

pub fn ideal_sum<'a, IteratorType, VariableType>(
    &self,
    generators_left: &[Expression],
    generators_right: &[Expression],
    variables: IteratorType,
    order: MonomialOrdering,
) -> Result<Option<Vec<Expression>>, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

A Gröbner basis of the ideal sum I + J, the ideal generated by the two generator lists together. None on a non-Q[variables]\mathbb{Q}[\text{variables}] generator.

ideal_product#

api::algebra::Session method

pub fn ideal_product<'a, IteratorType, VariableType>(
    &self,
    generators_left: &[Expression],
    generators_right: &[Expression],
    variables: IteratorType,
    order: MonomialOrdering,
) -> Result<Option<Vec<Expression>>, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

A Gröbner basis of the ideal product IJI J, generated by all pairwise products of the two generator lists. None on a non-Q[variables]\mathbb{Q}[\text{variables}] generator.

ideal_intersection#

api::algebra::Session method

pub fn ideal_intersection<'a, IteratorType, VariableType>(
    &self,
    generators_left: &[Expression],
    generators_right: &[Expression],
    variables: IteratorType,
    order: MonomialOrdering,
) -> Result<Option<Vec<Expression>>, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

A generating set of the ideal intersection I∩JI \cap J, computed by the standard tag-variable elimination construction tI+(1−t)Jt I + (1-t) J. None on a non-Q[variables]\mathbb{Q}[\text{variables}] generator.

elimination_ideal#

api::algebra::Session method

pub fn elimination_ideal<'a, 'b, VariablesType, EliminateType, VariableType, EliminatedType>(
    &self,
    generators: &[Expression],
    variables: VariablesType,
    eliminate: EliminateType,
) -> Result<Option<Vec<Expression>>, ApiError>
where
    VariablesType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,
    EliminateType: IntoIterator<Item = EliminatedType>,
    EliminatedType: Into<VariableLike<'b>>,

A Gröbner basis of the elimination ideal ⟨generators⁡⟩∩Q[surviving variables]\langle\operatorname{generators}\rangle \cap \mathbb{Q}[\text{surviving variables}], projecting away the variables named in eliminate via the Elimination Theorem (a block order ranks the eliminated variables high and the generators free of them are kept). Exact: it neither drops nor introduces components. None on a non-Q[variables]\mathbb{Q}[\text{variables}] generator. Example: eliminating t from {x−t2,y−t3}\{x - t^2, y - t^3\} returns the twisted-cubic implicit equation y2−x3y^2 - x^3.

Order change and implicitisation#

These consume a Gröbner basis rather than compute one from scratch. The order change runs the standard FGLM algorithm; implicitisation is parameter elimination with the rational-parametrisation saturation wired in.

change_monomial_order#

api::algebra::Session method

pub fn change_monomial_order<'a, IteratorType, VariableType>(
    &self,
    basis: &[Expression],
    variables: IteratorType,
    source_order: MonomialOrdering,
    target_order: MonomialOrdering,
) -> Result<Option<Vec<Expression>>, ApiError>
where
    IteratorType: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,

Convert a Gröbner basis of a zero-dimensional ideal from source_order to target_order by FGLM (Faugère–Gianni–Lazard–Mora) — linear algebra in the finite-dimensional quotient ring Q[variables]/I\mathbb{Q}[\text{variables}]/I, far cheaper than computing the target basis directly (the msolve route to a lexicographic basis is a cheap degrevlex basis followed by this conversion). The result is the canonical reduced Gröbner basis under target_order, identical to a direct groebner_basis call. None when the ideal is positive-dimensional (the quotient ring is infinite-dimensional, so FGLM does not apply) or any generator is outside Q[variables]\mathbb{Q}[\text{variables}].

implicitize#

api::algebra::Session method

pub fn implicitize<'a, 'b, CoordinatesType, ParametersType, CoordinateType, ParameterType>(
    &self,
    coordinates: CoordinatesType,
    parameters: ParametersType,
    parametric_expressions: &[Expression],
) -> Result<Option<Vec<Expression>>, ApiError>
where
    CoordinatesType: IntoIterator<Item = CoordinateType>,
    CoordinateType: Into<VariableLike<'a>>,
    ParametersType: IntoIterator<Item = ParameterType>,
    ParameterType: Into<VariableLike<'b>>,

The implicit ideal of a parametric curve or surface xi=fi(parameters⁡)x_i = f_i(\operatorname{parameters}) (the i-th coordinate paired with the i-th parametric expression), returned as a generator list over Q[coordinates]\mathbb{Q}[\text{coordinates}] — the elimination of the parameters (Cox–Little–O'Shea ch. 3). A polynomial parametrisation eliminates the parameters directly; a rational one fi=pi/qif_i = p_i/q_i clears denominators and saturates by the denominator product through a fresh tag variable, so the eliminant is the true implicit equation rather than a multiple carrying spurious components. None when a parametric expression is outside Q(parameters⁡)\mathbb{Q}(\operatorname{parameters}) or there are no parameters. Examples: {x=t2,y=t3}\{x = t^2, y = t^3\} returns y2−x3y^2 - x^3; {x=(1−t2)/(1+t2),y=2t/(1+t2)}\{x = (1 - t^2)/(1 + t^2), y = 2t/(1 + t^2)\} returns x2+y2−1x^2 + y^2 - 1.

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#

api::algebra#

api module

pub mod algebra;

Polynomial, ideal, and algebraic-rewrite operations of the native API.

cylindrical_algebraic_decomposition#

api::Session method

pub fn cylindrical_algebraic_decomposition< 'a, ExpressionIterator, VariableIterator, VariableType, ConstraintIterator, >(
    &self,
    expressions: ExpressionIterator,
    variables: VariableIterator,
    equational_constraints: ConstraintIterator,
) -> Result<CylindricalAlgebraicDecomposition, ApiError>
where
    ExpressionIterator: IntoIterator<Item = Expression>,
    VariableIterator: IntoIterator<Item = VariableType>,
    VariableType: Into<VariableLike<'a>>,
    ConstraintIterator: IntoIterator<Item = usize>,

Provides the cylindrical_algebraic_decomposition operation on this native type.

factor_over_gaussian_integers#

api::Session method

pub fn factor_over_gaussian_integers(
    &self,
    target: &Expression,
) -> Result<Expression, ApiError>

Factors a univariate polynomial over the Gaussian integers.

IsolatingInterval#

api re_export

pub use results::IsolatingInterval;

A rational interval that isolates exactly one real root.

Calling forms

Type: api::results::IsolatingInterval

pub struct IsolatingInterval

MonomialOrdering#

api re_export

pub use options::MonomialOrdering;

A monomial ordering supported by the native polynomial API.

Calling forms

Type: api::options::MonomialOrdering

pub enum MonomialOrdering

MonomialOrdering.DegreeLexicographic#

api::options::MonomialOrdering variant

DegreeLexicographic,

Degree-lexicographic ordering.

MonomialOrdering.DegreeReverseLexicographic#

api::options::MonomialOrdering variant

DegreeReverseLexicographic,

Degree-reverse-lexicographic ordering.

MonomialOrdering.Lexicographic#

api::options::MonomialOrdering variant

Lexicographic,

Lexicographic ordering.

MonomialOrdering.from_name#

api::options::MonomialOrdering method

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

Resolves a stable monomial-order spelling, including documented aliases.

MonomialOrdering.into_core#

api::options::MonomialOrdering method

pub fn into_core(
    self,
) -> crate::polynomial::monomial_order::MonomialOrder

Converts this binding-neutral value to the engine representation.

MonomialOrdering.name#

api::options::MonomialOrdering method

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

Returns the stable binding spelling of this monomial ordering.

PiecewiseBranch#

api re_export

pub use results::PiecewiseBranch;

One condition and value pair of a piecewise expression.

Calling forms

Type: api::results::PiecewiseBranch

pub struct PiecewiseBranch

PiecewiseBranch.condition#

api::results::PiecewiseBranch method

pub fn condition(&self) -> Expression

The condition guarding this branch.

PiecewiseBranch.new#

api::results::PiecewiseBranch method

pub fn new(condition: &Expression, value: &Expression) -> Self

Construct a branch from its condition and value.

PiecewiseBranch.value#

api::results::PiecewiseBranch method

pub fn value(&self) -> Expression

The value taken when the condition holds.