neuralqx.experimental.operators.symbolic.core package

Core symbolic operator types.

class AbstractSymbolicOperator(hilbert, *, name, dtype_str='complex64', is_hermitian=False, metadata=None)

Bases: ComputationalJaxOperator

Abstract base class for all symbolic (DSL-defined) operators.

Symbolic operators extend ComputationalJaxOperator and declare their action through a typed IR rather than a hand-written JAX kernel. They cannot execute until the compiler has lowered them to a concrete JAX kernel via neuralqx.experimental.operators.symbolic.compiler.SymbolicCompiler.compile().

Attempting to call _get_conn_padded() before compilation raises SymbolicOperatorExecutionError.

Parameters:

  • hilbert (DiscreteHilbert) – Discrete Hilbert space this operator is defined on.

  • name (str) – User-facing operator name.

  • dtype_str (str) – String label for the matrix-element dtype.

  • is_hermitian (bool) – Whether this operator is declared Hermitian.

  • metadata (dict[str, Any] | None) – Optional extra metadata dictionary.

class CompiledOperator(hilbert, *, name, fn, is_hermitian, dtype)

Bases: ComputationalJaxOperator

An executable operator produced by lowering a SymbolicOperator.

CompiledOperator is the concrete result of symbolic_op.compile() or DOperator(...).compile(). Its get_conn_padded kernel is a pure JAX function that can be JIT-compiled, vmapped, and differentiated.

The class name is fixed and stable, it does not encode the operator name or structure. The readable operator name is available via the name property.

name

Operator name (from the DSL definition).

is_hermitian

Whether this operator is declared Hermitian.

dtype

Matrix-element NumPy dtype.

class SymbolicOperator(hilbert, name, ir_terms, *, dtype_str='complex64', is_hermitian=False, metadata=None)

Bases: AbstractSymbolicOperator

A symbolic operator built via the DOperator DSL.

SymbolicOperator is the canonical result of DOperator(...).build(). It holds an ordered list of typed IR terms and provides a .compile() method to lower them to an executable CompiledOperator.

Instances are not directly executable: calling get_conn_padded before compilation raises SymbolicOperatorExecutionError.

name

User-facing operator name.

hilbert

The NetKet Hilbert space.

dtype

Matrix-element dtype.

is_hermitian

Whether this operator is declared Hermitian.

Example:

op = (
    DOperator(hi, "hopping")
    .for_each_pair("i", "j")
    .where(site("i") > 0)
    .emit(shift("i", -1).shift("j", +1), amplitude=1.0)
    .build()
)
compiled = op.compile()
xp, mels = compiled.get_conn_padded(x_batch)
class SymbolicOperatorSum(hilbert, terms, *, name=None, dtype_str=None, is_hermitian=None, metadata=None)

Bases: AbstractSymbolicOperator

Additive composition of multiple symbolic operators sharing one Hilbert space.

SymbolicOperatorSum is the canonical Hamiltonian-style container for DSL-defined operators. It preserves term ordering, flattens nested sums, and aggregates fanout bounds across all contained terms.

Parameters:

  • hilbert (DiscreteHilbert) – Shared Hilbert space.

  • terms (Sequence[AbstractSymbolicOperator]) – Sequence of symbolic operator terms.

  • name (str | None) – Optional user-facing operator name.

  • dtype_str (str | None) – Optional explicit dtype override.

  • is_hermitian (bool | None) – Optional Hermiticity override (defaults to True iff all contained terms are Hermitian).

  • metadata (dict[str, Any] | None) – Optional metadata dictionary.

Submodules