neuralqx.experimental.operators.symbolic.compiler.passes package

Symbolic compiler pass implementations.

class AbstractSymbolicPass

Bases: ABC

Abstract base for all symbolic compiler passes.

Each concrete pass implements run() which mutates the compilation context and optionally returns a metadata dictionary. The public execute() wrapper times the pass, wraps any raised exception with context, records a SymbolicPassReport on the context, and re-raises failures.

Subclasses must define name.

class SymbolicValidationPass

Bases: AbstractSymbolicPass

Validates symbolic operator IR before lowering.

This pre-cache pass calls validate_symbolic_ir() on the context IR. When strict_validation is enabled on the compiler options, any validation error is raised immediately. In non-strict mode the error is recorded in the pass metadata but execution continues, allowing the remaining pipeline to proceed.

Analysis key written: "validation_summary"

class SymbolicNormalizationPass

Bases: AbstractSymbolicPass

Normalizes and fingerprints the symbolic operator IR.

This pre-cache pass:

  1. Computes the static IR fingerprint (SHA-256 over the JSON-serialized IR) and stores it as analysis key "ir_fingerprint".

  2. Resolves the effective backend (auto -> jax) and stores it as analysis key "resolved_backend", also updating the context via set_selected_backend().

  3. Stores a canonical term ordering (by term name, stable) as analysis key "term_order" - a tuple of term names in sorted order.

Analysis keys written: "ir_fingerprint", "resolved_backend", "term_order"

class SymbolicFanoutAnalysisPass

Bases: AbstractSymbolicPass

Computes per-term and total fanout (max connected states) bounds.

Analysis keys written:

"term_fanouts" - dict[unique_key, int] "total_fanout" - int

class SymbolicFusionPass

Bases: AbstractSymbolicPass

Groups IR terms into fusion-compatible clusters.

This post-cache pass (only runs on cache misses) plans which terms can be lowered inside a single vmapped loop rather than separate loops.

When enable_fusion is False in the compiler options, each term is placed in its own singleton group.

Analysis keys written:

"fusion_groups", list[list[str]], each inner list is a group of term names that can be lowered in a single fused kernel loop.

The lowerer reads "fusion_groups" to decide loop structure.

Submodules