Struct Context 

pub struct Context { /* private fields */ }

The user-facing entry point for symplex.

A Context owns an expression arena and an assumption cache. It is cheaply cloneable — clones share the same underlying state.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let x = ctx.symbol("x");
let expr = &x + 1;
assert_eq!(format!("{expr}"), "x + 1");

Implementations

impl Context

pub fn new() -> Self

Creates a new context with default configuration.

pub fn with_config(config: EvalConfig) -> Self

Creates a new context with custom evaluation configuration.

pub fn symbol(&self, name: &str) -> Ex

Creates a symbolic variable.

Panics

Panics if name is empty.

pub fn var(&self, name: &str) -> Ex

Create a symbolic variable (alias for symbol).

pub fn parse(&self, input: &str) -> Result<Ex, SymplexError>

Parse a mathematical expression string in this context.

All symbols created during parsing belong to this context, so the result can be freely combined with other expressions from the same context.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let expr = ctx.parse("x^2 + 1").unwrap();
assert!(format!("{expr}").contains("x"));

pub fn symbol_with(&self, name: &str, assumptions: &[Assumption]) -> Ex

Create a symbol with mathematical assumptions.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let t = ctx.symbol_with("t", &[Assumption::Positive, Assumption::Real]);
assert_eq!(ctx.query(&t, Props::POSITIVE), Some(true));
assert_eq!(ctx.query(&t, Props::REAL), Some(true));
// Inferred by forward-chaining:
assert_eq!(ctx.query(&t, Props::COMPLEX), Some(true));

pub fn query(&self, ex: &Ex, prop: Props) -> Option<bool>

Query a mathematical property of an expression.

Returns Some(true) if the property is provably true, Some(false) if provably false, or None if unknown.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let one = ctx.int(1);
assert_eq!(ctx.query(&one, Props::POSITIVE), Some(true));
assert_eq!(ctx.query(&one, Props::INTEGER), Some(true));

pub fn int(&self, n: i64) -> Ex

Creates an integer expression.

pub fn zero(&self) -> Ex

The additive identity (0) in this context.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let z = ctx.zero();
assert_eq!(format!("{z}"), "0");
assert!(z.is_zero_structural());

pub fn one(&self) -> Ex

The multiplicative identity (1) in this context.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let o = ctx.one();
assert_eq!(format!("{o}"), "1");
assert!(o.is_one_structural());

pub fn rational(&self, p: i64, q: i64) -> Ex

Creates a rational expression p/q, reduced to lowest terms.

A zero denominator never panics: p/0 with p ≠ 0 is zoo (complex infinity) and 0/0 is nan — the same values that ctx.int(p) / ctx.int(0) produces.

use symplex::prelude::*;

let ctx = Context::new();
assert_eq!(format!("{}", ctx.rational(6, -4)), "-3/2");
assert_eq!(ctx.rational(1, 0), ctx.complex_infinity());
assert_eq!(ctx.rational(-7, 0), ctx.complex_infinity());
assert_eq!(ctx.rational(0, 0), ctx.nan());
assert_eq!(ctx.rational(1, 0), ctx.int(1) / ctx.int(0));

pub fn pi(&self) -> Ex

The constant π.

pub fn e(&self) -> Ex

Euler’s number e.

pub fn i_unit(&self) -> Ex

The imaginary unit i.

pub fn euler_gamma(&self) -> Ex

The Euler–Mascheroni constant γ ≈ 0.5772156649…

Evaluates to arbitrary precision (Brent–McMillan). Its (ir)rationality is unproven, so is_rational() returns None.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let g = ctx.euler_gamma();
assert_eq!(format!("{g}"), "EulerGamma");
assert!(g.eval_decimal(30).unwrap().starts_with("0.57721566490153286060651209008"));
assert_eq!(g.is_positive(), Some(true));
assert_eq!(g.is_rational(), None);

pub fn catalan(&self) -> Ex

Catalan’s constant G = Σ (−1)ⁿ/(2n+1)² ≈ 0.9159655942…

Examples

use symplex::prelude::*;

let ctx = Context::new();
let g = ctx.catalan();
assert_eq!(format!("{g}"), "Catalan");
assert!(g.eval_decimal(30).unwrap().starts_with("0.91596559417721901505460351493"));

pub fn golden_ratio(&self) -> Ex

The golden ratio φ = (1 + √5)/2 ≈ 1.6180339887…

Examples

