feat: improve understandability with comprehensive comments, API addi…#24
Merged
feat: improve understandability with comprehensive comments, API addi…#24
Conversation
…tions, and code cleanup Add physics and algorithm explanations to every quantum gate, simulator kernel, transpilation algorithm, noise channel, and Pauli algebra routine. The primary goal of Goqu is to be learnable by reading the code, and these comments explain the WHY behind each operation — not just the WHAT. Code improvements: - Unify duplicate barrierGate into circuit/gate/pseudo.go - Replace fragile string-based gate dispatch (strings.HasPrefix) with interface-based dispatch (Diagonal2Q, ControlDiagonal2Q, ControlU2Q) - Add Sim.Apply() for incremental state evolution without reset - Add Sim.Reset() as an explicit state initialization method - Extract parallel kernel boilerplate into runParallel2q helper - Add NumOps/Op/RangeOps to ir.Circuit to avoid defensive copy allocation
Replace the single getting-started notebook with a comprehensive 16-part curriculum covering qubits through advanced algorithms. Each notebook uses predict-then-verify pedagogy, Bloch sphere and histogram visualizations, and progressive exercises. Notebooks: the qubit, single-qubit gates, measurement, entanglement, teleportation, multi-qubit gates, QFT, phase estimation, Grover, Shor, noise, transpilation, variational algorithms, quantum ML, error mitigation, and advanced topics (Trotter, HHL, Clifford, pulse, QASM/Quil, backends). Also updates tools.go with all package imports and README.md with the full curriculum table.
- Convert all exercises (NB02-16) from pre-solved to scaffolded format with TODO comments and placeholder markers, matching the NB01 pattern. Learners must now fill in the blanks rather than just running cells. - Reorder notebooks 04-06: multi-qubit gates now precedes entanglement (04-multi-qubit-gates, 05-entanglement, 06-teleportation) so CNOT is formally taught before being used to create Bell states. - Add Bloom's taxonomy learning objectives to every notebook (NB02-16), with 4 measurable outcomes per notebook using action verbs like Describe, Implement, Predict, Verify, Compare, Explain.
- Add manual circuit construction sections before SDK wrapper calls in NB08 (Deutsch-Jozsa), NB09 (Grover), and NB10 (Shor) so learners see the algorithm internals before the high-level API. - Add new notebook 11b covering quantum error correction: 3-qubit bit-flip code, phase-flip code, Shor 9-qubit code, syndrome measurement, and stabilizer formalism preview with Clifford sim.
- Split NB08 into 08 (QPE + state prep) and 08b (DJ, BV, Simon's) - Split NB10 into 10 (Shor's algorithm) and 10b (quantum counting, AE) - Split NB16 into 16 (Trotter, HHL, Clifford, Pauli) and 16b (pulse, operators, QASM/Quil, backends, observability) - Add barren plateaus subsection to NB13 with numerical demonstration - Add prerequisite statements to all 20 notebooks - Add 2-3 conceptual self-check questions before exercises in each notebook
- Remove duplicated DJ/BV/Simon content from NB08 (now solely in 08b) - Remove duplicated counting/AE content from NB10 (now solely in 10b) - Remove duplicated pulse/operators/QASM/backends from NB16 (now in 16b) - Add pointer notes in NB08, NB10, NB16 directing to their b-notebooks - Fix NB14 "next up" to say "error mitigation" not "error correction" - Fix NB10 "next up" to say "noise and decoherence" not "error correction" - Add global phase explanation to NB02 before exercises - Add expected output comments to exercise scaffolds in NB01-03
…ting bug Switch all 20 notebooks from text-based draw.String() to graphical draw.SVG() circuit rendering via gonbui.DisplayHTML(). Fix notebook runtime errors: - Cross-cell variable scoping in gonb %% cells (06, 07, 11, 11b, 13, 15) - Unused variable declarations in exercise stubs (09, 10, 10b, 12, 13, 14, 16) - Swapped Switch correction cases in bit-flip/phase-flip codes (11b) - Syndrome truth table values matching actual qubit ordering (11b) Fix SABRE routing bug causing panics on large targets: - Size inverse layout array to physical device qubits, not circuit qubits - Guard layout/inv accesses against unoccupied physical qubit sentinels - Select initial layouts from full device instead of just [0, n) - Scale trial count for small circuits to avoid unnecessary overhead Update notebook 12 to use IBMBrisbane for decomposition demos and a small custom linear target for routing demos.
- Introduced a new markdown cell in the error mitigation notebook explaining the importance of error mitigation in quantum computing. - Simplified the markdown content in the advanced topics notebook for Trotter-Suzuki Hamiltonian simulation. - Updated the Hamiltonian in the Trotter simulation examples to include transverse-field terms. - Removed unnecessary output sections and adjusted execution counts for clarity. - Added exercise instructions for comparing Trotter accuracy with a focus on the transverse-field Heisenberg model.
…nspilation pipeline Add new transpiler passes and decomposition backends to support additional hardware targets (Google/Rigetti CZ, Quantinuum RZZ) and improve circuit optimization through iterative fixed-point loops. New passes: - DecomposeMultiQubit: break >2Q gates into 1Q+2Q before routing - Consolidate2QBlocks: merge adjacent 2Q blocks and re-synthesize via KAK - RemoveIdentity: remove gates whose matrix is the identity Pipeline changes: - Restructure to industry-standard flow: init -> pre-route -> route -> translate -> optimize -> validate - Add iterative fixed-point optimization loops for Basic and Full levels - Fix routed circuit to use target's physical qubit count Decomposition: - Add CZ backend (Google/Rigetti) with identity shortcut - Add RZZ backend (Quantinuum) with identity shortcut - Export OpsToUnitary4 for use by Consolidate2QBlocks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Improve Goqu's understandability and capabilities across the entire stack - from comprehensive code comments to a complete notebook curriculum to new transpilation features.
Documentation & Comments
Notebook Curriculum
Transpilation Pipeline
Code Improvements
Test plan