ComplexTermSet

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

Bases: TermSet[complex]

A collection of unique 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 set-like operations on them.

Note

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

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

__init__(qubits: int | Qubits = 0)

Initialize the term set.

Parameters:

qubits – The qubit register or qubit count.

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

Iterate over the elements of self.

__len__() → int

Get the number of elements in self.

__repr__() → str

Return a string representation of self.

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

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

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

classmethod from_iterable(iterable: Iterable[Term[ImplT, SpecT, CoeffT] | Cmpnt[ImplT, SpecT] | SpecT | tuple[SpecT | Cmpnt[ImplT, SpecT] | None, CoeffT | None] | None], *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.

insert(key: Term[ImplT, SpecT, CoeffT] | Cmpnt[ImplT, SpecT] | SpecT | tuple[SpecT | Cmpnt[ImplT, SpecT] | None, CoeffT | None] | 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] | None, CoeffT | None] | 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[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_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.

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.

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] | None, CoeffT | None] | 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.

terms_type

alias of ComplexTerms

to_dataframe() → DataFrame

Convert self to a DataFrame.

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

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