add string representations and update fixtures

Author: coruscating

README.md

@@ -9,15 +9,6 @@
 
 **GADD** is a Python package for empirically optimizing dynamical decoupling (DD) sequences on quantum processors using a genetic algorithm as described in the research paper ["Empirical learning of dynamical decoupling on quantum processors"](https://arxiv.org/abs/2403.02294).
 
-## Key Features
-
-- **Empirical Optimization**: Learn DD sequences directly from quantum hardware feedback
-- **Hardware Agnostic**: Works with any quantum backend that supports Qiskit
-- **Genetic Algorithm**: Efficient search through large DD sequence spaces
-- **Multiple Utility Functions**: Built-in metrics for various quantum applications
-- **Comparative Analysis**: Benchmark against standard DD sequences (XY4, CPMG, EDD, URDD)
-- **Comprehensive Results**: Detailed training progression and performance analytics
-
 ## Installation
 
 ### Requirements
@@ -30,6 +21,8 @@ This package is designed to be used with [Qiskit](https://github.com/Qiskit/qisk
 pip install gadd
 ```
 
+To install optional dependencies for developing the package and building documentation, run `pip install gadd[dev]` and `pip install gadd[docs]` respectively.
+
 ### Install from Source
 
 ```bash

gadd/circuit_padding.py

@@ -8,6 +8,7 @@
 from typing import List, Dict, Optional
 import numpy as np
 from qiskit import QuantumCircuit
+from qiskit.providers import BackendV2 as Backend
 from qiskit.circuit import Instruction, Gate, Delay
 from qiskit.circuit.library import IGate, RXGate, RYGate, RZGate
 from qiskit.transpiler import InstructionDurations, PassManager
@@ -54,21 +55,53 @@ def __repr__(self):
 
 
 def get_instruction_duration(
-    instruction: Instruction, qubits: List[int], unit: str = "dt", dt: float = 1.0
+    instruction: Instruction,
+    qubits: List[int],
+    backend: Optional[Backend] = None,
+    unit: str = "dt",
+    dt: float = 0.222e-9,
 ) -> float:
     """
-    Get duration of an instruction.
+    Get duration of an instruction from backend or defaults.
 
     Args:
-        instruction: The instruction to get duration for
-        qubits: Qubits the instruction acts on
-        unit: Time unit ('dt' or 's')
-        dt: Duration of a single dt in seconds
+        instruction: The instruction to get duration for.
+        qubits: Qubits the instruction acts on.
+        backend: Backend to get durations from.
+        unit: Time unit ('dt' or 's').
+        dt: Duration of a single dt in seconds.
 
     Returns:
-        Duration in specified units
+        Duration in specified units.
     """
-    # Default durations in dt units (these should be calibrated for actual backend)
+    # Handle delay specially
+    if isinstance(instruction, Delay):
+        duration = instruction.duration
+        if instruction.unit == "dt":
+            return duration if unit == "dt" else duration * dt
+        else:  # assumes 's'
+            return duration / dt if unit == "dt" else duration
+
+    # Try to get from backend first
+    if backend is not None:
+        try:
+            if hasattr(backend, "instruction_durations"):
+                durations = backend.instruction_durations
+            else:
+                durations = InstructionDurations.from_backend(backend)
+
+            gate_name = instruction.name.lower()
+            if len(qubits) == 1:
+                duration_dt = durations.get(gate_name, qubits[0], "dt")
+            else:
+                duration_dt = durations.get(gate_name, qubits, "dt")
+
+            if duration_dt is not None:
+                return duration_dt if unit == "dt" else duration_dt * dt
+        except:
+            pass  # Fall back to defaults
+
+    # Default durations in dt units
     default_durations = {
         "id": 0,  # Identity is virtual
         "x": 160,  # Single-qubit gate
@@ -79,21 +112,16 @@ def get_instruction_duration(
         "rx": 160,
         "ry": 160,
         "rz": 0,  # RZ is virtual
+        "u1": 0,  # U1 is virtual
+        "u2": 160,
+        "u3": 160,
         "cx": 800,  # Two-qubit gate
         "cz": 800,
+        "ecr": 800,
         "measure": 4000,  # Measurement
-        "delay": None,  # Delay has variable duration
+        "reset": 1000,
     }
 
-    # Handle delay specially
-    if isinstance(instruction, Delay):
-        duration = instruction.duration
-        if instruction.unit == "dt":
-            return duration if unit == "dt" else duration * dt
-        else:  # assumes 's'
-            return duration / dt if unit == "dt" else duration
-
-    # Get duration for standard gates
     gate_name = instruction.name.lower()
     duration_dt = default_durations.get(gate_name, 160)  # Default single-qubit duration
 
@@ -107,6 +135,7 @@ def apply_dd_strategy(
     circuit: QuantumCircuit,
     strategy: DDStrategy,
     coloring: Dict[int, int],
+    backend: Optional["Backend"] = None,
     instruction_durations: Optional[InstructionDurations] = None,
     min_idle_duration: int = 64,
     staggered: bool = False,
@@ -118,6 +147,7 @@ def apply_dd_strategy(
         circuit: Original quantum circuit.
         strategy: DD strategy containing sequences for each color.
         coloring: Mapping from qubit to color.
+        backend: Optional backend for extracting instruction durations.
         instruction_durations: Backend-specific instruction durations.
         min_idle_duration: Minimum idle duration to insert DD.
         staggered: Whether to apply CR-aware staggering for crosstalk suppression.
@@ -134,7 +164,13 @@ def apply_dd_strategy(
 
     # Get default durations if not provided
     if instruction_durations is None:
-        instruction_durations = InstructionDurations()
+        if backend is not None:
+            try:
+                instruction_durations = InstructionDurations.from_backend(backend)
+            except:
+                instruction_durations = InstructionDurations()
+        else:
+            instruction_durations = InstructionDurations()
 
     # Get unique colors and sort them
     unique_colors = sorted(set(coloring.values()))
@@ -179,13 +215,17 @@ def get_staggered_spacing(
             continue
 
         # Convert sequence gates to Qiskit gates
+        # Include identity gates as Delay operations to maintain sequence structure
         dd_gates = []
         for gate_name in dd_sequence.gates:
-            if gate_name not in ["I", "Ip", "Im"]:  # Skip identity gates
-                pulse = DDPulse(gate_name, 0, 0)  # Qubit and time don't matter here
-                dd_gates.append(pulse.to_gate())
-
-        if not dd_gates:
+            pulse = DDPulse(gate_name, 0, 0)  # Qubit and time don't matter here
+            dd_gates.append(pulse.to_gate())
+
+        if not dd_gates or len(dd_gates) % 2 == 1:
+            # Skip sequences that don't have even number of gates
+            print(
+                f"Warning: Skipping DD sequence for color {color} - odd number of gates ({len(dd_gates)})"
+            )
             continue
 
         # Get spacing for this color if staggered

gadd/gadd.py

@@ -96,6 +96,22 @@ def from_dict(cls, data: Dict[str, Any]) -> "TrainingConfig":
             data["decoupling_group"] = DecouplingGroup(**group_data)
         return cls(**data)
 
+    def __str__(self) -> str:
+        """Return human-readable string representation."""
+        lines = [
+            "GADD Training Configuration:",
+            f"  Population size: {self.pop_size}",
+            f"  Sequence length: {self.sequence_length}",
+            f"  Iterations: {self.n_iterations}",
+            f"  Colors: {self.num_colors}",
+            f"  Shots per evaluation: {self.shots}",
+            f"  Mutation probability: {self.mutation_probability}",
+            f"  Mode: {self.mode}",
+        ]
+        if self.dynamic_mutation:
+            lines.append(f"  Dynamic mutation: enabled (decay={self.mutation_decay})")
+        return "\n".join(lines)
+
 
 @dataclass
 class TrainingState:
@@ -135,6 +151,34 @@ def to_dict(self) -> Dict[str, Any]:
         result_dict["config"] = self.config.to_dict()
         return result_dict
 
+    def __str__(self) -> str:
+        """Return human-readable string representation."""
+        lines = [
+            "GADD Training Results:",
+            f"  Best score: {self.best_score:.4f}",
+            f"  Training time: {self.training_time:.1f}s",
+            f"  Iterations completed: {len(self.iteration_data)}",
+        ]
+
+        if self.iteration_data:
+            first_score = self.iteration_data[0]["best_score"]
+            improvement = self.best_score - first_score
+            lines.append(f"  Score improvement: +{improvement:.4f}")
+
+        if self.comparison_data:
+            lines.append(
+                f"  Compared against {len(self.comparison_data)} standard sequences"
+            )
+            best_standard = max(self.comparison_data.values())
+            advantage = self.best_score - best_standard
+            if advantage > 0:
+                lines.append(f"  Advantage over best standard: +{advantage:.4f}")
+
+        lines.append(f"\nBest sequence found:")
+        lines.append(f"  {self.best_sequence}")
+
+        return "\n".join(lines)
+
 
 class GADD:
     """Genetic Algorithm for Dynamical Decoupling optimization."""
@@ -240,6 +284,8 @@ def apply_dd(
         # Use provided backend or fall back to instance backend
         backend = backend or self._backend
 
+        print("strategy", strategy)
+
         # Get coloring for the circuit
         if self._coloring is not None:
             coloring_dict = self._coloring.to_dict()
@@ -254,7 +300,10 @@ def apply_dd(
         instruction_durations = None
         if backend:
             try:
-                instruction_durations = InstructionDurations.from_backend(backend)
+                if hasattr(backend, "instruction_durations"):
+                    instruction_durations = backend.instruction_durations
+                else:
+                    instruction_durations = InstructionDurations.from_backend(backend)
             except:
                 pass
 
@@ -263,6 +312,7 @@ def apply_dd(
             target_circuit,
             strategy,
             coloring_dict,
+            backend=backend,
             instruction_durations=instruction_durations,
             staggered=staggered,
         )

gadd/strategies.py

@@ -77,6 +77,9 @@ def __post_init__(self):
             if gate not in valid_gates:
                 raise ValueError(f"Invalid gate: {gate}. Must be one of {valid_gates}")
 
+    def __str__(self) -> str:
+        return "-".join(self.gates)
+
     def __len__(self):
         return len(self.gates)
 
@@ -211,6 +214,19 @@ def get_sequence(self, color: int) -> DDSequence:
     def __len__(self) -> int:
         return len(self.sequences)
 
+    def __str__(self) -> str:
+        if len(self.sequences) == 1:
+            # Single sequence case
+            seq = next(iter(self.sequences.values()))
+            return f"DD Strategy: {seq}"
+        else:
+            # Multi-color case
+            lines = [f"DD Strategy ({len(self.sequences)} colors):"]
+            for color in sorted(self.sequences.keys()):
+                seq = self.sequences[color]
+                lines.append(f"  Color {color}: {seq}")
+            return "\n".join(lines)
+
     def to_dict(self) -> Dict[str, any]:
         """Convert strategy to dictionary for serialization."""
         return {
@@ -271,6 +287,51 @@ def __init__(
         # Create reverse mapping for efficiency
         self._qubit_to_color = self._color_map.copy()
 
+    def __str__(self) -> str:
+        """Return human-readable string representation."""
+        lines = [f"Qubit Coloring ({self.n_colors} colors):"]
+        for color in sorted(self.assignments.keys()):
+            qubits = self.assignments[color]
+            qubit_ranges = self._format_qubit_ranges(qubits)
+            lines.append(f"  Color {color}: {qubit_ranges}")
+        return "\n".join(lines)
+
+    def _format_qubit_ranges(self, qubits: List[int]) -> str:
+        """Format qubit list as ranges where possible."""
+        if not qubits:
+            return "[]"
+
+        sorted_qubits = sorted(qubits)
+        if len(sorted_qubits) <= 3:
+            return str(sorted_qubits)
+
+        # Try to find consecutive ranges
+        ranges = []
+        start = sorted_qubits[0]
+        end = start
+
+        for i in range(1, len(sorted_qubits)):
+            if sorted_qubits[i] == end + 1:
+                end = sorted_qubits[i]
+            else:
+                if end == start:
+                    ranges.append(str(start))
+                elif end == start + 1:
+                    ranges.append(f"{start},{end}")
+                else:
+                    ranges.append(f"{start}-{end}")
+                start = end = sorted_qubits[i]
+
+        # Add final range
+        if end == start:
+            ranges.append(str(start))
+        elif end == start + 1:
+            ranges.append(f"{start},{end}")
+        else:
+            ranges.append(f"{start}-{end}")
+
+        return "[" + ",".join(ranges) + "]"
+
     @classmethod
     def from_circuit(cls, circuit: QuantumCircuit) -> "ColorAssignment":
         """

gadd/utility_functions.py

@@ -148,6 +148,10 @@ def compute(self, counts: CountsType) -> float:
     def get_name(self) -> str:
         return f"Success Probability (|{self._target}⟩)"
 
+    def __str__(self) -> str:
+        """Return human-readable string representation."""
+        return f"Success probability for |{self._target}⟩"
+
 
 class OneNormDistance(UtilityFunction):
     """Utility function based on 1-norm distance to ideal distribution."""
@@ -190,6 +194,17 @@ def compute(self, counts: CountsType) -> float:
     def get_name(self) -> str:
         return "1-Norm Distance"
 
+    def __str__(self) -> str:
+        """Return human-readable string representation."""
+        ideal_states = [
+            state for state, prob in self.ideal_distribution.items() if prob > 0.01
+        ]
+        if len(ideal_states) <= 3:
+            states_str = ", ".join(f"|{state}⟩" for state in ideal_states)
+        else:
+            states_str = f"{len(ideal_states)} target states"
+        return f"1-norm fidelity to {states_str}"
+
 
 class GHZUtility(OneNormDistance):
     """Specialized utility function for GHZ states."""
@@ -209,6 +224,11 @@ def __init__(self, n_qubits: int):
     def get_name(self) -> str:
         return "GHZ State Fidelity"
 
+    def __str__(self) -> str:
+        """Return human-readable string representation."""
+        n_qubits = len(next(iter(self.ideal_distribution.keys())))
+        return f"GHZ state fidelity ({n_qubits} qubits)"
+
 
 class CustomUtility(UtilityFunction):
     """Wrapper for custom utility functions provided by users."""
@@ -234,6 +254,10 @@ def compute(self, counts: CountsType) -> float:
     def get_name(self) -> str:
         return self._name
 
+    def __str__(self) -> str:
+        """Return human-readable string representation."""
+        return f"Custom Utility {self._name}"
+
 
 class UtilityFactory:
     """Factory class for creating common utility functions."""