Recording Experimental Results

Circuits are provided as Circuit objects.

A circuit object contains a Results object into which experimental results should be input once the circuit is performed (or simulated). This results object is a thin wrapper for a dictionary class and is initially empty. Once data have been collected, results contain a mapping between bitstrings and the number of shots that resulted in that bitstring. A results object also contains attributes such as the timestamp of when the results were last modified, the dimension of the system, the total number of measurements (i.e. the length of the bitstrings), and the total number of shots.


The Results object supports ditstrings in general, however this document only talks about bitstrings for brevity.

Bitstrings that were not observed should not be entered. For instance, if a 2-qubit device performs 50 shots of a given circuit object, then circuit.results might have the value

>>> Results({'00': 47, '01': 2, '10': 1})

In this example, the qubits were measured as being in the \(|00\rangle\) state 47 times, in the \(|01\rangle\) state two times, and in the \(|10\rangle\) state once.


Each bitstring must have a length equal to n_sys. The order of bitstrings coincides with meas_locs, which is a list of tuples (cycle_idx, qubit_idx).

Setting Results

Results can be entered simply by setting the results property to a new dictionary, which will automatically convert to a Results object, or by updating the existing dictionary using unary addition with a compatible results-like object (refer to the following example).


The following is a functional example showing how to populate and modify the results of a Circuit object.

# Recording results example.
# Copyright 2020 Quantum Benchmark Inc.

import trueq as tq

# Initialize a 3-qubit circuit.
circuit = tq.Circuit(tq.Cycle({(0, 1):, (2,): tq.Gate.x}))

# Set the results of the circuit and print.
circuit.results = {"011": 5, "101": 15}

# Add the '111' result and print the updated results.
circuit.results["111"] = 10

# Increment the '111' result and print the updated results.
circuit.results["111"] += 5

# Add multiple results and print.
circuit.results += {"010": 1, "110": 10}

The output of the above example is:

Results({'011': 5, '101': 15})
Results({'011': 5, '101': 15, '111': 10})
Results({'011': 5, '101': 15, '111': 15})
Results({'011': 5, '101': 15, '111': 15, '010': 1, '110': 10})