braket.experimental.algorithms.adaptive_shot_allocation.adaptive_allocator module

braket.experimental.algorithms.adaptive_shot_allocation.adaptive_allocator.MeasurementData

Helper functions for Pauli operator commutation and Bayesian statistics calculations. These functions support the AdaptiveShotAllocator class.

alias of List[List[Dict[Tuple[int, int], int]]]

braket.experimental.algorithms.adaptive_shot_allocation.adaptive_allocator.commute(a: str, b: str, qwc: bool = True) → bool

Check if two Pauli strings commute.

Parameters:

• a (str) – First Pauli string (e.g., “IXYZ”)

• b (str) – Second Pauli string

• qwc (bool) – If True, use qubit-wise commutation rules. If False, use general commutation rules.

Returns:

bool – True if the Pauli strings commute, False otherwise

Raises:

ValueError – If the Pauli strigns are of different length.

braket.experimental.algorithms.adaptive_shot_allocation.adaptive_allocator.qwc_commute(a: str, b: str, *, qwc: bool = True) → bool

Check if two Pauli strings commute.

Parameters:

• a (str) – First Pauli string (e.g., “IXYZ”)

• b (str) – Second Pauli string

• qwc (bool) – If True, use qubit-wise commutation rules. If False, use general commutation rules.

Returns:

bool – True if the Pauli strings commute, False otherwise

Raises:

ValueError – If the Pauli strigns are of different length.

braket.experimental.algorithms.adaptive_shot_allocation.adaptive_allocator.gen_commute(a: str, b: str, *, qwc: bool = False) → bool

Check if two Pauli strings commute.

Parameters:

• a (str) – First Pauli string (e.g., “IXYZ”)

• b (str) – Second Pauli string

• qwc (bool) – If True, use qubit-wise commutation rules. If False, use general commutation rules.

Returns:

bool – True if the Pauli strings commute, False otherwise

Raises:

ValueError – If the Pauli strigns are of different length.

braket.experimental.algorithms.adaptive_shot_allocation.adaptive_allocator.term_variance_estimate(term_idx: int, measurements: List[List[Dict[Tuple[int, int], int]]] | None = None) → float

Estimate variance for a single Pauli term. See Eq 14 in Appendix B of “Adaptive Estimation of Quantum Observables (arXiv:2110.15339v6)

Parameters:

• term_idx (int) – Index of the Pauli term

• measurements (List[List[Dict]], optional) – Measurement outcomes

Returns:

float – Estimated variance for the term

braket.experimental.algorithms.adaptive_shot_allocation.adaptive_allocator.terms_covariance_estimate(i: int, j: int, measurements: List[List[Dict[Tuple[int, int], int]]] | None = None) → float

Estimate covariance between two Pauli terms. See Eq 25-6 in Appendix B of “Adaptive Estimation of Quantum Observables (arXiv:2110.15339v6)

Parameters:

• i (int) – Index of first Pauli term

• j (int) – Index of second Pauli term

• measurements (List[List[Dict]], optional) – Measurement outcomes

Returns:

float – Estimated covariance between terms

class braket.experimental.algorithms.adaptive_shot_allocation.adaptive_allocator.AdaptiveShotAllocator(paulis: List[str], coeffs: List[float])

Bases: object

A class for adaptive measurement allocation in expectation value calculations.

This class manages a Hamiltonian encoded as a graph of commuting Pauli operators, and estimates measurement covariances in clique measurements, to reduce the variance of an expectation value calculation. It uses a graph-based approach where: - Nodes represent Pauli terms - Edges connect commuting terms - Terms are grouped into cliques for simultaneous measurement - Shot allocation is optimized based on (estimation of) clique error contributions

num_terms

Number of Pauli terms in the Hamiltonian

Type:

int

paulis

List of Pauli string representations

Type:

List[str]

coeffs

Coefficients for each Pauli term

Type:

List[float]

graph

Graph representing commuting relationships

Type:

nx.Graph

cliq

List of cliques for measurement grouping

Type:

List[List[int]]

measurements

