Quantum Software Engineering Best Practices

Quantum Software Engineering Best Practices

Quantum software development is still maturing. Most academic quantum code is single-file scripts with no tests, no documentation, and no reproducibility. Production quantum software demands the same engineering rigor as classical software, plus additional considerations unique to the quantum domain.

Code Organization

Module Structure

Organize a quantum project like any Python package:

my_quantum_project/
├── README.md
├── requirements.txt          # Pinned versions: qiskit==1.0.2, pennylane==0.35.0
├── pyproject.toml
├── src/
│   └── myproject/
│       ├── __init__.py
│       ├── circuits/
│       │   ├── __init__.py
│       │   ├── ansatz.py     # Parameterized circuit definitions
│       │   ├── oracle.py     # Problem-specific oracles
│       │   └── primitives.py # Reusable gate blocks
│       ├── algorithms/
│       │   ├── __init__.py
│       │   ├── vqe.py        # VQE implementation
│       │   ├── qaoa.py       # QAOA implementation
│       │   └── grover.py     # Grover's search
│       ├── backend/
│       │   ├── __init__.py
│       │   ├── simulator.py  # Local simulation
│       │   └── cloud.py      # Cloud backend interface
│       └── utils/
│           ├── noise.py      # Noise models
│           ├── mitigation.py # Error mitigation
│           └── benchmarks.py # Benchmarking utilities
└── tests/
    ├── unit/
    │   ├── test_ansatz.py
    │   ├── test_vqe.py
    │   └── test_grover.py
    ├── integration/
    │   └── test_full_vqe.py
    └── conftest.py           # Shared fixtures (backend, noise model)

Separation of Concerns

This makes each layer testable independently.

Documentation

Docstrings for Quantum Functions

Quantum functions need extra documentation: what state is prepared, what the observable represents, what assumptions are made.

def hea_ansatz(n_qubits: int, params: list[float], reps: int = 1) -> QuantumCircuit:
    """Hardware-efficient ansatz (HEA) for variational algorithms.

    Constructs a parameterized circuit of the form:
    H^⊗n → [RY(θ_i)⊗n → CX chain] × reps

    Args:
        n_qubits: Number of qubits in the circuit.
        params: Variational parameters. Length must equal n_qubits * reps.
                params[layer * n_qubits + qubit] is the RY angle for
                the given qubit in the given layer.
        reps: Number of RY+CX repetitions (circuit depth).

    Returns:
        QuantumCircuit: Parameterized circuit with n_qubits qubits.

    Note:
        The HEA has no chemically motivated structure. It may miss
        important correlation effects for strongly correlated systems.
        Consider UCCSD for molecular simulation.

    Example:
        >>> qc = hea_ansatz(3, [0.1, 0.2, 0.3], reps=1)
        >>> qc.gate_count()  # 3H + 3RY + 2CX = 8 gates
        8
    """

Reproducibility

Quantum programs are stochastic, reproducibility requires careful seeding.

Circuit construction: Deterministic (no randomness, unless using random circuits).

Simulation with shots: Requires seeding the random number generator:

random.seed(42)         # Python stdlib
np.random.seed(42)      # NumPy (if used)
qiskit.utils.algorithm_globals.random_seed = 42  # Qiskit

Storing results: Always log: circuit parameters, backend name, noise model, shots, timestamp, SDK versions.

result_metadata = {
    "timestamp": datetime.utcnow().isoformat(),
    "circuit": "hea_2q_4p",
    "params": params.tolist(),
    "backend": "ibm_kyoto",
    "shots": 10000,
    "qiskit_version": qiskit.__version__,
    "energy": energy_value,
}
with open("results/vqe_run_001.json", "w") as f:
    json.dump(result_metadata, f, indent=2)

Version Control for Quantum Projects

Pin SDK versions: Qiskit, PennyLane, Cirq have frequent breaking API changes. Pin exact versions:

# requirements.txt
qiskit==1.0.2
qiskit-aer==0.14.0
pennylane==0.35.0
numpy==1.26.4
scipy==1.12.0

Commit messages for quantum code:

feat(vqe): add UCCSD ansatz with BFGS optimizer

- Implements UCCSD with singles and doubles up to n_electrons=4
- Uses L-BFGS-B optimizer with parameter-shift gradients
- Tested on H2 (F=0.9997), LiH (F=0.9923) with Aer noiseless sim
- Hardware run scheduled for ibm_kyoto (2024-04-15)

Refs: #47, DOI:10.1038/nature23879

Team Collaboration Patterns