qdk_chemistry.data.term_partition module

Term-partition metadata for QubitOperator.

A TermPartition records how the Pauli terms of a QubitOperator are organised into algorithm- relevant subsets. Concrete subclasses include FlatPartition (single-level groups) and LayeredPartition (group → layer hierarchy).

The partition stores indices into pauli_strings so that it serialises trivially and remains small.

Lifecycle

• The partition is optional metadata. term_partition is None means the partition has not been computed for this Hamiltonian.

• Transformations that change the term ordering or qubit support (for example to_interleaved()) must reset the partition to None on the new Hamiltonian.

• Algorithms that consume a partition should treat its presence as an explicit signal to exploit it (for example, by applying schedule-level Suzuki recursion or grouping measurements by basis).

class qdk_chemistry.data.term_partition.FlatPartition(*, strategy, groups)

Bases: TermPartition

Single-level partition: each group is a list of term indices.

Suitable for algorithms that only care about which terms belong together (for example, qubit-wise commuting groups for measurement basis selection).

The groups field is a tuple of groups; each group is a tuple of term indices into pauli_strings.

Raises:

TypeError – If groups is not a sequence of sequences of integers.

Parameters:

• strategy (str)

• groups (tuple[tuple[int, ...], ...])

__init__(*, strategy, groups)

Initialize a flat partition.

Parameters:

• strategy (str) – Label identifying how the partition was produced.

• groups (tuple[tuple[int, ...], ...]) – Tuple of groups; each group is a tuple of term indices.

Return type:

None

property num_groups: int

Return the number of groups.

all_indices()

Return every term index referenced by the partition, in order.

Return type:

list[int]

get_summary()

Return a summary of the flat partition.

Return type:

str

to_json()

Return a JSON-serialisable dict of this FlatPartition.

Return type:

dict[str, Any]

class qdk_chemistry.data.term_partition.LayeredPartition(*, strategy, groups)

Bases: TermPartition

Two-level partition: each group is a sequence of parallelisable layers.

Suitable for Trotter-style decompositions where the outer level controls Strang/Suzuki splitting order and the inner level groups operators with disjoint qubit supports that can be applied in parallel.

The groups field is a nested tuple (group, layer, term_index): outer = groups, middle = layers within a group, inner = term indices into pauli_strings.

Raises:

TypeError – If groups is not the expected nested-sequence shape.

Parameters:

• strategy (str)

• groups (tuple[tuple[tuple[int, ...], ...], ...])

__init__(*, strategy, groups)

Initialize a layered partition.

Parameters:

• strategy (str) – Label identifying how the partition was produced.

• groups (tuple[tuple[tuple[int, ...], ...], ...]) – Nested tuple (group, layer, term_index).

Return type:

None

property num_groups: int

Return the number of top-level groups.

num_layers(group_index)

Return the number of parallelisable layers in group_index.

Return type:

int

Parameters:

group_index (int)

all_indices()

Return every term index referenced by the partition, in order.

Return type:

list[int]

get_summary()

Return a summary of the layered partition.

Return type:

str

to_json()

Return a JSON-serialisable dict of this LayeredPartition.

Return type:

dict[str, Any]

class qdk_chemistry.data.term_partition.TermPartition(*, strategy)

Bases: DataClass

Base class for index-based partitions of Hamiltonian terms.

Use FlatPartition for single-level partitions or LayeredPartition for hierarchical (group → layer) partitions.

The strategy field is a free-form label identifying how the partition was produced (for example "geometry_coloring", "commuting", "qubit_wise_commuting").

Parameters:

strategy (str)

__init__(*, strategy)

Initialize the term partition.

Parameters:

strategy (str) – Label identifying how the partition was produced.

Return type:

None

property num_groups: int

Return the number of top-level groups in the partition.

all_indices()

Return every term index referenced by the partition, in order.

Return type:

list[int]

get_summary()

Return a summary of the partition.

Return type:

str

to_json()

Convert this partition to a JSON-serialisable dictionary.

Return type:

dict[str, Any]

to_hdf5(group)

Save this partition to an HDF5 group.

Return type:

None

static from_json(data)

Reconstruct a TermPartition from to_json() output.

Return type:

TermPartition

Parameters:

data (dict[str, Any]) – Dict produced by to_json() of either FlatPartition or LayeredPartition.

Returns:

The reconstructed partition.

Raises:

ValueError – If data["kind"] is not a recognised partition kind.

classmethod from_hdf5(group)

Load a TermPartition from an HDF5 group.

Return type:

TermPartition