randomized_benchmarking_seq(nseeds=1, length_vector=None, rb_pattern=None, length_multiplier=1, seed_offset=0, align_cliffs=False, interleaved_gates=None, interleaved_elem=None, is_purity=False, group_gates=None, rand_seed=None)[source]

Generate generic randomized benchmarking (RB) sequences.

  • nseeds (int) – The number of seeds. For each seed the function generates a separate list of output RB circuits.

  • length_vector (Optional[List[int]]) –

    Length vector of the RB sequence lengths. Must be in ascending order. RB sequences of increasing length grow on top of the previous sequences.

    For example:

    • length_vector = [1, 10, 20, 50, 75, 100, 125, 150, 175]

    • length_vector = None is the same as length_vector = [1, 10, 20]

  • rb_pattern (Optional[List[List[int]]]) –

    A list of the lists of integers representing the qubits indexes. For example, [[i,j],[k],...] will make simultaneous RB sequences, where there is a 2-qubit RB sequence on qbits Qi and Qj, and a 1-qubit RB sequence on qubit Qk, etc. Each qubit appers at most once. The number of qubits on which RB is done is the sum of the lists sizes.

    For example:

    • rb_pattern = [[0]] or rb_pattern = None – create a 1-qubit RB sequence on qubit Q0.

    • rb_pattern = [[0,1]] – create a 2-qubit RB sequence on qubits Q0 and Q1.

    • rb_pattern = [[2],[6,4]] – create RB sequences that are 2-qubit RB for qubits Q6 and Q4, and 1-qubit RB for qubit Q2.

  • length_multiplier (Optional[List[int]]) – An array that scales each RB sequence by the multiplier.

  • seed_offset (int) – What to start the seeds at, if we want to add more seeds later.

  • align_cliffs (bool) –

    If True adds a barrier across all qubits in the pattern after each set of group elements (not necessarily Cliffords).

    Note: the alignment considers the group multiplier.

  • interleaved_gates (Optional[List[List[str]]]) – Deprecated. Please use the interleaved_elem kwarg that supersedes it.

  • interleaved_elem (Union[List[QuantumCircuit], List[Instruction], List[Clifford], List[CNOTDihedral], None]) – A list of QuantumCircuits or gate objects or group elements that will be interleaved. It is not None only for interleaved randomized benchmarking. The lengths of the lists should be equal to the length of the lists in rb_pattern.

  • is_purity (bool) –

    True only for purity randomized benchmarking (default is False).

    Note: if is_purity = True then all patterns in rb_pattern should have the same dimension (e.g. only 1-qubit sequences, or only 2-qubit sequences), and length_multiplier = None.

  • group_gates (Optional[str]) –

    On which group (or set of gates) we perform RB (the default is the Clifford group).

    • group_gates='0' or group_gates=None or group_gates='Clifford' – Clifford group.

    • group_gates='1' or group_gates='CNOT-Dihedral' or group_gates='Non-Clifford' – CNOT-Dihedral group.

  • rand_seed (Union[int, RandomState, None]) – Optional. Set a fixed seed or generator for RNG.

Return type

(typing.List[typing.List[qiskit.circuit.quantumcircuit.QuantumCircuit]], typing.List[typing.List[int]], typing.Union[typing.List[typing.List[qiskit.circuit.quantumcircuit.QuantumCircuit]], NoneType], typing.Union[typing.List[typing.List[typing.List[qiskit.circuit.quantumcircuit.QuantumCircuit]]], NoneType], typing.Union[int, NoneType])


A tuple of different fields depending on the inputs. The different fields are:

  • circuits: list of lists of circuits for the RB sequences (a separate list for each seed).

  • xdata: the sequences lengths (with multiplier if applicable).

  • circuits_interleaved: (only if interleaved_elem is not None): list of lists of circuits for the interleaved RB sequences (a separate list for each seed).

  • circuits_purity: (only if is_purity=True): list of lists of lists of circuits for purity RB (a separate list for each seed and each of the \(3^n\) circuits).

  • npurity: (only if is_purity=True): the number of purity RB circuits (per seed) which equals to \(3^n\), where n is the dimension.

  • ValueError – if group_gates is unknown.

  • ValueError – if rb_pattern is not valid.

  • ValueError – if length_multiplier is not valid.

  • ValueError – if interleaved_elem type is not valid.


  1. Generate simultaneous standard RB sequences.

length_vector = [1,10,20]
rb_pattern = [[0,3],[2],[1]]
length_multiplier = [1,3,3]
align_cliffs = True

Create RB sequences that are 2-qubit RB for qubits Q0 and Q3, 1-qubit RB for qubit Q1, and 1-qubit RB for qubit Q2. Generate three times as many 1-qubit RB sequence elements, than 2-qubit elements. Place a barrier after 1 group element for the first pattern and after 3 group elements for the second and third patterns. The output xdata in this case is

  1. Generate simultaneous interleaved RB sequences.

rb_pattern = [[0,3],[2],[1]]

# as a QuantumCircuit:
qc_cx = QuantumCircuit(2)
qc_cx.cx(0, 1)
qc_x = QuantumCircuit(1)
qc_h = QuantumCircuit(1)

interleaved_elem = [qc_cx, qc_x, qc_h]

# or as gate objects:
interleaved_elem = [CXGate(), XGate(), HGate()]

Interleave the 2-qubit gate cx on qubits Q0 and Q3, a 1-qubit gate x on qubit Q2, and a 1-qubit gate h on qubit Q1.

  1. Generated purity RB sequences.

rb_pattern = [[0,3],[1,2]]
npurity = True

Create purity 2-qubit RB circuits separately on qubits Q0 and Q3 and on qubtis Q1 and Q2. The output is npurity = 9 in this case.