Alice_Bob / catch-the-flip
PublicCHALLENGE.md, the challenge statement, and docs/THEORY.md, the physics primer.dynamiqs? Run tutorials 1 to 3 of notebooks/ before the event.notebooks/04_tutorial_monitoring_a_cat.py: quantum trajectories, click records,
heterodyne records and the dark buffer.notebooks/05_tutorial_catching_flips_in_click_records.py: a dataset of the
challenge format, what a flip looks like in a record, what a detector is and how it is
scored. It uses click records, where a flip can be seen by eye, and nothing in it is
handed in.notebooks/10_challenge_template.py. It walks through the four steps of the
challenge, builds a first detector for the heterodyne records and writes a submission
file, submission_template/tierB.csv. Save that file with the button of the notebook, then
sign in on the live leaderboard,
type your team name and press Submit to get your first score. Then improve it.split (train, val or test), and its page describes the columns.
| dataset | records | role | segments (train, val, test) |
|---|---|---|---|
| Alice_Bob/catch-the-flip-tier-b | two quadratures of a heterodyne detector | the records of the challenge: your detector works on them, and the leaderboard scores them | 15 000, 7 500, 22 500 |
| Alice_Bob/catch-the-flip-tier-a | click times of a photon counter | tutorial 5 and the physics questions; not scored, nothing to submit | 30 000, 15 000, 30 000 |
catchtheflip.records.load_dataset("data/tierB_train.npz") returns the
train split of tier B as NumPy arrays, and likewise for the five other splits. It reads the
split from the Aqora dataset, or from a file of that name if you put one in data/.
data/README.md describes the arrays.CHALLENGE.md | the challenge statement: device sheet, the four steps, open routes, deliverables, scoring, rules |
docs/THEORY.md | the physics in eight sections: cat qubits, the buffer, why flips shine, unravelings, labels, rates, what a herald could buy, further reading |
notebooks/01…03_tutorial_*.py | tutorials: dynamiqs, open quantum systems, cat qubits (read before the event) |
notebooks/04_tutorial_monitoring_a_cat.py | tutorial: quantum trajectories, click records, heterodyne records, the dark buffer |
notebooks/05_tutorial_catching_flips_in_click_records.py | tutorial: a dataset of the challenge format, a flip in a record, a detector and its score, on click records |
notebooks/10_challenge_template.py | a template that walks through the four steps and writes a first submission file |
catchtheflip/ | helper package: models, rates from the Liouvillian spectrum, stochastic simulations, records, scoring, repetition code |
data/ | data/README.md: what the datasets hold (the records themselves are the two Aqora datasets above) |
scripts/ | generate_dataset.py (make your own labelled data), score_submission.py |
submission_template/ | what to hand in |
catchtheflip of this workspace.
The simulations use dynamiqs (JAX), and nothing needs a GPU. Most
computations run in seconds to minutes. The statistics of step 2 can take 10 to 20 minutes per
cat size once flips get rare: plan them and start them early. If something takes longer, you
are probably simulating more than you need (ask a mentor).docs/THEORY.md, section 8). You do not need it, and you will get
more out of it after the hackathon, once you have found the answers yourself.
Tutorials 1–3 are adapted from the Alice & Bob challenges at MIT iQuHACK 2025 and
DuQuantum 2026. Everything here is released under the MIT license.