Struct TwoLocal 

pub struct TwoLocal { /* private fields */ }

The TwoLocal ansatz, a versatile hardware-efficient parameterized circuit.

TwoLocal is a popular ansatz architecture consisting of alternating layers of single-qubit rotations and two-qubit entanglement gates. It serves as the foundation for many common ansatz patterns including RealAmplitudes and EfficientSU2.

Architecture

The circuit structure follows this pattern:

Layer 0:    [R]───────[R]───────[R]───────[R]    (Rotation)
              │       │       │       │
Layer 0.5:   └─[E]───┘       └─[E]───┘        (Entanglement)

Layer 1:    [R]───────[R]───────[R]───────[R]
              │       │       │       │
Layer 1.5:   └─[E]───┘       └─[E]───┘
...

Where [R] represents parameterized rotation gates and [E] represents entanglement gates.

Configuration

Use the builder pattern to configure the ansatz:

• reps: Number of repetition layers
• rotation_gates: Single-qubit gates (e.g., [RY], [RY, RZ])
• entanglement_gate: Two-qubit gate (e.g., CX, CZ)
• entanglement: Connectivity pattern
• skip_final_rotation_layer: Omit final rotation

Parameter Count

The total number of parameters is: layers × num_qubits × rotation_gates.len()

where layers = reps if skip_final_rotation_layer is true, otherwise layers = reps + 1.

Implementations

impl TwoLocal

pub fn new(num_qubits: usize) -> Self

Creates a new TwoLocal ansatz with sensible defaults.

Default Configuration

• reps: 3 layers
• rotation_gates: [RY]
• entanglement_gate: CX
• entanglement: Linear
• skip_final_rotation_layer: false

Arguments

• num_qubits - The number of qubits in the ansatz.

Example

use cqlib_core::circuit::ansatz::{Ansatz, TwoLocal};

let ansatz = TwoLocal::new(5);
assert_eq!(ansatz.num_qubits(), 5);

pub fn reps(self, reps: usize) -> Self

Sets the number of repetition layers.

Each repetition consists of one rotation layer followed by one entanglement layer. The default is 3.

Arguments

• reps - The number of repetitions (must be >= 0).

pub fn rotation_gates(self, gates: Vec<StandardGate>) -> Self

Sets the rotation gates used in the rotation layers.

Each qubit receives all specified rotation gates in sequence. Valid choices are single-parameter single-qubit rotation gates:

• [RX], [RY], [RZ] individually
• [RY, RZ] for EfficientSU2 ansatz
• [RX, RY, RZ] for full SU(2) coverage

Arguments

• gates - A vector of single-qubit parameterized gates (RX, RY, or RZ).

Errors

Validation is performed in build_circuit. Returns CircuitError::InvalidOperation if any gate is not RX, RY, or RZ.

pub fn entanglement_gate(self, gate: StandardGate) -> Self

Sets the entanglement gate used in the entanglement layers.

Valid choices are two-qubit controlled gates that create entanglement:

• CX (CNOT): Standard choice, universal for entanglement (default)
• CY: Controlled-Y gate
• CZ: Symmetric, native on some hardware

Arguments

• gate - A two-qubit controlled entanglement gate (CX, CY, or CZ).

Errors

Validation is performed in build_circuit. Returns CircuitError::InvalidOperation if the gate is not CX, CY, or CZ.

pub fn entanglement(self, topology: EntanglementTopology) -> Self

Sets the entanglement topology.

See EntanglementTopology for available options.

Arguments

• topology - The desired connectivity pattern.

pub fn skip_final_rotation_layer(self, skip: bool) -> Self

Sets whether to skip the final rotation layer.

The default TwoLocal architecture adds a final rotation layer after the last entanglement layer (total reps + 1 rotation layers). When enabled, this final rotation layer is omitted, meaning the ansatz ends with an entanglement layer and has exactly reps rotation layers.

Arguments

• skip - If true, omit the final rotation layer.

Trait Implementations

impl Ansatz for TwoLocal

fn validate(&self) -> Result<(), CircuitError>

Validates the ansatz configuration without building the circuit.

fn build_circuit(&self, prefix: &str) -> Result<Circuit, CircuitError>

Builds the ansatz circuit and returns it.

fn num_parameters(&self) -> usize

Returns the number of independent parameters required by this ansatz.

fn num_qubits(&self) -> usize

Returns the number of qubits this ansatz acts upon.

impl Clone for TwoLocal

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TwoLocal

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.