Skip to content
Quon

More samples

Reference: the Quon constructs in this recipe are defined normatively — syntax, typing contract, constraints, and a minimal example — in the Language reference.

Optional detour. This page is not part of the cookbook curriculum — the canonical sequence is Bell → teleportation → Bernstein–Vazirani → Grover → QFT → Ising → QAOA → Shor → NA QAOA schedule (the capstone). Browse this catalog whenever you like. To resume the curriculum, return to the Cookbook overview or continue from the capstone, NA QAOA schedule.

This cookbook’s eight pages are a fixed, hand-curated tour of the compiler’s own end-to-end fixtures. The repository also carries a growing samples/ corpus — narrative demos organized by taxonomy (learning, algorithms, workflows, visualization, applications, research, neutral-atom pedagogy, and creative / games) and indexed by a machine-readable catalog, ADR-0025.

Start with samples/README.md for the taxonomy and pack-ownership table, or browse the catalog directly:

Taxonomy

Section titled “Taxonomy”
Category What it’s for Pack owner
learning/ One concept per file, narrated for newcomers —
algorithms/ Named algorithms / canonical constructions —
workflows/ Edit → verify loops, pass dumps, failure clinics #188
visualization/ Schedule/graph goldens, “what you should see” #189
applications/ Real-world use-case framing —
creative/ Playful / games programs that teach one concept each #200
research/ Literate notebooks + .py smoke twins #190
neutral-atom/ NA pedagogy: zoned vs. flat, routing-agnostic vs. routing-aware placer #192

Current catalog

