nkdsl.dsl.rewrite¶

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, hop, 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 nkdsl.dsl import shift, hop, 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 = hop("i", "j")  # same hopping move
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(...).

Connected-state dedup semantics¶

The padded connected-states representation returned by get_conn_padded is deduplicated by default. If two terms (or two emissions within one term) produce the same x', they are merged and their matrix elements are summed. Zero-amplitude components are dropped before padding.

Set deduplicate_connected_components=False during .compile(...) to keep raw per-branch output when needed.

Functions

`affine`(site_ref, *, scale[, bias])	Returns an `Update` computing `x'[i] = scale * x[i] + bias`.
`coerce_amplitude_expr`(value)	Coerces user values into typed amplitude-expression nodes.
`coerce_predicate_expr`(value)	Coerces user values into typed predicate-expression nodes.
`hop`(src, dst, *[, amount])	Returns an `Update` transferring occupation from src to dst.
`identity`()	Returns the identity (no-op) `Update`.
`permute`(*site_refs)	Returns an `Update` performing a cyclic rotation over K sites.
`scatter`(flat_indices, values)	Returns an `Update` performing bulk writes to static flat indices.
`shift`(site_ref, delta)	Returns an `Update` that shifts site site_ref by delta.
`shift_mod`(site_ref, delta)	Returns an Update performing a Hilbert-aware wrapped modular shift.
`swap`(site_a, site_b)	Returns an `Update` that swaps sites site_a and site_b.
`write`(site_ref, value)	Returns an `Update` that writes value to site site_ref.

Classes

`AmplitudeExpr`(op[, args])	Typed expression node for operator matrix elements.
`Any`(args, *kwargs)	Special type indicating an unconstrained type.
`SiteSelector`(label[, namespace])	Symbolic selector for one Hilbert-space site iterator.
`Update`([_program])	Immutable, chainable site-update program builder.
`UpdateOp`(kind[, params])	One primitive site-update operation.
`UpdateProgram`([ops])	Ordered immutable sequence of site-update operations.