qcmet.benchmarks.BaseBenchmark

class qcmet.benchmarks.BaseBenchmark(name, qubits, save_path=None)

Abstract base class for quantum computing benchmarks.

This class defines the structure for benchmarks that generate quantum circuits, run them on quantum devices or simulators, analyze the results, and optionally plot them.

Subclasses must implement:

• _generate_circuits

• _analyze

Optionally, subclasses can implement:

• _plot

name

Name of the benchmark.

Type:

str

qubits

List of qubit indices.

Type:

int | List[int]

config

Configuration dictionary for benchmark-specific settings.

Type:

dict

save_enabled

Whether saving is enabled.

Type:

bool

file_manager

Manages file saving and loading.

Type:

FileManager | None

__init__(name, qubits, save_path=None)

Define constructor for benchmarks.

Parameters:

• name (str) – This is the name of the benchmark

• qubits (int | List[int]) – The number of qubits as either a list of qubit indices or int specifying number of qubits. If int, qubit indices default to 0-indexed list.

• save_path (str | Path | FileManager, optional) – Path to save benchmark outputs. Defaults to None.

Raises:

ValueError – If an invalid parameter is set, such as negative number of qubits

Methods

__init__(name, qubits[, save_path])	Define constructor for benchmarks.
analyze()	Analyze measurements to return benchmark results.
generate_circuits()	Generate benchmark circuits, user facing.
has_plotting()	Check if _plot function is implemented in benchmark.
load_circuit_measurements(circuit_measurements)	Load measurement counts into the experiment_data DataFrame.
measurements_to_probabilities()	Convert raw measurement counts to normalized probabilities.
plot([axes])	Plot benchmark result, user facing.
run([device, num_shots, max_circs_per_job])	Run benchmark.
save()	Save benchmark current state.
set_save_path(save_path)	Set benchmark save path if not set in class constructor.

Attributes

circuits	Gets all benchmark circuits.
experiment_data	Getter for experiment_data dataframe.
num_qubits	Number of qubits in this benchmark.

has_plotting()

Check if _plot function is implemented in benchmark.

Returns:

True if benchmark class has a plot function

Return type:

Bool

plot(axes=None)

Plot benchmark result, user facing.

Parameters:

axes (matplotlib.axes._axes.Axes, optional) – Plot will use axes if provided. Defaults to None.

property experiment_data

Getter for experiment_data dataframe.

Returns:

a dataframe where each row represents a circuit and all metadata represented to the circuit

Return type:

pd.Dataframe

property num_qubits: int

Number of qubits in this benchmark.

Always returns the current length of self.qubits, so it stays in sync if self.qubits is ever modified.

property circuits: List[QuantumCircuit]

Gets all benchmark circuits.

Returns:

list of all benchmark circuits.

Return type:

List[QuantumCircuit]

run(device=None, num_shots=1024, max_circs_per_job=None, **kwargs)

Run benchmark.

If no device is provided, run_offline is executed which provides all necessary data to run benchmark offline in a saved directory.

Parameters:

• device (BaseDevice, optional) – Device to run benchmark on. Defaults to None.

• num_shots (int, optional) – Number of measurements per circuit. Defaults to 1024.

• max_circs_per_job (int, optional) – Maximum number of circuits to be submitted per job. This is for when

• None. (benchmark requires more circuits than hardware can run in one job. Defaults to)

• **kwargs (Dict[str, any]) – Optional keyword arguments passed to device in _runtime_params.

Raises:

MeasurementOutcomesExistError – When benchmark already has measurements

generate_circuits()

Generate benchmark circuits, user facing.

The benchmark circuits are routed based on user-defined qubit indices (if specified).

Return type:

None

measurements_to_probabilities()

Convert raw measurement counts to normalized probabilities.

Takes measurement results from quantum circuits stored in the experiment_data[“circuit_measurements”] DataFrame column and computes the corresponding probability for each outcome. Probabilities are calculated by dividing each count by the total number of shots.

The normalized results are stored in a new column experiment_data[“meas_prob”].

Returns:

The method modifies the experiment_data in place.

Return type:

None

load_circuit_measurements(circuit_measurements)

Load measurement counts into the experiment_data DataFrame.

Supports two modes: - Multiple circuits: pass a list of dicts/Counters, one per row. - Single circuit: pass a single dict/Counter if the DataFrame has exactly one row.

The method assigns the measurement results to the ‘circuit_measurements’ column.

Parameters:

• circuit_measurements (Union[List[Union[Dict[str, int], Counter]], Dict[str, int], Counter]) – Either

• Counter (- A single dict or)

• experiment_data. (length must equal the number of rows in)

• Counter

• row. (only valid when experiment_data has exactly one)

Raises:

ValueError – If the input type or length does not match the DataFrame shape.

Return type:

None

analyze()

Analyze measurements to return benchmark results.

Returns:

results of benchmark in dictionary format

Return type:

Dict

save()

Save benchmark current state.

Raises:

ValueError – If no save path is set

set_save_path(save_path)

Set benchmark save path if not set in class constructor.

Parameters:

save_path (str | Path) – path to create bencmark output save folder