Struct PauliString 

pub struct PauliString { /* private fields */ }

A dense unsigned Pauli operator over len qubits, stored as XZ bit vectors.

Phaseless, with each site read as the Hermitian single-qubit Pauli it names — a site carrying both bits is Y = iXZ, not the bare product XZ. A product of Hermitian factors on distinct sites is Hermitian, so every PauliString is a valid measurement observable or rotation axis by construction; there is no phase to make it otherwise. Operations between different widths treat missing trailing sites as identities; XOR keeps the wider width. Parse strings of I, _, X, Y, and Z with str::parse; Display renders identity as _.

Implementations

impl PauliString

pub fn new(num_qubits: usize) -> Self

Creates the identity Pauli string over num_qubits qubits.

pub fn single(num_qubits: usize, index: usize, pauli: Pauli) -> Self

Creates the string with pauli at index and identity everywhere else.

Panics

Panics if index >= num_qubits.

Examples

use bloq_utils::{Pauli, PauliString};

let observable = PauliString::single(4, 2, Pauli::Y);
assert_eq!(observable.to_string(), "__Y_");

pub fn from_terms( num_qubits: usize, terms: impl IntoIterator<Item = (usize, Pauli)>, ) -> Self

Collects (index, pauli) terms into a string over num_qubits qubits.

Terms are assignments, not factors: a repeated index keeps the last Pauli given for it rather than multiplying the two.

Panics

Panics if any index is >= num_qubits.

Examples

use bloq_utils::{Pauli, PauliString};

let stabilizer = PauliString::from_terms(3, [(0, Pauli::Z), (2, Pauli::Z)]);
assert_eq!(stabilizer.to_string(), "Z_Z");

pub fn commutes_with(&self, other: &Self) -> bool

Returns true if self and other commute as operators.

Two Pauli strings anticommute exactly when they anticommute on an odd number of sites, which the symplectic form ⟨x, other.z⟩ + ⟨z, other.x⟩ counts mod 2.

The two strings need not name the same number of qubits. Where one runs out the other is being compared against implicit identities, which commute with everything — so the fold below stops at the shorter operand rather than requiring equal widths. Going through the words directly is also what avoids BitVec::dot, whose length assertion holds in release builds and would turn a width mismatch into a panic.

Examples

use bloq_utils::PauliString;

let xx = PauliString::try_from("XX")?;
let zz = PauliString::try_from("ZZ")?;
let zi = PauliString::try_from("Z_")?;
assert!(xx.commutes_with(&zz));   // two anticommuting sites
assert!(!xx.commutes_with(&zi));  // one

// Widths may differ; the shorter string ends in implicit identities.
let x_wide = PauliString::try_from("X___")?;
assert!(!x_wide.commutes_with(&PauliString::try_from("Z")?));
assert!(x_wide.commutes_with(&PauliString::try_from("_Z")?));

pub fn product_phase(&self, other: &Self) -> u8

Returns the power of i contributed by multiplying these strings. Missing sites are identities.

pub fn x_words(&self) -> &[u64]

The X components as u64 words, least-significant qubit first.

Word-level access for bit algebra over whole strings — the simulator’s frame decomposition walks these directly rather than one site at a time. Bits at or beyond len are always clear.

pub fn z_words(&self) -> &[u64]

The Z components as u64 words. See x_words.

pub fn len(&self) -> usize

Returns the number of qubits.

pub fn is_empty(&self) -> bool

Returns true if there are no qubits.

pub fn weight(&self) -> usize

Returns the number of non-identity Paulis.

pub fn is_identity(&self) -> bool

Returns whether every site is identity, stopping at the first nonzero word.

pub fn iter_support(&self) -> impl Iterator<Item = (usize, Pauli)> + '_

Iterates the non-identity sites in ascending index order.

Panics

Panics if the packed X/Z representation contains an impossible support bit.

pub fn get(&self, index: usize) -> Pauli

Returns the Pauli at index.

Panics

Panics if index is out of bounds.

pub fn set(&mut self, index: usize, pauli: Pauli)

Sets the Pauli at index.

Panics

Panics if index is out of bounds.

Trait Implementations

impl BitXor for &PauliString

type Output = PauliString

The resulting type after applying the ^ operator.

fn bitxor(self, rhs: Self) -> Self::Output

Performs the ^ operation.

impl BitXorAssign<&PauliString> for PauliString

fn bitxor_assign(&mut self, other: &Self)

Performs the ^= operation.

impl Clone for PauliString

fn clone(&self) -> PauliString

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for PauliString

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

Formats the value using the given formatter.

impl Display for PauliString

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

Formats the value using the given formatter.

impl Eq for PauliString

impl FromStr for PauliString

type Err = PauliError

The associated error which can be returned from parsing.

fn from_str(value: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl PartialEq for PauliString

fn eq(&self, other: &PauliString) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for PauliString

impl TryFrom<&str> for PauliString

type Error = PauliError

The type returned in the event of a conversion error.

fn try_from(value: &str) -> Result<Self, Self::Error>

Performs the conversion.