qcmet.benchmarks.CycleBenchmarking

class qcmet.benchmarks.CycleBenchmarking(g_layer, repetitions_list, qubits=None, num_random_sequences=10, full_pauli_subspace=True, subspace_size=None, seed=None, fidelity_method='ratio', save_path=None)

Benchmark class for estimating composite process fidelity using cycle benchmarking.

Cycle benchmarking characterizes the average fidelity of a repeated layered operation (called G or the “cycle”) by measuring diagonal elements of the Pauli transfer matrix (PTM) across different cycle repetition counts.

The protocol: 1. Prepare an eigenstate of a Pauli operator P 2. Apply m repetitions of the cycle G (with Pauli twirling) 3. Measure in the P basis 4. Average over many Pauli operators and random sequences 5. Extract composite process fidelity from PTM elements

config

Configuration dictionary containing: - g_layer (QuantumCircuit): The gate layer/cycle to benchmark - repetitions_list (list): List of cycle repetition counts [m1, m2, …] - num_random_sequences (int): Number of random twirled sequences per Pauli - full_pauli_subspace (bool): Whether to use full Pauli subspace - subspace_size (int): Size of Pauli subspace if not using full - fidelity_method (str): Method to calculate fidelity (‘fit’ or ‘ratio’)

Type:

dict

__init__(g_layer, repetitions_list, qubits=None, num_random_sequences=10, full_pauli_subspace=True, subspace_size=None, seed=None, fidelity_method='ratio', save_path=None)

Initialize the cycle benchmarking benchmark.

Parameters:

• g_layer (QuantumCircuit) – The repeated gate layer (cycle) to benchmark. Must be a QuantumCircuit on n qubits.

• repetitions_list (list) – List of cycle repetition counts to test. Example: [2, 4, 8, 10]

• qubits (int | List[int], optional) – The number of qubits as either a list of qubit indices or int specifying number of qubits. If no parameter given, defaults to number of qubits in g_layer.

• num_random_sequences (int, optional) – Number of random Pauli-twirled sequences per Pauli channel. Defaults to 10.

• full_pauli_subspace (bool, optional) – Whether to use the full Pauli subspace. For n qubits, this is 4^n - 1 operators (excluding all-I). Defaults to True.

• subspace_size (int, optional) – Size of random Pauli subspace if full_pauli_subspace is False. Defaults to None.

• seed (int, optional) – Seed for reproducibility. Used to create a np.random.Generator object.

• fidelity_method (str, optional) – Method to calculate composite process fidelity. Either ‘fit’ (exponential fit) or ‘ratio’ (direct ratio). Defaults to ‘ratio’.

• save_path (str | Path | FileManager | None, optional) – Directory path to save results. Defaults to None.

Raises:

• ValueError – If fidelity_method is not ‘fit’ or ‘ratio’.

• ValueError – If subspace_size is invalid when not using full subspace.

Methods

__init__(g_layer, repetitions_list[, ...])	Initialize the cycle benchmarking benchmark.
analyze()	Analyze measurements to return benchmark results.
fit_func(x, a, b, c)	Exponential decay fit function for fidelity vs cycle count.
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.

static fit_func(x, a, b, c)

Exponential decay fit function for fidelity vs cycle count.

Parameters:

• x (array) – Cycle repetition counts.

• a (float) – Amplitude parameter.

• b (float) – Decay rate parameter.

• c (float) – Baseline offset.

Returns:

Fitted fidelity values.

Return type:

array