Struct FermionicOp 

pub struct FermionicOp { /* private fields */ }

A finite complex linear combination of ordered fermionic products.

The declared mode count is retained even for zero and identity operators. Equal ordered products are merged automatically; only exact zero coefficients are removed. Products are not automatically normal ordered. Use Self::chop for explicit numerical truncation and Self::equiv for algebraic equivalence. Structural equality also compares the declared mode count.

Fallible arithmetic operators return Result, for example (&a + &b)?.

Implementations

impl FermionicOp

pub fn new(num_modes: usize) -> Self

Creates the zero operator on the declared mode space, including zero modes.

pub fn identity(num_modes: usize) -> Self

Creates the identity. An empty product is the identity, not the zero operator.

pub fn from_term( num_modes: usize, term: impl IntoIterator<Item = FermionicLadder>, coefficient: Complex64, ) -> Result<Self, QisError>

Creates a weighted ordered product. Even zero-weight terms are validated.

pub fn from_terms( num_modes: usize, terms: impl IntoIterator<Item = (Vec<FermionicLadder>, Complex64)>, ) -> Result<Self, QisError>

Creates a sum of products, merging duplicates without numerical truncation.

pub fn add_term( &mut self, term: impl IntoIterator<Item = FermionicLadder>, coefficient: Complex64, ) -> Result<(), QisError>

Adds a weighted product atomically; an error leaves this operator unchanged.

pub fn creation(num_modes: usize, mode: usize) -> Result<Self, QisError>

Creates a single creation operator.

pub fn annihilation(num_modes: usize, mode: usize) -> Result<Self, QisError>

Creates a single annihilation operator.

pub fn number(num_modes: usize, mode: usize) -> Result<Self, QisError>

Creates the number operator a†_p a_p.

pub fn total_number(num_modes: usize) -> Self

Creates the total particle-number operator, or zero for zero modes.

pub fn excitation_generator( num_modes: usize, sources: &[usize], targets: &[usize], ) -> Result<Self, QisError>

Creates the unit-weight Hermitian excitation generator G = i(T - T†).

For sources = [i_0, ..., i_{r-1}] and targets = [a_0, ..., a_{r-1}], the ordered excitation is T = a†_{a_0} ... a†_{a_{r-1}} a_{i_{r-1}} ... a_{i_0}. The rightmost operator acts first. Thus [i, j] -> [a, b] means T = a†_a a†_b a_j a_i.

Input order is preserved, without implicit sorting or normal ordering. An odd permutation of either list negates G; applying odd permutations to both lists preserves it. Explicit Self::normal_order preserves these fermionic signs. No factorial or other normalization is applied.

Mapping G and evolving it with crate::circuit::ansatz::PauliEvolutionAnsatz implements exp(-i θ G) = exp(θ (T - T†)). The evolution parameter belongs to the ansatz, not this operator. The generator conserves total particle number. Reference occupations and spin interpretations are caller choices.

Errors

Returns QisError::InvalidParameterValue if the lists are empty, have unequal lengths, contain repeated modes, or overlap. Returns QisError::ModeOutOfBounds if an index is outside 0..num_modes.

Example

use cqlib_core::qis::FermionicOp;
let single = FermionicOp::excitation_generator(4, &[0], &[2])?;
let double = FermionicOp::excitation_generator(4, &[0, 1], &[2, 3])?;
assert!(single.is_hermitian(0.0)?);
assert!(double.is_hermitian(0.0)?);

pub fn num_modes(&self) -> usize

Returns the declared mode count.

pub fn num_terms(&self) -> usize

Returns the number of stored ordered products.

pub fn terms( &self, ) -> impl ExactSizeIterator<Item = (&[FermionicLadder], Complex64)> + '_

Iterates over products and their coefficients in deterministic structural order.

pub fn is_zero(&self) -> bool

Reports whether the stored sum is zero. Algebraic cancellations require normal ordering.

pub fn try_add(&self, other: &Self) -> Result<Self, QisError>

Adds operators on the same mode space, without modifying either operand.

pub fn try_sub(&self, other: &Self) -> Result<Self, QisError>

Subtracts operators on the same mode space.

