neuralqx.experimental.operators.symbolic.compiler package¶

Symbolic operator compiler package.

class SymbolicCompiler(*, pipeline=None, lowerer_registry=None, artifact_store=None, options=None)¶

Bases: object

Orchestrates the symbolic operator compilation pipeline.

The compiler accepts a symbolic operator (an AbstractSymbolicOperator), runs it through the registered pass pipeline, optionally resolves a cache hit, and, on a miss, invokes the appropriate lowerer to produce a concrete ComputationalJaxOperator.

Typical usage:

from neuralqx.experimental.operators.symbolic import SymbolicCompiler

compiler = SymbolicCompiler()
compiled_op = compiler.compile_operator(my_symbolic_op)
xp, mels = compiled_op.get_conn_padded(x_batch)

Parameters:

pipeline (SymbolicPassPipeline | None) – Pass pipeline to use. Defaults to default_symbolic_pass_pipeline().
lowerer_registry (SymbolicLowererRegistry | None) – Lowerer registry. Defaults to default_symbolic_lowerer_registry().
artifact_store (AbstractSymbolicArtifactStore | None) – Artifact cache store. Defaults to the module-level shared default_symbolic_artifact_store().
options (SymbolicCompilerOptions | None) – Compiler options. Defaults to SymbolicCompilerOptions with all defaults.

compile_symbolic_operator(operator, *, options=None, metadata=None)¶

Module-level convenience function for one-shot symbolic compilation.

Uses the module-level shared SymbolicCompiler instance (lazily created). The shared compiler reuses the global in-process artifact cache.

Parameters:

operator (Any) – Symbolic operator with a to_ir() method.
options (SymbolicCompilerOptions | None) – Override compiler options.
metadata (dict[str, Any] | None) – Extra metadata for the context.

Return type:

ComputationalJaxOperator

Returns:

Executable ComputationalJaxOperator.

Example:

from neuralqx.experimental.operators.symbolic import compile_symbolic_operator

compiled_op = compile_symbolic_operator(my_symbolic_op)
xp, mels = compiled_op.get_conn_padded(x_batch)

class SymbolicCompilerOptions(backend_preference='auto', enable_fusion=True, strict_validation=True, cache_enabled=True, cache_namespace='nqx_symbolic_v1', debug_flags=<factory>)¶

Bases: object

Static and runtime controls for symbolic compiler execution.

backend_preference¶: Preferred lowering backend (currently only jax is supported, auto resolves to jax).

enable_fusion¶: Whether fusion-planning passes are enabled.

strict_validation¶: Whether validation passes fail hard on errors.

cache_enabled¶: Whether compiled artifacts are cached in-process.

cache_namespace¶: Namespace string used in cache-key generation.

debug_flags¶: Optional debug / instrumentation flags.

class SymbolicCompiledArtifact(operator_name, backend, lowerer_name, compiled_operator, cache_key=None, pass_reports=<factory>, metadata=<factory>)¶

Bases: object

Compilation artifact produced by the symbolic compiler pipeline.

operator_name¶: Source operator name.

backend¶: Selected backend name.

lowerer_name¶: Lowerer identifier used for code generation.

compiled_operator¶: Executable compiled operator object.

cache_key¶: Optional compilation cache key.

pass_reports¶: Ordered tuple of pass-execution reports.

metadata¶: Optional artifact metadata.

class SymbolicCompilationContext(*, operator, ir, options, metadata=None)¶

Bases: object

Holds per-compilation mutable state across pipeline stages.

The context is created by the compiler, mutated in-place by passes and lowerers, and finally read when packaging the compiled artifact.

Parameters:

operator (Any) – Source symbolic operator.
ir (SymbolicOperatorIR) – Symbolic operator IR extracted from the operator.
options (SymbolicCompilerOptions) – Effective compiler options.
metadata (Mapping[str, Any] | None) – Optional extra context metadata.

class SymbolicCacheKey(token, namespace)¶

Bases: object

Immutable cache key for compiled symbolic operator artifacts.

class SymbolicCompilationSignature(operator_ir_fingerprint, backend_target, hilbert_size, dtype_str, options_signature=<factory>)¶

Bases: object

Deterministic compilation signature for cache-key generation.

operator_ir_fingerprint¶: Stable digest of the operator IR.

backend_target¶: Resolved backend name.

hilbert_size¶: Hilbert space size.

dtype_str¶: Matrix-element dtype string.

options_signature¶: Static compiler-options signature.

default_symbolic_pass_pipeline()¶

Builds the default two-stage symbolic compiler pass pipeline.

Pre-cache passes (run on every compile() call):

SymbolicValidationPass - validates IR symbol scopes and update-op parameters.
SymbolicNormalizationPass - computes the IR fingerprint and resolves the target backend.

Post-cache passes (run only on cache misses):

SymbolicFanoutAnalysisPass - derives per-term fanout bounds and the total padded output size.
SymbolicFusionPass - groups terms into fusion-compatible clusters for the lowerer.

Return type:: SymbolicPassPipeline
Returns:: Configured SymbolicPassPipeline.

default_symbolic_lowerer_registry()¶

Builds the default symbolic lowerer registry.

Currently registers only the JAX backend lowerer (JAXSymbolicLowerer).

Return type:: SymbolicLowererRegistry
Returns:: Configured SymbolicLowererRegistry.

default_symbolic_artifact_store()¶

Returns the module-level shared in-memory artifact store.

The store is lazily created and reused across compiler instances in the same process. Call InMemorySymbolicArtifactStore.clear() to evict all compiled artifacts if needed.

Return type:: InMemorySymbolicArtifactStore
Returns:: Shared InMemorySymbolicArtifactStore.

neuralqx.experimental.operators.symbolic.compiler package¶

Subpackages¶

Submodules¶