Section titled “Current catalog”
# Sample corpus catalog (ADR-0025, issue #185).
#
# One row per sample under `samples/`. A contribution is not complete until
# it has a row here — see `samples/CONTRIBUTING.md`. Schema, path-existence,
# category-coverage, and README-section checks live in
# `quonc/tests/samples_catalog.rs`, run via `cargo test --workspace` (or
# standalone with `just ci-samples`).
#
# `id`, not `path`, determines a sample's category: the id prefix must be
# one of the seven taxonomy categories, but path may point elsewhere for a
# linked canonical artifact (e.g. `neutral-atom/...` -> `test/na/` or
# `examples/na_qec/`, per the "link, don't fork" rule in that category's
# README).
#
# Fields (all required):
#   id           <category>/<slug> — category must be one of the seven
#                top-level directories under samples/.
#   path         Repo-root-relative path to the primary artifact (usually a
#                `.qn` program; `research/` entries may point at a literate
#                `.md`/notebook instead — see that pack's README).
#   tags         Free-form labels for future search/filter UI.
#   difficulty   beginner | intermediate | advanced
#   quonc_args   Extra CLI flags a reader should pass to `quonc` to compile
#                this sample (before the source path); [] for defaults.
#   artifacts    Paths to checked-in generated artifacts this sample owns
#                (goldens, reports, images); [] if it produces none yet.
#   ci           smoke | none — smoke entries are compiled with the real
#                `quonc` binary in CI (typecheck + lowering); none is the
#                default for narrative-only or not-yet-fleshed-out seeds.
version: 1
entries:
  - id: learning/hello-bell
    path: samples/learning/hello_bell.qn
    tags: [learning, beginner, bell-state, entanglement]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: learning/hello-quon
    path: samples/learning/hello_quon.qn
    tags: [learning, tutorial, beginner, hello-world, x-gate, measurement]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: learning/states-measurement
    path: samples/learning/states_measurement.qn
    tags: [learning, tutorial, beginner, superposition, born-rule, hadamard, aer-verify]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: learning/gates-composition
    path: samples/learning/gates_composition.qn
    tags: [learning, tutorial, beginner, composition, parallel, depth]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: learning/linearity-borrow
    path: samples/learning/linearity_borrow.qn
    tags: [learning, tutorial, beginner, linearity, no-cloning, ancilla, cnot]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: learning/entanglement
    path: samples/learning/entanglement.qn
    tags: [learning, tutorial, beginner, entanglement, bell-state, correlation]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: learning/oracles-algorithms
    path: samples/learning/oracles_algorithms.qn
    tags: [learning, tutorial, beginner, oracle, phase-kickback, bernstein-vazirani, algorithm]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: algorithms/ghz-state
    path: samples/algorithms/ghz_state.qn
    tags: [algorithms, entanglement, ghz, beginner]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: algorithms/deutsch-jozsa
    path: samples/algorithms/deutsch_jozsa.qn
    tags: [algorithms, textbook, deutsch-jozsa, oracle, phase-kickback, learning]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: algorithms/simon
    path: samples/algorithms/simon.qn
    tags: [algorithms, textbook, simon, oracle, gf2, learning]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: algorithms/phase-estimation
    path: samples/algorithms/phase_estimation.qn
    tags: [algorithms, textbook, qpe, phase-estimation, phase-kickback, learning]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: applications/quantum-coin-flip
    path: samples/applications/quantum_coin_flip.qn
    tags: [applications, randomness, superposition]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: none

  # ── Application-domain demos (#191) ─────────────────────────────────────
  - id: applications/maxcut-qaoa
    path: samples/applications/maxcut_prism6.qn
    tags: [applications, optimization, qaoa, maxcut, graph, aer-verify]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: applications/qaoa-depth-p1
    path: samples/applications/maxcut_c5_p1.qn
    tags: [applications, optimization, qaoa, maxcut, depth-scaling, aer-verify]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: applications/qaoa-depth-p2
    path: samples/applications/maxcut_c5_p2.qn
    tags: [applications, optimization, qaoa, maxcut, depth-scaling, aer-verify]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: applications/ising-ring
    path: samples/applications/ising_ring.qn
    tags: [applications, simulation, ising, trotter, lattice, ring, periodic, aer-verify]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: applications/vqe-ansatz
    path: samples/applications/vqe_ansatz.qn
    tags: [applications, optimization, vqe, ansatz, variational, aer-verify]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: applications/tsp-sketch
    path: samples/applications/tsp_sketch.qn
    tags: [applications, optimization, tsp, sketch, ising, qaoa]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: workflows/edit-verify-loop-stub
    path: samples/workflows/edit_verify_loop.qn
    tags: [workflows, stub, pack-188]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: none

  - id: visualization/dense-swap-mismatch
    path: test/verify/qaoa.qn
    tags: [visualization, mapping, swap, qaoa, mapper-viz, pack-189]
    difficulty: intermediate
    quonc_args:
      ["--target", "targets/ibm/fake_manila_v2.json", "--emit-qasm"]
    artifacts:
      [
        samples/visualization/goldens/dense_swap_mismatch/qaoa_manila.qasm,
        samples/visualization/goldens/dense_swap_mismatch/metrics.json,
      ]
    ci: smoke

  - id: visualization/teleport-dynamic
    path: test/verify/teleport.qn
    tags: [visualization, teleportation, dynamic, deferral, circuit-viz, pack-189]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts:
      [
        samples/visualization/goldens/teleport_dynamic/teleport.qasm,
        samples/visualization/goldens/teleport_dynamic/metrics.json,
      ]
    ci: smoke

  - id: visualization/qft-depth
    path: test/verify/qft.qn
    tags: [visualization, qft, optimizer, depth, circuit-viz, pack-189]
    difficulty: intermediate
    quonc_args: ["--emit-qasm", "--dump-ir"]
    artifacts:
      [
        samples/visualization/goldens/qft_depth/before_optimization.mlir,
        samples/visualization/goldens/qft_depth/after_optimization.mlir,
        samples/visualization/goldens/qft_depth/metrics.json,
      ]
    ci: smoke

  - id: visualization/na-interaction-graph
    path: test/na/qaoa_graph.qn
    tags: [visualization, neutral-atom, qaoa, interaction-graph, topology-viz, pack-189]
    difficulty: intermediate
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--na-backend",
        "zoned",
        "--emit-na-graph",
        "-",
      ]
    artifacts: [samples/visualization/goldens/na_interaction_graph/qaoa_graph.dot]
    ci: smoke

  - id: visualization/na-schedule-metrics-bell
    path: test/na/bell.qn
    tags: [visualization, neutral-atom, schedule, resource-report, pack-189]
    difficulty: beginner
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--na-backend",
        "zoned",
        "--verify-na",
        "--emit-resource-report",
        "-",
      ]
    artifacts:
      [samples/visualization/goldens/na_schedule_metrics/bell_zoned.resource_report.json]
    ci: smoke

  - id: visualization/na-schedule-metrics-qaoa-graph
    path: test/na/qaoa_graph.qn
    tags: [visualization, neutral-atom, schedule, resource-report, pack-189]
    difficulty: beginner
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--na-backend",
        "zoned",
        "--verify-na",
        "--emit-resource-report",
        "-",
      ]
    artifacts:
      [samples/visualization/goldens/na_schedule_metrics/qaoa_graph_zoned.resource_report.json]
    ci: smoke

  - id: visualization/noise-aware-target-overlay
    path: test/verify/ising.qn
    tags: [visualization, noise, target-overlay, topology-viz, pack-189]
    difficulty: intermediate
    quonc_args:
      ["--target", "targets/ibm/fake_manila_v2.json", "--emit-qasm"]
    artifacts:
      [
        samples/visualization/goldens/noise_target_overlay/ising_manila.qasm,
        samples/visualization/goldens/noise_target_overlay/metrics.json,
      ]
    ci: smoke

  - id: research/compiler-experiment-log
    path: samples/research/compiler_experiment_log.ipynb
    tags: [research, literate-notebook, compiler, sabre, metrics, pack-190]
    difficulty: intermediate
    quonc_args: []
    artifacts: []
    ci: none

  - id: research/algorithm-correctness-narrative
    path: samples/research/algorithm_correctness_narrative.ipynb
    tags:
      [
        research,
        literate-notebook,
        bernstein-vazirani,
        grover,
        aer-verify,
        pack-190,
      ]
    difficulty: intermediate
    quonc_args: []
    artifacts: []
    ci: none

  - id: research/bernstein-vazirani-oracle
    path: test/verify/bernstein_vazirani.qn
    tags: [research, bernstein-vazirani, oracle, linked-not-forked, pack-190]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: research/grover-n4-marked-11
    path: test/verify/grover.qn
    tags: [research, grover, amplitude-amplification, linked-not-forked, pack-190]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: research/na-resource-study
    path: samples/research/na_resource_study.ipynb
    tags:
      [
        research,
        literate-notebook,
        neutral-atom,
        resource-report,
        na-placer,
        pack-190,
      ]
    difficulty: intermediate
    quonc_args: []
    artifacts: []
    ci: none

  - id: research/repro-appendix-template
    path: samples/research/repro_appendix_template.md
    tags: [research, template, reproducibility, pack-190]
    difficulty: beginner
    quonc_args: []
    artifacts: []
    ci: none

  - id: neutral-atom/bell-pair
    path: test/na/bell.qn
    tags: [neutral-atom, beginner, bell-state, na-backend, pack-192]
    difficulty: beginner
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--na-backend",
        "zoned",
        "--verify-na",
      ]
    artifacts: []
    ci: smoke

  - id: neutral-atom/qaoa-maxcut
    path: test/na/qaoa_graph.qn
    tags: [neutral-atom, qaoa, na-placer, routing-agnostic, pack-192]
    difficulty: intermediate
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--na-backend",
        "zoned",
        "--verify-na",
      ]
    artifacts: []
    ci: smoke

  - id: neutral-atom/qft-small
    path: test/na/qft_small.qn
    tags: [neutral-atom, qft, na-backend, footnote-flat, pack-192]
    difficulty: intermediate
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--na-backend",
        "zoned",
        "--verify-na",
      ]
    artifacts: []
    ci: smoke

  - id: neutral-atom/ising-trotter
    path: test/na/ising.qn
    tags: [neutral-atom, ising, na-placer, locality, pack-192]
    difficulty: intermediate
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--na-backend",
        "zoned",
        "--verify-na",
      ]
    artifacts: []
    ci: smoke

  - id: neutral-atom/repetition-d3-memory
    path: examples/na_qec/repetition_d3_memory.qn
    tags:
      [
        neutral-atom,
        qec,
        memory,
        dynamic-circuit,
        mid-circuit-measurement,
        pack-192,
      ]
    difficulty: intermediate
    quonc_args:
      ["--target", "targets/neutral_atom/generic_rna_v0.json", "--verify-na"]
    artifacts: []
    ci: smoke

  # ── Benchmark suite (#284) ──────────────────────────────────────────────
  - id: neutral-atom/bench-surface-d3-memory
    path: samples/neutral-atom/benchmarks/surface_d3_memory.qn
    tags: [neutral-atom, qec, benchmark, surface-code, memory, pack-284]
    difficulty: intermediate
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--emit-resource-report",
        "-",
      ]
    artifacts: []
    ci: smoke

  - id: neutral-atom/bench-surface-d3-measure
    path: samples/neutral-atom/benchmarks/surface_d3_measure.qn
    tags: [neutral-atom, qec, benchmark, surface-code, measurement, pack-284]
    difficulty: intermediate
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--emit-resource-report",
        "-",
      ]
    artifacts: []
    ci: smoke

  - id: neutral-atom/bench-surface-d3-cx
    path: samples/neutral-atom/benchmarks/surface_d3_cx.qn
    tags: [neutral-atom, qec, benchmark, surface-code, lattice-surgery, cx, pack-284]
    difficulty: advanced
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--emit-resource-report",
        "-",
      ]
    artifacts: []
    ci: smoke

  - id: neutral-atom/bench-surface-d3-ghz
    path: samples/neutral-atom/benchmarks/surface_d3_ghz.qn
    tags: [neutral-atom, qec, benchmark, surface-code, ghz, entanglement, pack-284]
    difficulty: advanced
    quonc_args:
      [
        "--target",
        "targets/neutral_atom/generic_rna_v0.json",
        "--emit-resource-report",
        "-",
      ]
    artifacts: []
    ci: smoke

  # ── Creative / games pack (#200) ───────────────────────────────────────
  - id: creative/quantum-dice
    path: samples/creative/quantum_dice.qn
    tags: [creative, games, superposition, parallel-composition, born-rule, randomness, aer-verify, pack-200]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: creative/entangled-twins
    path: samples/creative/entangled_twins.qn
    tags: [creative, games, entanglement, bell-state, correlation, anti-correlation, aer-verify, pack-200]
    difficulty: beginner
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

  - id: creative/interference-barcode
    path: samples/creative/interference_barcode.qn
    tags: [creative, games, interference, phase, superposition, t-gate, generative-art, aer-verify, pack-200]
    difficulty: intermediate
    quonc_args: ["--emit-qasm"]
    artifacts: []
    ci: smoke

Sample-based recipes in this cookbook

Section titled “Sample-based recipes in this cookbook”

Three cookbook pages draw their source from the samples/algorithms/ corpus rather than the compiler’s own end-to-end fixtures, so they live in the optional sidebar group alongside this catalog:

These are independent of the curriculum; read them in any order.

CI

Section titled “CI”

Every entry’s path is checked to exist, the schema is validated, and every ci: smoke entry is compiled with the debug quonc binary — see quonc/tests/samples_catalog.rs, run as part of just ci-rust’s workspace test suite (or standalone via just ci-samples).