neuralqx.experimental.operators.symbolic.ir package

Symbolic operator intermediate representation (IR).

class AmplitudeExpr(op, args=<factory>)

Bases: object

Typed expression node for operator matrix elements.

op

Expression operation name.

args

Ordered operation arguments (frozen tuple).

coerce_amplitude_expr(value)

Coerces user values into typed amplitude-expression nodes.

Parameters:

value (Any) – Input expression value.

Return type:

AmplitudeExpr

Returns:

Typed amplitude expression.

Raises:

TypeError – If value cannot be converted.

class EmissionSpec(update_program, amplitude, branch_tag=None)

Bases: object

One output branch (connected state + matrix element) of a term.

A single iterator evaluation can produce multiple branches, one per EmissionSpec in the parent term’s emissions tuple. This allows a plaquette term, for example, to emit both + and - connected states from the same site-tuple without splitting into two separate terms.

update_program

Site-update program mapping x -> x'.

amplitude

Matrix-element expression evaluated in the source environment.

branch_tag

Optional diagnostic tag for this emission slot.

class KBodyIteratorSpec(labels, index_sets)

Bases: object

Static K-body iterator over a pre-computed list of site-index tuples.

This iterator evaluates a term kernel once per entry in index_sets. Each entry is a K-tuple of integer site indices that are bound to the corresponding element of labels inside the evaluation environment.

For a single-site iterator over all N sites, use KBodyIteratorSpec(labels=("i",), index_sets=tuple((k,) for k in range(N))). For a static triplet iterator, provide the explicit list of (e1, e2, e3) triplets. For a global (one-branch) term, use KBodyIteratorSpec(labels=(), index_sets=((),)).

labels

Ordered tuple of K label strings bound per iteration.

index_sets

M-tuple of K-tuples of int site indices.

class PredicateExpr(op, args=<factory>)

Bases: object

Typed boolean expression node for operator branch filtering.

op

Predicate operation name.

args

Ordered operation arguments.

coerce_predicate_expr(value)

Coerces user values into typed predicate-expression nodes.

Parameters:

value (Any) – Input predicate value.

Return type:

PredicateExpr

Returns:

Typed predicate expression.

Raises:

TypeError – If value cannot be converted.

class SymbolicIRTerm(name, iterator, predicate, update_program, amplitude, branch_tag=None, metadata=<factory>, fanout_hint=None, emissions=None)

Bases: object

One primitive declarative symbolic operator term.

name

Term name.

iterator

Iterator descriptor (KBodyIteratorSpec).

predicate

Branch-selection predicate.

update_program

Matrix-element update program.

amplitude

Matrix-element expression.

branch_tag

Optional branch tag for diagnostics.

metadata

Optional stable term metadata tuple.

fanout_hint

Optional static upper-bound hint on the number of connected states this term produces per input configuration.

emissions

Optional multi-emission tuple that, when present, supersedes update_program and amplitude. Each entry is an EmissionSpec representing one output branch per iterator evaluation.

class SymbolicOperatorIR(operator_name, mode, hilbert_size, dtype_str, is_hermitian, terms=<factory>, metadata=<factory>)

Bases: object

Immutable symbolic operator IR container.

operator_name

Name of the operator this IR represents.

mode

IR mode (symbolic for DSL-built operators, jax_kernel for direct JAX-kernel operators).

hilbert_size

Size of the Hilbert space (number of sites).

dtype_str

String representation of the matrix-element dtype.

is_hermitian

Whether the source operator is declared Hermitian.

terms

Declarative term tuple for symbolic mode.

metadata

Optional stable metadata tuple.

class UpdateOp(kind, params=<factory>)

Bases: object

One primitive site-update operation.

kind

Update operation kind (see _UPDATE_OP_KINDS).

params

Deterministic parameter tuple ((key, value), ...). Values are AmplitudeExpr nodes, plain integers, or nested structures depending on kind.

class UpdateProgram(ops=<factory>)

Bases: object

Ordered immutable sequence of site-update operations.

ops

Ordered update-operation tuple.

validate_symbolic_ir(ir)

Validates a SymbolicOperatorIR structurally and semantically.

Parameters:

ir (SymbolicOperatorIR) – Operator IR to validate.

Return type:

dict

Returns:

Validation summary dictionary.

Raises:

ValueError – If the IR is structurally invalid.

Submodules