# alzweidi/qm3d architecture

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

- Interactive diagram: https://gitdiagram.com/alzweidi/qm3d
- Repository: https://github.com/alzweidi/qm3d

## Overview

1. **What this repo is**
   - `qm3d` is a browser-based 3D quantum wave simulator.
   - The app is built as a **React + Vite** frontend with **Three.js** for visualization and a **hand-rolled numerical physics core** for the time-dependent Schrödinger equation.

2. **Top-level runtime shape**
   - The browser hosts the whole system; there is no backend service.
   - `src/main.jsx` is the app entrypoint, `index.html` bootstraps Vite, and `src/index.css` plus Tailwind/PostCSS handle styling.
   - The main architectural boundary is between **UI/state management**, **physics simulation**, **rendering**, and **profiling**.

3. **Core orchestration layer**
   - `src/components/engine.jsx` is the central coordinator.
   - It likely owns the simulation lifecycle: reading control state, creating/reconfiguring the quantum solver, advancing time steps, and handing results to the renderer.
   - This file is the best place to draw the “hub” in an architecture diagram because it connects almost everything else.

4. **User controls and configuration**
   - `src/components/controls.jsx` provides the slider/parameter UI for grid size, domain length, timestep scale, packet parameters, absorber settings, and potential choice.
   - These controls feed simulation configuration into the engine; changes can trigger solver rebuilds because some derived data are cached/precomputed.
   - The README indicates key constraints such as k-vector clamping and stable `dt = dt_scale × dx²`, so controls are not just cosmetic—they directly shape the numerical model.

5. **Physics subsystem**
   - `src/physics/quantum.js` is the simulation core for the split-step Fourier / Strang solver.
   - `src/physics/fft.js` implements the 1D/3D FFT utilities used to move between position and momentum space.
   - `src/physics/potentials.js` defines the built-in potential fields: free space, plane barrier, box well, spherical well, and harmonic well.
   - The data flow here is: **ψ field + potential + precomputed k-space operators → one or more time steps → updated ψ**.

6. **Numerical model boundaries**
   - The solver is spectral and periodic by nature because of the FFT; absorbing boundary “cap” logic is used to reduce wrap-around artifacts.
   - The physics code appears to be intentionally separated from React and rendering, which makes it easier to test numerically and to reuse in different views.
   - README notes suggest cached exponential tables are rebuilt when `dt`, `V`, or cap parameters change, so the physics layer has both **stateful cached setup** and **pure stepping logic**.

7. **Rendering subsystem**
   - `src/rendering/visualisation.js` appears to translate simulation output into visible point-cloud data.
   - `src/rendering/shaders.js` likely contains the small shader pair used to map amplitude to point size and phase to color.
   - `src/rendering/capture.js` handles output capture/export or screenshot-like workflows.
   - Rendering is decoupled from the solver: the physics layer produces fields; rendering consumes derived quantities such as density and phase and displays them as additive sprites/points.

8. **Scene behavior and interaction model**
   - The visualization is described as an orbitable 3D scene, so the rendered world is likely driven by Three.js controls plus a point-cloud representation of the wavefunction.
   - The visible mapping is important for the architecture diagram: **|ψ|² controls point size / density**, and **arg(ψ) controls hue**.
   - This means the render path is not generic UI; it is a domain-specific visualization pipeline built around simulation semantics.

9. **Profiler subsystem**
   - `src/profiler/provider.jsx`, `store.js`, `rafMonitor.js`, and `ProfilerHUD.jsx` form a self-contained performance-monitoring layer.
   - It likely tracks requestAnimationFrame timing, frame cost, and perhaps simulation step time, then exposes that through a provider/store to a HUD overlay.
   - Architecturally, this is a cross-cutting concern that observes the render loop without being part of the physics model itself.

10. **Testing strategy**
   - The repo has **unit tests** for physics and profiler logic, **component tests** for UI pieces, and **Playwright end-to-end tests** for the app.
   - `tests/unit/fft.test.js`, `quantum.test.js`, and `potentials.test.js` protect the numerical core.
   - `tests/component/controls.test.jsx` and `engine.test.jsx` validate React wiring, while `tests/e2e/app.spec.ts` exercises the full browser experience.
   - This separation mirrors the production boundaries: math, UI, and integrated behavior are all tested independently.

11. **Build, tooling, and delivery**
   - Vite is the build/dev runtime, Playwright handles browser automation, and ESLint enforces code quality.
   - `tailwind.config.js` and `postcss.config.js` indicate utility-first styling rather than a heavy CSS architecture.
   - GitHub Actions (`.github/workflows/ci.yml`) provides CI for linting/tests, so the repo is set up as a frontend application with reproducible numeric behavior under test.