use symplex::prelude::*;

let ctx = Context::new();
let phi = ctx.golden_ratio();
assert_eq!(format!("{phi}"), "GoldenRatio");
assert!(phi.eval_decimal(30).unwrap().starts_with("1.61803398874989484820458683437"));
assert_eq!(phi.is_rational(), Some(false));

pub fn physical_constant(&self, name: &str, value: Ex) -> Ex

Create a named physical constant with a known exact value.

The constant displays as name but evaluates numerically to value.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let c = ctx.physical_constant("c", ctx.int(299_792_458));
assert_eq!(format!("{c}"), "c");

pub fn infinity(&self) -> Ex

Positive infinity.

pub fn neg_infinity(&self) -> Ex

Negative infinity (-∞).

pub fn complex_infinity(&self) -> Ex

Complex infinity (zoo) — infinite magnitude, undefined direction.

This is the value of 1/0, ζ(1), Γ(0), …

Examples

use symplex::prelude::*;

let ctx = Context::new();
let zoo = ctx.complex_infinity();
assert_eq!(format!("{zoo}"), "zoo");
assert_eq!(ctx.int(1).zeta(), zoo);

pub fn nan(&self) -> Ex

Not-a-number.

pub fn empty_set(&self) -> SetEx

The empty set ∅.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let e = ctx.empty_set();
assert_eq!(format!("{e}"), "EmptySet");

pub fn universal_set(&self) -> SetEx

The universal set (all values).

Examples

use symplex::prelude::*;

let ctx = Context::new();
let u = ctx.universal_set();
assert_eq!(format!("{u}"), "UniversalSet");

pub fn reals(&self) -> SetEx

The real number line: (-∞, ∞).

Examples

use symplex::prelude::*;

let ctx = Context::new();
let r = ctx.reals();
let s = format!("{r}");
assert!(s.contains("-oo") && s.contains("oo"), "reals: {s}");

pub fn interval( &self, start: &Ex, end: &Ex, left_open: bool, right_open: bool, ) -> SetEx

Create an interval with explicit open/closed flags.

left_open = true means the left endpoint is excluded (open bracket). right_open = true means the right endpoint is excluded (open bracket).

Examples

use symplex::prelude::*;

let ctx = Context::new();
// Closed interval [0, 1]
let i = ctx.interval(&ctx.int(0), &ctx.int(1), false, false);
let s = format!("{i}");
assert!(s.contains("[") && s.contains("]"), "closed interval: {s}");

// Open interval (0, 1)
let i = ctx.interval(&ctx.int(0), &ctx.int(1), true, true);
let s = format!("{i}");
assert!(s.contains("(") && s.contains(")"), "open interval: {s}");

pub fn finite_set(&self, elements: &[Ex]) -> SetEx

Create a finite set {elements[0], elements[1], …}.

Elements are sorted and deduplicated.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let s = ctx.finite_set(&[ctx.int(3), ctx.int(1), ctx.int(2)]);
let display = format!("{s}");
assert!(display.contains("{") && display.contains("}"), "finite set: {display}");

pub fn with_arena_mut<R>(&self, f: impl FnOnce(&mut Arena) -> R) -> R

Provides mutable access to the expression arena.

The closure receives &mut Arena and can call any arena method (e.g., arena.add(), arena.sin(), arena.symbol()).

This is primarily used by the rule! macro to build pattern expressions directly in the arena. Most users should prefer the higher-level Ex methods instead.

Panics

Deadlock warning: The write lock on the context is held for the entire duration of the closure. If the closure captures and uses a Context or Ex handle from the same context (calling methods like .sin(), .expand(), format!(), or any operation that acquires the lock), the thread will deadlock.

Safe: Only call Arena methods inside the closure.

Unsafe (deadlocks): Do NOT call Context methods, Ex methods, or format!("{}", some_ex) inside the closure.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let result = ctx.with_arena_mut(|arena| {
    let x = arena.symbol("x");
    let two = arena.int(2);
    arena.pow(x, two)
});

pub fn from_tree(&self, tree: &ExprTree) -> Ex

Convert a serialized ExprTree back into an expression handle in this context.

The resulting expression is fully canonicalized.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let x = ctx.symbol("x");
let expr = &x.powi(2) + 1;
let tree = expr.to_tree();
let back = ctx.from_tree(&tree);
assert_eq!(format!("{back}"), format!("{expr}"));

