neuralqx.experimental.operators.symbolic.dsl.rewrite module

Fluent immutable update-program builder for the symbolic operator DSL.

The Update class is designed for ergonomic construction of site-update programs: every method is chainable and returns a new immutable Update instance.

Module-level factory functions (shift, write, swap, permute, affine, scatter, identity) serve as zero-boilerplate entry points, there is no need to first construct an empty Update() before chaining.

Examples:

from neuralqx.experimental.operators.symbolic.dsl import shift, write, swap, permute, scatter

# Single operation, direct factory call
update = shift("i", +1)

# Compound update, chain freely
update = shift("i", -1).shift("j", +1)  # hopping
update = swap("i", "j").write("k", 0)  # swap then zero
update = permute("i", "j", "k")  # cyclic rotation
update = affine("i", scale=2, bias=-1)  # x[i] = 2*x[i] - 1

# Bulk scatter to static flat indices
update = scatter([0, 5, 10], [val_0, val_5, val_10])

# Identity (no-op), for diagonal operators
update = identity()

# Conditional update
update = Update.cond(
    site("i") > 0,
    if_true=shift("i", -1),
    if_false=write("i", 0),
)

Amplitude-side semantics

Amplitude expressions are evaluated after the emitted/connected state x' has been constructed for the current branch.

By default: - site("i").value refers to the source configuration x[i]. - emitted("i").value refers to the connected/emitted configuration x'[i].

This allows matrix elements to depend on either the source state, the emitted state, or both. In addition, wrap_mod(expr) applies the same Hilbert-aware modulo-wrap semantics used by shift_mod(...).

Branch-multiset semantics

The padded connected-states representation returned by get_conn_padded is a branch multiset, not a deduplicated adjacency row. If two terms (or two emissions within one term) produce the same x', both appear as separate entries with separate matrix elements. Callers that accumulate matrix elements must sum over duplicate x' entries explicitly.

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