neuralqx.experimental.operators.symbolic.dsl package

User-facing declarative symbolic operator DSL.

class DOperator(hilbert, name='operator', *, dtype='float64', hermitian=False)

Bases: object

Fluent builder for declarative symbolic quantum operators.

The builder accumulates one or more terms. Each term consists of an iterator (which sites to visit), an optional predicate (which visits to activate), and one or more emissions (how to rewrite the configuration and what matrix element to assign per active visit).

Calling any iterator method (for_each_site, for_each_pair, …, globally) seals the previous term (if any) and begins a new one. .where and .emit always target the current open term.

Parameters:

  • hilbert (DiscreteHilbert) – NetKet DiscreteHilbert space.

  • name (str) – Readable operator name (accessible as .name on the resulting SymbolicOperator).

  • dtype (str) – Matrix-element dtype string (default "float64").

  • hermitian (bool) – Whether to declare the operator Hermitian.

class Update(_program=None)

Bases: object

Immutable, chainable site-update program builder.

Every instance method appends one operation and returns a new Update object, the original is never mutated. The canonical entry points are the module-level free functions (shift(), write(), swap(), permute(), affine(), scatter(), identity()) which avoid the Update() boilerplate.

Parameters:

_program (UpdateProgram | None) – Internal update program (do not pass manually).

shift(site_ref, delta)

Appends x'[i] = x[i] + delta.

Parameters:

  • site_ref (str | SiteSelector | int | AmplitudeExpr) – Target site (label string, selector, or flat index).

  • delta (Any) – Shift amount, numeric or amplitude expression.

Return type:

Update

Returns:

New Update with this operation appended.

shift_mod(site_ref, delta)

Appends a Hilbert-aware wrapped shift.

Semantics are resolved from the enclosing operator’s Hilbert space at build/compile time. For now this requires contiguous unit-spaced integer local_states such as [-m_max, …, m_max].

Resulting runtime semantics:

x’[i] = ((x[i] + delta - state_min) % mod_span) + state_min

Return type:

Update

write(site_ref, value)

Appends x'[i] = value.

Parameters:
Return type:

Update

Returns:

New Update with this operation appended.

swap(site_a, site_b)

Appends x'[a], x'[b] = x[b], x[a].

Parameters:
Return type:

Update

Returns:

New Update with this operation appended.

permute(*site_refs)

Appends a cyclic rotation over K sites.

After the operation:

x'[s0] ← x[s1],   x'[s1] ← x[s2],   ...,   x'[sK-1] ← x[s0]

All K source values are captured from the current x' state before any writes are applied, so the rotation is atomic.

Parameters:

*site_refs (str | SiteSelector | int | AmplitudeExpr) – Two or more site references in rotation order.

Return type:

Update

Returns:

New Update with this operation appended.

Raises:

ValueError – If fewer than 2 site references are provided.

affine(site_ref, *, scale, bias=0)

Appends x'[i] = scale * x[i] + bias.

Parameters:

  • site_ref (str | SiteSelector | int | AmplitudeExpr) – Target site.

  • scale (Any) – Multiplicative scale, numeric or amplitude expression.

  • bias (Any) – Additive bias, numeric or amplitude expression (default 0).

Return type:

Update

Returns:

New Update with this operation appended.

scatter(flat_indices, values)

Appends bulk writes to static flat site indices.

For each (flat_index, value) pair:

x'[flat_index] = value

Indices must be compile-time-constant integers (baked into the IR). Values may be arbitrary amplitude expressions.

Parameters:

  • flat_indices (list[int] | tuple[int, ...]) – Sequence of static integer site indices.

  • values (list[Any] | tuple[Any, ...]) – Sequence of amplitude expressions (or coercible values).

Return type:

Update

Returns:

New Update with this operation appended.

Raises:

ValueError – If flat_indices and values have different lengths.

affine(site_ref, *, scale, bias=0)

Returns an Update computing x'[i] = scale * x[i] + bias.

