# waleed-sh/neuralqx architecture

> Architecture diagram of the GitHub repository waleed-sh/neuralqx, 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/neuralqx
- Repository: https://github.com/waleed-sh/neuralqx

## Overview

neuraLQX is a Python toolkit for variational simulations of canonical Loop Quantum Gravity, exposing LQG-specific graphs, Hilbert spaces, gauge groups, constraints, and operators through a NetKet/JAX-based variational backend. The main documented workflow is to define a physical problem, represent a variational state, and run a simulation; the sampled solver delegates its execution loop to a VMC driver and integrates samplers and other runtime services. The graph preserves documented domain capabilities and experimental symbolic-operator infrastructure, but several relationships are dashed because their implementation was not sampled.

Main entry points: [`neuralqx/solver/solver.py`](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/solver/solver.py) (Simulation solver), [`neuralqx/vqs/base.py`](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/vqs/base.py) (Variational states), [`neuralqx/hilbert/abstract_hilbert_core.py`](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/hilbert/abstract_hilbert_core.py) (Hilbert spaces), [`neuralqx/experimental/operators/symbolic/ir/expressions.py`](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/experimental/operators/symbolic/ir/expressions.py) (Symbolic IR)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_physics["LQG building blocks"]
  node_graphs["Graphs<br/>[graph_handler.py]"]
  node_hilbert["Hilbert spaces"]
  node_u1["U&#40;1&#41; constraints"]
  node_gauge["Gauge groups"]
  node_lqx["LQG models"]
end

subgraph group_operators["Operators and compilation"]
  node_operator_api["Operator types<br/>[jax.py]"]
  node_physics_ops["LQG operators"]
end

subgraph group_variational["Variational simulation"]
  node_models["Neural networks"]
  node_vqs["Variational states<br/>[base.py]"]
  node_mc_state["Monte Carlo state<br/>[state.py]"]
  node_solver["Simulation solver<br/>[solver.py]"]
  node_driver["VMC drivers<br/>[vmc.py]"]
  node_samplers["Monte Carlo samplers"]
  node_optimizer["Optimizers"]
end

subgraph group_runtime["Runtime services"]
  node_callbacks["Run callbacks<br/>[live_monitoring.py]"]
  node_profiling["Profiling<br/>[profiler.py]"]
  node_debug["Logging and debug<br/>[debug.py]"]
  node_configuration["Configuration<br/>[configs.py]"]
  node_serialization["Serialization<br/>[serialization.py]"]
  node_distributed["Distributed runtime<br/>[core.py]"]
end

subgraph group_experimental["Experimental extensions"]
  node_symbolic_ir["Symbolic IR<br/>[expressions.py]"]
  node_symbolic_predicates["IR predicates<br/>[predicates.py]"]
  node_symbolic_dsl["Operator DSL<br/>[context.py]"]
  node_compiler["Symbolic compiler<br/>[pipeline.py]"]
end

node_user(("Researcher"))

node_user -.->|"defines topology"| node_graphs
node_user -.->|"runs simulation"| node_solver
node_hilbert -->|"uses graph"| node_graphs
node_u1 -->|"specializes"| node_hilbert
node_user -.->|"configures symmetry"| node_gauge
node_user -.->|"defines model"| node_lqx
node_user -.->|"specifies operators"| node_operator_api
node_lqx -.->|"provides constraints"| node_physics_ops
node_symbolic_dsl -->|"builds expressions"| node_symbolic_ir
node_symbolic_dsl -->|"uses predicates"| node_symbolic_predicates
node_symbolic_ir -->|"references predicates"| node_symbolic_predicates
node_compiler -.->|"compiles program"| node_symbolic_ir
node_user -.->|"chooses ansatz"| node_models
node_vqs -->|"binds state space"| node_hilbert
node_vqs -.->|"evaluates ansatz"| node_models
node_vqs -.->|"estimates expectations"| node_operator_api
node_solver -->|"runs iterations"| node_driver
node_solver -->|"builds sampler"| node_samplers
node_solver -->|"configures optimization"| node_optimizer
node_solver -->|"uses variational state"| node_vqs
node_solver -->|"registers callbacks"| node_callbacks
node_solver -->|"loads state"| node_serialization
node_solver -->|"uses runtime"| node_distributed
node_user -.->|"profiles runs"| node_profiling
node_profiling -.->|"reads rank info"| node_distributed
node_user -.->|"configures diagnostics"| node_debug
node_configuration -->|"initializes logging"| node_debug
node_configuration -->|"controls initialization"| node_distributed
node_mc_state -.->|"implements state"| node_vqs
node_samplers -.->|"samples configurations"| node_hilbert