pub fn from_json(&self, json: &str) -> Result<Ex, Error>

Parse a JSON string into an expression in this context.

This is a convenience shorthand for deserializing an ExprTree from JSON and converting it.

Errors

Returns Err if the JSON is malformed or doesn’t represent a valid ExprTree.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let json = r#"{"type":"Symbol","name":"x"}"#;
let expr = ctx.from_json(json).unwrap();
assert_eq!(format!("{expr}"), "x");

pub fn solve_system<E: ZeroForm>( &self, equations: &[E], variables: &[Ex], ) -> Result<LinearSolution, SymplexError>

Solve a system of linear equations (convenience wrapper over linsolve).

Each equation in equations is an expression that equals zero (or an Equation); variables are the symbols to solve for. Coefficients may be symbolic. The result distinguishes a unique solution, a parametric family (free variables), and an inconsistent system — see LinearSolution.

Errors

Returns SymplexError::InvalidArgument if the equations are not linear in variables or the input is empty.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let (x, y) = (ctx.symbol("x"), ctx.symbol("y"));
// x + y = 3, x - y = 1  →  x = 2, y = 1
let eq1 = &x + &y - 3;
let eq2 = &x - &y - 1;
match ctx.solve_system(&[eq1, eq2], &[x, y]).unwrap() {
    LinearSolution::Unique(pairs) => {
        assert_eq!(format!("{}", pairs[0].1), "2");
        assert_eq!(format!("{}", pairs[1].1), "1");
    }
    other => panic!("expected a unique solution, got {other:?}"),
}

pub fn compact(&self, roots: &[Ex]) -> (Context, Vec<Ex>)

Create a new, compacted context containing only the expression trees reachable from roots.

Returns the new context and the corresponding root expressions (in the same order as roots). The old context remains valid — existing expression handles continue to work.

Use Case

After a heavy computation that creates thousands of intermediate nodes, compact the handful of results into a fresh arena:

use symplex::prelude::*;

let ctx = Context::new();
let x = ctx.symbol("x");
// ... heavy computation creating many intermediates ...
let result = &x + 1;
let (new_ctx, new_exprs) = ctx.compact(&[result]);
// old ctx can be dropped — only the reachable nodes survive
assert_eq!(format!("{}", new_exprs[0]), "x + 1");

pub fn node_count(&self) -> usize

Number of interned expression nodes.

pub fn liveness_ratio(&self, roots: &[Ex]) -> f64

Compute the fraction of arena nodes reachable from the given root expressions.

Returns a value between 0.0 and 1.0. A value of 0.3 means 70% of arena nodes are unreachable (dead) and would be freed by compact().

pub fn should_compact(&self, roots: &[Ex]) -> bool

Heuristic: should the arena be compacted?

Returns true when the arena has grown large (>100K nodes), has doubled since the last compact, and less than 50% of nodes are reachable from the given roots.

impl Context

pub fn from_f64(&self, v: f64) -> Result<Ex, SymplexError>

Convert an f64 to the exact rational it represents.

Every finite f64 is a dyadic rational m · 2ᵏ, and this method preserves it bit-for-bit. That means decimal literals are not what they look like:

• 0.5 → 1/2 (exact in binary — fine)
• 0.1 → 3602879701896397/36028797018963968 (not 1/10)
• 0.3 → 5404319552844595/18014398509481984

This is the honest conversion: the library never rounds behind your back. When you want the “nice” rational a human meant, use from_f64_approx / from_f64_nice, or write the decimal as a string with decimal_str.

+∞ / −∞ become the symbolic oo / -oo nodes.

Errors

SymplexError::InvalidArgument for NaN — it has no numeric value. (Use Context::nan if you want the symbolic nan node.)

Examples

use symplex::prelude::*;

let ctx = Context::new();
assert_eq!(format!("{}", ctx.from_f64(0.5).unwrap()), "1/2");
assert_eq!(format!("{}", ctx.from_f64(-3.0).unwrap()), "-3");
assert_eq!(
    format!("{}", ctx.from_f64(0.1).unwrap()),
    "3602879701896397/36028797018963968"
);
assert_eq!(format!("{}", ctx.from_f64(f64::INFINITY).unwrap()), "oo");
assert!(ctx.from_f64(f64::NAN).is_err());

pub fn from_f64_approx( &self, v: f64, max_denominator: u64, ) -> Result<Ex, SymplexError>

Convert an f64 to the closest rational with denominator at most max_denominator — the “human” reading of a float.

