Utility Functions¶

Utility function implementations.

This module implements the general class for utility functions as well as common utility functions described in the paper.

gadd.utility_functions.normalize_counts(counts: QuasiDistribution | Counts | Dict[str | int, float]) → Dict[str, float][source]¶

Normalize measurement counts into a standardized format.

Converts various count dictionary formats into a consistent representation with bitstring keys and normalized probability values. Handles both integer and string keys, ensuring proper normalization and format standardization.

Parameters:: counts – Measurement counts in QuasiDistribution, Counts, or dict format.
Returns:: Dictionary mapping bitstrings to normalized probabilities.
Raises:: ValueError – If counts format is invalid, empty, or total is non-positive.

class gadd.utility_functions.UtilityFunction[source]¶

Bases: ABC

Abstract base class for DD utility functions used in GADD optimization.

Utility functions quantify the performance of dynamical decoupling sequences by analyzing the measurement outcomes from quantum circuits. They serve as the fitness function for the genetic algorithm, guiding the search toward sequences that maximize computational fidelity or other performance metrics.

The utility function takes measurement counts in various formats and returns a scalar score between 0 and 1, where higher values indicate better performance. The specific computation depends on the target application and desired error suppression goals.

Subclasses must implement the abstract methods to define how measurement outcomes are processed and scored for their specific use case.

abstract compute(counts: QuasiDistribution | Counts | Dict[str | int, float]) → float[source]¶: Compute utility value from measurement counts.

abstract get_name() → str[source]¶: Get the name of the utility function.

verify_state(state: str, counts: Dict[str, float]) → None[source]¶

Verify that a quantum state has the correct format relative to counts.

Parameters:

state – Target state to verify
counts – Normalized count dictionary

Raises:

ValueError – If state format doesn’t match counts format

class gadd.utility_functions.SuccessProbability(target_state: str | int)[source]¶

Bases: UtilityFunction

Utility function measuring success probability for a target quantum state.

This utility function evaluates DD sequence performance by calculating the probability of measuring a specific target state. It is particularly useful for oracular algorithms like Bernstein-Vazirani where the ideal outcome is a single known bitstring, and higher success probability indicates better error suppression.

The function normalizes measurement counts and returns the probability of observing the target state. This provides a direct measure of computational success that can guide the genetic algorithm toward sequences that preserve the desired quantum computation.

Parameters:: target_state – Expected quantum state as binary string or integer. For integer inputs, the value is converted to binary representation.

Example

>>> utility = SuccessProbability("101")
>>> score = utility.compute(measurement_counts)
>>> # Returns probability of measuring |101⟩ state

__init__(target_state: str | int)[source]¶

compute(counts: QuasiDistribution | Counts | Dict[str | int, float]) → float[source]¶

Compute success probability from measurement counts.

Parameters:: counts – Measurement outcomes in various formats
Returns:: Success probability for measuring target state

get_name() → str[source]¶: Get the name of the utility function.

__str__() → str[source]¶: Return human-readable string representation.

class gadd.utility_functions.OneNormDistance(ideal_distribution: Dict[str | int, float])[source]¶

Bases: UtilityFunction

Utility function based on 1-norm distance to an ideal probability distribution.

This utility function measures DD sequence performance by comparing the observed measurement distribution to an ideal target distribution. It computes the 1-norm (total variation) distance and returns 1 minus half the distance, normalized to [0,1] where 1 indicates perfect agreement.

This metric is particularly useful for quantum state preparation tasks where the ideal outcome is a known probability distribution over measurement outcomes, such as GHZ states or other entangled states with well-defined measurement statistics.

The 1-norm distance is calculated as: Σ|p_ideal(k) - p_observed(k)| over all possible measurement outcomes k, providing a comprehensive measure of distributional fidelity.

Parameters:: ideal_distribution – Target probability distribution mapping states to their ideal probabilities. States can be specified as binary strings or integers.

Example

>>> ideal = {"000": 0.5, "111": 0.5}  # GHZ state
>>> utility = OneNormDistance(ideal)
>>> score = utility.compute(measurement_counts)

__init__(ideal_distribution: Dict[str | int, float])[source]¶

