How strilanc/quirk works
Project type and purpose
• Quirk is a single-page, in-browser quantum circuit simulator. There is no separate backend server—the entire system runs as static HTML/JS/CSS, built and tested via Node/Grunt and deployed as a self-contained web app.
• Its purpose is to let users drag-and-drop quantum gates onto a canvas and instantly see simulation results. Key features include real-time animation, inline state displays, bookmarkable circuits, and support for up to 16 qubits.
File structure
• Top-level build/configuration:
• GruntFile.js – build & bundling tasks
• package.json, npm scripts – dependency management, test runner, build pipeline
• .github/workflows/ci.yml – CI integration (Travis/GitHub Actions)
• PuppeteerRunTests.js, PuppeteerScreenshotCircuit.js – headless‐browser test automation
• Core application code under src/:
• src/base – shared utilities (throttling, RNG, error handling, formatting)
• src/math – linear algebra & complex-number support (Matrix, Complex, FormulaParser)
• src/circuit – simulation engine (CircuitDefinition, EvalContext, Serializer, stats)
• src/gates – gate definitions and display-only gates (FourierTransformGates, MeasurementGate, BlochSphereDisplay, etc.)
• src/ui – user-interaction layer (drag/drop, toolbox, menu, URL routing, undo/redo)
• src/browser – cross-browser glue (clipboard, history, touch blocking, file saving)
• src/main.js – entry point that wires UI ↔ simulation ↔ renderer
• Tests under test/ and performance tests under test_perf/ use Karma and Puppeteer.
README for insights
• Confirms it’s a pure-client SPA with no server component.
• Describes build steps: python/npm → test → build → output to out/quirk.html.
a. Main components
• Build & CI System (Node/npm, Grunt, Karma, Puppeteer, GitHub CI)
• Static Web App Host (serves out/quirk.html + assets)
• Browser Runtime
– UI Layer (src/ui + src/browser)
– Simulation Engine (src/circuit + src/base + src/math)
– Gate Library (src/gates)
– Rendering Layer
· WebGL Renderer (src/webgl)
– State & Serialization (URL bookmark, Serializer)
b. Relationships & interactions
• UI dispatches user events → Simulation Engine evaluates circuit → Engine emits qubit states → Rendering Layer paints canvas/updates WebGL displays → UI updates inspector panels + URL state.
• Build & CI kicks off unit tests and performance tests, then bundles src/ into a single HTML+JS.
c. Architectural patterns & principles
• Single Responsibility: each subfolder has a well-defined role.
• Dependency injection via Config.js and EvalContext.
d. Key technologies/frameworks
• Node.js, npm, Grunt for build
• Karma and Puppeteer for testing
• WebGL for GPU-accelerated rendering
• HTML partials (handlebars-style templates) for error/export dialogs
• Vanilla JS modules, no frontend framework