qdk_chemistry.algorithms.term_grouper package

Term-grouper algorithms for QubitOperator.

A term grouper takes a QubitOperator and returns a new one with a populated term_partition that downstream algorithms can exploit.

Example

>>> from qdk_chemistry.algorithms import registry
>>> grouper = registry.create("term_grouper", "qubit_wise_commuting")
>>> grouped = grouper.run(my_hamiltonian)
>>> grouped.term_partition  # FlatPartition with strategy="qubit_wise_commuting"
class qdk_chemistry.algorithms.term_grouper.FullCommutingTermGrouper

Bases: TermGrouper

Group terms by full Pauli commutation ([P_i, P_j] = 0).

The resulting FlatPartition stores a QubitOperator partition where every pair of terms in the same group commutes globally. Useful for Trotter-style decompositions, which can exponentiate a commuting block as a single ordered product without splitting error.

name()

Return commuting as the algorithm name.

Return type:

str

class qdk_chemistry.algorithms.term_grouper.IdentityTermGrouper

Bases: TermGrouper

Trivial grouper — every term is placed in its own single-element group.

Useful to clear an existing term_partition while still passing through the standard term_grouper interface, or to disable downstream group-aware optimisation in a controlled way.

name()

Return identity as the algorithm name.

Return type:

str

class qdk_chemistry.algorithms.term_grouper.QubitWiseCommutingTermGrouper

Bases: TermGrouper

Group terms by qubit-wise commutation.

Two labels qubit-wise commute when, on every qubit position, the two single-qubit Paulis individually commute (i.e. one is identity or both are equal). All members of a group can be measured in a single basis, which is the property exploited by QdkExpectationEstimator for measurement-cost reduction.

name()

Return qubit_wise_commuting as the algorithm name.

Return type:

str

class qdk_chemistry.algorithms.term_grouper.TermGrouper

Bases: Algorithm

Abstract base class for algorithms that partition Hamiltonian terms.

A TermGrouper consumes a QubitOperator and returns a new QubitOperator whose term_partition is populated with the grouping computed by the strategy.

Subclasses implement _run_impl, which must return a new QubitOperator (the input must not be mutated).

__init__()

Initialise the term grouper with default settings.

type_name()

Return term_grouper as the algorithm type name.

Return type:

str

class qdk_chemistry.algorithms.term_grouper.TermGrouperFactory

Bases: AlgorithmFactory

Factory for TermGrouper instances.

algorithm_type_name()

Return term_grouper as the algorithm type name.

Return type:

str

default_algorithm_name()

Return commuting as the default term-grouper algorithm.

Return type:

str

class qdk_chemistry.algorithms.term_grouper.TermGrouperSettings

Bases: Settings

Settings for term-grouper algorithms.

__init__()

Initialise default term-grouper settings (currently empty).

class qdk_chemistry.algorithms.term_grouper.VacuumAnnihilatingTermGrouper

Bases: TermGrouper

Group Pauli terms whose weighted amplitudes cancel on \(|0\ldots0\rangle\).

Only terms sharing a flipped-qubit set reach the same basis state \(|b_F\rangle\), so they are the only ones whose amplitudes can cancel. Each set has to satisfy \(\sum_j c_j\, P_j\, |0\ldots0\rangle = 0\) to within tolerance, otherwise grouping fails with a ValueError. A certified set is then cut wherever its running sum vanishes exactly, so every group but the last cancels on its own and the last carries the tolerated residual. Diagonal (\(I\)/\(Z\)) strings only phase the vacuum, which a consumer can correct for, so they form one group whose sum is left unconstrained.

Groups hold a single \(Y\)-count parity, which makes their members commute: two strings sharing a flipped-qubit set disagree only inside it, and the number of such positions has parity \(n_Y^{(a)} + n_Y^{(b)} \bmod 2\). No cancellation is lost, since with real coefficients the even-parity terms contribute \(\pm 1\) and the odd-parity ones \(\pm i\), so the two sub-sums are the real and imaginary parts of the total.

The motivating case is fermionic chemistry, where each excitation annihilates the all-zero reference only through the weighted sum of its Pauli strings, which is the ordering the ControlledSwapPauliSequenceMapper requires.

__init__()

Initialise the VacuumAnnihilatingTermGrouper.

name()

Return vacuum_annihilating as the algorithm name.

Return type:

str

class qdk_chemistry.algorithms.term_grouper.VacuumAnnihilatingTermGrouperSettings

Bases: TermGrouperSettings

Settings for the VacuumAnnihilatingTermGrouper.

tolerance

Absolute tolerance on the vacuum amplitude of a flipped-qubit set.

__init__()

Initialise the settings for VacuumAnnihilatingTermGrouper.

Submodules