compute(counts: QuasiDistribution | Counts | Dict[str | int, float]) → float[source]¶

Compute 1-norm distance between measured and ideal distributions.

Parameters:: counts – Measurement outcomes in various formats
Returns:: 1 - (1/2 * ∑|p(k) - p̂(k)|), normalized to [0,1] where 1 is perfect

get_name() → str[source]¶: Get the name of the utility function.

__str__() → str[source]¶: Return human-readable string representation.

class gadd.utility_functions.GHZUtility(n_qubits: int)[source]¶

Bases: OneNormDistance

Specialized utility function for Greenberger-Horne-Zeilinger state preparation.

This utility function is optimized for evaluating DD sequence performance on GHZ state preparation circuits. GHZ states are maximally entangled states of the form (|00…0⟩ + |11…1⟩)/√2, which should ideally produce equal probability of measuring all-zero or all-one bitstrings.

The function automatically constructs the ideal GHZ distribution for the specified number of qubits and uses the 1-norm distance metric to evaluate how well the observed measurements match this target distribution. This provides a specialized utility function for one of the key benchmarking tasks described in the GADD paper.

Parameters:: n_qubits – Number of qubits in the GHZ state preparation circuit.
Raises:: ValueError – If n_qubits is not positive.

Example

>>> utility = GHZUtility(3)  # For 3-qubit GHZ state
>>> # Expects 50% probability each for |000⟩ and |111⟩

__init__(n_qubits: int)[source]¶

get_name() → str[source]¶: Get the name of the utility function.

__str__() → str[source]¶: Return human-readable string representation.

class gadd.utility_functions.CustomUtility(function: Callable[[Dict[str, float]], float], name: str | None = 'Custom Utility')[source]¶

Bases: UtilityFunction

Wrapper for user-defined custom utility functions.

This class allows users to provide their own utility functions for specialized applications beyond the standard use cases. The custom function receives normalized measurement counts as a dictionary mapping bitstrings to probabilities and should return a scalar utility value.

This flexibility enables GADD optimization for novel quantum algorithms or specialized error suppression goals not covered by the built-in utility functions. The custom function should be deterministic and return values in a consistent range to ensure proper genetic algorithm convergence.

Parameters:

function – Custom function taking normalized counts dict and returning float.
name – Optional descriptive name for the utility function.

Example

>>> def my_utility(counts):
...     return counts.get("000", 0) + 0.5 * counts.get("001", 0)
>>> utility = CustomUtility(my_utility, "Custom Weighting")

__init__(function: Callable[[Dict[str, float]], float], name: str | None = 'Custom Utility')[source]¶

compute(counts: QuasiDistribution | Counts | Dict[str | int, float]) → float[source]¶: Compute utility value from measurement counts.

get_name() → str[source]¶: Get the name of the utility function.

__str__() → str[source]¶: Return human-readable string representation.

class gadd.utility_functions.UtilityFactory[source]¶

Bases: object

Factory class providing convenient creation methods for common utility functions.

This factory simplifies the instantiation of utility functions for common use cases in dynamical decoupling optimization. It provides static methods that encapsulate the parameter setup for standard utility functions, reducing boilerplate code and potential configuration errors.

The factory methods correspond to the main experimental scenarios described in the GADD paper: success probability for oracular algorithms, 1-norm distance for state preparation tasks, GHZ state fidelity for entanglement benchmarks, and custom functions for specialized applications.

Example

>>> # Create utility for Bernstein-Vazirani with target "101"
>>> utility = UtilityFactory.success_probability("101")
>>>
>>> # Create utility for 4-qubit GHZ state
>>> ghz_utility = UtilityFactory.ghz_state(4)

static success_probability(target_state: str | int) → UtilityFunction[source]¶: Create success probability utility function.

static one_norm(ideal_distribution: Dict[str | int, float]) → UtilityFunction[source]¶: Create 1-norm distance utility function.

static ghz_state(n_qubits: int) → UtilityFunction[source]¶: Create GHZ state utility function.

static custom(function: Callable[[Dict[str, float]], float], name: str = 'Custom Utility Function') → UtilityFunction[source]¶: Create custom utility function.