qpe_toolbox.circuit.parametrized_circuits

Functions

one_qubit_layer(circ, gate_label, *[, param_scaling, ...])

Apply a single-body gate layer to all qubits of a quimb Circuit.

two_qubit_nn_layer(circ, start, gate_label, *[, ...])

Apply a nearest-neighbor two-body entangling layer to a quimb Circuit.

two_qubit_rand_layer(circ, gate_label, gate_range, ...)

Apply a random two-body entangling layer to a quimb Circuit.

generate_brickwall_circuit(n_qubits, depth, ...[, ...])

Generate a brickwall-structured quimb Circuit.

generate_rand_circuit(n_qubits, depth, ...[, ...])

Generate a random entangling quimb Circuit.

ansatz_circuit(n_qubits, depth, *[, gate_round, ...])

Construct an ansatz circuit of single qubit and entangling layers.

ansatz_circuit_su4(n_qubits, depth, *[, gate_round, ...])

Construct an ansatz circuit using SU(4) two-qubit gates.

ansatz_circuit_sym(n_qubits, depth, *[, gate_round, ...])

Construct a U(1)-symmetry-preserving ansatz circuit.

Module Contents

qpe_toolbox.circuit.parametrized_circuits.one_qubit_layer(circ, gate_label, *, param_scaling=1.0, gate_round=None, parametrize=False, rng=None)[source]

Apply a single-body gate layer to all qubits of a quimb Circuit.

This function applies the same single-qubit gate to every qubit in the circuit at a specified circuit round. If the gate is parametrized, random parameters are generated using the provided random number generator and shared across all qubits in the layer.

Parameters:

  • circ (Circuit) – The quimb circuit to which the layer is applied.

  • gate_label (str) – Label identifying the single-body gate to apply (e.g. "RX"). The label must be compatible with Circuit.apply_gate.

  • param_scaling (float, default 1.0) – Scaling factor for randomly initialized parameters.

  • gate_round (int or None, default None) – Circuit layer at which the gates are applied.

  • parametrize (bool, default False) – Activate the possibility of using the layer as a parametrized Ansatz on some variational scheme.

  • rng (numpy.random.Generator, default None) – Random number generator for gate parameters. If None a new Generator is initialized.

Notes

  • The same set of parameters is used for all qubits in the layer.

qpe_toolbox.circuit.parametrized_circuits.two_qubit_nn_layer(circ, start, gate_label, *, param_scaling=1.0, gate_round=None, parametrize=False, reverse=False, rng=None)[source]

Apply a nearest-neighbor two-body entangling layer to a quimb Circuit.

This function applies a two-qubit entangling gate between nearest neighbors in a brickwork pattern. The starting qubit index determines the parity of the layer.

Parameters:

  • circ (Circuit) – The quimb circuit to which the layer is applied.

  • start (int) – Starting qubit index for the nearest-neighbor pattern (typically 0 or 1). Allows for defining even (0) and odd (1) layers.

  • gate_label (str) – Label identifying the two-body entangling gate (e.g. "CNOT").

  • param_scaling (float, default 1.0) – Scaling factor for randomly initialized parameters.

  • gate_round (int or None, default None) – Gate round index used to tag gates.

  • parametrize (bool, default False) – Activate the possibility of using the layer as a parametrized Ansatz on some variational scheme.

  • reverse (bool, default False) – Possibility to invert direction of the layer. Relevant when using controlled gates.

  • rng (numpy.random.Generator, default None) – Random number generator for gate parameters. If None a new Generator is initialized.

Notes

  • The same parameters are reused for all entangling gates in the layer.

  • Gates are applied between qubits (i, i+1) for i = start, start+2, …

qpe_toolbox.circuit.parametrized_circuits.two_qubit_rand_layer(circ, gate_label, gate_range, gate_prob, *, rng=None, param_scaling=1.0, gate_round=None, parametrize=True, reverse=False)[source]

Apply a random two-body entangling layer to a quimb Circuit.

This function applies two-qubit entangling gates between randomly chosen qubit pairs. For each qubit, a partner qubit is selected within a given range, and the entangling gate is applied with a specified probability.

Parameters:

  • circ (Circuit) – The quimb circuit to which the layer is applied.

  • gate_label (str) – Label identifying the two-body entangling gate.

  • gate_range (int) – Sets a maximum interaction range (gate_range+1) for two-body entangling gates, measured in qubit index separation.

  • gate_prob (float) – Probability threshold controlling whether an entangling gate is applied. A gate is applied if rng_prob.random() <= gate_prob.

  • rng (numpy.random.Generator, default None) – Random number generator for gate_range and gate_prob. If None a new Generator is initialized.

  • param_scaling (float, default 1.0) – Scaling factor for randomly initialized parameters.

  • gate_round (int or None, default None) – Gate round index used to tag gates.

  • parametrize (bool, default False) – Activate the possibility of using the layer as a parametrized Ansatz on some variational scheme.

  • reverse (bool, default False) – Possibility to invert direction of the layer. Relevant when using controlled gates.

Notes

  • The same parameters are reused for all entangling gates in the layer.

  • Entangling partners are chosen as j = i + 1 + Δ, where Δ is sampled uniformly from [0, gate_range).

qpe_toolbox.circuit.parametrized_circuits.generate_brickwall_circuit(n_qubits, depth, one_qubit_gate_label, two_qubit_gate_label, *, start_ent=False, param_scaling=1.0, rng=None)[source]

Generate a brickwall-structured quimb Circuit.

This function constructs a quantum circuit composed of alternating single-body layers and nearest-neighbor two-body entangling layers arranged in a brickwall pattern. Each circuit layer is assigned a distinct circuit round.

Circuit structure (one layer, start_ent=False):

