ComplexTermSum¶

class zixy.qubit.state.ComplexTermSum(qubits: int | Qubits = 0)[source]¶

Bases: NumericTermSum[QubitStateArray, None | Sequence[bool] | set[int] | str, complex], TermSum[complex]

A sum of terms consisting of state strings and complex coefficients.

A set-like container of qubit-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__(scalar: int | float | complex | Sign | ComplexSign | Expr) → Self¶: In-place multiplication of self by scalar.

__init__(qubits: int | Qubits = 0)¶

Initialize the term set.

Parameters:: qubits – The qubit register or qubit count.

__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__(scalar: int | float | complex | Sign | ComplexSign | Expr) → Self¶: Multiplication of self by scalar.

__repr__() → str¶: Return a string representation of self.

__rmul__(scalar: int | float | complex | Sign | ComplexSign | Expr) → Self¶: Multiplication of scalar by self.

__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.

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.

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_type: type[Coeffs[CoeffT]]¶: Get the coefficient container type of self.

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.

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_dense(qubits: int | Qubits | None = None, source: Sequence[float] = (), big_endian: bool = False) → ComplexTermSum[source]¶

Create an instance of cls from a dense vector.

Parameters:

qubits – The qubit register or qubit count.
source – The vector to read from.
big_endian – Whether to use big endian ordering for the resulting matrix. If False, little endian ordering is used. In big (little) endian ordering, the least significant bit in the basis index integer is determined by the last (first) qubit in the register.

Returns:

The constructed instance.

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_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.

property imag_part: RealTermSum¶: Return the imaginary part of self.

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 many terms from an iterable source.

Parameters:: source – Iterable over any term specifiers.

Note

This method operates in-place.

into(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.

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.

property qubits: Qubits¶: Get the qubits corresponding to self.

property real_part: RealTermSum¶: Return the real part of self.

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.

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.

terms_type¶: alias of ComplexTerms

to_dataframe() → DataFrame¶: Convert self to a DataFrame.

to_dense(big_endian: bool = False) → NDArray[complex128][source]¶

Convert self to a dense vector.

Parameters:: big_endian – Whether to use big endian ordering for the resulting matrix. If False, little endian ordering is used. In big (little) endian ordering, the least significant bit in the basis index integer is determined by the last (first) qubit in the register.
Returns:: The dense vector.

to_terms() → Terms[ImplT, SpecT, CoeffT]¶: Get a collection of terms containing the same data as self.

vdot(rhs: ComplexTermSum) → complex[source]¶: Compute the inner product of self with rhs.