Case Study · Quantum · Education
Qlearn
The idea
Qlearn is an open-source quantum-computing education platform, and unlike the rest of this catalog it is a team’s work rather than mine alone. It was built for UConn Senior Design by a team of five, Avery Hogrefe, Connor Ravenberg, me, Jonathon Le, and Erin Paquin, and it is live at qlearn.live. The premise is the one that runs through everything on this site: you do not learn quantum computing by reading about it, you learn it by pushing on the state and watching what pushes back. So Qlearn walks a programmer from the mathematical foundations (complex numbers, linear algebra) through qubits, gates, measurement, and entanglement, and on to Grover search, and at every stumbling point the prose hands you an instrument: a Bloch sphere you can drag, a circuit you can step through amplitude by amplitude, a Python prompt that runs right there in the page.
Under the platform sits QLeap, the project’s quantum-simulation library. It wraps IBM Qiskit and is published on PyPI, and it is the one runtime the whole system speaks: the backend simulates circuits with it, the in-browser tools run it through Pyodide, and a translator page renders QLeap and Qiskit side by side so learners can graduate to the industry framework. If the instinct behind my earlier statevector simulator was “rebuild the interesting part yourself,” Qlearn is that instinct scaled to a whole curriculum and a whole team. The source lives on UConn’s internal GitHub, so there is no public repository to link yet; the platform itself is the demo.
The architecture
The stack is deliberately boring in the right places: Flask 3 behind Gunicorn with psycopg 3 pooling into Postgres 16, a React 18 + Vite 5 frontend, KaTeX for the mathematics, and a single docker-compose file that brings up all three services. The interesting part is the content pipeline. The canonical curriculum is a single LaTeX document of roughly 9,500 lines, and Python migration scripts compile it into the JSON modules and question banks the frontend consumes: headings become sections, code blocks and figures survive the trip, and inline interactable markers resolve to tool routes. When a lesson hands you off to a tool, a small handoff protocol records where you were and walks you back to the exact section afterward.
Python execution comes in two flavors. In the browser, Pyodide runs learner code client-side, which is what powers the sandbox IDE, the circuit stepper, and the block-code compiler. On the server, a circuit-execution endpoint runs QLeap simulations with a shots cap, and a separate sandbox runs untrusted Python in an isolated subprocess with conservative code-size, wall-time, and output limits. Accounts, progress, achievements, and the leaderboard sit behind feature flags, so either subsystem can be switched off at runtime without touching the schema.
From a LaTeX document to a lesson
The pipeline is the part I would defend in a design review, so here it is at the
level where the decisions live. The curriculum author writes ordinary LaTeX, and
where a paragraph wants an instrument they write a marker inline,
\qleapinteractable{type}{id}{description}. The type is the whole contract:
it is looked up in a table that maps interactable types to tool routes, so
grovsearch resolves to the Grover page and bloch_sphere to the Bloch sphere.
Two Python migration scripts then do the compiling, one for the prose and one for
the question bank.
The prose compiler is the messier of the two, because a document written to be
read by humans carries a great deal that a JSON module should not. It walks
headings, sections, code blocks, images, and markers; it skips the metadata
front matter (executive summary, unit structure, and the like); it cleans the
artifacts that mean nothing outside a .tex file (\label, \ref, \vspace,
comment blocks); it converts the environments KaTeX cannot render; it strips the
formative-question blocks that would otherwise appear twice, once in the prose
and once in the question bank; and it reads an estimated time out of sentences
like “approximately two hours” so the reader can show one. What comes out is a
module record: a slug such as u0-complex-foundations, its unit and chapter
index, an ordered list of typed sections (text, code, image, video, interactable,
assessment), and a status of draft, published, or archived. A question record
carries its module slug and section id, the prompt, an optional code prompt with
its language, the choices where there are choices, and the answer.
Two smaller decisions are the ones I would point at. The first is that an unmapped interactable type renders a placeholder and does not gate progression. A curriculum author can name a tool that nobody has built yet, and the lesson still compiles, still reads, and still completes. That is a pipeline that fails open, which is the right default when the document and the code are written by different people on different schedules. The second is that content writes are atomic: a temporary file followed by a rename, per-path locks against concurrent writers, and a backup taken before every migration run. Neither is interesting to demo. Both are why a bad parse is a thing you undo rather than a thing you restore from.
The last piece is what happens when a learner takes the pipeline up on its offer and clicks an interactable. The lesson does not simply navigate away: it records where the reader was, the tool shows a banner offering the way back, and the return trip restores the section and the scroll position rather than dropping them at the top of a chapter. It is a small thing that decides whether an instrument feels like part of the lesson or like a detour away from it.
The instruments
The tools are the argument of the whole platform, so here is the shelf. QuExp is a draggable Bloch sphere with gate buttons running from and through and , each gate carrying a pronunciation tooltip and symbolic amplitudes like rendered properly. BasComp stands next to it and asks the question a single sphere cannot: fix a state, choose two measurement bases from , , and , run the shots in each, and read the two histograms side by side. That is the moment the choice of basis stops being notation and becomes a thing that changes what you observe. CircStep takes a QLeap-style Python program and simulates it step by step in the browser, annotating each step with the Bloch description, the amplitude breakdown, and the probability distribution. GrovSearch animates Grover’s algorithm: pick a problem size and a marked set, then step or auto-play through oracle and diffuser iterations while an amplitude chart and a curve of success probability track the search. On the mathematical-foundations side, ImGen puts two draggable points on a complex plane and renders their sum, product, and quotient; VecViz builds geometric intuition for complex inner-product spaces (Cauchy–Schwarz, the parallelogram law); MatExp dissects complex matrices, drawing eigenvalues on the unit circle when the matrix is unitary.
For writing actual code there is a Pyodide-backed sandbox IDE with starter programs from a lone superposition up to a three-qubit GHZ chain, a drag-and-drop block-code builder that compiles visual blocks to runnable Python, and the QLeap–Qiskit translator. And the CHSH Bell-test mini-lab lets you choose measurement bases for two parties, run the shots, and compute the correlation yourself; push it past and the page congratulates you on violating a Bell inequality.
Every one of those has its own route on qlearn.live, and the curriculum reaches them through the markers described above, which is the point of the whole arrangement: an instrument is a page you can open on its own and also the thing a paragraph hands you when the paragraph runs out of words.
Making it stick
The layer I find easiest to underestimate is the game. Qlearn carries a catalog of more than sixty achievements, a leaderboard whose score is a weighted sum of six components (exercises passed, tools used, time spent, questions attempted and correct, achievements earned), and eighteen hidden easter eggs: the Konami code puts the interface into superposition, the 404 page hides a collapsing cat, and a backgrounded tab flips its favicon between and until you observe it again. Sillier than a syllabus, yes. But an “Explain Like I’m Classical” toggle in the same spirit annotates roughly fifty quantum terms with analogies from a metaphor family of your choosing, each with an explicit “where this breaks” caveat, and that caveat is the difference between an analogy that teaches and one that lies.
What it measures, and what the measurement is worth
Underneath the game is an assessment system with actual gates in it. Each chapter ends in a review drawn from that module’s question bank, and clearing a pass ratio is what unlocks the next chapter; the platform keeps the best ratio rather than the last, so a second attempt can only help. After all the chapters of a module comes a longer final assessment drawn across the whole module, and passing it writes an exam score and a completion date into the learner’s transcript. The leaderboard sits on top of that as a weighted sum of six counters, with the weights configurable rather than compiled in, and with the counts and their weighted totals cached so ranking is an indexed read rather than a scan.
The component worth looking at closely is time spent, because of where the number comes from. The client posts a heartbeat every thirty seconds, but only while the learner is signed in and the tab is actually visible, carrying the elapsed seconds and any tool routes newly visited since the last beat, deduplicated per navigation. Both halves of that are deliberate. Gating on visibility is a real improvement on measuring time since login, which counts a forgotten tab as study; deduplicating per navigation is what stops the interactables counter rewarding someone for refreshing the Bloch sphere twenty times.
It is still a presence proxy, and this is the part I would say out loud in a design review rather than in a footnote. A visible tab is not attention: a learner who leaves a lesson open and reads a textbook on paper accrues score for it, and one who reads the same lesson quickly and understands it accrues less. Scoring questions answered alongside questions correct has the same double edge, and the same defense: it deliberately rewards attempting a hard question rather than avoiding it, and it just as deliberately rewards guessing. Neither is a defect exactly. They are the ordinary tension in gamified learning, where the things easy to count and the things worth counting are not the same set. What I would want before treating the leaderboard as a measure of anything beyond engagement is the one measurement nobody made: whether the six components correlate with final assessment scores at all, and which of them survives when you control for the others. The data to answer that is already in the tables, which is the frustrating part. It needs another semester of learners and an afternoon of regression, and it would tell you whether the score is measuring learning or measuring stamina.
What the team learned
Credit first: this was five people’s system, and this write-up describes the team’s work rather than my corner of it. The decision I would defend hardest is keeping the curriculum in LaTeX and compiling it, rather than authoring in the frontend’s native JSON: it kept a 9,500-line document reviewable as a document, and it meant the content pipeline had to be rigorous about parsing (cleaning artifacts, stripping duplicated question blocks, backing up before every migration). The cost is real too: two Python runtimes (Pyodide in the browser, a sandboxed subprocess on the server) means every capability question gets asked twice, and a translator between QLeap and Qiskit is a maintenance promise that grows with both languages. The feature-flag discipline (auth and progress can be switched off at runtime, with the schema left standing) is the sort of unglamorous operational choice that a five-person team only makes after imagining the demo-day failure it prevents. That, more than any single tool, is what senior design taught: the difference between a project and a platform is mostly what you build for the day something breaks.
This page is not the demo. The source sits on UConn’s internal GitHub, so there is no repository to read, and the diagrams above are descriptions of a system rather than the system. The platform is running: open qlearn.live, drag the Bloch sphere, step Grover through an oracle and a diffuser, and push the Bell test past . That takes about ten minutes and settles more than another thousand words here would.