Compiler

Compilation from DSL AST to executable quivers.

compiler

quivers.dsl.compiler: AST -> Program compiler.

Re-exports the public surface from the package's submodules.

Compiler

Compiler(module: Module)

Bases: _DeclarationsMixin, _ProgramsMixin, _StructuralMixin, _DeductionsMixin, _ResolutionMixin, _ExpressionsMixin

Compile a quivers DSL AST into a Program.

The compiler maintains three environments:

• objects: name -> SetObject (discrete finite sets)
• spaces: name -> ContinuousSpace
• morphisms: name -> Morphism or ContinuousMorphism (any morphism-like)

It processes statements in order and compiles the output expression into a Program wrapping the morphism DAG.

PARAMETER	DESCRIPTION
module	The parsed AST. TYPE: Module

Source code in src/quivers/dsl/compiler/core.py

def __init__(self, module: Module) -> None:
    self._module = module
    self._algebra: Algebra = PRODUCT_FUZZY
    self._categories: list[str] = []
    self._rules: dict = {}
    self._bundles: dict[str, tuple[str, ...]] = {}
    self._aliases: dict[str, ObjectExpr] = {}
    self._alias_names: set[str] = set()
    # Built-in transformation catalog: singletons looked up by
    # bare name (``expectation``, ``log_prob``, …) and
    # constructors invoked with arguments (``softmax(B)``,
    # ``bayes_invert(prior)``).  Disjoint from
    # `_transformations`, which holds user let-bound
    # transformations defined inside the module.
    self._trans_singletons: dict = _build_default_trans_singletons()
    self._trans_constructors: dict = _build_default_trans_constructors()
    # User-defined transformations bound via ``let t = …``.
    # Disjoint from `_morphisms`: a ``let`` whose RHS
    # resolves to a transformation lands here; a ``let`` whose
    # RHS resolves to a morphism lands in ``_morphisms``.
    self._transformations: dict = {}
    self._objects: dict[str, SetObject] = {}
    self._spaces: dict = {}
    self._morphisms: dict = {}
    self._groups: dict[str, list[str]] = {}
    self._output_expr: Expr | None = None
    # Parametric-program templates: dependent kernels Π(p:P).Kern(dom(p),cod(p))
    # stored as their unsubstituted AST decl. Instantiated at each call
    # site by parameter substitution + α-renaming of internal latents.
    self._program_templates: dict[str, ProgramDecl] = {}
    # Operadic contraction declarations. Each entry is callable
    # from the DSL at let-binding sites; the value records the
    # compiled `EinsumWiring` plus the declared domain /
    # codomain typing for shape-checking at invocation time.
    self._contractions: dict[str, "_CompiledContraction"] = {}

categories property

categories: list[str]

The declared category atoms.

rules property

rules: dict

The compiled rule schemas from rule declarations.

objects property

objects: dict[str, SetObject]

The compiled object environment.

spaces property

spaces: dict

The compiled space environment.

morphisms property

morphisms: dict

The compiled morphism environment.

algebra property

algebra: Algebra

The active algebra.

programs property

programs: dict

Declared parametric program templates (program NAME(...)).

deductions property

deductions: dict

Declared deduction systems (deduction NAME : ...).

signatures property

signatures: dict

Declared signatures (signature NAME).

encoders property

encoders: dict

Declared encoders (encoder NAME : Sig).

decoders property

decoders: dict

Declared decoders (decoder NAME : Sig).

losses property

losses: dict

Declared loss heads (loss NAME : ... [on=...]).

Keyed by entry name; values are the registered :class:LossEntry records. Empty when no loss decl appears in the module.

bundles property

bundles: dict[str, tuple[str, ...]]

Declared bundle aliases (bundle NAME = R1 | R2 | ...).

contractions property

contractions: dict

Declared tensor-network contractions (contraction NAME : ... [wiring=...]).

transformations property

transformations: dict

User-declared transformation constructors / singletons.

compile

compile() -> Program

Compile the module into a trainable Program.

RETURNS	DESCRIPTION
Program	The compiled nn.Module wrapping the morphism DAG.

RAISES	DESCRIPTION
CompileError	On semantic errors (undefined names, type mismatches, etc.).

Source code in src/quivers/dsl/compiler/core.py

