How alzweidi/qm3d works
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: engine.jsx Engine · main.jsx main · provider.jsx Profiler provider · quantum.js Quantum solver
Components 15
App shell
Browser entrypoint and simulation orchestration
- main · Bootstraps the React app
src/main.jsx - Controls · Simulation parameter and domain controls
src/components/controls.jsx - Engine · Coordinates state, stepping, and rendering
src/components/engine.jsx - Styles · App-wide base styling
src/index.css - index.html · Vite HTML entry shell
index.html
Physics core
Numerical solver and model definitions
- Quantum solver · Split-step Schrödinger evolution and cached operators
src/physics/quantum.js - FFT · Position/momentum space transforms
src/physics/fft.js - Potentials · Built-in potential energy profiles
src/physics/potentials.js
Rendering
Three.js visualization and export
- Visualisation · Maps wavefunction output into visible scene data
src/rendering/visualisation.js - Shaders · Shader logic for density and phase display
src/rendering/shaders.js - Capture · Screenshot or output capture path
src/rendering/capture.js
Profiler
Performance monitoring and HUD
- Profiler provider · Exposes profiling data to the UI
src/profiler/provider.jsx - Profiler store · Holds timing and frame metrics
src/profiler/store.js - RAF monitor · Measures requestAnimationFrame behavior
src/profiler/rafMonitor.js - Profiler HUD · Displays performance metrics in-app
src/profiler/ProfilerHUD.jsx
Connections 17
- 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