Qamomile Development Roadmap

[yuyamashiro]

Qamomile Development Roadmap

Project Direction

Role of qamomile.circuit

• Focus on quantum computation: Does not accept complex classical processing
• Minimal classical processing: Only dynamic measurements and simple conditional branching based on measurement results
• Keep Transpile simple: Hybrid workflows will be handled by a separate product

Definition of stdlib

• Basic quantum operations: QFT, IQFT, QPE, etc.
• FTQC components: T-gate optimized basic operations
• Algorithms like VQE are separate: Consider a new module like `qamomile.algorithms`

Out of Scope

• Circuit optimization (to be considered separately)
• Error correction code integration (to be considered separately)
• Cirq / Amazon Braket backends (excluded)

---

Current State Analysis

Well-Implemented Features

Module	Completeness	Notes
Frontend (@qkernel, Handles)	High	Qubit, Float, UInt, Bit, QFixed, etc.
IR (Value, Operations, Types)	High	SSA-like versioning, linear types
Transpiler Pipeline	Medium-High	inline, constant_fold, analyze, separate, emit
QAOA/FQAOA/QRAO Converters	High	Fully implemented
Qiskit Backend	High	Native control flow support
QuriParts Backend	Medium-High	Control flow via unrolling only

Key Issues

Issue	Current State	Impact
core module organization	Scheduled for deletion	Migration to optimization/ required
Graph.estimate()	Commented out	Resource estimation fragmented
Observable/Estimator	Protocol only	No unified expectation value API
CUDA-Q new API	Old API only	qamomile.circuit not supported
Legacy code	qiskit_old/	Technical debt
Type system	Basic types only	No complex number type, etc.

---

Issue List

Category 1: Code Migration & Cleanup

CM-1: Migrate core → optimization

• Priority: Highest
• Dependencies: None
• Tasks:
  • Migrate core/converters/ to optimization/converters/
  • Migrate core/ansatz/ to optimization/ansatz/
  • Migrate core/modeler/ to optimization/modeler/
  • Migrate core/post_process/ to optimization/post_process/
  • Update dependencies (fix import statements)
  • Migrate and update tests
  • Delete core directory

CM-2: Delete qiskit_old/ directory

• Priority: High
• Dependencies: None
• Tasks:
  • Check for usage
  • Confirm migration to new API is complete
  • Delete directory
  • Update documentation

CM-3: Simplify Transpiler

• Priority: Medium
• Dependencies: CM-1
• Tasks:
  • Clarify scope of classical processing support
  • Limit Orchestrator role to dynamic measurements
  • Remove unnecessary classical processing code paths
  • Document scope clearly

---

Category 2: Core Infrastructure

CI-1: Strengthen Type System

• Priority: High
• Dependencies: None
• Tasks:
  • Support for complex number type
  • Extend QFixed type operations
  • Enhance multi-dimensional Array type support
  • Improve type inference
  • Improve error messages

CI-2: Observable/Estimator Backend Implementation

• Priority: High
• Dependencies: None
• Tasks:
  • Concrete implementation of `ObservableEstimator` protocol
  • Complete `QiskitExpectationEstimator`
  • Complete `QuriPartsEstimator`
  • Implement `CudaqEstimator`
  • Sampling-based expectation value estimation

CI-3: Revive Graph.estimate() Implementation

• Priority: High
• Dependencies: None
• Tasks:
  • Implement `estimate()` method (basic qubit counting)
  • Implement `estimate_hierarchical()` method
  • Implement `call_graph()` method

CI-4: Control Flow for Dynamic Measurements

• Priority: Medium
• Dependencies: CI-1
• Tasks:
  • Clarify control flow needed for dynamic measurements
  • Confirm mid-circuit measurement support
  • Support for conditional gate application
  • Backend capability detection mechanism

---

Category 3: Backend Completion

BC-1: CUDA-Q New API (qamomile.circuit) Support

• Priority: High
• Dependencies: None
• Tasks:
  • Create `CudaqGateEmitter` class
  • Implement `CudaqCircuitTranspiler`
  • Implement `CudaqExecutor`
  • Implement `CudaqEstimator`
  • Consider native control flow support

BC-2: PennyLane New API Support

• Priority: Medium
• Dependencies: None
• Tasks:
  • Create `PennyLaneGateEmitter` class
  • Implement `PennyLaneCircuitTranspiler`
  • Implement `PennyLaneExecutor`
  • Implement `PennyLaneEstimator`

BC-3: QuTiP Transpiler Circuit Support

• Priority: Low
• Dependencies: None
• Tasks:
  • Implement `transpile_circuit()`
  • Convert to QuTiP Qobj
  • Support simulation execution

BC-4: Control Flow Support for All Backends

• Priority: Medium
• Dependencies: CI-4, BC-1, BC-2
• Tasks:
  • QURI Parts: Investigate and implement native control flow
  • CUDA-Q: Native control flow support
  • Create backend capability table

---

Category 4: stdlib & Algorithms

SA-1: stdlib Extension - Basic Quantum Operations

• Priority: High
• Dependencies: None
• Tasks:
  • Grover's diffusion operator
  • Amplitude Estimation basic components
  • Quantum adder (Draper adder, etc.)
  • Quantum comparator
  • Add documentation