def compile(self) -> Program:
    """Compile the module into a trainable Program.

    Returns
    -------
    Program
        The compiled nn.Module wrapping the morphism DAG.

    Raises
    ------
    CompileError
        On semantic errors (undefined names, type mismatches, etc.).
    """
    _register_extra_algebras()
    for stmt in self._module.statements:
        self._compile_statement(stmt)
    if self._output_expr is None:
        # A module may declare only structural artifacts
        # (signatures, encoders, decoders, losses) with no
        # exported morphism; the returned Program is a container
        # carrying those artifacts.
        program = Program(None)
    elif isinstance(
        self._output_expr, ExprIdent
    ) and self._output_expr.name in getattr(self, "_program_templates", {}):
        # The export names a parametric program template. A
        # template has no root morphism on its own (a function
        # ``Pi (p : P). Kern(dom(p), cod(p))`` rather than a
        # single Kleisli arrow); the returned Program is a
        # container holding the template, which the caller
        # instantiates by attribute access.
        tmpl_name = self._output_expr.name
        program = Program(None)
        invoker = self._make_template_invoker(tmpl_name)
        program.templates = {tmpl_name: invoker}
        # Convenience: ``program.<name>(...)`` works directly.
        object.__setattr__(program, tmpl_name, invoker)
    else:
        root_morphism = self._compile_expr(self._output_expr)
        program = Program(root_morphism)
    # Attach the compiler's deduction and posterior registries to
    # the Program so downstream callers can reach them after
    # `quivers.dsl.load(...)`.
    program.deductions = getattr(self, "_deductions", {})
    program.posteriors = getattr(self, "_posteriors", {})
    program.signatures = getattr(self, "_signatures", {})
    program.encoders = getattr(self, "_encoders", {})
    program.decoders = getattr(self, "_decoders", {})
    program.losses = getattr(self, "_loss_registry", None)
    # Wire the loss registry into every compiled deduction so the
    # agenda's rule-firing and chart-completion paths can fire
    # rule-attached and chart-attached losses automatically.
    if program.losses is not None:
        for name, system in program.deductions.items():
            system._loss_registry = program.losses  # type: ignore[attr-defined]
            system._deduction_name = name  # type: ignore[attr-defined]
    return program

compile_env

compile_env() -> dict

Compile all statements and return the full environment.

Useful for inspection without requiring an output declaration.

RETURNS	DESCRIPTION
dict	Combined environment of every declared atom: the active algebra, objects, spaces, morphisms, rules, programs (parametric templates), deductions, signatures, encoders, decoders, losses, bundles, contractions, transformations.

Source code in src/quivers/dsl/compiler/core.py

def compile_env(self) -> dict:
    """Compile all statements and return the full environment.

    Useful for inspection without requiring an output declaration.

    Returns
    -------
    dict
        Combined environment of every declared atom: the active
        algebra, objects, spaces, morphisms, rules, programs
        (parametric templates), deductions, signatures, encoders,
        decoders, losses, bundles, contractions, transformations.
    """
    _register_extra_algebras()
    for stmt in self._module.statements:
        self._compile_statement(stmt)
    env: dict = {}
    env["__algebra__"] = self._algebra
    for name, obj in self._objects.items():
        env[name] = obj
    for name, space in self._spaces.items():
        env[name] = space
    for name, morph in self._morphisms.items():
        env[name] = morph
    for name, rule in self._rules.items():
        env[name] = rule
    for name, tmpl in getattr(self, "_program_templates", {}).items():
        env[name] = tmpl
    for name, system in getattr(self, "_deductions", {}).items():
        env[name] = system
    for name, sig in getattr(self, "_signatures", {}).items():
        env[name] = sig
    for name, enc in getattr(self, "_encoders", {}).items():
        env[name] = enc
    for name, dec in getattr(self, "_decoders", {}).items():
        env[name] = dec
    reg = getattr(self, "_loss_registry", None)
    if reg is not None:
        for entry in reg.entries:
            env[entry.name] = entry
    for name, bundle in self._bundles.items():
        env[name] = bundle
    for name, contr in getattr(self, "_contractions", {}).items():
        env[name] = contr
    return env

CompileError

CompileError(message: str, line: int = 0, col: int = 0)

Bases: Exception

Raised when the compiler encounters a semantic error.

PARAMETER	DESCRIPTION
message	Error description. TYPE: str
line	Source line number (0 if unknown). TYPE: int DEFAULT: 0
col	Source column number (0 if unknown). TYPE: int DEFAULT: 0

Source code in src/quivers/dsl/compiler/_prelude.py

def __init__(self, message: str, line: int = 0, col: int = 0) -> None:
    self.line = line
    self.col = col
    loc = f"line {line}, col {col}: " if line else ""
    super().__init__(f"{loc}{message}")