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.
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_objectDefault-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() -> strSessions 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]) -> AnyCalling forms
Explicit context: Context.simplify_bulk
simplify_bulk(targets: Iterable[ExpressionLike]) -> AnyThe 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,
) -> AnyDifferentiate an ordered collection in the thread's default context.
Calling forms
Explicit context: Context.differentiate_bulk
differentiate_bulk(
targets: Iterable[ExpressionLike],
variable: ExpressionLike,
) -> Anyevaluate_numeric_bulk#
Default context
evaluate_numeric_bulk(
targets: Iterable[ExpressionLike],
significant_digits: int = ...,
accuracy: str = ...,
maximum_precision_bits: int = ...,
work_budget: int = ...,
) -> AnyEvaluate 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 = ...,
) -> Anyexpand_bulk#
Default context
expand_bulk(targets: Iterable[ExpressionLike]) -> AnyExpand an ordered collection in the thread's default context.
Calling forms
Explicit context: Context.expand_bulk
expand_bulk(targets: Iterable[ExpressionLike]) -> Anyinitialize_parallelism#
Default context
initialize_parallelism(worker_count: int) -> strInitialize the process-wide parallel backend from the thread's default context.
Calling forms
Explicit context: Context.initialize_parallelism
initialize_parallelism(worker_count: int) -> strparallelism_capability#
Default context
parallelism_capability() -> AnyReturn capability facts for the thread's default context.
serialize_bulk#
Default context
serialize_bulk(targets: Iterable[ExpressionLike]) -> AnySerialize an ordered collection in the thread's default context.
Calling forms
Explicit context: Context.serialize_bulk
serialize_bulk(targets: Iterable[ExpressionLike]) -> Anyset_execution_mode#
Default context
set_execution_mode(name: str) -> NoneSelect the execution mode used by the thread's default context.
substitute_bulk#
Default context
substitute_bulk(
targets: Iterable[ExpressionLike],
variable: ExpressionLike,
value: ExpressionLike,
) -> AnySubstitute one symbol and value throughout an ordered collection in the thread's default context.