A reproducible quantum project is less about choosing a fashionable SDK and more about controlling change: isolate dependencies, test circuits locally, record assumptions, and treat hardware execution as a measured experiment. This starter kit gives software engineers a reusable folder layout for Qiskit, Cirq, or PennyLane projects, a workflow for simulator and hardware runs, and a simple method for estimating execution effort, cost, and maintenance risk before committing to a backend.
Overview
Quantum code has two kinds of variability that conventional applications usually separate more cleanly. The first is software variability: SDK interfaces, transpilers, serialization formats, plugins, and cloud-provider clients change over time. The second is experimental variability: measurement shots, device noise, queue time, calibration, and backend constraints affect results even when the source code is unchanged.
A good quantum development workflow makes both visible. Keep circuit construction independent from backend execution, make configuration explicit, save raw results alongside derived metrics, and test small deterministic cases before running expensive or slow jobs. This approach works for a Qiskit starter project, a Cirq project template, or a PennyLane starter kit because it relies on engineering boundaries rather than framework-specific assumptions.
Use this layout as a starting point:
quantum-project/
├── README.md
├── pyproject.toml # or another pinned environment file
├── src/
│ └── quantum_project/
│ ├── circuits.py # circuit factories and ansatz definitions
│ ├── algorithms.py # VQE, QAOA, Grover, or QML logic
│ ├── backends.py # simulator and hardware adapters
│ ├── metrics.py # energy, success rate, loss, and error metrics
│ └── config.py
├── tests/
│ ├── test_circuits.py
│ ├── test_small_instances.py
│ └── test_serialization.py
├── notebooks/
│ └── experiment.ipynb
├── experiments/
│ ├── configs/
│ └── results/
└── .github/workflows/ci.yml
Keep notebooks for exploration and explanation, but place reusable logic under src/. A notebook should call a tested function, not contain the only copy of your circuit or optimizer loop.
How to estimate
Before selecting a backend, estimate the workload in layers. The goal is not to predict a perfectly accurate bill or runtime; it is to decide whether the next experiment belongs on a local simulator, a managed simulator, or real quantum hardware.
- Estimate circuit evaluations. For a variational algorithm, multiply the number of optimizer iterations by the number of expectation-value evaluations per iteration. If an iteration evaluates several Hamiltonian terms, count each term or grouped measurement setting according to the execution model you use.
- Estimate shots. Multiply circuit evaluations by shots per circuit. For example, 40 circuit evaluations at 1,000 shots each implies 40,000 sampled measurements before retries or calibration overhead.
- Estimate hardware submissions. A provider may batch several circuits into one job, but the exact behavior depends on the service and workflow. Track both logical circuits and submitted jobs in your experiment metadata.
- Estimate classical work. Include parameter updates, data preprocessing, result aggregation, and post-processing. In QML, preprocessing and repeated model evaluation can dominate the quantum portion of a small experiment.
- Estimate maintenance effort. Assign a review checkpoint to every external dependency, backend name, authentication method, serialization format, and import path. A project with a short circuit can still be costly to maintain if its integration points are scattered.
A practical planning formula is:
total_shots = circuit_evaluations × shots_per_circuit
expected_submissions = ceil(total_circuits / circuits_per_job)
experiment_load = total_shots + retry_budget + validation_runs
Use a conservative retry budget when running on hardware. The value is an explicit assumption, not a universal constant. Record it in a configuration file so that two experiment reports can be compared honestly.
For VQE, estimate the number of terms in the Hamiltonian and the number of parameter updates. For QAOA, include the cost of evaluating the objective for each candidate parameter vector and each depth value you plan to compare. For Grover-style demonstrations, focus less on optimization iterations and more on qubit count, oracle construction, transpiled depth, and the number of shots needed to distinguish the marked state from sampling variation. For a minimal QML experiment, count training epochs, batches, circuit evaluations per batch, and validation evaluations separately.
Inputs and assumptions
Place the assumptions that affect reproducibility in a small, reviewable configuration object. The exact syntax differs between Qiskit, Cirq, and PennyLane, but the fields should be recognizable:
project:
seed: 1234
problem_size: 4
shots: 1000
optimizer_iterations: 50
repetitions: 3
execution_mode: simulator
backend: local_default
transpilation_or_compilation_level: documented_default
noise_model: none
retry_budget: 0
save_raw_results: true
Separate inputs into four groups:
- Problem inputs: qubit count, graph edges, Hamiltonian terms, feature vectors, labels, and ansatz depth.
- Execution inputs: shots, batching behavior, simulator or hardware target, noise model, measurement settings, and timeout policy.
- Algorithm inputs: initial parameters, optimizer, stopping rule, number of restarts, and random seed.
- Reporting inputs: metrics, confidence summaries, raw-result retention, circuit diagrams, and software versions.
Do not hide backend-specific behavior inside algorithm code. Instead, expose a narrow adapter such as run_circuit(circuit, parameters, execution_config). The adapter can translate the common request into Qiskit, Cirq, or PennyLane operations while the algorithm remains testable with a fake runner or deterministic simulator.
Pin direct dependencies for a reproducible project and review transitive dependencies during a scheduled audit. Avoid claiming that one import path or backend identifier will remain stable indefinitely. Framework documentation and release notes should be treated as part of the project’s maintenance inputs.
For circuit correctness, test properties rather than implementation details where possible. Examples include the number of qubits, expected measurement keys, conservation of a known quantity, and agreement with a small hand-checked result. Add serialization tests if circuits, parameters, or results cross a process or storage boundary. Keep raw counts or expectation values; a final accuracy number alone is difficult to debug.
Worked examples
Example 1: a small VQE experiment
Assume a VQE prototype uses 4 Hamiltonian terms, 30 optimizer iterations, 1,000 shots per measurement circuit, and 2 independent repetitions. If every term is measured separately, the estimated circuit count is:
4 terms × 30 iterations × 2 repetitions = 240 circuit evaluations
240 × 1,000 shots = 240,000 shots
This is a planning estimate, not a provider quote. Grouping compatible measurements, changing the ansatz, early stopping, retries, or framework execution primitives can change the actual workload. Run the first version on a local simulator with a fixed seed, then validate the energy calculation against a small reference case. Only after the circuit and metric tests pass should you compare a noise model or real backend.
Example 2: a QAOA comparison
Suppose you compare depths 1 and 2, use 20 parameter updates per depth, evaluate one objective circuit per update, and repeat each configuration three times at 500 shots. The planned sampled workload is:
2 depths × 20 updates × 3 repetitions × 500 shots = 60,000 shots
Store the depth, graph instance, parameter initialization, seed, shots, backend label, and result file together. This prevents an apparently better result from being separated from the configuration that produced it. For a larger study, add a manifest file with one row per run and a status field such as planned, completed, failed, or superseded.
Example 3: a minimal QML notebook
For a binary classifier with 80 training examples, 10 epochs, a batch size of 8, and one circuit evaluation per example, the simple estimate is 100 training batches or 800 example evaluations, plus validation evaluations. If the feature map or model evaluates several measurement observables, multiply accordingly. Start with a tiny dataset and a simulator, compare against a classical baseline, and record whether the reported metric comes from training, validation, or test data. The [quantum data encoding guide](https://coqbit.com/quantum-data-encoding-methods-qml) provides useful context for choosing a feature map before you increase circuit complexity.
For framework-specific decisions, compare execution semantics rather than labels alone. The [Qiskit versus Cirq guide](https://coqbit.com/qiskit-vs-cirq) and [Qiskit, Cirq, and PennyLane comparison](https://coqbit.com/qiskit-vs-cirq-vs-pennylane) can help you map a project’s priorities to a framework. When a circuit is ready for a device, review [quantum circuit transpilation](https://coqbit.com/quantum-circuit-transpilation-guide) and the [hardware access workflow](https://coqbit.com/quantum-hardware-access-guide) before submitting jobs.
When to recalculate
Recalculate workload, compatibility, and backend assumptions whenever an input changes. The most important triggers are:
- A major Qiskit, Cirq, PennyLane, plugin, or cloud-client release changes imports, execution primitives, compilation, or result objects.
- A provider changes backend availability, access conditions, job behavior, authentication, or pricing inputs.
- You change qubit count, ansatz depth, Hamiltonian grouping, shots, optimizer iterations, batch size, or repetition count.
- You move from an ideal simulator to a noise model or real hardware.
- A CI failure, serialization failure, or changed numerical result indicates that an assumption is no longer valid.
As a routine, perform a dependency and workflow audit at least quarterly, and immediately before a hardware campaign. Refresh pinned versions, CI commands, backend lists, and code snippets after relevant SDK or provider changes. Add template variants when the recommended testing or serialization practice changes, such as canonical state save/load patterns or noise-mitigation hooks.
Before each new project, copy the template, rename the package, create a clean environment, run the smallest circuit test, and record the resulting software versions. Before each hardware run, recalculate circuit evaluations, shots, expected submissions, retry budget, and the decision rule for success. After the run, preserve raw results and update the manifest. This short loop turns the starter kit into a living engineering asset rather than a one-time code sample.
For broader algorithm selection, consult the [developer’s algorithm decision guide](https://coqbit.com/how-to-choose-a-quantum-algorithm), and use the [quantum circuit debugging guide](https://coqbit.com/quantum-circuit-debugging-guide) when simulator and hardware results diverge.