ComplexTermSum

class zixy.fermion.ComplexTermSum(modes: int | Modes = 0)

Bases: NumericTermSum[NormalFermionOperatorArray, str | tuple[Sequence[int] | Sequence[bool], Sequence[int] | Sequence[bool]], complex], TermSum[complex]

A sum of terms consisting of normal-ordered fermionic strings and complex coefficients.

A set-like container of mode-based terms with complex coefficients that may be used to store unique terms and perform algebraic operations on them.

Note

Coefficients are mutable in-place, but components are the keys of a hashmap and therefore are not.

__add__(rhs: Term[ImplT, SpecT, CoeffT] | Self) → Self

Addition of self and rhs.

__eq__(other: object) → bool

Return whether self and other are equal.

__getitem__(value: SpecT | Cmpnt[ImplT, SpecT] | Term[ImplT, SpecT, CoeffT]) → CoeffT

Get the coefficient of the term with component specified by value.

Parameters:

value – The component or term specifier.

Returns:

The coefficient of the term with component specified by value.

Raises:

KeyError – The component specified by value was not found in self.

__iadd__(rhs: Term[ImplT, SpecT, CoeffT] | Self) → Self

Add rhs to self in-place.

__imul__(other: int | float | complex | Sign | ComplexSign | Expr | Coeffs[CoeffT]) → Self

Multiply self in-place by a scalar or coefficient vector.

__init__(modes: int | Modes = 0)

Initialize the term set.

Parameters:

modes – The mode space or number of modes.

__isub__(rhs: Term[ImplT, SpecT, CoeffT] | Self) → Self

Subtract rhs from self in-place.

__iter__() → Iterator[Term[ImplT, SpecT, CoeffT]]

Iterate over the elements of self.

__itruediv__(scalar: int | float | complex | Sign | ComplexSign | Expr) → Self

In-place division of self by scalar.

__len__() → int

Get the number of elements in self.

__mul__(rhs: int | float | complex | Sign | ComplexSign | Expr | Coeffs[complex] | Self) → Self | ComplexTermSum

Overloads:

• self, rhs (Coeff | Coeffs[complex]) → Self

• self, rhs (Self) → ComplexTermSum

Multiplication of self by rhs.

__neg__() → Self

Return the negation of self.

__pos__() → Self

Return self.

__repr__() → str

Return a string representation of self.

__rmul__(coeff: int | float | complex | Sign | ComplexSign | Expr | Coeffs[CoeffT]) → Self

Return self multiplied by a scalar or coefficient vector.

__setitem__(key: SpecT | Term[ImplT, SpecT, CoeffT], coeff: CoeffT) → None

Set the coefficient of the term with component specified by key.

__sub__(rhs: Term[ImplT, SpecT, CoeffT] | Self) → Self

Subtraction of rhs from self.

__truediv__(scalar: int | float | complex | Sign | ComplexSign | Expr) → Self

Division of self by scalar.

active_modes() → set[int]

Return the set of mode indices on which self acts.

add_iterable(iterable: Iterable[Term[ImplT, SpecT, CoeffT]]) → None

In-place addition of the terms in iterable to self.

Parameters:

iterable – Iterable of terms to add to self.

Note

This method operates in-place.

anticommutator(rhs: TermSum[complex]) → ComplexTermSum

Return the anticommutator {self, rhs}.

apply(state: ComplexTermSum) → ComplexTermSum

Apply self to a state.

Parameters:

state – The state to apply to.

Returns:

The resulting state.

clone() → Self

Return a deep copy of self.

property cmpnt_type: type[Cmpnt[ImplT, SpecT]]

Get the component type of self.

property cmpnts_type: type[Cmpnts[ImplT, SpecT]]

Get the component container type of self.

property coeff_type: type[CoeffT]

Get the coefficient type of self.

property coeffs: Any

Get the coefficients of self.

property coeffs_type: type[Coeffs[CoeffT]]

Get the coefficient container type of self.

commutator(rhs: TermSum[complex]) → ComplexTermSum

Return the commutator [self, rhs].

conserves_particle_number(atol: float = 1e-10) → bool

Check whether self conserves particle number within the given tolerance.

contains(value: SpecT | Cmpnt[ImplT, SpecT] | Term[ImplT, SpecT, CoeffT]) → bool

Check whether the component specified by value is stored in self.