Measurement outcomes for term pairs “measurements[i][j][key]” is the nuber of times paulis[i] and paulis[j] have been measured together and produced the tuple “key” (one of the four possible outcomes (1,1), (1,-1), (-1, 1) and (-1,-1)). Note that measurements[i][j][key] should be non-zero only if i and j are in the same clique. In practice, measurements[i][j] is never referenced if i and j are not members of the same clique.

Type:

MeasurementData

shots

Number of shots allocated to each clique

Type:

Union[List[int], None]

Initialize the AdaptiveShotAllocator with Pauli terms and their coefficients.

Parameters:

• paulis (List[str]) – List of Pauli string representations (e.g., “IXYZ”)

• coeffs (List[float]) – Corresponding coefficients for each Pauli term

Raises:

• ValueError – If number of Paulis doesn’t match number of coefficients

• ValueError – If any Pauli string contains invalid characters

cliq: List[List[int]]

measurements: List[List[Dict[Tuple[int, int], int]]]

shots: List[int] | None

num_terms: int

paulis: List[str]

coeffs: List[float]

graph: Graph

reset()

Reset the measurement data and shot allocation. This would be used e.g. when changing the state on which the Hamiltonian expectation value is calculated.

This method: - Reinitializes the measurement counts matrix - Clears shot allocation history - Updates graph weights to initial values

visualize_graph(node_size: int = 1230, font_size: int = 10, show_cliques: bool = True) → None

Visualize the graph with colored edges based on clique membership.

Parameters:

• node_size (int) – Size of nodes in the visualization

• font_size (int) – Size of font for node labels

• show_cliques (bool) – If True, color edges by clique membership. If False, show all edges in the graph.

incremental_shot_allocation(num_shots: int) → List[int]

Propose allocation of measurement shots to cliques using greedy minimization of the estimated error.

The allocation strategy minimizes the estimated total variance by: 1. Calculating the contribution from each clique based on current shots 2. Allocating shots one at a time to the clique with highest contribution 3. Updating the estimates after each shot allocation

This greedy approach ensures that each new shot is allocated to the clique that will provide the largest reduction in the total error estimate.

Parameters:

num_shots (int) – Total number of new shots to propose allocating across cliques

Returns:

List[int] –

Proposed number of new shots for each clique, where the index

corresponds to the clique index and the value is the number of new shots proposed for that clique.

Raises:

• ValueError – If num_shots is not a positive integer

• RuntimeError – If graph weights have not been properly initialized

error_estimate() → float

Calculate the estimated standard error of the energy expectation value.

The error is computed as sqrt(sum(variance/shots)) where: - variance comes from the weighted covariance matrix (product of coefficients

and estimated variances/covariances)

• shots is the number of measurements for each clique

Returns:

float –

Estimated standard error based on current shot allocation

and measurement statistics.

Raises:

• RuntimeError – If no shots have been allocated yet

• ValueError – If graph weights have not been properly initialized

expectation_from_measurements(measurements: List[List[Dict[Tuple[int, int], int]]] | None = None) → float

Calculate the energy expectation value from measurement results for the different Pauli string observables.

For each Pauli term, computes <P> = (N++ - N–)/N_total where: - N++ is the count of +1 measurements - N– is the count of -1 measurements - N_total is the total number of measurements

Parameters:

measurements (Optional[List[List[Dict]]]) – Measurement outcomes to use. If None, uses the instance’s measurements.

Returns:

float – Estimated expectation value of the Hamiltonian

Raises:

AssertionError – If invalid measurement combinations are found

shots_from_measurements(measurements: List[List[Dict[Tuple[int, int], int]]]) → List[int]

Extract the number of shots allocated to each clique from measurement data.

Parameters:

measurements (List[List[Dict]]) – Measurement data to analyze

Returns:

List[int] – Number of shots for each clique

Note

Validates measurements before extracting shot counts to ensure data consistency.

update_measurements(new_measurements: List[List[Dict[Tuple[int, int], int]]]) → None

Update the allocator with a new set of measurements.

Parameters:

new_measurements (List[List[Dict]]) – New measurement outcomes to incorporate. Must follow the same structure as self.measurements: - List[List[Dict]] where each Dict contains measurement outcomes - Dict keys are tuples (±1, ±1) representing measurement results - Dict values are counts of those results