nkdsl.dsl.operator

Fluent operator builder, the primary entry point to the symbolic DSL.

The SymbolicDiscreteJaxOperator class is the single entry point for constructing symbolic quantum operators.

Usage

from nkdsl import SymbolicDiscreteJaxOperator
from nkdsl.dsl import site, shift, swap, identity

# diagonal operator
N_e0 = (
    SymbolicDiscreteJaxOperator(hi, "N_e0", hermitian=True)
    .globally()
    .emit(identity(), matrix_element=my_sq_norm_expr)
    .build()
)

# single-site off-diagonal
h_plus = (
    SymbolicDiscreteJaxOperator(hi, "h+")
    .for_each_site("e")
    .where(site("e") < cutoff)
    .emit(shift("e", +1))
    .build()
)

# hopping: compound update + matrix element from both DOFs
hop = (
    SymbolicDiscreteJaxOperator(hi, "hopping")
    .for_each_pair("i", "j")
    .where(site("i") > 0)
    .emit(
        shift("i", -1).shift("j", +1),
        matrix_element=site("i").value * site("j").value,
    )
    .build()
)

# K-body: static triplet iterator
vol = (
    SymbolicDiscreteJaxOperator(hi, "triplet_volume")
    .for_each(("e1", "e2", "e3"), over=triplet_index_sets)
    .emit(identity(), matrix_element=triple_product_expr)
    .build()
)

# multi-emission: two branches per iterator evaluation
two_branch = (
    SymbolicDiscreteJaxOperator(hi, "two_branch")
    .for_each_site("i")
    .where(site("i").abs() < 2)
    .emit(shift("i", +1), matrix_element=+0.5)
    .emit(shift("i", -1), matrix_element=-0.5)
    .build()
)

# compile directly (skip explicit .build())
compiled = SymbolicDiscreteJaxOperator(hi, "my_op").for_each_site("i").emit(shift("i", +1)).compile()

Iterator methods

Calling any for_each_* / globally method seals the current in-progress term and begins a new one. Calling .where or .emit after is always associated with the most recent iterator call.

Multi-emission

Multiple .emit(...) calls on the same iterator scope produce multiple output branches (EmissionSpec entries) from a single iterator evaluation. This avoids the overhead of iterating over sites twice and keeps the semantic unit cohesive.

Connected-state dedup note

By default, if two terms (or two emissions within one term) produce the same x', those entries are merged and their matrix elements are summed. Final zero-amplitude components are dropped before padding.

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

Functions

apply_emission_clause(builder, clause_name, ...)

Resolves and applies one registered emission clause.

apply_iterator_clause(builder, clause_name, ...)

Resolves and applies one registered iterator clause.

apply_predicate_clause(builder, clause_name, ...)

Resolves and applies one registered predicate clause.

available_emission_clause_names()

Lists emission clause names currently registered.

available_iterator_clause_names()

Lists iterator clause names currently registered.

available_predicate_clause_names()

Lists predicate clause names currently registered.

coerce_amplitude_expr(value)

Coerces user values into typed amplitude-expression nodes.

coerce_predicate_expr(value)

Coerces user values into typed predicate-expression nodes.

debug_event(msg, *[, scope, pass_name, tag, ...])

Structured debug event with scope and optional pass filtering.

ensure_default_emission_clause_registrations()

Registers all built-in emission clauses exactly once.

ensure_default_iterator_clause_registrations()

Registers all built-in iterator clauses exactly once.

ensure_default_predicate_clause_registrations()

Registers all built-in predicate clauses exactly once.

resolve_emission_clause(name)

Resolves one registered emission clause by fluent method name.

resolve_iterator_clause(name)

Resolves one registered iterator clause by fluent method name.

resolve_predicate_clause(name)

Resolves one registered predicate clause by fluent method name.

Classes

AmplitudeExpr(op[, args])

Typed expression node for operator matrix elements.

Any(*args, **kwargs)

Special type indicating an unconstrained type.

DiscreteHilbert([size])

EmissionClauseSpec([mode, predicate, ...])

One normalized emission-clause action.

EmissionSpec(update_program, amplitude[, ...])

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

KBodyIteratorSpec(labels, index_sets)

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

PredicateExpr(op[, args])

Typed boolean expression node for operator branch filtering.

Sequence()

All the operations on a read-only sequence.

SymbolicDiscreteJaxOperator(hilbert[, name, ...])

Fluent builder for declarative symbolic quantum operators.

SymbolicIRTerm(name, iterator, predicate, ...)

One primitive declarative symbolic operator term.

Update([_program])

Immutable, chainable site-update program builder.

UpdateProgram([ops])

Ordered immutable sequence of site-update operations.