Parameters:

value – The component specifier.

Returns:

Whether the lookup of value was successful.

dagger() → None

Take the adjoint of self in-place.

daggered() → Self

Return the adjoint of self.

exp_val(state: ComplexTermSum) → complex

Evaluate the expectation value of self with respect to a state.

Parameters:

state – The state to evaluate with respect to.

Returns:

The resulting expectation value.

filter_insignificant(atol: float = 1e-08) → Self

Eagerly get terms in self with coefficients less than atol.

Parameters:

atol – Absolute tolerance.

Returns:

New instance containing all terms that meet the criterion.

filter_map(f: Callable[[Term[ImplT, SpecT, CoeffT]], bool]) → Self

Eagerly evaluate a filter-map operation over the terms of self.

Parameters:

f – Function which may mutate copies of the terms of self, returning True if those mutated copies are to be included in the generator. The function signature should take a single Term instance as an argument, and return a boolean.

Returns:

New instance containing the occurrences of selected (and possibly mutated) components of self according to f.

Note

The resulting generator enforces uniqueness of components by overwriting coefficients of duplicate components.

filter_nonzero() → Self

Filter self to only the non-zero terms.

filter_significant(atol: float = 1e-08) → Self

Eagerly get terms in self with coefficients no less than atol.

Parameters:

atol – Absolute tolerance.

Returns:

New instance containing all terms that meet the criterion.

classmethod from_iterable(iterable: Iterable[Term[ImplT, SpecT, CoeffT]], *args: Any, **kwargs: Any) → Self

Create a new instance of cls from an iterable.

Parameters:

• iterable – Iterable returning specifiers of all the terms to be appended.

• args – Positional arguments to forward to the constructor of cls.

• kwargs – Keyword arguments to forward to the constructor of cls.

Returns:

New instance of cls containing the terms specified by iterable.

classmethod from_str(source: str, *args: Any, **kwargs: Any) → Self

Create a new instance of cls from a string.

Parameters:

• source – String to parse.

• *args – Positional arguments to forward to the component constructor.

• **kwargs – Keyword arguments to forward to the component constructor.

Returns:

An instance of cls parsed from source.

classmethod from_terms(terms: Terms[ImplT, SpecT, CoeffT]) → Self

Create a new instance of cls from terms.

Parameters:

terms – Terms-derived object from which to construct the set of terms.

Returns:

A new instance of cls containing the terms in terms.

insert(key: Term[ImplT, SpecT, CoeffT] | Cmpnt[ImplT, SpecT] | SpecT | tuple[SpecT | Cmpnt[ImplT, SpecT], CoeffT | None]) → int

Try to insert the given term.

Parameters:

key – The term specifier.

Returns:

The index at which the term was inserted, or the index at which it already was stored if insertion is unsuccessful.

Note

This method operates in-place.

insert_iterable(source: Iterable[Term[ImplT, SpecT, CoeffT] | Cmpnt[ImplT, SpecT] | SpecT | tuple[SpecT | Cmpnt[ImplT, SpecT], CoeffT | None]] = ()) → None

Insert many terms from an iterable source.

Parameters:

source – Iterable over any term specifiers.

Note

This method operates in-place.

into(t: type[OutT] | type[TermSet[ImplT, SpecT, OtherCoeffT]]) → OutT | TermSet[ImplT, SpecT, OtherCoeffT]

Overloads:

• self, t (type[OutT]) → OutT

• self, t (type[TermSet[ImplT, SpecT, OtherCoeffT]]) → TermSet[ImplT, SpecT, OtherCoeffT]

Clone self into a new related container of type t.

Parameters:

t – Type of the new container to create.

Returns:

A new instance of t containing the same data as self.

is_hermitian(atol: float = 1e-10) → bool

Check whether self is Hermitian within the given tolerance.

iter_filter_insignificant(atol: float = 1e-08) → Iterator[Term[ImplT, SpecT, NumberT]]

Lazily generate terms in self with coefficients less than atol.

Parameters:

atol – Absolute tolerance.

Returns:

Iterator of terms that meet the criterion.

iter_filter_map(f: Callable[[Term[ImplT, SpecT, CoeffT]], bool]) → Iterator[Term[ImplT, SpecT, CoeffT]]

Lazily evaluate a filter-map operation over the terms of self.

Parameters:

