Struct PauliFeatureMap 

pub struct PauliFeatureMap { /* private fields */ }

Pauli Feature Map: A general-purpose data encoding circuit using Pauli evolution.

The PauliFeatureMap encodes classical data into quantum states through parameterized Pauli evolution gates. It supports arbitrary Pauli strings (e.g., “Z”, “ZZ”, “ZZZ”) and flexible entanglement topologies.

Mathematical Foundation

For a k-local Pauli template P and feature vector x, the encoding applies:

Locality	Evolution	Angle θ (passed to pauli_evolution)
k = 1	$e^{-i x_i P}$	$2 x_i$
k ≥ 2	$e^{-i 2 \prod_{j \in S}(\pi - x_j) P}$	$4 \prod_{j \in S}(\pi - x_j)$

where pauli_evolution(θ) implements $e^{-i \frac{\theta}{2} P}$.

The non-linear k-local mapping $\prod_{j \in S}(\pi - x_j)$ creates a rich feature space through the kernel trick, making the kernel function hard to evaluate classically for large circuits.

Architecture

The circuit structure for each repetition layer:

1. Hadamard Layer: Apply $H$ gates to all qubits to create superposition.
2. k-local Pauli Evolution: For each Pauli template P and each k-tuple of qubit indices $(q_0, \ldots, q_{k-1})$ from the entanglement topology, apply $e^{-i \phi(x_{q_0}, \ldots, x_{q_{k-1}}) P}$.

Example

use cqlib_core::circuit::ansatz::{Ansatz, PauliFeatureMap, EntanglementTopology};
use cqlib_core::qis::pauli::PauliString;

// 3-qubit feature map with Z (1-local) + ZZ (2-local) + ZZZ (3-local)
let feature_map = PauliFeatureMap::new(3)
    .reps(1)
    .paulis(vec![
        ("Z".parse::<PauliString>().unwrap(),   "Z".to_string()),
        ("ZZ".parse::<PauliString>().unwrap(),  "ZZ".to_string()),
        ("ZZZ".parse::<PauliString>().unwrap(), "ZZZ".to_string()),
    ])
    .entanglement(EntanglementTopology::Full);

let circuit = feature_map.build_circuit("x").unwrap();
assert_eq!(feature_map.num_parameters(), 3);

Implementations

impl PauliFeatureMap

pub fn new(num_qubits: usize) -> Self

Creates a new PauliFeatureMap with default configuration.

Default Configuration

• reps: 2 layers
• paulis: [“Z”, “ZZ”] (single-qubit Z and two-qubit ZZ interactions)
• entanglement: Full all-to-all connectivity
• parameter_prefix: “x”

Arguments

• num_qubits - The number of qubits (features) in the feature map.

Example

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

let fm = PauliFeatureMap::new(4);
assert_eq!(fm.num_qubits(), 4);

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

Sets the number of repetition layers.

Each repetition applies the full encoding sequence (Hadamard + Pauli evolutions). More repetitions increase the expressiveness of the feature map but also increase circuit depth.

Arguments

• reps - The number of repetition layers.

pub fn paulis(self, paulis: Vec<(PauliString, String)>) -> Self

Sets the Pauli strings to use for evolution.

Each Pauli string specifies a type of interaction:

• Single-character strings (e.g., “Z”, “X”, “Y”) create 1-local interactions.
• Multi-character strings (e.g., “ZZ”, “XY”) create multi-qubit interactions.

Arguments

• paulis - A vector of (PauliString, label) tuples.

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

Sets the entanglement topology for 2-local interactions.

The topology determines which qubit pairs are connected by 2-local Pauli evolution gates.

Arguments

• topology - The entanglement topology.

pub fn parameter_prefix(self, prefix: impl Into<String>) -> Self

Sets the parameter name prefix.

Parameter names are generated as {prefix}_{index} (e.g., “x_0”, “x_1”).

Arguments

• prefix - The parameter name prefix.

Trait Implementations

impl Ansatz for PauliFeatureMap

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 PauliFeatureMap

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 PauliFeatureMap

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

Formats the value using the given formatter.