Uses continued-fraction convergents (see numeric::f64_to_ratio_approx), so 0.1 → 1/10, 0.3333333333333333 → 1/3, and 3.14159 → 355/113 for max_denominator = 1000. ±∞ become oo / -oo.

Errors

SymplexError::InvalidArgument for NaN or max_denominator == 0.

Examples

use symplex::prelude::*;

let ctx = Context::new();
assert_eq!(format!("{}", ctx.from_f64_approx(0.1, 1_000_000).unwrap()), "1/10");
assert_eq!(format!("{}", ctx.from_f64_approx(1.0 / 3.0, 1_000_000).unwrap()), "1/3");
assert_eq!(format!("{}", ctx.from_f64_approx(std::f64::consts::PI, 1000).unwrap()), "355/113");
assert!(ctx.from_f64_approx(1.5, 0).is_err());

pub fn from_f64_nice(&self, v: f64) -> Result<Ex, SymplexError>

The “nice” rational for a float: from_f64_approx with max_denominator = 1_000_000_000.

This recovers every decimal with up to nine fractional digits exactly (0.1 → 1/10, 2.375 → 19/8, 0.123456789 → 123456789/1000000000) while still turning 1.0/3.0 into 1/3.

Errors

SymplexError::InvalidArgument for NaN.

Examples

use symplex::prelude::*;

let ctx = Context::new();
assert_eq!(format!("{}", ctx.from_f64_nice(0.1).unwrap()), "1/10");
assert_eq!(format!("{}", ctx.from_f64_nice(0.1 + 0.2).unwrap()), "3/10");
assert_eq!(format!("{}", ctx.from_f64_nice(2.375).unwrap()), "19/8");

pub fn from_bigint(&self, n: BigInt) -> Ex

Create an integer expression from a BigInt.

use symplex::prelude::*;
use num_bigint::BigInt;

let ctx = Context::new();
let big = BigInt::parse_bytes(b"123456789012345678901234567890", 10).unwrap();
assert_eq!(format!("{}", ctx.from_bigint(big)), "123456789012345678901234567890");

pub fn from_ratio(&self, r: Ratio<BigInt>) -> Ex

Create a rational expression from a Ratio<BigInt>.

The value is stored in lowest terms. A ratio with a zero denominator (only constructible via Ratio::new_raw) maps to zoo (complex infinity), or nan for 0/0, instead of panicking.

use symplex::prelude::*;
use num_bigint::BigInt;
use num_rational::Ratio;

let ctx = Context::new();
let r = Ratio::new(BigInt::from(6), BigInt::from(-4));
assert_eq!(format!("{}", ctx.from_ratio(r)), "-3/2");

pub fn from_i128(&self, n: i128) -> Ex

Create an integer expression from an i128.

use symplex::prelude::*;

let ctx = Context::new();
assert_eq!(format!("{}", ctx.from_i128(i128::MIN)), "-170141183460469231731687303715884105728");

pub fn from_u64(&self, n: u64) -> Ex

Create an integer expression from a u64.

use symplex::prelude::*;

let ctx = Context::new();
assert_eq!(format!("{}", ctx.from_u64(u64::MAX)), "18446744073709551615");

pub fn rational_str(&self, s: &str) -> Result<Ex, SymplexError>

Parse an exact rational from a string of the form "p", "p/q", or "-p/q" (arbitrary-precision integers, surrounding whitespace ignored).

Errors

SymplexError::InvalidArgument if the string is not two integers separated by /, or if the denominator is zero.

Examples

use symplex::prelude::*;

let ctx = Context::new();
assert_eq!(format!("{}", ctx.rational_str("22/7").unwrap()), "22/7");
assert_eq!(format!("{}", ctx.rational_str("-6/4").unwrap()), "-3/2");
assert_eq!(format!("{}", ctx.rational_str(" 42 ").unwrap()), "42");
assert!(ctx.rational_str("1/0").is_err());
assert!(ctx.rational_str("0.5").is_err()); // use decimal_str

pub fn decimal_str(&self, s: &str) -> Result<Ex, SymplexError>

Parse a decimal literal exactly: "0.1" → 1/10, "2.5e3" → 2500, "-1.25e-2" → -1/80.

Accepts [+|-] digits [. digits] [(e|E) [+|-] digits] with arbitrary length; nothing is rounded. (The general parse also reads decimals exactly, but it accepts whole expressions; this method rejects anything that is not a plain number.)

