[Roadmap] Reimplement the Five Starter Problems in QUBONotebooks

[bernalde]

Context

The reference repository, arulrhikm/Solving-QUBOs-on-Quantum-Computers, accompanies Mazumder and Tayur's Five Starter Problems tutorial. Its five Python notebooks cover:

• three canonical models: number partitioning, Max-Cut, and minimum vertex cover;
• two applied models: order partitioning for A/B testing and altered-pathway discovery from TCGA AML mutation data;
• three QAOA presentations (custom Qiskit circuits, OpenQAOA, and Qiskit Optimization);
• D-Wave simulated annealing and quantum annealing.

Placement decision

The clean-room Julia reimplementations should live in QUBONotebooks.

This repository owns end-to-end, teaching-oriented workflows spanning modeling, decoding, visualization, local solvers, and optional hardware. In contrast:

• QUBO.jl is the umbrella package and should keep its package documentation focused on the core API;
• QiskitOpt.jl already owns the reusable QAOA/IBM integration, including local Aer execution, fixed-parameter circuits, resource audits, and IBM Runtime handoff;
• DWave.jl already owns the reusable local Neal and D-Wave QPU optimizer interfaces.

No missing reusable package capability was identified during the placement review. If implementation reveals a genuine API gap, open the smallest upstream issue in the owning package and link it here; do not work around a reusable solver limitation with notebook-only bridge code.

Reimplementation policy

The source repository currently has no LICENSE file and GitHub reports no detected license. Treat it as a source of ideas and references, not copyable implementation material:

• write original Julia code and original explanatory text;
• derive formulations from the published paper and other cited primary sources;
• do not copy notebook cells, prose, saved output, figures, or other assets without explicit permission;
• cite both the paper and the companion repository;
• record any independently chosen example data and random seeds.

The reimplementation must also independently validate the mathematics. In particular, do not reproduce two defects visible in the companion notebooks:

• the order-partitioning risk term places the square inside the inner sum, making that term constant for binary variables; the published formula squares the sum over orders for each risk factor;
• the cancer-genomics co-mutation matrix loop uses a stale index in the notebooks; construct and test every off-diagonal pair explicitly.

Proposed notebook sequence

Reserve notebook number 6 for the existing Python-only QCi topic and add the Julia series as:

1. notebooks_jl/7-CanonicalProblems.ipynb
2. notebooks_jl/8-OrderPartitioning.ipynb
3. notebooks_jl/9-CancerGenomics.ipynb
4. notebooks_jl/10-QAOA.ipynb
5. notebooks_jl/11-Annealing.ipynb

Each notebook should be useful on its own, but should link to the earlier modeling notebook instead of repeating long derivations.

Follow-up issues

• Add reproducible, provenance-checked TCGA AML inputs for the cancer-genomics example #91 — implemented by Add reproducible TCGA AML data inputs #98
• Add a Julia notebook for the three canonical QUBO starter problems #92 — implemented by Add Julia notebook for canonical QUBO starter problems #99
• Add a corrected Julia order-partitioning case study #93 — implemented by Add corrected Julia order-partitioning case study #100
• Add a Julia cancer-pathway QUBO case study from reproducible TCGA AML aggregates #94 — implemented by Add reproducible Julia cancer-genomics case study #102
• Add a local-first Julia QAOA tutorial with QiskitOpt.jl #95 — implemented by Add local-first Julia QAOA tutorial #103
• Add a local/quantum annealing comparison with DWave.jl #96 — implemented by Add local and quantum annealing comparison #104
• Integrate the Five Starter Problems series into README, Colab, and verification #97 — implemented by Integrate Five Starter Problems series #105

Cross-cutting requirements

• Local, credential-free execution is the default.
• Hardware sections are explicitly opt-in and read credentials only from environment variables or hosted-notebook secret stores.
• Small examples are checked against independent enumeration or ExactSampler results.
• Stochastic examples use fixed seeds where supported and validate energies/feasibility rather than one exact bit string.
• Every notebook includes setup, learning objectives, prerequisites, practice checkpoints, summary, and primary references consistent with the existing repository.
• Default verification must not call live data or quantum-computing services.
• No claim of quantum advantage or solver superiority is made from these tutorial-scale instances.

Definition of done

• All follow-up issues are closed by independently reviewable PRs.
• The five problem formulations and the QAOA/annealing workflows are represented in original Julia notebooks.
• The default local paths run from a fresh checkout and are covered by documented verification targets.
• Optional IBM and D-Wave paths fail closed with clear instructions when credentials are absent.
• README navigation, citations, dependency locks, Colab bootstrap behavior, and notebook hygiene tests cover the new series.

Out of scope

• Vendoring or maintaining OpenQAOA as a Python dependency.
• Porting the reference notebooks cell-for-cell or preserving their solver-by-problem duplication.
• Adding reusable solver behavior to this repository instead of the appropriate package.
• Treating live QPU results as deterministic CI requirements.