-
-
The learner predicts first, then reveals every possible answer before seeing any quantum comparison.
-
The same exact-first method applied to a compact problem derived from governed public folk-data research.
-
Sanitised evidence from an independent 81-cell IBM hardware replication, presented with its limitations and controls.
-
Beginner Foundations lessons and a searchable Glossary support the active experiments.
Inspiration
Quantum computing demonstrations often begin with impressive charts, but give beginners no simple way to know whether the quantum result is actually right.
Quantum Folk Lab reverses that order.
Folk tunes contain understandable patterns of repetition, variation and family resemblance. These ideas provide a human-scale way to introduce optimisation: first understand the ordinary grouping question, then translate it into binary choices, a score and a quantum experiment.
The aim is not to claim that a quantum computer understands music. It is to teach people how to judge a quantum result honestly.
What it does
Quantum Folk Lab is an interactive, beginner-first Streamlit learning experience.
The learner:
- inspects eight invented tune variants;
- predicts which four belong together;
- reveals all 256 possible binary assignments;
- sees the exact best grouping using named variants and bitstrings;
- learns why lower “energy” means a better-scoring answer;
- follows the translation from a human question to binary choices, a QUBO and a quantum circuit;
- watches 4,096 repeated measurements form a distribution;
- compares ideal simulation with exact classical truth;
- moves to a separate, smaller registered problem derived from governed folk-music data;
- inspects results recorded from real IBM quantum hardware;
- asks GPT‑5.6 to explain an already-validated evidence packet;
- completes a five-question exit check.
Exact classical enumeration remains the reference throughout. Simulation, hardware and AI explanation are clearly labelled as different evidence layers.
The core journey works without Qiskit, IBM credentials, an OpenAI API key or a live cloud service.
How we built it
Quantum Folk Lab began as a reproducible quantum-optimisation research repository. During Build Week, I used Codex to transform that research into a coherent educational product.
The application is built in Python and Streamlit. Deterministic code enumerates every candidate answer and verifies the QUBO and Ising representations. Qiskit supports bounded local QAOA simulation, while sanitised committed artefacts preserve the results of separately governed IBM hardware experiments.
The optional GPT‑5.6 layer receives only a filtered, validated evidence packet. Its structured output is checked for unsupported numbers, incorrect claims and disagreement with the exact result. If the model is unavailable or its response fails validation, the app falls back to a complete deterministic explanation.
Codex accelerated implementation, testing, documentation, CI diagnosis and visual verification. I retained responsibility for the research direction, source and licence decisions, hardware authorisation, stopping rules, interpretation and final claims.
The final release passed 264 tests alongside formatting, linting, type, release-integrity and public-safety checks.
Challenges we ran into
The hardest challenge was turning a technically rigorous research repository into something a first-time learner could follow without weakening the science.
Bitstrings had to be translated back into named human-readable groups. Complementary bitstrings also needed careful treatment: 00001111 and 11110000 describe the same partition with the family labels exchanged.
We also had to keep five things unambiguously separate:
- exact classical truth;
- registered ideal simulation;
- optional local simulation;
- recorded IBM hardware evidence;
- GPT‑5.6 explanation.
The real-data work required licence and provenance review, negative truth gates and restraint when early formulations were scientifically weak. Hardware execution was similarly governed through frozen plans, preflight checks, explicit human authorisation and no automatic retries.
Accomplishments that we're proud of
The strongest product moment is the prediction and Reveal: a learner commits to a grouping, then sees the complete 256-answer landscape and the exact named solution.
The project also connects that teaching example to governed real-data and IBM evidence without pretending they are the same problem.
In the registered hardware programme:
- the exact optimum remained the most likely state in the first compact validation;
- a controlled 25-cell hardware landscape achieved rank correlation rho = 0.96 against the ideal reference;
- an independent 81-cell replication achieved rho = 0.9047, with cross-run rho = 0.9777.
The original control warnings remain visible. These results are bounded experimental evidence—not proof of quantum advantage.
I am also proud that the core experience is credential-free, reproducible and honest about what was established and what was not.
What we learned
The most important lesson was that quantum education works better when exact truth comes first.
A distribution from a simulator or physical quantum computer becomes meaningful only when the learner has a trustworthy reference against which to judge it.
We also learned that negative results and stopping gates improve a project. Rejecting weak formulations was more scientifically valuable than forcing every experiment into a positive story.
Finally, generative AI is most useful here as a bounded translation layer. GPT‑5.6 can adapt an explanation to a learner, but deterministic evidence—not the model—must remain the source of truth.
What's next for Quantum Folk Lab
The next step is evaluation with learners and educators: testing comprehension, accessibility and which explanations work best.
Future research fixtures will only be added after licence, provenance and cultural-context review. Further quantum-hardware work will require a new predeclared research question rather than simply running larger experiments.
Possible product extensions include classroom materials, bilingual learning content and additional governed examples. The exact-first evidence hierarchy will remain central.
Quantum Folk Lab does not claim quantum advantage. It shows, step by step, how an ordinary question becomes a quantum experiment—and how exact evidence lets us judge the result honestly.
Log in or sign up for Devpost to join the conversation.