“Run the circuit” can mean several different things
The preceding lessons constructed chemical models, trial states, and quantum circuits. We now reach an execution boundary. Generating a gate description, compiling it into QIR, simulating it on a classical computer, and submitting it to a quantum device are different operations with different prerequisites and evidence.
A successful classical simulation can validate the action of a small circuit. It does not demonstrate that a physical processor can run it reliably, that it is faster than the best classical chemistry method, or that its chemical model predicts experiment. A resource estimate is another kind of result again: a conditional calculation of cost under specified assumptions, not an executed experiment.
Our main scientific record remains neutral singlet N₂ at 1.85 Å in the selected active model. The external-framework examples below use other small molecules and models; none supplies new nitrogen results. This lesson is based entirely on source and test inspection. No imports, compilations, simulations, device jobs, credentials, or network provider operations are performed here.
The executor contract
The CircuitExecutor interface takes a Circuit, a shot count, and an optional QuantumErrorProfile, and returns CircuitExecutorData. The family’s default registered implementation is qdk_sparse_state_simulator. The other native adapter is qdk_full_state_simulator; the optional Qiskit Aer plugin registers qiskit_aer_simulator.
“Native” here means the adapter is maintained in QDK Chemistry. The actual QDK language runtime/simulator or Qiskit Aer numerical engine is an external dependency. This repository does not contain a newly written full-state simulator merely because it exposes a class with that name.
A shot executes a program’s preparation, gates, measurement, and result logic under its backend contract. The ordinary executor interface returns sampled measurement data, not a dense wavefunction. Supplying a state-preparation circuit that returns Unit is not the same as supplying a program returning the Result array expected by the native histogram adapter. Measurement wrappers, QPE builders, and Hadamard-test builders provide explicit readout programs for that reason. There is no general rule that every Circuit automatically measures all its qubits at the end.
The common abstract executor interface does not enforce every possible positivity/type constraint on shots; concrete paths delegate important validation to their backend or enclosing algorithm. Use a positive integer and check the returned counts rather than assume successful construction establishes a valid measurement request.
Dense, sparse, and structured classical simulation
A generic pure state of q qubits has complex amplitudes. A state-vector simulator stores and updates those amplitudes. In complex128 arithmetic, just the raw vector uses bytes. At q=30 that is 16 GiB, before indices, work arrays, compiled circuits, or parallelization. This is illustrative memory arithmetic, not a measurement of a backend in this session.
A sparse-state simulator stores supported basis states rather than every basis index. It can be efficient for circuits whose state remains sparse in that basis. Sparsity is not preserved by all useful gates: H on many independent qubits can turn one supported bitstring into exponentially many, and interacting evolution can quickly spread support. A sparse input CI list does not guarantee a sparse state throughout QPE or time evolution.
A density matrix represents mixed states, for example after averaging over unknown noise outcomes. It has complex entries; a 15-qubit dense density matrix already has the same raw-entry count as a 30-qubit statevector. Noise can also be simulated through sampled trajectories rather than explicitly storing that matrix, depending on the external backend. The QDK Chemistry adapter does not prescribe all those internal numerical choices.
Supplementary · Analytical illustration
- Pure vector: 16×2ⁿ bytes
- Density matrix: 16×4ⁿ bytes
Dotted reference: 16 GiB: vector n = 30, density matrix n = 15.
Model and source. Raw complex128 arrays only: pure vector uses 16×2ⁿ bytes; dense density matrix uses 16×4ⁿ bytes. GiB = 2³⁰ bytes. No workspace, indexing, tensor-network/sparse compression, or distributed overhead is included.
How to read this. A 30-qubit vector and a 15-qubit density matrix both need 16 GiB just for their entries. A sparse input does not ensure sparse evolution.
Inspect plotted values
Selected coordinates from the declared analytical or teaching data. Continuous curves are sampled for drawing; discrete outcomes remain discrete.
| Series | x | y |
|---|---|---|
| Pure vector: 16×2ⁿ bytes | 0 | 1.4901e-8 |
| Pure vector: 16×2ⁿ bytes | 10 | 1.5259e-5 |
| Pure vector: 16×2ⁿ bytes | 20 | 0.015625 |
| Pure vector: 16×2ⁿ bytes | 30 | 16 |
| Pure vector: 16×2ⁿ bytes | 40 | 16,384 |
| Density matrix: 16×4ⁿ bytes | 0 | 1.4901e-8 |
| Density matrix: 16×4ⁿ bytes | 5 | 1.5259e-5 |
| Density matrix: 16×4ⁿ bytes | 10 | 0.015625 |
| Density matrix: 16×4ⁿ bytes | 15 | 16 |
| Density matrix: 16×4ⁿ bytes | 20 | 16,384 |
A stabilizer simulation tracks a structured description of states reachable through Clifford operations and compatible measurements/noise. Clifford gates map Pauli operators to Pauli operators under conjugation. This permits efficient classical methods for a special circuit family, not a way to cheaply execute arbitrary non-Clifford chemistry rotations. A method option named clifford is not permission to approximate unsupported rotations silently.
Tensor-network and matrix-product-state methods exploit limited entanglement or suitable contraction structure. Their intermediate dimensions can grow strongly with entanglement, and truncation can introduce approximation when used. They are not universally efficient alternatives to statevectors. We discuss them because the Aer adapter accepts those method names, not because this repository implements or guarantees every external method’s availability on the current machine.
The two QDK adapters take different paths
The native adapters both default to seed 42. Full-state execution has setting type="cpu", with accepted values cpu, gpu, and clifford. The constructor argument is named simulator_type, while the registry setting is type. Accepted strings are configuration options, not evidence that a GPU or every required backend feature is installed.
qdk_full_state_simulator calls circuit.get_qir(), converts a supplied error profile to QDK NoiseConfig, and calls external run_qir with shots, noise, seed, and type. Existing QIR can be used directly; a Q# factory may first compile; QASM-only input uses the Circuit conversion path described in Lesson 17. A rendered native circuit object alone does not necessarily supply executable QIR.
qdk_sparse_state_simulator first checks for Q# factory data. If present, it executes the factory in its owning QDK context with the ordered classical parameter values. This direct interpreter path can support a program that the current QIR compiler cannot lower. Without a factory, it obtains QASM and calls the external OpenQASM sparse-state execution function. A QIR-only Circuit therefore does not automatically enter a native sparse-QIR path: obtaining QASM may require the optional Qiskit conversion machinery.
The presence of both QASM and a factory is consequently meaningful. Different executors can prefer different stored representations. The Circuit object does not prove those descriptions are semantically identical. Keep them produced from the same source, with controlled phases, output ordering, and target profiles validated.
A concrete current example is unary phase estimation. Its orchestration permits only qdk_sparse_state_simulator because the recursive higher-order Q# schedule does not lower to QIR in the other path. That is an implementation restriction, not a general theorem that unary QPE cannot be represented as a circuit. Conversely, a QIR-oriented full-state executor cannot execute that workflow merely because both are labeled QDK.
What seeds do and do not establish
The native adapters pass the configured seed to each backend call. A seed makes pseudorandom choices reproducible under compatible software/runtime conditions. It does not eliminate quantum sampling variation as a statistical concept, prove independent trials, or make a noisy model experimentally calibrated.
Reusing the same seed for repeated builds/executions can repeat a random sequence rather than supply independent evidence. Distinct seeds are useful for reproducibility studies, but backend/version changes can still change random-number consumption and outputs. The Aer adapter supplies seed_simulator; its ordinary transpilation calls do not set a separate seed_transpiler. Do not interpret one seed field as guaranteeing every compilation and simulation choice is identical across runs.
Raw counts also depend on what the circuit returns. The QDK executor tests prepare Bell-style circuits and a deterministic X on qubit 0, checking both histogram labels and raw results. These are examples of portable action/ordering checks. They are not tests run by this writer and not measured machine performance.
Qiskit Aer: simulator choices and fake devices
The optional QiskitAerSimulator first calls Circuit.get_qiskit_circuit(). Its defaults are method="statevector", seed=42, transpile_optimization_level=0, empty device_backend_name, and empty pre/post-transpilation pass lists.
Accepted method strings are automatic, statevector, density_matrix, stabilizer, extended_stabilizer, matrix_product_state, unitary, superop, and tensor_network. These are forwarded to Aer. Extended stabilizer techniques concern non-Clifford extensions of stabilizer simulation; a unitary method represents an entire circuit matrix, while a superoperator represents a channel on density matrices. Their storage can scale even more severely than a statevector. Some methods require particular builds/devices or are incompatible with measurement/noise features. The adapter does not expose every Aer option or prove that each method fits its own counts-returning path: a method intended to save a unitary is not automatically useful with the unconditional get_counts() call.
With a QuantumErrorProfile, the adapter builds an Aer NoiseModel and transpiles to its basis gates. Without a profile, it still transpiles using the default basis gates from an empty Aer NoiseModel. Optional pre/post pass names must come from the repository’s transpiler module; unknown names raise. Those passes can be state-specific or preserve only an overall phase, so they must not be used blindly before a later coherent control. Transpilation changes which gates receive gate-keyed noise and can change cost/noise behavior even if noiseless unitary action is preserved.
device_backend_name refers only to a fake backend, such as fake_manila. The adapter constructs a Fake...V2 class from qiskit_ibm_runtime.fake_provider, builds Aer from it, and transpiles against that synthetic device description. The value must start with fake_; an unknown class or missing optional dependency raises. An explicit noise profile and a fake-device name are mutually exclusive.
The plugin registration loads the IBM fake-provider module but does not register a live IBM hardware executor. The inspected executor never creates an authenticated runtime service, submits a remote quantum job, or waits in a real hardware queue. “Device backend simulation” in the tests is still classical Aer execution. A real-device integration would need a separately supported submission/authentication/result contract; none was contacted or assumed here.
After execution, Aer returns its count dictionary and a raw Aer result in CircuitExecutorData. It does not populate QDK-style loss bitstrings. The Aer adapter tests check simple measurement circuits, noise-profile use, and fake-device validation. A passing small example is not evidence that all methods, dynamic circuits, or devices work interchangeably.
Noise is a quantum process, not just corrupted output text
A quantum channel describes how a state changes when information may pass to an environment or an unobserved random process. Gate noise can alter amplitudes and coherence before measurement; it is not generally equivalent to flipping a bit in the final histogram.
The chemistry-side class is QuantumErrorProfile. It stores a name, description, and a mapping from supported gate names to error-type/rate entries. The currently exposed error types are only depolarizing_error and qubit_loss. There are no profile entries here for arbitrary amplitude damping, coherent overrotation, general Kraus channels, or independently parameterized X/Y/Z error probabilities. An external simulator might support more, but this adapter does not expose that whole catalog.
Depolarizing noise mixes the state toward a fully mixed state on the affected gate subsystem. One common convention is
where is a normalized density matrix and d is subsystem dimension. Another convention describes a total probability of a nonidentity Pauli error. Those parameters differ by normalization factors. The chemistry adapters forward the supplied rate to external QDK set_depolarizing or Aer depolarizing_error without an independently derived cross-library calibration. Verify the relevant external version’s convention before comparing equal numeric rates as equal physical noise. The equation is explanatory, not a claim that this source review inspected all backend channel internals.
Qubit loss means the qubit’s measurement outcome is undefined, not simply zero or one with a higher error probability. A lost shot is tracked separately by the QDK adapter. How loss and depolarization compose in time is a simulator contract; the order of keys in the Python dictionary does not establish a universal physical channel-ordering model.
The profile constructor normalizes supported gate/error names and checks that rates are numeric. It does not enforce a complete finite probability interval at construction. Invalid, negative, non-finite, or otherwise unphysical rates may fail later or have backend-dependent behavior; supply valid probabilities and check external constraints instead of treating construction as certification. The default profile has no errors, not a realistic device calibration.
Gate classes include one-, two-, and three-qubit operations. Profile basis_gates excludes measurement/reset-like entries. Converting to QDK rewrites names such as sdg to s_adj, tdg to t_adj, sxdg to sx_adj, and measure to mresetz; unavailable gate attributes raise. For each gate it sets depolarizing noise and/or loss on the external configuration.
The Aer noise adapter supports depolarizing errors on recognized gate arities and explicitly rejects qubit loss. It uses a uniform all-qubit error for each selected gate type, not arbitrary location-specific hardware calibration. A supported gate-name enum does not guarantee every backend accepts that gate in its noise basis. Existing noise tests and Aer-noise tests check these conversions and rejections.
Synthetic gate errors are not the logical failure model of an error-correcting code. They also do not by themselves describe drift, leakage, correlated faults, calibration changes, or chemistry-model error. Later QEC/resource estimation needs its own explicitly justified assumptions.
Results, loss, ordering, and normalization
CircuitExecutorData holds bitstring_counts, total_shots, executor, optional loss_bitstrings, and an in-memory raw executor metadata object. QDK fills that raw object with per-shot results; Aer fills it with its backend result.
The QDK conversion recognizes only string forms Zero, One, and Loss. It reverses each returned result sequence into the standardized histogram string, placing the first returned measurement at the right. Any shot containing Loss goes into the separate dictionary, with L at the relevant position. Unexpected result labels raise rather than being silently treated as zero.
For example, raw [One, Zero] becomes 01. A Bell circuit returning the two system measurements should yield only 00/11 in an ideal noiseless model. Those conventions are pinned by tests. But a returned measurement sequence need not list every allocated qubit: identity positions may be omitted by the measurement wrapper, QPE returns phase bits only, and other programs can choose their result order. Do not equate string length with peak circuit width or the underlying electron-mode count.
A dense state dump has a separate amplitude-index convention determined by its simulator and wire ordering. Histogram reversal is not a universal recipe for converting every statevector. The course’s earlier Q# dump, Pauli-label, and determinant-order distinctions still apply. The common executor output is sampled counts, not an automatically available full state dump.
Aer counts are forwarded as Aer returns them. Multiple classical registers can introduce formatting conventions such as spaces that downstream chemistry parsers may not accept as a binary integer. The adapter does not flatten every possible output schema into the native Result-array format. Use a tested measurement layout and explicit parsing conventions.
In normal QDK noisy runs, clean plus loss counts account for total shots. Clean counts alone can be smaller than total_shots, or empty. Normalizing only surviving shots conditions on survival and may bias an observable if loss depends on the state. The expectation estimator currently consumes clean counts only and errors on no clean counts; iterative QPE’s majority comparison can instead choose zero when neither result is present. These are consumer-specific behaviors, not a universal successful fallback.
Serialization preserves basic counts, executor name, total shots, and loss dictionaries, but does not generally serialize the arbitrary raw metadata object. Keep compiled program identity, model/basis/sector, profile, seed, versions, and rejected-shot accounting separately if the result must support scientific review. More digits in a count-derived energy cannot compensate for missing provenance.
Profiles, readout, and ancillas must fit the backend
Mid-circuit measurements, reset, and feedback need a compatible target profile and importer. The current shared Q# context defaults to Adaptive_RIF, while the QASM-only Circuit.get_qir fallback requests Base. The QIR-to-Qiskit converter supports specific direct-result branch structures, not arbitrary classical control flow or loops. A program that runs directly in the sparse interpreter may fail QIR lowering or a subsequent framework conversion.
Similarly, a callable that expects a preinitialized trailing phase-gradient register cannot be executed on only its system width. Some standalone factories initialize their own gradient; their resource behavior differs from a composed shared-gradient callable. Circuit.num_qubits is an argument-width declaration, not all internal scratch or physical qubits. A diagram that prunes apparently classical wires does not establish a reduced executable circuit.
A serialized factory-derived Circuit commonly retains QIR but not the live Q# callable or factory. It may remain executable through one backend while no longer supporting native composition or unary interpretation. “It serialized successfully” does not mean all of its prior capabilities survived.
OpenFermion: operator interoperability, not hardware execution
The OpenFermion example constructs a LiH active Hamiltonian, maps it through the optional plugin, converts the QDK Pauli operator to an OpenFermion operator, diagonalizes a small matrix, and converts it back. This is an operator/data handoff and classical reference calculation, not a circuit-execution backend.
The conversion routines preserve complex Pauli coefficients and translate explicit qubit indices into rightmost-qubit-zero dense labels. The native molecular integral convention is chemist order; the plugin conversion performs the required tensor permutation and one-half scaling when constructing OpenFermion interaction tensors. The plugin maps in blocked spin order and removes the core scalar from its ordinary mapped output to follow QDK’s active-operator convention.
Third-party mapping dispatch uses MajoranaMapping.base_encoding by name, not a supplied custom table. Its output width can also be inferred from surviving nonidentity terms; zero/identity-only or trailing-unused-mode cases need explicit attention. Use active matrix dimension rather than an unrelated full-MO count when establishing the intended mapping size. A round-trip coefficient check does not prove correct electron sector or total-energy reconstruction.
The sample test compares full qubit-matrix ground energies from matching mapped operators. That establishes a representation comparison for its fixture, not a general fixed-electron-sector chemistry reference. The example’s active operator ground value is not automatically the SCF total energy printed elsewhere; the omitted scalar and physical sector must be handled explicitly.
PennyLane and exact-evolution examples need their own validation
The PennyLane example demonstrates an external QNode workflow: construct chemistry data, form a PennyLane fermionic/Pauli observable, place phase/system wires, apply controlled qml.evolve, inverse QFT, and inspect qml.probs on default.qubit with shots=None. That final object is an analytic simulator probability array, not finite-shot experimental counts or the registered CircuitExecutorData path. PennyLane is an example dependency, not a registered chemistry executor in the inspected plugin catalog.
Its “no Trotter” intention means using exact matrix-based evolution for a small represented operator, not an efficient arbitrary large Hamiltonian oracle. Classical matrix construction and simulation still scale exponentially. More importantly, the present example should not be copied as a validated universal adapter: it stacks the pair returned by get_one_body_integrals() rather than explicitly selecting the expected two-dimensional spin block, includes core energy in the external fermionic constant and later adds core again, and chooses among sign/period candidates by closeness to a known CASCI reference. These are source-visible interpretation/conversion hazards. The sample test checks process completion when dependencies are present; it does not assert a complete correct energy/sector invariant. We have not run it or changed it.
The Qiskit no-Trotter example similarly uses MatrixExponential synthesis as a small reference route rather than a general registered fast simulator. It has local feedback and energy-decoding helpers, so their sign convention must be checked against the actual synthesized exponential rather than assumed identical to the native IQPE contract. Reference-guided alias selection can hide a sign or shift discrepancy; it is not a method for discovering an unknown energy branch.
These examples illustrate useful interoperability directions, but examples, smoke tests, adapter interfaces, and scientifically validated end-to-end results are different evidence levels. Prefer small analytic operator/action checks, explicit offsets, and nonpalindromic bit-order tests before transferring an external framework’s result into the main nitrogen record.
RDKit begins at a different boundary
The RDKit example starts with a molecular graph specified by SMILES, a compact notation for chemical connectivity. It adds hydrogens, embeds three-dimensional coordinates, and applies the UFF molecular-mechanics force field. A conformer is one spatial arrangement consistent with molecular connectivity; obtaining one does not prove it is the global minimum or relevant experimental state.
The converter extracts atomic symbols and coordinates, multiplying Angstrom coordinates by ANGSTROM_TO_BOHR before constructing a QDK Structure. Charge and spin multiplicity are separately supplied to the SCF calculation. The helper does not infer all electronic-state information, basis quality, solvation, or a converged quantum-chemical geometry from the RDKit object.
UFF is a parameterized force-field approximation, not the ab-initio energy surface used by the later SCF stage. The source explicitly warns that it may not yield high-quality geometries. The RDKit test uses a particular approximate water geometry and SCF reference as a regression check. It does not establish general conformer accuracy, molecular stability, or chemistry outside that fixture.
PySCF and geomeTRIC, discussed earlier, occupy still other boundaries: electronic-structure methods and geometry optimization. Their optional adapters retain their method-specific limitations—for example, the PySCF SCF adapter rejects any directly supplied BasisSet object, not merely a custom basis. Interoperability is explicit conversion plus a supported contract, not automatic interchangeability of every object named molecule, basis, state, or circuit.
Dependency and platform boundaries are part of reproducibility
The pinned python/pyproject.toml requires Python at least 3.10 and QDK at least 1.31.0, with NumPy/SciPy and other core dependencies. Optional extras separately cover OpenFermion, Qiskit, NetworkX, chemistry plugins, and QRE. Registration depends on optional library discovery; this source review does not imply those packages are installed.
The metadata contains real platform/version exclusions: PySCF in the plugins extra excludes Windows; OpenFermion is conditioned on Python below 3.14; much of the Qiskit/PennyLane stack is excluded on Windows ARM64; Aer has an additional Python/platform wheel condition; RDKit testing also excludes Windows ARM64. Such package constraints are not scientific restrictions, but they affect whether a proposed workflow can actually be reproduced. No dependency was installed or restored during this authoring task.
Library/runtime version changes can affect compilation, noise conventions, gate sets, random streams, and reference snapshots. Preserve versions alongside results, and prefer portable physical/mathematical invariants when deciding whether a change is acceptable.
A minimal measurement program with an explicit consumer
This unexecuted example follows the measured-QASM shape used in the executor tests:
from qdk_chemistry.algorithms import create
from qdk_chemistry.data import Circuit, QuantumErrorProfile
program = Circuit(qasm="""
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
bit[2] c;
h q[0];
cx q[0], q[1];
c[0] = measure q[0];
c[1] = measure q[1];
""", num_qubits=2)
profile = QuantumErrorProfile(errors={"cx": {"depolarizing_error": 0.001}})
executor = create("circuit_executor", "qdk_full_state_simulator", type="cpu", seed=42)
# Authorized execution: result = executor.run(program, shots=1000, noise=profile)
The error rate and shot count are illustrative. The circuit explicitly defines readout rather than assuming all qubits are sampled automatically. Its histogram would describe this Bell experiment, not an electronic energy. A noisy histogram is evidence about the supplied synthetic channel model, not about a particular device.
For a trustworthy execution record, retain the exact circuit/representation and its origin, target profile, backend and versions, seed policy, shot request, returned clean/loss counts, measurement ordering, compiler options, noise assumptions, and full chemical or model provenance. Check what was actually executed rather than relying on a class name or an attractive diagram.
We can now interpret an execution result without confusing it with a physical quantum demonstration. The next lesson assembles the entire evidence chain: which energy was computed, which approximations and uncertainties remain, and what a scientific team can responsibly conclude before asking how much a fault-tolerant implementation would cost.