qrunch.quantum.groupers.shadow_grouper

Module containing the Shadow Grouping algorithm for Pauli string grouping.

Classes

`ShadowGrouper`	Grouper for grouping pauli strings into groups following the Shadow Grouping algorithm.
`ShadowGrouperOptions`	Options for the ShadowGrouper.

class ShadowGrouper

Bases: MeasurementGrouper

Grouper for grouping pauli strings into groups following the Shadow Grouping algorithm.

Algorithm described in: https://www.nature.com/articles/s41467-024-54859-x

The authors of the original paper also provide an implementation of the algorithm, which can be found here: https://gitlab.com/GreschAI/shadowgrouping

The algorithm iteratively forms measurement groups by taking into account previously generated groups and reweighing Pauli strings based on how well they are already covered by existing groups. As such, specifying the number of measurements to be used can have an impact on the resulting grouping.

This reweighing scheme uses the Bernstein bound as the weight function to prioritize Pauli strings when forming new measurement groups. In principle, functions other than the Bernstein bound can be employed, see original implementation for details.

Ideally the number of groups should be the actual number of measurements that will be performed, but it is also possible to specify a lower number. In practice, the benefit of including more measurements diminishes as the number of measurements increases, and the overhead on a quantum computer means that running running less than 100-1000 shots per groups has limited practical benefit. This can be controlled by the shots_to_group_ratio parameter in the ShadowGrouperOptions, which determines the number of groups

__init__(shot_distributor: ShotDistributor | None = None, options: ShadowGrouperOptions | None = None) → None

Initialize the ShadowGrouper.

Parameters:

options (ShadowGrouperOptions | None) – Options for the ShadowGrouper.
shot_distributor (ShotDistributor | None) – Optional custom shot distributor to use for distributing shots among the groups.

Return type:

None

change_shot_distributor(shot_distributor: ShotDistributor) → MeasurementGrouper | None

Change shot distributor. The identity grouper does not support a shot distributor, so we return None.

Parameters:: shot_distributor (ShotDistributor)
Return type:: MeasurementGrouper | None

group(pauli_sums: Sequence[HermitianPauliSum], shots: int | None, circuit: Circuit | None = None) → tuple[MeasurementGroup, ...]

Group Pauli strings using the ShadowGrouping algorithm.

Parameters:

pauli_sums (Sequence[HermitianPauliSum]) – The Pauli sums to group.
shots (int | None) – Total number of shots available for measurement.
circuit (Circuit | None) – Optional circuit context (unused).

Return type:

tuple[MeasurementGroup, …]

validate_shots_type(shots_type: Type[int | ShotsPerGroup | None]) → list[str]

Validate that the grouper supports the given shots type. Return a list of error messages if not supported.

Parameters:: shots_type (Type[int | ShotsPerGroup | None])
Return type:: list[str]

class ShadowGrouperOptions

Bases: DataclassPublicAPI

Options for the ShadowGrouper.

Parameters:

shots_to_group_ratio – The ratio of shots to groups. Setting, e.g., to 1000 means that the number of groups will be at most total_shots / 1000. However, the actual number of shots allocated to each group will depend on the shot distributor used. (default=1000)
ungrouped_scaling_factor – The scaling factor for the weights of ungrouped Pauli strings. If not specified, the scaling factor will be determined by the algorithm based on the weights of the Pauli strings. (default=None)
saturate_groups – Whether to add all compatible Pauli strings to the groups after the initial grouping is done. (default=False)
qubit_wise – Whether to only consider qubit-wise compatible Pauli strings when saturating groups. This is only relevant if saturate_groups is True. (default=True)

__init__(*, shots_to_group_ratio: int = 1000, ungrouped_scaling_factor: float | None = None, saturate_groups: bool = False, qubit_wise: bool = True) → None

Parameters:

shots_to_group_ratio (int)
ungrouped_scaling_factor (float | None)
saturate_groups (bool)
qubit_wise (bool)

Return type:

None

qubit_wise: bool = True

saturate_groups: bool = False

shots_to_group_ratio: int = 1000

ungrouped_scaling_factor: float | None = None