Skip to content
Symi Docs
Python

Getting started: Python

Alpha releases are published on PyPI as prebuilt wheels for CPython 3.9 or newer. Install the symi-cas distribution, then import symi:

Shell
python -m pip install --pre symi-cas

To build the extension from source instead, run in the activated project environment:

Shell
cd symi-python
maturin develop --release

Prefer a qualified import so Symi names do not shadow Python builtins:

Python
from fractions import Fraction
import symi

x = symi.symbol("x", positive=True)
polynomial = x**2 + 2*x + 1

print(polynomial.factor())                  # (x + 1)^2
print(symi.integrate(symi.sin(x), x))
print(polynomial.substitute(x, 3))
print(symi.rational(2, 3) + Fraction(1, 3))
assert str(symi.integer(1 << 4096)) == str(1 << 4096)
Output
(x + 1)^2
-cos(x)
16
1

Python int, excluding bool, is accepted anywhere an expression-like value is expected and retains arbitrary precision. fractions.Fraction is converted exactly. A float is never silently promoted to an exact expression.

Constants are values, not calls:

Python
circle_area = symi.pi * symi.symbol("radius")**2
assert symi.evaluate_truth(symi.rational(1, 3) < 1) is True

Relations are symbolic expressions. Use evaluate_truth for an explicit True, False, or None; use execute when a symbolic true/false expression is wanted. Python truth testing of an undecidable symbolic value raises an error instead of guessing.

Classes take Python's CapWords spelling — Expression, Matrix, Context, Point2d — while methods, module functions, and keyword arguments keep the Symi underscore spelling. For an isolated computation, create an explicit context:

Python
context = symi.Context()
x = context.symbol("x")
matrix = context.matrix(((1, x), (x, 1)))
print(matrix.determinant())

Variable parameters accept either a name or a symbol from the same context. Collections accept finite iterables according to their mathematical meaning: matrices require ordered rows, while finite_set also accepts unordered host collections. See Conversions and collections and Context safety.

Errors carry stable structured attributes:

Python
try:
    symi.integer(1.5)
except TypeError as error:
    print(error.category, error.operation, error.parameter_path)
    print(error.received, error.expected, error.hint)

Boundary validation raises TypeError for a wrong host type, ValueError for an invalid exact conversion, and RuntimeError for a context or staleness violation. The structured attributes above are present on boundary diagnostics; a mathematical precondition reported from inside an operation (for example a zero denominator in rational) raises a plain ValueError carrying only its message.

The supplied symi.pyi describes expression-like inputs, constants, structured objects, and context methods for editors and type checkers.

Symi documentation · Python