pub fn try_mul(&self, other: &Self) -> Result<Self, QisError>

Forms self * other; the right operand acts first. Does not normal order.

pub fn scaled(&self, factor: Complex64) -> Result<Self, QisError>

Scales all coefficients. The factor is validated even for the zero operator.

pub fn adjoint(&self) -> Self

Takes the conjugate transpose, reversing each product without reordering it.

pub fn normal_order(&self) -> Result<Self, QisError>

Expands using the canonical anticommutation relations.

Creators precede annihilators; each group uses ascending mode indices. This is an equivalent operator expansion, including contraction terms: a_p a†_p = I - a†_p a_p. Small nonzero coefficients are retained. An explicit work stack avoids recursion in long products. Sorting a branch of k ladders takes O(k²) comparisons; contractions can produce additional branches.

pub fn chop(&mut self, atol: f64) -> Result<(), QisError>

Explicitly removes coefficients whose complex magnitude is at most atol. Invalid tolerances leave the operator unchanged.

pub fn equiv(&self, other: &Self, atol: f64) -> Result<bool, QisError>

Compares operators algebraically after normal ordering their difference. Different mode counts are an error; atol must be finite and nonnegative.

pub fn is_hermitian(&self, atol: f64) -> Result<bool, QisError>

Checks Hermiticity algebraically, allowing non-normal-ordered inputs.

Trait Implementations

impl Add for FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the + operator.

fn add(self, rhs: FermionicOp) -> Self::Output

Performs the + operation.

impl Add<&FermionicOp> for &FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the + operator.

fn add(self, rhs: &FermionicOp) -> Self::Output

Performs the + operation.

impl Add<&FermionicOp> for FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the + operator.

fn add(self, rhs: &FermionicOp) -> Self::Output

Performs the + operation.

impl Add<FermionicOp> for &FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the + operator.

fn add(self, rhs: FermionicOp) -> Self::Output

Performs the + operation.

impl Clone for FermionicOp

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 FermionicOp

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

Formats the value using the given formatter.

impl Mul for FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: FermionicOp) -> Self::Output

Performs the * operation.

impl Mul<&FermionicOp> for &FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: &FermionicOp) -> Self::Output

Performs the * operation.

impl Mul<&FermionicOp> for FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: &FermionicOp) -> Self::Output

Performs the * operation.

impl Mul<&FermionicOp> for f64

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: &FermionicOp) -> Self::Output

Performs the * operation.

impl Mul<&FermionicOp> for Complex64

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: &FermionicOp) -> Self::Output

Performs the * operation.

impl Mul<Complex<f64>> for &FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: Complex64) -> Self::Output

Performs the * operation.

impl Mul<Complex<f64>> for FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: Complex64) -> Self::Output

Performs the * operation.

impl Mul<FermionicOp> for &FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: FermionicOp) -> Self::Output

Performs the * operation.

impl Mul<FermionicOp> for f64

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: FermionicOp) -> Self::Output

Performs the * operation.

impl Mul<FermionicOp> for Complex64

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: FermionicOp) -> Self::Output

Performs the * operation.

impl Mul<f64> for &FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: f64) -> Self::Output

Performs the * operation.

impl Mul<f64> for FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the * operator.

fn mul(self, rhs: f64) -> Self::Output

Performs the * operation.

impl Neg for &FermionicOp

type Output = FermionicOp

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl Neg for FermionicOp

type Output = FermionicOp

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl PartialEq for FermionicOp

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

Equality operator ==.

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

Inequality operator !=.

impl StructuralPartialEq for FermionicOp

impl Sub for FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the - operator.

fn sub(self, rhs: FermionicOp) -> Self::Output

Performs the - operation.

impl Sub<&FermionicOp> for &FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the - operator.

fn sub(self, rhs: &FermionicOp) -> Self::Output

Performs the - operation.

impl Sub<&FermionicOp> for FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the - operator.

fn sub(self, rhs: &FermionicOp) -> Self::Output

Performs the - operation.

impl Sub<FermionicOp> for &FermionicOp

type Output = Result<FermionicOp, QisError>

The resulting type after applying the - operator.

fn sub(self, rhs: FermionicOp) -> Self::Output

Performs the - operation.