supermarq.qcvv.base_experiment

Base experiment class and tools used across all experiments.

Attributes

ResultsT

Classes

`QCVVExperiment`	Base class for gate benchmarking experiments.
`QCVVResults`	A dataclass for storing the data and analyze results of the experiment. Requires
`Sample`	A sample circuit to use along with any data about the circuit

Module Contents

class supermarq.qcvv.base_experiment.QCVVExperiment(num_qubits: int, num_circuits: int, cycle_depths: collections.abc.Iterable[int], *, random_seed: int | numpy.random.Generator | None = None, results_cls: type[ResultsT], **kwargs: Any)

Bases: abc.ABC, Generic[ResultsT]

Base class for gate benchmarking experiments.

The interface for implementing these experiments is as follows:

First instantiate the desired experiment object

experiment = ExampleExperiment(<<args/kwargs>>)

Prepare the circuits and run the experiment on the desired target. This can either be a custom simulator or a real device name. For example:

noise_model = cirq.depolarize(p=0.01, n_qubits=1)
sim = cirq.DensityMatrixSimulator(noise=noise_model)

results = experiment.run_with_simulator(simulator=sim, <<args/kwargs>>)

Then we analyse the results. If the target was a local simulator this will be available as soon as the run_with_simulator() method has finished executing. On the other hand if a real device was accessed via Superstaq then it may take time for the data to be available from the server. The results.data_ready attribute will return True when all data has been collected and is ready to be analyzed.
```
if results.data_ready():
    results.analyze(<<args>>)
```

When implementing a new experiment, 4 methods need to be implemented:

experiment._build_circuits(): Given a number of circuits and an iterable of the
different numbers of layers to use, return a list of Sample objects that need to be sampled during the experiment.
results._analyse_results(): Analyse the experimental data and store the final
results, for example some fidelities.
results.plot_results(): Produce any relevant plots that are useful for understanding
the results of the experiment.
results.print_results(): Prints the results to the console.

run_on_device(target: str, repetitions: int = 10000, method: str | None = None, **target_options: Any) → ResultsT

Submit the circuit samples to the desired target device and store the resulting probabilities.

The set of circuits is partitioned as necessary to not exceed the maximum circuits that can be submitted to the given target device. The function then waits for the jobs to complete before saving the resulting probability distributions.

Parameters:

target – The name of a Superstaq target.
repetitions – The number of shots to sample. Defaults to 10,000.
method – Optional method to use on the Superstaq device. Defaults to None corresponding to normal running.
target_options – Optional configuration dictionary passed when submitting the job.

Returns:

The experiment results object.

run_with_callable(circuit_eval_func: collections.abc.Callable[[cirq.Circuit], dict[str | int, float]], **kwargs: Any) → ResultsT

Evaluates the probabilities for each circuit using a user provided callable function. This function should take a circuit as input and return a dictionary of probabilities for each bitstring (including states with zero probability).

Parameters:

circuit_eval_func – The custom function to use when evaluating circuit probabilities.
kwargs – Additional arguments to pass to the custom function.

Raises:

RuntimeError – If the returned probabilities dictionary keys is missing include an incorrect number of bits.
RuntimeError – If the returned probabilities dictionary values do not sum to 1.0.

Returns:

The experiment results object.

run_with_simulator(simulator: cirq.Sampler | None = None, repetitions: int = 10000) → ResultsT

Use the local simulator to sample the circuits and store the resulting probabilities.

Parameters:

simulator – A local Sampler to use. If None then the default cirq.Simulator simulator is used. Defaults to None.
repetitions – The number of shots to sample. Defaults to 10,000.

Returns:

The experiment results object.

cycle_depths: The different cycle depths to test at.

num_circuits: The number of circuits to build for each cycle depth.

property num_qubits: int: Returns: The number of qubits used in the experiment

qubits: The qubits used in the experiment.

samples: Create all the samples needed for the experiment.

class supermarq.qcvv.base_experiment.QCVVResults

Bases: abc.ABC

A dataclass for storing the data and analyze results of the experiment. Requires subclassing for each new experiment type.

analyze(plot_results: bool = True, print_results: bool = True) → None

Perform the experiment analysis and store the results in the results attribute.

Parameters:

plot_results – Whether to generate plots of the results. Defaults to True.
print_results – Whether to print the final results. Defaults to True.

abstract plot_results() → None: Plot the results of the experiment

abstract print_results() → None: Prints the key results data.

data: pandas.DataFrame | None = None: The raw data generated.

property data_ready: bool

Whether the experimental data is ready to analyse.

Raises:: RuntimeError – If their is no stored data and no Superstaq job to use to collect the results.

experiment: QCVVExperiment[QCVVResults]: Reference to the underlying experiment that generated these results experiment.

job: cirq_superstaq.Job | None = None: The associated Superstaq job (if applicable).

property num_circuits: int: Returns: The number of circuits in the experiment.

property num_qubits: int: Returns: The number of qubits in the experiment.

property samples: collections.abc.Sequence[Sample]: Returns: The number of samples used.

target: str: The target device that was used.

class supermarq.qcvv.base_experiment.Sample

A sample circuit to use along with any data about the circuit that is needed for analysis

circuit: cirq.Circuit: The raw (i.e. pre-compiled) sample circuit.

circuit_index: int: The index of the circuit. There will be D samples with matching circuit index, one for each cycle depth being measured. This index is useful for grouping results during analysis.

data: dict[str, Any]: The corresponding data about the circuit that is needed when analyzing results (e.g. cycle depth).

supermarq.qcvv.base_experiment.ResultsT