click node_graphs "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/graph/core/graph_handler.py"
click node_hilbert "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/hilbert/abstract_hilbert_core.py"
click node_u1 "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/hilbert/u1/constrained_core.py"
click node_gauge "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/gauge_groups/abstract_gauge_group_interface.py"
click node_lqx "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/lqx/abstract_lqx_interface.py"
click node_operator_api "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/operators/types/computational_operator/jax.py"
click node_physics_ops "https://github.com/waleed-sh/neuralqx/tree/main/neuralqx/operators/computational"
click node_symbolic_ir "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/experimental/operators/symbolic/ir/expressions.py"
click node_symbolic_predicates "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/experimental/operators/symbolic/ir/predicates.py"
click node_symbolic_dsl "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/experimental/operators/symbolic/dsl/context.py"
click node_compiler "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/experimental/operators/symbolic/compiler/core/pipeline.py"
click node_models "https://github.com/waleed-sh/neuralqx/tree/main/neuralqx/nn/models"
click node_vqs "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/vqs/base.py"
click node_mc_state "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/vqs/mc/mc_state/state.py"
click node_solver "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/solver/solver.py"
click node_driver "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/driver/vmc.py"
click node_samplers "https://github.com/waleed-sh/neuralqx/tree/main/neuralqx/samplers/rules"
click node_optimizer "https://github.com/waleed-sh/neuralqx/tree/main/neuralqx/optimizer"
click node_callbacks "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/callbacks/live_monitoring.py"
click node_profiling "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/profile/profiler.py"
click node_debug "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/debug.py"
click node_configuration "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/configs.py"
click node_serialization "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/utils/serialization.py"
click node_distributed "https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/utils/distributed/core.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_graphs,node_hilbert,node_u1,node_gauge,node_lqx toneBlue
class node_operator_api,node_physics_ops toneAmber
class node_models,node_vqs,node_mc_state,node_solver,node_driver,node_samplers,node_optimizer toneMint
class node_callbacks,node_profiling,node_debug,node_configuration,node_serialization,node_distributed toneRose
class node_symbolic_ir,node_symbolic_predicates,node_symbolic_dsl,node_compiler,node_user toneIndigo
```

## Components

### LQG building blocks

- [Graphs](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/graph/core/graph_handler.py): `neuralqx/graph/core/graph_handler.py`
- [Hilbert spaces](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/hilbert/abstract_hilbert_core.py): `neuralqx/hilbert/abstract_hilbert_core.py`
- [U(1) constraints](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/hilbert/u1/constrained_core.py): `neuralqx/hilbert/u1/constrained_core.py`
- [Gauge groups](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/gauge_groups/abstract_gauge_group_interface.py): `neuralqx/gauge_groups/abstract_gauge_group_interface.py`
- [LQG models](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/lqx/abstract_lqx_interface.py): `neuralqx/lqx/abstract_lqx_interface.py`

### Operators and compilation

- [Operator types](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/operators/types/computational_operator/jax.py): `neuralqx/operators/types/computational_operator/jax.py`
- [LQG operators](https://github.com/waleed-sh/neuralqx/tree/main/neuralqx/operators/computational): `neuralqx/operators/computational`

### Variational simulation

- [Neural networks](https://github.com/waleed-sh/neuralqx/tree/main/neuralqx/nn/models): `neuralqx/nn/models`
- [Variational states](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/vqs/base.py): `neuralqx/vqs/base.py`
- [Monte Carlo state](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/vqs/mc/mc_state/state.py): `neuralqx/vqs/mc/mc_state/state.py`
- [Simulation solver](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/solver/solver.py): `neuralqx/solver/solver.py`
- [VMC drivers](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/driver/vmc.py): `neuralqx/driver/vmc.py`
- [Monte Carlo samplers](https://github.com/waleed-sh/neuralqx/tree/main/neuralqx/samplers/rules): `neuralqx/samplers/rules`
- [Optimizers](https://github.com/waleed-sh/neuralqx/tree/main/neuralqx/optimizer): `neuralqx/optimizer`

### Runtime services

- [Run callbacks](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/callbacks/live_monitoring.py): `neuralqx/callbacks/live_monitoring.py`
- [Profiling](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/profile/profiler.py): `neuralqx/profile/profiler.py`
- [Logging and debug](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/debug.py): `neuralqx/debug.py`
- [Configuration](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/configs.py): `neuralqx/configs.py`
- [Serialization](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/utils/serialization.py): `neuralqx/utils/serialization.py`
- [Distributed runtime](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/utils/distributed/core.py): `neuralqx/utils/distributed/core.py`

### Experimental extensions

- [Symbolic IR](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/experimental/operators/symbolic/ir/expressions.py): `neuralqx/experimental/operators/symbolic/ir/expressions.py`
- [IR predicates](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/experimental/operators/symbolic/ir/predicates.py): `neuralqx/experimental/operators/symbolic/ir/predicates.py`
- [Operator DSL](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/experimental/operators/symbolic/dsl/context.py): `neuralqx/experimental/operators/symbolic/dsl/context.py`
- [Symbolic compiler](https://github.com/waleed-sh/neuralqx/blob/main/neuralqx/experimental/operators/symbolic/compiler/core/pipeline.py): `neuralqx/experimental/operators/symbolic/compiler/core/pipeline.py`

### Other components

- **Researcher**

## Connections

- Researcher → Graphs: defines topology
- Researcher → Simulation solver: runs simulation
- Hilbert spaces → Graphs: uses graph (evidence: `neuralqx/hilbert/abstract_hilbert_core.py`)
- U(1) constraints → Hilbert spaces: specializes (evidence: `neuralqx/hilbert/u1/constrained_core.py`)
- Researcher → Gauge groups: configures symmetry
- Researcher → LQG models: defines model
- Researcher → Operator types: specifies operators
- LQG models → LQG operators: provides constraints
- Operator DSL → Symbolic IR: builds expressions (evidence: `neuralqx/experimental/operators/symbolic/dsl/context.py`)
- Operator DSL → IR predicates: uses predicates (evidence: `neuralqx/experimental/operators/symbolic/dsl/context.py`)
- Symbolic IR → IR predicates: references predicates (evidence: `neuralqx/experimental/operators/symbolic/ir/expressions.py`)
- Symbolic compiler → Symbolic IR: compiles program
- Researcher → Neural networks: chooses ansatz
- Variational states → Hilbert spaces: binds state space (evidence: `neuralqx/vqs/base.py`)
- Variational states → Neural networks: evaluates ansatz
- Variational states → Operator types: estimates expectations (evidence: `neuralqx/vqs/base.py`)
- Simulation solver → VMC drivers: runs iterations (evidence: `neuralqx/solver/solver.py`)
- Simulation solver → Monte Carlo samplers: builds sampler (evidence: `neuralqx/solver/solver.py`)
- Simulation solver → Optimizers: configures optimization (evidence: `neuralqx/solver/solver.py`)
- Simulation solver → Variational states: uses variational state (evidence: `neuralqx/solver/solver.py`)
- Simulation solver → Run callbacks: registers callbacks (evidence: `neuralqx/solver/solver.py`)
- Simulation solver → Serialization: loads state (evidence: `neuralqx/solver/solver.py`)
- Simulation solver → Distributed runtime: uses runtime (evidence: `neuralqx/solver/solver.py`)
- Researcher → Profiling: profiles runs
- Profiling → Distributed runtime: reads rank info
- Researcher → Logging and debug: configures diagnostics
- Configuration → Logging and debug: initializes logging (evidence: `neuralqx/__init__.py`)
- Configuration → Distributed runtime: controls initialization
- Monte Carlo state → Variational states: implements state (evidence: `neuralqx/vqs/mc/mc_state/state.py`)
- Monte Carlo samplers → Hilbert spaces: samples configurations