SA-2: stdlib Extension - FTQC Components

• Priority: High
• Dependencies: SA-1
• Tasks:
  • T-gate optimized Toffoli
  • Clifford+T decomposition utilities
  • Magic state preparation circuits
  • Enrich resource metadata

SA-3: Create algorithms Module

• Priority: Medium
• Dependencies: SA-1
• Tasks:
  • Create `qamomile/algorithms/` directory
  • VQE template
  • Grover search algorithm
  • Quantum Approximate Optimization (integration with stdlib)
  • Design algorithm interface

SA-4: Expand Ansatz Library

• Priority: Medium
• Dependencies: CM-1
• Tasks:
  • Hardware Efficient Ansatz
  • UCCSD Ansatz (for quantum chemistry)
  • QAOA Mixer Ansatz variations
  • Custom Ansatz builder

---

Category 5: Resource Estimation

RE-1: Detailed Gate Counting

• Priority: High
• Dependencies: CI-3
• Tasks:
  • Count each gate type
  • Calculate circuit depth
  • Critical path analysis
  • Report generation functionality

RE-2: T-gate Counting / T-depth Calculation

• Priority: High
• Dependencies: RE-1
• Tasks:
  • T-gate / T-depth counter
  • Integration with Clifford+T decomposition
  • FTQC cost estimation

RE-3: Symbolic Resource Estimation

• Priority: Medium
• Dependencies: RE-1
• Tasks:
  • Unify symbolic representation using SymPy
  • Resource formulas for parametric circuits
  • Concrete value calculation via variable substitution

---

Category 6: Documentation & Testing

DT-1: Automated API Reference Generation

• Priority: High
• Dependencies: None
• Tasks:
  • Evaluate sphinx-autodoc, pdoc, etc.
  • Improve docstrings
  • Set up automated build in CI
  • Decide integration method with Jupyter Book 2

DT-2: Enhance Tutorials

• Priority: High
• Dependencies: None
• Tasks:
  • Detailed @qkernel API tutorial
  • QRAO tutorial (2:1, 3:1, 3:2)
  • FQAOA tutorial
  • Backend selection guide
  • Troubleshooting guide

DT-3: Strengthen Integration Tests

• Priority: High
• Dependencies: BC-1, BC-2
• Tasks:
  • End-to-end tests (JijModeling → optimization results)
  • Regression tests for all backends
  • Automated testing in CI/CD (including docs tests)

DT-4: Organize pyproject.toml

• Priority: Medium
• Dependencies: None
• Tasks:
  • Write description
  • Add optional dependency groups (cudaq, pennylane)
  • Add Python 3.12 tests (CI)

---

Recommended Implementation Order

Phase 1 (First 2 weeks) - Code Migration and Technical Debt Resolution

1. CM-1: Migrate core → optimization ⭐ Highest Priority
2. CM-2: Delete qiskit_old/
3. CI-3: Implement Graph.estimate()

Phase 2 (Month 1) - Core Features and Backend

4. CI-1: Strengthen type system
5. CI-2: Implement Observable/Estimator backends
6. BC-1: CUDA-Q new API support
7. DT-1: Automated API Reference generation

Phase 3 (Months 2-3) - stdlib Extension and Resource Estimation

8. SA-1: stdlib extension - Basic quantum operations
9. SA-2: stdlib extension - FTQC components
10. RE-1: Detailed gate counting
11. RE-2: T-gate counting
12. BC-2: PennyLane new API support
13. DT-2: Enhance tutorials

Phase 4 (3+ months) - Algorithms and Advanced Features

14. SA-3: Create algorithms module
15. SA-4: Expand Ansatz library
16. RE-3: Symbolic resource estimation
17. CM-3: Simplify Transpiler
18. CI-4: Control flow organization
19. BC-3: QuTiP support (low priority)
20. DT-3: Strengthen integration tests

---

Key Files

File	Role
`qamomile/core/`	Scheduled for deletion, migrate to optimization/
`qamomile/optimization/`	Destination for optimization-related code
`qamomile/circuit/ir/graph/graph.py`	Resource estimation (estimate())
`qamomile/circuit/transpiler/gate_emitter.py`	GateEmitter protocol
`qamomile/circuit/observable/estimator.py`	Expectation value estimation protocol
`qamomile/circuit/stdlib/`	Basic quantum operations & FTQC components
`qamomile/cudaq/`	CUDA-Q backend (high priority)
`qamomile/quri_parts/transpiler.py`	New API reference implementation

---

Total Issues: 24

Category	Issue Count	High Priority
Code Migration & Cleanup	3	CM-1, CM-2
Core Infrastructure	4	CI-1, CI-2, CI-3
Backend Completion	4	BC-1
stdlib & Algorithms	4	SA-1, SA-2
Resource Estimation	3	RE-1, RE-2
Documentation & Testing	4	DT-1, DT-2, DT-3

---

Verification Methods

1. Unit tests: `uv run pytest tests/`
2. Documentation tests: `uv run pytest -m docs -v`
3. Type checking: `uv run zuban qamomile/`
4. Lint: `uv run ruff check qamomile/`
5. Documentation build: `cd docs && make build`