# waleed-sh/nkdsl architecture

> Architecture diagram of the GitHub repository waleed-sh/nkdsl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/waleed-sh/nkdsl
- Repository: https://github.com/waleed-sh/nkdsl

## Overview

nkDSL lets users describe discrete operators symbolically and compile them into executable JAX-backed operators compatible with NetKet. The main workflow is DSL construction (iteration domains, predicates, updates and emissions), symbolic IR, compiler passes, backend lowering, then execution through a compiled operator. The compiler also supports artifact caching, diagnostics and configurable lowering targets. Connections below are limited to README statements and relationships listed in the supplied SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`src/nkdsl/compiler/compiler.py`](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/compiler.py) (Compiler orchestration), [`src/nkdsl/dsl/operator.py`](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/dsl/operator.py) (Operator DSL), [`src/nkdsl/compiler/lowering/jax_lowerer.py`](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/lowering/jax_lowerer.py) (JAX lowerer), [`src/nkdsl/ir/term.py`](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/term.py) (Term IR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Operator authoring"]
  node_dsl["Operator DSL<br/>[operator.py]"]
  node_iterators["Iteration clauses<br/>[defaults.py]"]
  node_predicates["Predicate clauses"]
  node_emissions["Emission clauses"]
  node_rewrites["Update programs<br/>[rewrite.py]"]
end

subgraph group_representation["Symbolic representation"]
  node_expressions["Amplitude expressions<br/>[expressions.py]"]
  node_predicate_ir["Predicate IR<br/>[predicates.py]"]
  node_update_ir["Update IR<br/>[update.py]"]
  node_terms["Term IR<br/>[term.py]"]
  node_program["Operator IR<br/>[program.py]"]
  node_symbolic_operator["Symbolic operator<br/>[operator.py]"]
end

subgraph group_compiler["Compilation"]
  node_compiler["Compiler orchestration<br/>[compiler.py]"]
  node_pipeline["Pass pipeline<br/>[pipeline.py]"]
  node_context["Compilation context<br/>[context.py]"]
  node_artifact["Compiled artifact<br/>[artifact.py]"]
  node_cache[("Artifact cache<br/>[store.py]")]
  node_lowerer["JAX lowerer<br/>[jax_lowerer.py]"]
  node_connectivity["Connectivity analysis<br/>[connectivity.py]"]
  node_diagnostics["Diagnostics"]
  node_signature["Cache signature<br/>[signature.py]"]
  node_options["Compiler options<br/>[options.py]"]
  node_pass_report["Pass reports<br/>[pass_report.py]"]
  node_kernel["Kernel representation<br/>[kernel.py]"]
end

subgraph group_runtime["Execution and integration"]
  node_compiled["Compiled operator<br/>[compiled.py]"]
  node_config["Compiler configuration<br/>[configs.py]"]
  node_debug["Debug and profiling<br/>[debug.py]"]
end

node_user(("Operator author"))
node_netket(("NetKet user"))

node_user -->|"defines operator"| node_dsl
node_dsl -->|"selects domains"| node_iterators
node_dsl -->|"adds conditions"| node_predicates
node_dsl -->|"adds emissions"| node_emissions
node_dsl -->|"defines updates"| node_rewrites
node_dsl -->|"builds"| node_symbolic_operator
node_symbolic_operator -->|"compiles from terms"| node_program
node_program -->|"contains terms"| node_terms
node_terms -->|"uses amplitudes"| node_expressions
node_terms -->|"uses predicates"| node_predicate_ir
node_terms -->|"uses updates"| node_update_ir
node_symbolic_operator -->|"compile request"| node_compiler
node_compiler -->|"creates context"| node_context
node_compiler -->|"runs passes"| node_pipeline
node_pipeline -->|"mutates state"| node_context
node_compiler -->|"looks up artifact"| node_cache
node_compiler -->|"creates cache key"| node_signature
node_compiler -->|"dispatches lowering"| node_lowerer
node_lowerer -->|"creates artifact"| node_artifact
node_compiler -->|"stores result"| node_artifact
node_lowerer -->|"uses connectivity"| node_connectivity
node_lowerer -->|"builds operator"| node_compiled
node_compiled -->|"provides execution"| node_netket
node_config -->|"selects target"| node_lowerer
node_compiler -->|"accepts options"| node_options
node_context -->|"records reports"| node_pass_report
node_lowerer -->|"uses kernel lowering"| node_kernel
node_compiler -.->|"runs diagnostics"| node_diagnostics
node_compiler -->|"emits debug events"| node_debug

click node_dsl "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/dsl/operator.py"
click node_iterators "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/dsl/iterators/defaults.py"
click node_predicates "https://github.com/waleed-sh/nkdsl/tree/main/src/nkdsl/dsl/predicates"
click node_emissions "https://github.com/waleed-sh/nkdsl/tree/main/src/nkdsl/dsl/emissions"
click node_rewrites "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/dsl/rewrite.py"
click node_expressions "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/expressions.py"
click node_predicate_ir "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/predicates.py"
click node_update_ir "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/update.py"
click node_terms "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/term.py"
click node_program "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/program.py"
click node_symbolic_operator "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/core/operator.py"
click node_compiler "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/compiler.py"
click node_pipeline "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/pipeline.py"
click node_context "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/context.py"
click node_artifact "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/artifact.py"
click node_cache "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/cache/store.py"
click node_lowerer "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/lowering/jax_lowerer.py"
click node_connectivity "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/connectivity.py"
click node_diagnostics "https://github.com/waleed-sh/nkdsl/tree/main/src/nkdsl/compiler/diagnostics"
click node_compiled "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/core/compiled.py"
click node_config "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/configs.py"
click node_debug "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/debug.py"
click node_signature "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/signature.py"
click node_options "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/options.py"
click node_pass_report "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/pass_report.py"
click node_kernel "https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/kernel.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dsl,node_iterators,node_predicates,node_emissions,node_rewrites,node_netket toneBlue
class node_expressions,node_predicate_ir,node_update_ir,node_terms,node_program,node_symbolic_operator toneAmber
class node_compiler,node_pipeline,node_context,node_artifact,node_cache,node_lowerer,node_connectivity,node_diagnostics,node_signature,node_options,node_pass_report,node_kernel toneMint
class node_compiled,node_config,node_debug toneRose
class node_user toneIndigo
```

## Components

### Operator authoring

- [Operator DSL](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/dsl/operator.py): `src/nkdsl/dsl/operator.py`
- [Iteration clauses](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/dsl/iterators/defaults.py): `src/nkdsl/dsl/iterators/defaults.py`
- [Predicate clauses](https://github.com/waleed-sh/nkdsl/tree/main/src/nkdsl/dsl/predicates): `src/nkdsl/dsl/predicates`
- [Emission clauses](https://github.com/waleed-sh/nkdsl/tree/main/src/nkdsl/dsl/emissions): `src/nkdsl/dsl/emissions`
- [Update programs](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/dsl/rewrite.py): `src/nkdsl/dsl/rewrite.py`

### Symbolic representation

- [Amplitude expressions](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/expressions.py): `src/nkdsl/ir/expressions.py`
- [Predicate IR](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/predicates.py): `src/nkdsl/ir/predicates.py`
- [Update IR](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/update.py): `src/nkdsl/ir/update.py`
- [Term IR](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/term.py): `src/nkdsl/ir/term.py`
- [Operator IR](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/ir/program.py): `src/nkdsl/ir/program.py`
- [Symbolic operator](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/core/operator.py): `src/nkdsl/core/operator.py`

### Compilation

- [Compiler orchestration](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/compiler.py): `src/nkdsl/compiler/compiler.py`
- [Pass pipeline](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/pipeline.py): `src/nkdsl/compiler/core/pipeline.py`
- [Compilation context](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/context.py): `src/nkdsl/compiler/core/context.py`
- [Compiled artifact](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/artifact.py): `src/nkdsl/compiler/core/artifact.py`
- [Artifact cache](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/cache/store.py): `src/nkdsl/compiler/cache/store.py`
- [JAX lowerer](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/lowering/jax_lowerer.py): `src/nkdsl/compiler/lowering/jax_lowerer.py`
- [Connectivity analysis](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/connectivity.py): `src/nkdsl/compiler/core/connectivity.py`
- [Diagnostics](https://github.com/waleed-sh/nkdsl/tree/main/src/nkdsl/compiler/diagnostics): `src/nkdsl/compiler/diagnostics`
- [Cache signature](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/signature.py): `src/nkdsl/compiler/core/signature.py`
- [Compiler options](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/options.py): `src/nkdsl/compiler/core/options.py`
- [Pass reports](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/pass_report.py): `src/nkdsl/compiler/core/pass_report.py`
- [Kernel representation](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/compiler/core/kernel.py): `src/nkdsl/compiler/core/kernel.py`

### Execution and integration

- [Compiled operator](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/core/compiled.py): `src/nkdsl/core/compiled.py`
- [Compiler configuration](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/configs.py): `src/nkdsl/configs.py`
- [Debug and profiling](https://github.com/waleed-sh/nkdsl/blob/main/src/nkdsl/debug.py): `src/nkdsl/debug.py`

### Other components

- **Operator author**
- **NetKet user**

## Connections

- Operator author → Operator DSL: defines operator
- Operator DSL → Iteration clauses: selects domains (evidence: `src/nkdsl/dsl/operator.py`)
- Operator DSL → Predicate clauses: adds conditions (evidence: `src/nkdsl/dsl/operator.py`)
- Operator DSL → Emission clauses: adds emissions (evidence: `src/nkdsl/dsl/operator.py`)
- Operator DSL → Update programs: defines updates (evidence: `src/nkdsl/dsl/operator.py`)
- Operator DSL → Symbolic operator: builds (evidence: `src/nkdsl/core/operator.py`)
- Symbolic operator → Operator IR: compiles from terms (evidence: `src/nkdsl/core/operator.py`)
- Operator IR → Term IR: contains terms (evidence: `src/nkdsl/ir/program.py`)
- Term IR → Amplitude expressions: uses amplitudes (evidence: `src/nkdsl/ir/term.py`)
- Term IR → Predicate IR: uses predicates (evidence: `src/nkdsl/ir/term.py`)
- Term IR → Update IR: uses updates (evidence: `src/nkdsl/ir/term.py`)
- Symbolic operator → Compiler orchestration: compile request (evidence: `src/nkdsl/core/operator.py`)
- Compiler orchestration → Compilation context: creates context (evidence: `src/nkdsl/compiler/compiler.py`)
- Compiler orchestration → Pass pipeline: runs passes (evidence: `src/nkdsl/compiler/compiler.py`)
- Pass pipeline → Compilation context: mutates state (evidence: `src/nkdsl/compiler/core/pipeline.py`)
- Compiler orchestration → Artifact cache: looks up artifact (evidence: `src/nkdsl/compiler/compiler.py`)
- Compiler orchestration → Cache signature: creates cache key (evidence: `src/nkdsl/compiler/compiler.py`)
- Compiler orchestration → JAX lowerer: dispatches lowering (evidence: `src/nkdsl/compiler/compiler.py`)
- JAX lowerer → Compiled artifact: creates artifact (evidence: `src/nkdsl/compiler/lowering/jax_lowerer.py`)
- Compiler orchestration → Compiled artifact: stores result (evidence: `src/nkdsl/compiler/compiler.py`)
- JAX lowerer → Connectivity analysis: uses connectivity (evidence: `src/nkdsl/compiler/lowering/jax_lowerer.py`)
- JAX lowerer → Compiled operator: builds operator (evidence: `src/nkdsl/compiler/lowering/jax_lowerer.py`)
- Compiled operator → NetKet user: provides execution
- Compiler configuration → JAX lowerer: selects target
- Compiler orchestration → Compiler options: accepts options (evidence: `src/nkdsl/compiler/compiler.py`)
- Compilation context → Pass reports: records reports (evidence: `src/nkdsl/compiler/core/context.py`)
- JAX lowerer → Kernel representation: uses kernel lowering (evidence: `src/nkdsl/compiler/lowering/jax_lowerer.py`)
- Compiler orchestration → Diagnostics: runs diagnostics
- Compiler orchestration → Debug and profiling: emits debug events (evidence: `src/nkdsl/compiler/compiler.py`)
