nkdsl

Symbolic operator subsystem for NetKet.

Typical workflow:

from nkdsl import SymbolicDiscreteJaxOperator
from nkdsl.dsl import site, hop

hopping_op = (
    SymbolicDiscreteJaxOperator(hi, "hopping")
    .for_each_pair("i", "j")
    .where(site("i") > 0)
    .emit(hop("i", "j"), matrix_element=1.0)
    .build()
)
compiled = hopping_op.compile()
xp, mels = compiled.get_conn_padded(x_batch)

Functions

affine(site_ref, *, scale[, bias])	Returns an Update computing x'[i] = scale * x[i] + bias.
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.
compile_symbolic_operator(operator, *[, ...])	Module-level convenience function for one-shot symbolic compilation.
default_symbolic_artifact_store()	Returns the module-level shared in-memory artifact store.
default_symbolic_lowerer_registry(*[, ...])	Builds the default symbolic lowerer registry.
default_symbolic_operator_lowering_registry()	Returns the module-level shared operator-lowering target registry.
default_symbolic_pass_pipeline()	Builds the default two-stage symbolic compiler pass pipeline.
emitted(label)	Returns a symbolic selector bound to the emitted/connected state x'.
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.
register(-> type[~typing.Any])	Registers either an iterator clause, predicate clause or an emission clause class.
register_emission_clause(-> type[])	Registers one emission clause class.
register_iterator_clause(-> type[])	Registers one iterator clause class.
register_predicate_clause(-> type[])	Registers one predicate clause class.
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.
site(label)	Returns a symbolic site selector.
source_index(flat_index)	Returns a static source-configuration read x[flat_index].
swap(site_a, site_b)	Returns an Update that swaps sites site_a and site_b.
symbol(name, *[, default, doc, dtype])	Returns a free symbolic amplitude expression by name.
target_index(flat_index)	Returns a static emitted/target-configuration read x'[flat_index].
write(site_ref, value)	Returns an Update that writes value to site site_ref.

Classes

AbstractEmissionClause(builder)	Abstract base class for custom fluent emission clauses.
AbstractIteratorClause(builder)	Abstract base class for custom fluent iterator clauses.
AbstractPredicateClause(builder)	Abstract base class for custom fluent predicate clauses.
AbstractSymbolicOperator(hilbert, *, name[, ...])	Abstract base class for all symbolic (DSL-defined) operators.
AmplitudeExpr(op[, args])	Typed expression node for operator matrix elements.
CompiledOperator(hilbert, *, name, fn, ...)	An executable operator produced by lowering a SymbolicOperator.
EmissionClauseSpec([mode, predicate, ...])	One normalized emission-clause action.
EmissionSpec(update_program, amplitude[, ...])	One output branch (connected state + matrix element) of a term.
ExpressionContext()	Utility context passed to DSL callables at build time.
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.
SiteSelector(label[, namespace])	Symbolic selector for one Hilbert-space site iterator.
SymbolicCacheKey(token, namespace)	Immutable cache key for compiled symbolic operator artifacts.
SymbolicCompilationContext(*, operator, ir, ...)	Holds per-compilation mutable state across pipeline stages.
SymbolicCompilationSignature(...[, ...])	Deterministic compilation signature for cache-key generation.
SymbolicCompiledArtifact(operator_name, ...)	Compilation artifact produced by the symbolic compiler pipeline.
SymbolicCompiler(*[, pipeline, ...])	Orchestrates the symbolic operator compilation pipeline.
SymbolicCompilerOptions([...])	Static and runtime controls for symbolic compiler execution.
SymbolicDiscreteJaxOperator(hilbert[, name, ...])	Fluent builder for declarative symbolic quantum operators.
SymbolicIRTerm(name, iterator, predicate, ...)	One primitive declarative symbolic operator term.
SymbolicOperator(hilbert, name, ir_terms, *)	A symbolic operator built via the SymbolicDiscreteJaxOperator DSL.
SymbolicOperatorIR(operator_name, mode, ...)	Immutable symbolic operator IR container.
SymbolicOperatorLoweringRegistry([targets, ...])	Registry for selectable compiled-operator targets.
SymbolicOperatorLoweringTarget(name, ...)	Describes one compiled-operator target selectable during lowering.
SymbolicOperatorSum(hilbert, terms, *[, ...])	Additive composition of multiple symbolic operators sharing one Hilbert space.
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.

Exceptions

NKDSLError([message, hint, details])	Base exception for all nkdsl-specific errors.
SymbolicCompilationError([message, hint, ...])	Base exception for symbolic compilation failures.
SymbolicCompilerError([message])	Raised when symbolic compilation fails at any pipeline stage.
SymbolicDiagnosticsError([message])	Raised when diagnostics are configured to fail the compilation flow.
SymbolicError([message, hint, details])	Base exception for symbolic-DSL and symbolic-compiler errors.
SymbolicOperatorError([message, hint, details])	Base exception for symbolic operator construction and execution errors.
SymbolicOperatorExecutionError([message])	Raised when a symbolic operator is executed before compilation.