Example:

affine("i", scale=2, bias=-1)  # x'[i] = 2*x[i] - 1
affine(0, scale=-1, bias=0)  # negate flat site 0
Return type:

Update

identity()

Returns the identity (no-op) Update.

Use for diagonal operators where x' = x:

DOperator(hi, "diagonal").globally().emit(identity(), amplitude=my_expr)
Return type:

Update

permute(*site_refs)

Returns an Update performing a cyclic rotation over K sites.

Example:

permute("i", "j", "k")  # x'[i]←x[j], x'[j]←x[k], x'[k]←x[i]
permute(0, 5, 10)  # same with flat indices
Return type:

Update

scatter(flat_indices, values)

Returns an Update performing bulk writes to static flat indices.

Example:

scatter([0, 10, 20], [1, -1, 0])  # write constant values
scatter([0, 10], [site("i").value, 0])  # mixed expr / constant
Return type:

Update

shift(site_ref, delta)

Returns an Update that shifts site site_ref by delta.

Example:

shift("i", +1)  # raise site i by 1
shift(0, -1)  # lower flat site 0 by 1
shift("j", site("i").value)  # shift j by x[i]
Return type:

Update

shift_mod(site_ref, delta)

Returns an Update performing a Hilbert-aware wrapped modular shift.

Example:

shift_mod("i", +1)
shift_mod(0, -2)
Return type:

Update

swap(site_a, site_b)

Returns an Update that swaps sites site_a and site_b.

Example:

swap("i", "j")  # exchange x[i] and x[j]
swap(0, 10)  # exchange flat sites 0 and 10
Return type:

Update

write(site_ref, value)

Returns an Update that writes value to site site_ref.

Example:

write("i", 0)  # zero site i
write(5, site("j").value)  # copy x[j] into flat site 5
Return type:

Update

class ExpressionContext(*args, **kwargs)

Bases: object

Utility context passed to DSL callables at build time.

This context only builds IR expression nodes and never captures Python-runtime callbacks.

Example

>>> def my_amplitude(ctx):
...     i = ctx.site("i")
...     return ctx.sqrt(i.value + 1)
symbol(name)

Returns a free symbolic amplitude expression.

Return type:

AmplitudeExpr

site(label)

Returns a site selector by label.

Return type:

SiteSelector

emitted(label)

Returns an emitted-state selector by label.

Return type:

SiteSelector

site(label)

Returns a symbolic site selector.

Parameters:

label (str) – Iterator label bound by for_each_site(label) or for_each_pair(label_a, label_b).

Return type:

SiteSelector

Returns:

Site selector handle.

Example

from neuralqx.experimental.operators.symbolic.dsl import site

s = site("i")
print(s.value)          # AmplitudeExpr, x[i]
print(s.index)          # AmplitudeExpr, i
print(s.value < 3)      # PredicateExpr, x[i] < 3
print(s.value + 1)      # AmplitudeExpr, x[i] + 1
emitted(label)

Returns a symbolic selector bound to the emitted or connected state x'.

Return type:

SiteSelector

Example

from neuralqx.experimental.operators.symbolic.dsl import emitted

e = emitted("i")
print(e.value)   # AmplitudeExpr, x'[i]
print(e.index)   # AmplitudeExpr, i
symbol(name)

Returns a free symbolic amplitude expression by name.

Free symbols are not bound to any site iterator, they are resolved at operator-evaluation time from external parameter dictionaries.

Parameters:

name (str) – Symbol name.

Return type:

AmplitudeExpr

Returns:

Symbolic amplitude expression.

class SiteSelector(label, namespace='site')

Bases: object

Symbolic selector for one Hilbert-space site iterator.

SiteSelector is created by site() and used inside DSL predicates, amplitude rules, and update programs. Attribute access on a selector returns symbolic AmplitudeExpr nodes that are resolved by the compiler at lowering time.

Parameters:

label (str) – Iterator label bound by for_each_site(label).

Submodules