f – Function which may mutate copies of the terms of self, returning True if those mutated copies are to be included in the generator. The function signature should take a single Term instance as an argument, and return a boolean.

Returns:

Iterator over the selected (and possibly mutated) components of self according to f.

Note

The resulting generator does not enforce uniqueness of components.

iter_filter_nonzero() → Iterator[Term[ImplT, SpecT, CoeffT]]

Iterate over the non-zero terms of self.

iter_filter_significant(atol: float = 1e-08) → Iterator[Term[ImplT, SpecT, NumberT]]

Lazily generate terms in self with coefficients no less than atol.

Parameters:

atol – Absolute tolerance.

Returns:

Iterator of terms that meet the criterion.

property l1_norm: NumberT

Get the L1 norm of self.

l1_normalize() → None

Divide self by its L1 norm.

Note

This method operates in-place.

property l2_norm: int | float | complex

Get the L2 norm of self.

property l2_norm_square: NumberT

Get the square of the L2 norm of self.

l2_normalize() → None

Divide self by its L2 norm.

Note

This method operates in-place.

lookup(value: SpecT | Cmpnt[ImplT, SpecT] | Term[ImplT, SpecT, CoeffT]) → tuple[int, CoeffT] | None

Try to find the index and coefficient of the component specified by value.

Parameters:

value – The component or term specifier.

Returns:

The index at which the value was inserted, or None if the value was not found.

lookup_coeff(value: SpecT | Cmpnt[ImplT, SpecT] | Term[ImplT, SpecT, CoeffT]) → CoeffT | None

Try to find the coefficient of the term specified by value in self.

Parameters:

value – The component or term specifier.

Returns:

The coefficient of the term specified by value if it is present in self, and None otherwise.

lookup_index(value: SpecT | Cmpnt[ImplT, SpecT] | Term[ImplT, SpecT, CoeffT]) → int | None

Try to find the index of the component specified by value in self.

Parameters:

value – The component or term specifier.

Returns:

The index of the component specified by value if it is present in self, and None otherwise.

mat_elem(bra: ComplexTermSum, ket: ComplexTermSum) → complex

Evaluate the matrix element of self between a bra and ket state.

Parameters:

• bra – The bra state.

• ket – The ket state.

Returns:

The resulting matrix element.

max_n_body() → int

Return the maximum n-body order across all terms.

property modes: Modes

Get the modes corresponding to self.

classmethod parse(source: str) → Self

Parse a string into an instance of cls.

Deprecated:

use from_str() instead.

Parameters:

source – String to parse.

Returns:

An instance of cls parsed from source.

remove(value: SpecT | Cmpnt[ImplT, SpecT] | Term[ImplT, SpecT, CoeffT]) → int

Try to remove the component specified by value from self.

If the component is found, removal proceeds via swap-remove.

Parameters:

value – The component specifier.

Returns:

The index at which the component was removed.

Raises:

KeyError – The component was not found.

soft_insert(key: Term[ImplT, SpecT, CoeffT] | Cmpnt[ImplT, SpecT] | SpecT | tuple[SpecT | Cmpnt[ImplT, SpecT], CoeffT | None]) → tuple[int, bool]

Insertion method which does not overwrite coefficient values.

Operates similarly to insert(), but does not overwrite coefficient values if the component specified by key is already present in self.

Parameters:

key – The term specifier.

Returns:

Index at which the term was inserted or found, and a boolean indicating whether insertion was successful (i.e. whether the component specified by key was not already present in self).

Note

This method operates in-place.

property strings: Strings[ImplT, SpecT, ElemT]

Get the string components of the terms.

terms_type

alias of ComplexTerms

to_dataframe() → DataFrame

Convert self to a DataFrame.

to_general() → ComplexTermSum

Convert this normal-ordered term sum to the raw general representation.

to_qubit(mapper: type[Mapper] | None = None, qubits: int | Qubits | None = None) → ComplexTermSum

Map this fermionic term sum to a qubit Pauli term sum.

Parameters:

• mapper – The mapper class to use. If None, use JordanWignerMapper.

• qubits – The qubit register or qubit count. If None, the qubit register is inferred from the number of fermionic modes.

Returns:

The mapped Pauli term sum.

to_str() → str

Return the canonical string representation of self.

to_terms() → Terms[ImplT, SpecT, CoeffT]

Get a collection of terms containing the same data as self.