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

Migration

Python#

  • Classes are spelled in CapWords: symi.expression is now symi.Expression, symi.context is symi.Context, and symi.point_2d is symi.Point2d. Methods, module functions, and keyword arguments keep the Symi underscore spelling.
  • Replace constant calls such as symi.pi() with properties such as symi.pi.
  • Bare integers and fractions.Fraction values are now accepted exactly in expression-like positions; explicit lifting remains valid.
  • Variable parameters may receive an existing symbol expression instead of repeating its name.
  • assumptions_of returns a native mapping rather than JSON text.
  • Symbolic equality and ordering construct relations. Use evaluate_truth for an explicit host Boolean result and do not rely on incidental Python truthiness.
  • Invalid arguments now raise categorized errors instead of returning undefined, empty containers, or unrelated conversion messages.

JavaScript#

Wrap the generated module with createFacade(rawModule) and use the returned facade as the default public API.

  • Public names use JavaScript spelling: classes are PascalCase (Expression, Matrix, Context) and members are camelCase, so the Symi names evaluate_truth, numerator_denominator, real_part, imaginary_part, absolute_value, and evaluate_limit are reached as evaluateTruth, numeratorDenominator, realPart, imaginaryPart, absoluteValue, and evaluateLimit.
  • Constants are properties.
  • Expression-like values accept bigint or safe integral number values.
  • Iterable arguments are non-destructive.
  • Matrices use nested row iterables instead of (rows, columns, flatEntries).
  • Logical pairs use records, for example { condition, value }, instead of flat interleaved arrays.
  • Optional values use facade defaults and named records where applicable, rather than positional undefined placeholders.
  • Three-valued queries use null for unknown.
  • Failures are SymiError instances with stable diagnostic fields.

The generated wasm-bindgen exports remain reachable as facade.raw. This raw layer preserves compatibility names and ABI-shaped ownership behavior for advanced callers; it is not the recommended surface for new code.

Rust#

New application code should import symi::api::prelude::*, construct a Session, and retain facade handles. Existing engine code may continue using crate-root modules, raw contexts, interners, and expression references. Migrate at an application boundary rather than mixing raw and facade objects inside one computation.

Numeric functions of other systems#

Other computer algebra systems commonly name their numeric functions N, evalf, nsolve, nroots, and nsum. Their counterparts are the operations in Numeric evaluation. The Python spellings are shown; JavaScript uses the camelCase forms of the same names.

Common name Symi Notes
N(expr, n), expr.evalf(n) evaluate_numeric(expr, n) Returns a NumericValue, not a float expression
evalf with values for the symbols evaluate_numeric(expr, n, substitutions={x: v}) Every free symbol must be bound
float(expr), complex(expr) float(expr), complex(expr), evaluate_to_float float raises unless the value is certified and exactly real
a chop option No option A value that cannot be separated from zero is decided exactly or declines
nsolve(f, x, x0) find_root_numeric(f, x, x0) Returns a NumericRootFindingResult with a status
nsolve([f, g], [x, y], [x0, y0]) find_root_numeric([f, g], [x, y], [x0, y0]) variable_values maps each variable to its value
nsolve with a bisection solver on (a, b) find_root_numeric_in_bracket(f, x, a, b) The endpoint signs must differ
a working precision in bits significant_digits=d Precision is requested in decimal digits
nroots(p, n) polynomial_roots_numeric(p, x, n) Each distinct root once, with its exact multiplicity
isolating intervals of real roots isolate_real_roots_numeric(p, x, lower, upper) Exact rational enclosures of the real roots
numeric value of an unevaluated integral integrate_definite_numeric(f, x, a, b, n) Also evaluate_numeric(integral(f, x, a, b), n)
numeric value of an unevaluated sum, nsum summation_numeric(f, k, a, b, n) Also evaluate_numeric(summation(f, k, a, b), n)
a float literal such as 0.1 in an expression rational(1, 10) Expressions hold exact numbers only
recovering a rational from a float value.to_simplest_rational(), rational_from_float(v, q) Explicit conversions back to exact numbers

The behaviour differs from those functions in these ways:

  • No partial evaluation. Some systems evaluate the numeric parts of an expression and leave the symbols, so N(x + pi) becomes x + 3.14159265358979. Symi declines with unbound_symbol unless every free symbol is bound through substitutions; evaluate the constant part on its own to get its value.
  • Numbers never enter expressions. A NumericValue is not an expression and has no arithmetic. Compute in exact expressions and evaluate the result, or convert a value back explicitly with to_rational (the exact midpoint of its enclosure) or to_simplest_rational. A host float given as a bound value or a start point is read as the exact binary fraction it denotes.
  • Certified unless estimates are allowed. Every value is labelled certified or estimated. By default, a function without a certified method for its arguments makes the request decline with no_certified_kernel, as bessel_j(0, 3) does; pass accuracy="estimated_allowed" to accept an estimate. The table in Certified functions lists which functions are certified.
  • Exact zeros instead of chop. Where a small number such as 0.e-15 would be printed or discarded, Symi either proves that the value is zero and returns an exact zero, or declines with magnitude_below_resolution and a bound on the magnitude.
  • Declines are typed. Where a divergent sum or a root search that does not converge raises a generic error elsewhere, Symi raises with a reason attribute, such as series_divergent, or, for root finding and polynomial roots, returns a result whose status is declined and whose decline_reason says why.
  • Roots come with their status. A root found by find_root_numeric is certified only when a box around it is proved to contain exactly one root. A multiple root, such as the root of (x−1)3(x - 1)^3, is not certified: it declines by default and is returned as converged_uncertified, with a multiplicity estimate, under accuracy="estimated_allowed".
  • Polynomial roots are listed once. polynomial_roots_numeric lists each distinct root once with its exact multiplicity and marks the list complete; a double root is not returned as two nearby values.