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

Relations and predicates

Relations construct symbolic formulas. They are distinct from host-language truth queries.

Relations#

Relation nodes are used as equations for solve/solveset, as piecewise conditions, and as boolean-valued results.

Each relation is also a method of the left operand: x.less_than(1) builds the same node as context.less_than(x, 1). In Python, <, <=, >, and >= build the strict and non-strict order relations, so x < 1 is the relation x < 1. == and != are deliberately not relation builders: they compare two expressions structurally, which keeps expressions usable as dictionary keys and set members; build an equation value with equation. A relation has no Python truth value — its truth is three-valued, so bool(x < 1) raises, and so does a chained comparison such as 0 < x < 1. Ask for the verdict with evaluate_truth.

equal#

api::Session method

pub fn equal(
    &self,
    left: &Expression,
    right: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::equal

pub fn equal(&self, other: &Expression) -> Result<Expression, ApiError>

equation#

api::Session method

pub fn equation(
    &self,
    left: &Expression,
    right: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::equation

pub fn equation(
    &self,
    other: &Expression,
) -> Result<Expression, ApiError>

Constructs an equation value without evaluating it as a Boolean relation. Its two sides remain available for sidewise arithmetic and exact source-preserving solving.

transform_equation#

api::solving::Session method

pub fn transform_equation(
    &self,
    left: &Expression,
    right: &Expression,
    operation: EquationOperation,
) -> Result<EquationTransformation, ApiError>

Applies operation — "add", "subtract", "multiply", or "divide" — to an equation and a scalar, or adds or subtracts two equations, threading the operation over both sides. At least one operand must be an equation; two equations cannot be multiplied or divided, an equation cannot be a divisor, and a truth value beside an equation is refused.

The result says how the new equation relates to the old one, because not every side-wise operation preserves solutions. Adding or subtracting a scalar, multiplying by a factor proved nonzero, and dividing are equivalences: the new equation holds exactly where the old one does. Multiplying by a factor not proved nonzero, and combining two equations, give only a consequence: every solution of the input solves the result, but x(x−1)=0x(x - 1) = 0 also holds at x=0x = 0, where x−1=0x - 1 = 0 does not.

The relation is claimed under a condition on the free symbols. It records where a scalar operand is defined, because automatic simplification can cancel a pole out of the result — multiplying x=0x = 0 by 1/x1/x builds 1=01 = 0, and only the condition x≠0x \ne 0 still shows the lost point — and, for a divisor not proved nonzero, that the divisor is nonzero: dividing x2=xx^2 = x by xx gives x=1x = 1 under x≠0x \ne 0. A condition of true admits every point; false means the operand's domain could not be described and no claim is made.

The arithmetic operators and the add, subtract, multiply, and divide operations thread over equations the same way but return only the equation, so they refuse a multiplication or division that would need a guard to stay honest.

EquationTransformation#

What transform_equation returns:

Member Meaning
equation The transformed equation
relation equivalence or consequence
condition The Boolean condition under which the relation is claimed

api re_export

pub use results::EquationTransformation;

An equation produced by side-wise arithmetic, with how it relates to its input.

Calling forms

Type: api::results::EquationTransformation

pub struct EquationTransformation

transformation_equation#

api::results::EquationTransformation method

pub fn equation(&self) -> Expression

Getter on EquationTransformation: the transformed equation.

transformation_relation#

api::results::EquationTransformation method

pub fn relation(&self) -> EquationRelation

Getter on EquationTransformation: whether the transformed equation is equivalent to its input or only implied by it.

transformation_condition#

api::results::EquationTransformation method

pub fn condition(&self) -> Expression

Getter on EquationTransformation: the Boolean condition on the free symbols under which the relation is claimed.

not_equal#

api::Session method

pub fn not_equal(
    &self,
    left: &Expression,
    right: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::not_equal

pub fn not_equal(
    &self,
    other: &Expression,
) -> Result<Expression, ApiError>

less_than#

api::Session method

pub fn less_than(
    &self,
    left: &Expression,
    right: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::less_than

pub fn less_than(
    &self,
    other: &Expression,
) -> Result<Expression, ApiError>

less_than_or_equal#

api::Session method

pub fn less_than_or_equal(
    &self,
    left: &Expression,
    right: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::less_than_or_equal

pub fn less_than_or_equal(
    &self,
    other: &Expression,
) -> Result<Expression, ApiError>

greater_than#

api::Session method

pub fn greater_than(
    &self,
    left: &Expression,
    right: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::greater_than

pub fn greater_than(
    &self,
    other: &Expression,
) -> Result<Expression, ApiError>

greater_than_or_equal#

api::Session method

pub fn greater_than_or_equal(
    &self,
    left: &Expression,
    right: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::greater_than_or_equal

pub fn greater_than_or_equal(
    &self,
    other: &Expression,
) -> Result<Expression, ApiError>

Example#

Relations are symbolic expressions until they are evaluated.

Rust
use symi::api::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let session = Session::new();
    let x = session.symbol("x");

    println!("{}", session.less_than(&x, &session.integer(1))?);
    println!("{}", session.equal(&session.rational(2, 4)?, &session.rational(1, 2)?)?);
    Ok(())
}

Additional API#

equation_left_side#

api::expression_operations::Expression method

pub fn equation_left_side(&self) -> Result<Expression, ApiError>

The left side of this equation, or an error when this expression is not an equation.

equation_right_side#

api::expression_operations::Expression method

pub fn equation_right_side(&self) -> Result<Expression, ApiError>

The right side of this equation, or an error when this expression is not an equation.

is_equation#

api::expression_operations::Expression method

pub fn is_equation(&self) -> Result<bool, ApiError>

Whether this expression is an immutable equation value.

EquationOperation#

api re_export

pub use solving::EquationOperation;

One of the four arithmetic operations that thread over the sides of an equation.

Calling forms

Type: api::solving::EquationOperation

pub enum EquationOperation

EquationOperation.Add#

api::solving::EquationOperation variant

Add,

Add the right operand to the left one.

EquationOperation.Divide#

api::solving::EquationOperation variant

Divide,

Divide the left operand by the right one.

EquationOperation.Multiply#

api::solving::EquationOperation variant

Multiply,

Multiply the two operands.

EquationOperation.Subtract#

api::solving::EquationOperation variant

Subtract,

Subtract the right operand from the left one.

EquationOperation.from_name#

api::solving::EquationOperation method

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

Resolve the stable spelling a binding passes across the boundary.

EquationOperation.name#

api::solving::EquationOperation method

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

The stable spelling of this operation.

EquationRelation#

api re_export

pub use results::EquationRelation;

How the solution set of a transformed equation relates to the solution set of its input.

Calling forms

Type: api::results::EquationRelation

pub enum EquationRelation

EquationRelation.Consequence#

api::results::EquationRelation variant

Consequence,

Every admitted point satisfying the input satisfies the result; the converse can fail.

EquationRelation.Equivalence#

api::results::EquationRelation variant

Equivalence,

At every point the condition admits, the result holds exactly when the input does.

EquationRelation.name#

api::results::EquationRelation method

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

The stable lowercase spelling shared by every binding.