Executing Circuits and Reading Results
Circuit.execute() performs pure-state simulation and returns an ExecutionResult. The result object provides the final state, probability queries, sampling, expectation values, and results from measurement instructions in the circuit.
from unitarylab import Circuit
qc = Circuit(2)
qc.h(0)
qc.cx(0, 1)
result = qc.execute()execute(initial_state=None, backend="torch", device="cpu",
dtype=np.complex128, shots=1, seed=42,
backend_options=None)ExecutionResult
state: final state vector; for multiple shots, this is the state from the last shot.backend_state: original backend state before any device-to-host copy.probabilities,probability(), andmarginal_probabilities(): full, individual, and marginal probabilities.sample(): computational-basis sampling without collapsing the state.expectation(): expectation value of an observable.measure(): projective measurement that collapses the internally stored state.counts: classical bit-string counts accumulated over all shots.classical_results_mapandclassical_registers: classical measurement results from the last shot.
print(result.state)
print(result.probabilities)
print(result.expectation("ZZ", qubits=(0, 1)))Characters in a Pauli string correspond to qubits in the order given by qubits. Probability bit strings use little-endian ordering, with qubit 0 at the rightmost position.
Probabilities, sampling, and expectation values
print(result.probability("00"))
print(result.marginal_probabilities(qubits=[0], threshold=1e-12))
print(result.sample(shots=20, qubits=[0, 1], seed=7))
print(result.expectation("Z", qubits=[0]))| Interface | Changes state | Return value |
|---|---|---|
probability() | No | Probability of the specified bit string |
marginal_probabilities() | No | Marginal distribution for selected qubits |
sample() | No | List of bit strings drawn from the final distribution |
expectation() | No | Expectation value of a Pauli string or observable |
measure() | Yes | Projective result; collapses the state held by the result object |
When querying a subset of qubits, the bit-string length must equal the number of selected qubits. A Pauli string must likewise have the same length as its target-qubit selection.
Circuit measurement and multiple shots
qc.measure([0, 1], [0, 1])
result = qc.execute(shots=1000, seed=None)
print(result.counts) # Only 00 and 11 occur; exact counts vary.Circuits without measurement perform one unitary evolution. Circuits with terminal-only measurement reuse a single unitary evolution to generate the measurement results for each shot. Dynamic circuits with mid-circuit measurement execute independently for every shot. For shots > 1, state and classical_results_map refer to the final sample, while counts aggregates every shot. Unmeasured classical bits are represented by # in count keys, with the highest classical bit on the left. result.measure() collapses the state. Use marginal_probabilities() or sample() when only a distribution query is required.
If the circuit contains no Circuit.measure() instructions, counts and the classical-register results do not represent an implicit full-state measurement. Use sample() to obtain computational-basis samples instead.
For backend selection and the complete execution parameters, see Execution Backends and Parameters.