q0 ──[]───●───────
          │
q1 ──[]───●───●───
              │
q2 ──[]───●───●───
          |
q3 ──[]───●───●───
              |
q4 ──[]───●───●───
          |
q5 ──[]───●───────
  <─────────────>
    first layer

where:

[]     = single-body gate
●─●    = nearest-neighbor entangling gate
Parameters:

  • n_qubits (int) – Number of qubits in the circuit.

  • depth (int) – Number of circuit layers (identified here with the gate rounds).

  • one_qubit_gate_label (str) – Label identifying the single-body gate.

  • two_qubit_gate_label (str) – Label identifying the two-body entangling gate.

  • start_ent (bool, optional) – If True, each layer starts with the brickwall entangling layer. Otherwise (default False), the single-body layer is applied first.

  • param_scaling (float, default 1.0) – Scaling factor for randomly initialized parameters.

  • rng (numpy.random.Generator, optional) – Random number generator used to generate gate parameters. If None, a default generator is created.

Returns:

circ – The generated brickwall quantum circuit.

Return type:

Circuit

Raises:

ValueError – If one_qubit_gate_label does not correspond to a valid single-body gate, or if two_qubit_gate_label is not a valid two-body gate.

Notes

  • Separate random number generators are used for single-body and two-body gate parameters to ensure reproducibility and decoupled randomness.

  • The same gate parameters are reused across all gates within a given layer.

qpe_toolbox.circuit.parametrized_circuits.generate_rand_circuit(n_qubits, depth, one_qubit_gate_label, two_qubit_gate_label, two_qubit_gate_range, two_qubit_gate_prob, *, start_ent=False, param_scaling=1.0, rng=None)[source]

Generate a random entangling quimb Circuit.

This function constructs a quantum circuit consisting of alternating single-body layers and randomly generated two-body entangling layers. Entangling gates are applied probabilistically between qubits within a finite interaction range.

Circuit structure (one layer, start_ent=False):

q0 ──[]───●───────
          │
q1 ──[]───●───●───
              │
q2 ──[]───●───|───  ^
          |   |     |
q3 ──[]───|───●───  |
          |         | two_qubit_gate_range=2
q4 ──[]───|───────  |
          |         |
q5 ──[]───●───────  v
  <─────────────>
    first layer

where:

[]     = single-body gate
●─●    = entangling gate
Parameters:

  • n_qubits (int) – Number of qubits in the circuit.

  • depth (int) – Number of circuit layers (rounds).

  • one_qubit_gate_label (str) – Label identifying the single-body gate applied at each layer.

  • two_qubit_gate_label (str) – Label identifying the two-body entangling gate.

  • two_qubit_gate_range (int) – Sets a maximum interaction range (two_qubit_gate_range+1) for two-body entangling gates, measured in qubit index separation.

  • two_qubit_gate_prob (float) – Probability threshold controlling the application of an entangling gate for a given qubit.

  • start_ent (bool, optional) – If True, each layer starts with the random entangling layer. Otherwise (default False), the single-body layer is applied first.

  • param_scaling (float, default 1.0) – Scaling factor for randomly initialized parameters.

  • rng (numpy.random.Generator, optional) – Random number generator to generate gate parameters. If None, a default generator is created.

Returns:

circ – The generated random entangling quantum circuit.

Return type:

Circuit

Raises:

ValueError – If one_qubit_gate_label does not correspond to a valid single-body gate, or if two_qubit_gate_label is not a valid two-body gate.

Notes

  • Gate parameters are shared across all gates within the same layer.

qpe_toolbox.circuit.parametrized_circuits.ansatz_circuit(n_qubits, depth, *, gate_round=0, param_scaling=1.0, rng=None)[source]

Construct an ansatz circuit of single qubit and entangling layers.

Parameters:

  • n_qubits (int) – Number of qubits in the circuit.

  • depth (int) – Number of repeated ansatz layers.

  • gate_round (int, default 0) – Starting gate round index.

  • param_scaling (float, default 1.0) – Scaling factor for random parameter initialization.

  • rng (numpy.random.Generator, optional) – Random number generator to generate gate parameters. If None, a default generator is created.

Returns:

Parametrized ansatz circuit.

Return type:

Circuit

qpe_toolbox.circuit.parametrized_circuits.ansatz_circuit_su4(n_qubits, depth, *, gate_round=0, param_scaling=1.0, rng=None)[source]

Construct an ansatz circuit using SU(4) two-qubit gates.

Parameters:

  • n_qubits (int) – Number of qubits in the cricuit.

  • depth (int) – Number of circuit layers.

  • gate_round (int, default 0) – Starting gate round index.

  • param_scaling (float, default 1.0) – Scaling factor for random parameter initialization.

  • rng (numpy.random.Generator, optional) – Random number generator to generate gate parameters. If None, a default generator is created.

Returns:

Parametrized SU(4) ansatz circuit.

Return type:

Circuit

qpe_toolbox.circuit.parametrized_circuits.ansatz_circuit_sym(n_qubits, depth, *, gate_round=0, param_scaling=1.0, rng=None)[source]

Construct a U(1)-symmetry-preserving ansatz circuit.

This ansatz uses custom XX+YY gates, RZZ entanglers, and single-qubit Z rotations.

Parameters:

  • n_qubits (int) – Number of qubits in the circuit.

  • depth (int) – Number of ansatz layers.

  • gate_round (int, default 0) – Starting gate round index.

  • param_scaling (float, default 1.0) – Scaling factor for random parameter initialization.

  • rng (numpy.random.Generator, optional) – Random number generator to generate gate parameters. If None, a default generator is created.

Returns:

Parametrized U(1)-symmetric ansatz circuit.

Return type:

Circuit