Errors

SymplexError::InvalidArgument if the string is not a decimal literal.

Examples

use symplex::prelude::*;

let ctx = Context::new();
assert_eq!(format!("{}", ctx.decimal_str("0.1").unwrap()), "1/10");
assert_eq!(format!("{}", ctx.decimal_str("3.14159").unwrap()), "314159/100000");
assert_eq!(format!("{}", ctx.decimal_str("1e-5").unwrap()), "1/100000");
assert_eq!(format!("{}", ctx.decimal_str("-2.5E3").unwrap()), "-2500");
assert_eq!(format!("{}", ctx.decimal_str(".5").unwrap()), "1/2");
assert!(ctx.decimal_str("1/2").is_err());
assert!(ctx.decimal_str("abc").is_err());

pub fn complex(&self, re: &Ex, im: &Ex) -> Ex

Build the complex number re + im·I.

Both parts may be arbitrary expressions; the result is canonicalized like any other sum.

Panics

Panics if re or im belongs to a different context.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let z = ctx.complex(&ctx.int(3), &ctx.int(-4));
assert_eq!(format!("{z}"), "-4*I + 3");
let (re, im) = z.as_real_imag();
assert_eq!((format!("{re}"), format!("{im}")), ("3".to_string(), "-4".to_string()));

pub fn symbols(&self, names: &[&str]) -> Vec<Ex>

Create several symbols at once.

Panics

Panics if any name is empty (as symbol does).

Examples

use symplex::prelude::*;

let ctx = Context::new();
let v = ctx.symbols(&["x", "y", "z"]);
assert_eq!(v.len(), 3);
assert_eq!(format!("{}", &v[0] + &v[1] + &v[2]), "x + y + z");

pub fn symbols_indexed(&self, base: &str, n: usize) -> Vec<Ex>

Create the indexed family base0, base1, …, base{n-1}.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let a = ctx.symbols_indexed("a", 3);
assert_eq!(format!("{}", &a[0] * &a[1] * &a[2]), "a0*a1*a2");
assert!(ctx.symbols_indexed("q", 0).is_empty());

pub fn apply<T: AsRef<Ex>>(&self, name: &str, args: &[T]) -> Ex

Apply a named, otherwise undefined function to arguments: f(x, y).

This produces the generic Apply node. Nothing is known about f, so:

• eval and simplify leave it alone (its arguments are still evaluated / simplified);
• diff applies the chain rule and yields a formal Derivative(f(…), …) for the outer function;
• numeric evaluation / compile return SymplexError::NotImplemented.

args may be a slice of Ex or of &Ex.

Panics

Panics if name is empty or any argument belongs to another context.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let x = ctx.symbol("x");
let f = ctx.apply("f", &[&x]);
assert_eq!(format!("{f}"), "f(x)");
assert_eq!(f.eval(), f);
assert_eq!(format!("{}", f.diff(&x)), "Derivative(f(x), x)");
// Chain rule on the argument:
let g = ctx.apply("g", &[x.powi(2)]);
assert_eq!(format!("{}", g.diff(&x)), "2*x*Derivative(g(x^2), x^2)");

pub fn sum<I>(&self, iter: I) -> Ex

where I: IntoIterator, I::Item: AsRef<Ex>,

Sum an iterator of expressions, yielding 0 when it is empty.

Unlike iter.sum::<Ex>(), this never panics on empty input because the context is known. Items may be Ex or &Ex.

Panics

Panics if an item belongs to a different context.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let xs = ctx.symbols_indexed("x", 3);
assert_eq!(format!("{}", ctx.sum(&xs)), "x0 + x1 + x2");
assert_eq!(format!("{}", ctx.sum(Vec::<Ex>::new())), "0");

pub fn product<I>(&self, iter: I) -> Ex

where I: IntoIterator, I::Item: AsRef<Ex>,

Multiply an iterator of expressions, yielding 1 when it is empty.

Panics

Panics if an item belongs to a different context.

Examples

use symplex::prelude::*;

let ctx = Context::new();
let p = ctx.product((1..=4).map(|n| ctx.int(n)));
assert_eq!(format!("{p}"), "24");
assert_eq!(format!("{}", ctx.product(Vec::<Ex>::new())), "1");

Trait Implementations

impl Clone for Context

fn clone(&self) -> Context

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Context

fn default() -> Self

Returns the “default value” for a type.