nkDSL

nkDSL is a standalone extraction of the symbolic operator DSL from neuraLQX. It provides a compact, declarative way to define discrete operators in NetKet and compile them into executable JAX-backed operator kernels.

What it does

With nkDSL, you describe an operator in terms of

• where to iterate, such as sites, pairs, or user-defined index sets,
• when a branch is active, through symbolic predicates,
• how to rewrite a configuration, through update programs,
• what matrix element to assign to each emitted branch.

The result is a symbolic operator that can be compiled into a NetKet-compatible executable operator.

Example: 1D transverse-field Ising model

The example below builds $H = -J \sum_{\langle i,j \rangle} \sigma_i^z \sigma_j^z - h \sum_i \sigma_i^x$ for a periodic chain. The diagonal Ising interaction is emitted with an identity update, while the transverse-field term flips one spin at a time.

import netket as nk
from nkdsl import SymbolicDiscreteJaxOperator, site, write

L = 8
J = 1.0
h = 0.5

hilbert = nk.hilbert.Spin(s=0.5, N=L)
graph = nk.graph.Chain(length=L, pbc=True)

ising = (
    SymbolicDiscreteJaxOperator(hilbert, "ising_tfim", hermitian=True)
    .for_each(("i", "j"), over=graph.edges())
    .emit(
        matrix_element=1.2 * site("i").value * site("j").value,
    )
    .for_each_site("i")
    .emit(
        write("i", -site("i").value),
        matrix_element=-0.7,
    )
    .compile()
)

# now, `ising` is a NetKet DiscreteJaxOperator subclass, and can be used in NetKet

Installation

Install directly from PyPI:

python -m pip install --upgrade pip
python -m pip install nkdsl

NetKet is the default compiled operator family. For neuraLQX, install "nkDSL[neuralqx]", which selects a compatible NetKet version (>=3.20.0,<3.22.0). Then select its built-in target once:

import nkdsl

nkdsl.config.LOWERING = "neuralqx"

Subsequent .compile() calls use that choice. Custom operator families can be registered and selected with nkdsl.LOWERING_REGISTRY.register(...). Per-call operator_lowering=... overrides remain available. See choosing the compiled operator type for the complete workflow.

Status

nkdsl is a small, focused beta package for the symbolic operator work developed in neuraLQX. The goal is a clear, usable DSL with a stable core workflow and room for advanced APIs to continue maturing.

License

This project is licensed under Apache License 2.0. See LICENSE for the full text.

Documentation

The documentation uses MkDocs and Material. To preview it locally:

python -m pip install -r docs/requirements.txt
python -m mkdocs serve

Notebook pages display verified, saved outputs and do not execute during site builds. See the documentation guide for refreshing notebooks and running the checks used by CI and Read the Docs.