12. **Recommended architecture diagram emphasis**
   - Show `controls.jsx` and `ProfilerHUD.jsx` as UI overlays feeding into `engine.jsx`.
   - Show `engine.jsx` calling into `physics/quantum.js`, `physics/fft.js`, and `physics/potentials.js`.
   - Show the solver output flowing into `rendering/visualisation.js` and `rendering/shaders.js`, with `capture.js` as an auxiliary output path.
   - Show the profiler as a sidecar observing the animation loop, not as part of the simulation core.

Main entry points: [`src/components/engine.jsx`](https://github.com/alzweidi/qm3d/blob/main/src/components/engine.jsx) (Engine), [`src/main.jsx`](https://github.com/alzweidi/qm3d/blob/main/src/main.jsx) (main), [`src/profiler/provider.jsx`](https://github.com/alzweidi/qm3d/blob/main/src/profiler/provider.jsx) (Profiler provider), [`src/physics/quantum.js`](https://github.com/alzweidi/qm3d/blob/main/src/physics/quantum.js) (Quantum solver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_src_main(("main<br/>entrypoint<br/>[main.jsx]"))
  node_src_controls["Controls<br/>ui panel<br/>[controls.jsx]"]
  node_src_engine{{"Engine<br/>orchestrator<br/>[engine.jsx]"}}
  node_src_indexcss["Styles<br/>[index.css]"]
  node_index_html["index.html<br/>bootstrap<br/>[index.html]"]
end

subgraph group_physics["Physics core"]
  node_physics_quantum{{"Quantum solver<br/>time-step solver<br/>[quantum.js]"}}
  node_physics_fft["FFT<br/>spectral transforms<br/>[fft.js]"]
  node_physics_potentials["Potentials<br/>field library<br/>[potentials.js]"]
end

subgraph group_rendering["Rendering"]
  node_render_visualisation{{"Visualisation<br/>scene adapter<br/>[visualisation.js]"}}
  node_render_shaders["Shaders<br/>GPU material<br/>[shaders.js]"]
  node_render_capture["Capture<br/>export<br/>[capture.js]"]
end

subgraph group_profiler["Profiler"]
  node_prof_provider["Profiler provider<br/>state provider<br/>[provider.jsx]"]
  node_prof_store["Profiler store<br/>metrics store<br/>[store.js]"]
  node_prof_raf(("RAF monitor<br/>timing probe<br/>[rafMonitor.js]"))
  node_prof_hud["Profiler HUD<br/>overlay<br/>[ProfilerHUD.jsx]"]
end

node_index_html -->|"loads"| node_src_main
node_src_main -->|"mounts"| node_src_engine
node_src_main -->|"renders"| node_src_controls
node_src_main -->|"wraps"| node_prof_provider
node_src_main -->|"imports"| node_src_indexcss
node_src_controls -->|"configures"| node_src_engine
node_prof_hud -->|"reads"| node_prof_provider
node_prof_provider -->|"stores"| node_prof_store
node_prof_provider -->|"monitors"| node_prof_raf
node_src_engine -->|"steps"| node_physics_quantum
node_src_engine -->|"selects"| node_physics_potentials
node_physics_quantum -->|"uses"| node_physics_fft
node_physics_quantum -->|"applies"| node_physics_potentials
node_src_engine -->|"feeds"| node_render_visualisation
node_render_visualisation -->|"styles"| node_render_shaders
node_render_visualisation -->|"exports"| node_render_capture
node_src_engine -->|"reports"| node_prof_store

click node_src_main "https://github.com/alzweidi/qm3d/blob/main/src/main.jsx"
click node_src_controls "https://github.com/alzweidi/qm3d/blob/main/src/components/controls.jsx"
click node_src_engine "https://github.com/alzweidi/qm3d/blob/main/src/components/engine.jsx"
click node_src_indexcss "https://github.com/alzweidi/qm3d/blob/main/src/index.css"
click node_physics_quantum "https://github.com/alzweidi/qm3d/blob/main/src/physics/quantum.js"
click node_physics_fft "https://github.com/alzweidi/qm3d/blob/main/src/physics/fft.js"
click node_physics_potentials "https://github.com/alzweidi/qm3d/blob/main/src/physics/potentials.js"
click node_render_visualisation "https://github.com/alzweidi/qm3d/blob/main/src/rendering/visualisation.js"
click node_render_shaders "https://github.com/alzweidi/qm3d/blob/main/src/rendering/shaders.js"
click node_render_capture "https://github.com/alzweidi/qm3d/blob/main/src/rendering/capture.js"
click node_prof_provider "https://github.com/alzweidi/qm3d/blob/main/src/profiler/provider.jsx"
click node_prof_store "https://github.com/alzweidi/qm3d/blob/main/src/profiler/store.js"
click node_prof_raf "https://github.com/alzweidi/qm3d/blob/main/src/profiler/rafMonitor.js"
click node_prof_hud "https://github.com/alzweidi/qm3d/blob/main/src/profiler/ProfilerHUD.jsx"
click node_index_html "https://github.com/alzweidi/qm3d/blob/main/index.html"

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_src_main,node_src_controls,node_src_engine,node_src_indexcss,node_index_html toneBlue
class node_physics_quantum,node_physics_fft,node_physics_potentials toneAmber
class node_render_visualisation,node_render_shaders,node_render_capture toneMint
class node_prof_provider,node_prof_store,node_prof_raf,node_prof_hud toneRose
```

## Components

### App shell

Browser entrypoint and simulation orchestration

- [main](https://github.com/alzweidi/qm3d/blob/main/src/main.jsx): entrypoint · Bootstraps the React app · `src/main.jsx`
- [Controls](https://github.com/alzweidi/qm3d/blob/main/src/components/controls.jsx): ui panel · Simulation parameter and domain controls · `src/components/controls.jsx`
- [Engine](https://github.com/alzweidi/qm3d/blob/main/src/components/engine.jsx): orchestrator · Coordinates state, stepping, and rendering · `src/components/engine.jsx`
- [Styles](https://github.com/alzweidi/qm3d/blob/main/src/index.css): global styles · App-wide base styling · `src/index.css`
- [index.html](https://github.com/alzweidi/qm3d/blob/main/index.html): bootstrap · Vite HTML entry shell · `index.html`

### Physics core

Numerical solver and model definitions

- [Quantum solver](https://github.com/alzweidi/qm3d/blob/main/src/physics/quantum.js): time-step solver · Split-step Schrödinger evolution and cached operators · `src/physics/quantum.js`
- [FFT](https://github.com/alzweidi/qm3d/blob/main/src/physics/fft.js): spectral transforms · Position/momentum space transforms · `src/physics/fft.js`
- [Potentials](https://github.com/alzweidi/qm3d/blob/main/src/physics/potentials.js): field library · Built-in potential energy profiles · `src/physics/potentials.js`

### Rendering

Three.js visualization and export

- [Visualisation](https://github.com/alzweidi/qm3d/blob/main/src/rendering/visualisation.js): scene adapter · Maps wavefunction output into visible scene data · `src/rendering/visualisation.js`
- [Shaders](https://github.com/alzweidi/qm3d/blob/main/src/rendering/shaders.js): GPU material · Shader logic for density and phase display · `src/rendering/shaders.js`
- [Capture](https://github.com/alzweidi/qm3d/blob/main/src/rendering/capture.js): export · Screenshot or output capture path · `src/rendering/capture.js`

### Profiler

Performance monitoring and HUD

- [Profiler provider](https://github.com/alzweidi/qm3d/blob/main/src/profiler/provider.jsx): state provider · Exposes profiling data to the UI · `src/profiler/provider.jsx`
- [Profiler store](https://github.com/alzweidi/qm3d/blob/main/src/profiler/store.js): metrics store · Holds timing and frame metrics · `src/profiler/store.js`
- [RAF monitor](https://github.com/alzweidi/qm3d/blob/main/src/profiler/rafMonitor.js): timing probe · Measures requestAnimationFrame behavior · `src/profiler/rafMonitor.js`
- [Profiler HUD](https://github.com/alzweidi/qm3d/blob/main/src/profiler/ProfilerHUD.jsx): overlay · Displays performance metrics in-app · `src/profiler/ProfilerHUD.jsx`

## Connections

- index.html → main: loads · HTML shell bootstraps the React application
- main → Engine: mounts · Main entry renders the app shell and engine
- main → Controls: renders · App includes the control panel
- main → Profiler provider: wraps · Profiler context is provided to the UI
- main → Styles: imports · Global styles are loaded at startup
- Controls → Engine: configures · User parameter changes flow into simulation control
- Profiler HUD → Profiler provider: reads · HUD consumes profiling state
- Profiler provider → Profiler store: stores · Provider exposes the shared metrics store
- Profiler provider → RAF monitor: monitors · Profiler hooks into animation timing
- Engine → Quantum solver: steps · Engine advances the quantum simulation
- Engine → Potentials: selects · Engine chooses the active potential
- Quantum solver → FFT: uses · Solver relies on spectral transforms
- Quantum solver → Potentials: applies · Potential field contributes to evolution
- Engine → Visualisation: feeds · Updated wavefunction is handed to the renderer
- Visualisation → Shaders: styles · Scene data is mapped through shader materials
- Visualisation → Capture: exports · Rendered output can be captured
- Engine → Profiler store: reports · Engine and render loop contribute timing data
