Skip to content
Symi Docs
Python
On this page

Context safety

A context owns its symbols, assumptions, interned expressions, and structural objects. Rust calls this owner a Session. Every returned expression, matrix, geometry object, undefined function, and CAD result records both owner identity and reset generation.

The public surfaces validate provenance before reading or mutating mathematical state:

  • direct operands must have the receiver's owner;
  • variable expressions must be same-owner symbols;
  • every nested collection member is checked;
  • matrices and geometry values retain their owner;
  • callable undefined functions validate every argument;
  • reset invalidates all earlier handles.

Mixing contexts raises context_mismatch. Using an object after reset_context() or Session::reset() raises stale_object. Symi never reinterprets a foreign symbol identifier through the receiving symbol table.

Python
first = symi.Context()
second = symi.Context()
x = first.symbol("x")
y = second.symbol("y")

first.add(x, y)          # raises an error before computation
first.reset_context()
x + 1                    # raises stale_object

Default-context objects and objects from an explicit context also do not mix. Use one explicit context throughout an isolated computation. To transfer mathematics intentionally, serialize it and parse it in the destination context; assumptions are context state and must be established separately.

Releasing or freeing a JavaScript handle is also terminal for that handle. The recommended facade duplicates handles needed by raw iterable calls, so passing a value in an array does not unexpectedly free the caller's value.

execution_mode#

Default context

execution_mode() -> str
Calling forms

Explicit context: Context.execution_mode

execution_mode() -> str

Sessions expose sequential and automatic execution modes and start in sequential. Automatic mode permits the runtime to use its process-wide bounded backend; it does not promise a worker count. Initializing the backend does not by itself change how any session runs, so a caller wanting internal parallelism selects automatic as well. The mode is captured when an operation begins, so a mode change affects later operations only.

parallelism_capability() reports whether the target compiled a backend, whether it has been initialized, its pool worker count, the maximum concurrency one operation may use, and the stable reason for a serial fallback. Explicit contexts and their expressions remain the unit of ownership; the capability record is runtime metadata and is not part of a mathematical object or its serialization.

Native Python calls convert host values while the interpreter is attached, then detach it for pure Symi work before constructing Python results. An explicit Context and its immutable objects may therefore be shared by Python threads; module-level defaults remain thread-local. When a Python job system already provides outer worker threads, use sequential mode for those jobs or keep the outer worker count bounded so it does not multiply the internal Rayon workers. The automatic mode is a permission and does not promise a particular worker count.

init_thread_pool_with_capability#

The atomic browser package includes the canonical initThreadPool(worker_count) export from wasm-bindgen-rayon. Symi also exposes the generated initThreadPoolWithCapability(worker_count) adapter; call this adapter when using the Symi package so the runtime capability is published only after the shared Rayon workers are ready. Capability queries before that point report not_initialized and bulk operations use the serial implementation. A rejected bootstrap is recorded as initialization_failed and does not enable a fallback thread pool. The universal WASM package does not expose either thread bootstrap and reports not_compiled.

Kotlin and Swift calls retain the dedicated worker bridge for session and object ownership. Foreign calls through one mobile session are serialized at that bridge, while an operation running there may use the shared internal Rayon pool. Keep surrounding dispatch queues bounded and avoid adding a second per-operation worker pool; otherwise outer queue width and internal workers can oversubscribe the device.

simplify_bulk#

Default context

simplify_bulk(targets: Iterable[ExpressionLike]) -> Any
Calling forms

Explicit context: Context.simplify_bulk

simplify_bulk(targets: Iterable[ExpressionLike]) -> Any

The ordered bulk operations simplify_bulk, expand_bulk, differentiate_bulk, substitute_bulk, evaluate_numeric_bulk, and serialize_bulk validate every input against one context and generation before work begins. Results retain input order and use one captured operation configuration. A reset during the call rejects publication rather than returning a partially completed collection. An item-level decline or diagnostic does not reorder or cancel unrelated items.

generation#

Not exposed by the Python bindings. Available as api::AssumptionScope::generation in Rust.

The generation objects currently produced by this context belong to. Resetting a context advances its generation, which is what makes every object made before the reset stale. The same accessor exists on the objects themselves, reporting the generation the object was created in; comparing the two is exactly what is_stale does.

session#

Not exposed by the Python bindings. Available as api::AssumptionScope::session in Rust.

The context that owns this object. Every mathematical object belongs to one context for its whole life, and this accessor is how a host adapter carries the owner alongside the object. Objects from two different contexts cannot be combined; doing so is a context-mismatch error.

Additional API#

differentiate_bulk#

Default context

differentiate_bulk(
    targets: Iterable[ExpressionLike],
    variable: ExpressionLike,
) -> Any

Differentiate an ordered collection in the thread's default context.

Calling forms

Explicit context: Context.differentiate_bulk

differentiate_bulk(
    targets: Iterable[ExpressionLike],
    variable: ExpressionLike,
) -> Any

evaluate_numeric_bulk#

Default context

evaluate_numeric_bulk(
    targets: Iterable[ExpressionLike],
    significant_digits: int = ...,
    accuracy: str = ...,
    maximum_precision_bits: int = ...,
    work_budget: int = ...,
) -> Any

Evaluate an ordered collection numerically in the thread's default context.

Calling forms

Explicit context: Context.evaluate_numeric_bulk

evaluate_numeric_bulk(
    targets: Iterable[ExpressionLike],
    significant_digits: int = ...,
    accuracy: str = ...,
    maximum_precision_bits: int = ...,
    work_budget: int = ...,
) -> Any

expand_bulk#

Default context

expand_bulk(targets: Iterable[ExpressionLike]) -> Any

Expand an ordered collection in the thread's default context.

Calling forms

Explicit context: Context.expand_bulk

expand_bulk(targets: Iterable[ExpressionLike]) -> Any

initialize_parallelism#

Default context

initialize_parallelism(worker_count: int) -> str

Initialize the process-wide parallel backend from the thread's default context.

Calling forms

Explicit context: Context.initialize_parallelism

initialize_parallelism(worker_count: int) -> str

parallelism_capability#

Default context

parallelism_capability() -> Any

Return capability facts for the thread's default context.

Calling forms

Explicit context: Context.parallelism_capability

parallelism_capability() -> Any

serialize_bulk#

Default context

serialize_bulk(targets: Iterable[ExpressionLike]) -> Any

Serialize an ordered collection in the thread's default context.

Calling forms

Explicit context: Context.serialize_bulk

serialize_bulk(targets: Iterable[ExpressionLike]) -> Any

set_execution_mode#

Default context

set_execution_mode(name: str) -> None

Select the execution mode used by the thread's default context.

Calling forms

Explicit context: Context.set_execution_mode

set_execution_mode(name: str) -> None

substitute_bulk#

Default context

substitute_bulk(
    targets: Iterable[ExpressionLike],
    variable: ExpressionLike,
    value: ExpressionLike,
) -> Any

Substitute one symbol and value throughout an ordered collection in the thread's default context.

Calling forms

Explicit context: Context.substitute_bulk

substitute_bulk(
    targets: Iterable[ExpressionLike],
    variable: ExpressionLike,
    value: ExpressionLike,
) -> Any

Symi documentation · Python