experiments.md

Experiments Guide

This guide covers how to use and create experiments in LeeQ with EPII v0.2.0 integration.

EPII v0.2.0 Integration

LeeQ experiments now integrate seamlessly with EPII v0.2.0 for backend-aware discovery and execution.

Using ExperimentRouter

from leeq.epii.experiments import ExperimentRouter

# Initialize router with your setup for backend-aware filtering
router = ExperimentRouter(setup=my_setup)

# Discover available experiments
experiments = router.list_experiments()
print(f"Found {len(experiments)} experiments")

# Get experiment by canonical name
experiment_class = router.get_experiment("calibrations.NormalisedRabi")

Canonical Naming Convention

All experiments use module-qualified canonical names:

• Calibrations: calibrations.NormalisedRabi, calibrations.SimpleRamseyMultilevel
• Characterizations: characterizations.SimpleT1, characterizations.SpinEchoMultiLevel
• Multi-Qubit: multi_qubit_gates.CrossResonanceCalibration

Constructor-Only Execution Pattern

Important: Always pass parameters to the constructor - never call run() methods directly:

# CORRECT: Constructor-only pattern
exp = QubitSpectroscopyFrequency(
    dut_qubit=qubit,
    start=4900.0,
    stop=5100.0,
    step=2.0,
    num_avs=1000
)
# Experiment automatically executes based on setup type

# INCORRECT: Never do this
exp = QubitSpectroscopyFrequency()
exp.run_simulated(...)  # WRONG - never call run methods directly

Built-in Experiments

LeeQ provides a comprehensive library of built-in experiments for quantum system characterization and calibration.

Basic Calibrations

Resonator Spectroscopy

from leeq.experiments.builtin.basic.calibrations.resonator_spectroscopy import *

# Find resonator frequency
exp = ResonatorSweepTransmissionWithExtraInitialLPB(
    dut,                    # Your quantum element
    start=9.98,            # Start frequency (GHz)
    stop=10.02,            # Stop frequency (GHz) 
    step=0.001,            # Step size (GHz)
    num_avs=1000,          # Number of averages
    mp_width=8             # Measurement pulse width (μs)
)
result = exp.run()

Qubit Spectroscopy

from leeq.experiments.builtin.basic.calibrations.qubit_spectroscopy import *

# Find qubit frequency
exp = QubitSpectroscopy(
    dut,
    start=4.8,             # Start frequency (GHz)
    stop=4.9,              # Stop frequency (GHz)
    step=0.001,            # Step size (GHz)
    num_avs=500
)
result = exp.run()

Rabi Oscillations

from leeq.experiments.builtin.basic.calibrations.rabi import *

# Power Rabi - find π pulse amplitude
exp = PowerRabi(
    dut,
    start=0.0,             # Start amplitude
    stop=0.3,              # Stop amplitude  
    step=0.005,            # Step size
    num_avs=500
)

# Time Rabi - find π pulse width
exp = TimeRabi(
    dut,
    start=0.01,            # Start width (μs)
    stop=0.1,              # Stop width (μs)
    step=0.001,            # Step size (μs)
    num_avs=500
)

Ramsey Fringes

from leeq.experiments.builtin.basic.calibrations.ramsey import *

# Ramsey experiment for frequency calibration
exp = Ramsey(
    dut,
    start=0.0,             # Start delay (μs)
    stop=10.0,             # Stop delay (μs)
    step=0.1,              # Step size (μs)
    detuning=0.5,          # Detuning frequency (MHz)
    num_avs=500
)

DRAG Calibration

from leeq.experiments.builtin.basic.calibrations.drag import *

# Calibrate DRAG coefficient
exp = DragCalibration(
    dut,
    start=-2.0,            # Start DRAG coefficient
    stop=2.0,              # Stop DRAG coefficient
    step=0.1,              # Step size
    num_avs=500
)

Characterization Experiments

T1 (Energy Relaxation Time)

from leeq.experiments.builtin.basic.characterizations.t1 import *

exp = T1Measurement(
    dut,
    start=0.0,             # Start delay (μs)
    stop=100.0,            # Stop delay (μs)
    step=2.0,              # Step size (μs)
    num_avs=500
)
result = exp.run()
print(f"T1 = {result.fit_params['T1']:.2f} μs")

T2 (Dephasing Time)

from leeq.experiments.builtin.basic.characterizations.t2 import *

# T2* measurement (free induction decay)
exp = T2StarMeasurement(
    dut,
    start=0.0,             # Start delay (μs)
    stop=50.0,             # Stop delay (μs)
    step=0.5,              # Step size (μs)
    num_avs=500
)

# T2 Echo measurement (Hahn echo)
exp = T2EchoMeasurement(
    dut,
    start=0.0,
    stop=100.0,
    step=1.0,
    num_avs=500
)

Randomized Benchmarking

from leeq.experiments.builtin.basic.characterizations.randomized_benchmarking import *

# Single qubit randomized benchmarking
exp = SingleQubitRandomizedBenchmarking(
    dut,
    sequence_lengths=[1, 5, 10, 25, 50, 100, 200],
    num_sequences=20,      # Number of random sequences per length
    num_avs=500
)
result = exp.run()
print(f"Gate fidelity = {result.fit_params['fidelity']:.4f}")

Multi-Qubit Experiments

Two-Qubit Calibrations

from leeq.experiments.builtin.multi_qubit_gates import *

# Conditional Stark shift calibration
exp = ConditionalStarkShiftContinuous(
    control_qubit=dut1,
    target_qubit=dut2,
    start_frequency=4.85,
    stop_frequency=4.87,
    step=0.001,
    num_avs=500
)

# Cross-resonance calibration  
exp = CrossResonanceCalibration(
    control_qubit=dut1,
    target_qubit=dut2,
    start_amplitude=0.0,
    stop_amplitude=0.1,
    step=0.002,
    num_avs=500
)

State Discrimination

Gaussian Mixture Model (GMM)

from leeq.experiments.builtin.basic.calibrations.state_discrimination import *

# Calibrate measurement discrimination
exp = MeasurementCalibrationMultilevelGMM(
    dut,
    mprim_index=0,         # Measurement primitive index
    sweep_lpb_list=[       # States to prepare and measure
        dut.get_c1('f01')['I'],  # |0⟩ state
        dut.get_c1('f01')['X']   # |1⟩ state  
    ],
    num_avs=1000
)

Custom Experiments

Creating Your Own Experiment

All experiments inherit from the base experiment class:

from leeq.experiments.experiments import Experiment

class MyCustomExperiment(Experiment):
    def __init__(self, dut, custom_param, **kwargs):
        # Initialize experiment
        super().__init__(dut, **kwargs)
        self.custom_param = custom_param
        
    def _build_sequence(self):
        """Define the pulse sequence"""
        # Build your pulse sequence here
        sequence = []
        
        # Add initialization
        sequence.append(dut.get_c1('f01')['I'])  # Identity
        
        # Add custom operations
        custom_pulse = dut.get_c1('f01')['X'].clone()
        custom_pulse.set_parameter('amp', self.custom_param)
        sequence.append(custom_pulse)
        
        # Add measurement
        sequence.append(dut.get_measurement_prim_intlist(0))
        
        return sequence
    
    def _analyze_data(self, data):
        """Analyze experimental data"""
        # Process your data here
        result = {
            'signal': np.mean(data['I']),
            'std': np.std(data['I'])
        }
        return result

Parameter Sweeps

Use the Sweeper class for parameter variations:

from leeq.experiments.sweeper import Sweeper

# Single parameter sweep
freq_sweep = Sweeper(
    parameter=dut.get_c1('f01')['freq'],
    values=np.linspace(4.8, 4.9, 51)
)

# Multi-dimensional sweeps
amp_sweep = Sweeper(
    parameter=dut.get_c1('f01')['amp'],
    values=np.linspace(0.05, 0.15, 11)
)

# Grid sweep automatically handles combinations

Advanced Features

Live Plotting

# Enable live monitoring
from leeq.experiments import setup
setup().start_live_monitor()

# Experiments automatically display live plots
exp = PowerRabi(dut, start=0, stop=0.2, step=0.005)
exp.run()  # Shows live plot as data arrives

Data Persistence

from leeq.chronicle import Chronicle

# Start logging
Chronicle().start_log()

# All experiments automatically logged
exp = T1Measurement(dut, start=0, stop=100, step=2)
result = exp.run()

# Access logged data later
log_entry = Chronicle().get_last_log_entry()

AI-Assisted Experiments

from leeq.utils.ai.experiment_generation import ExperimentGenerator

# Generate experiment from description
generator = ExperimentGenerator()
code = generator.generate_experiment(
    description="Measure T2* with varying echo delays",
    requirements=["high precision", "automated fitting"]
)

Best Practices

1. Parameter Organization

• Group related parameters in dictionaries
• Use descriptive parameter names
• Document units and ranges

2. Error Handling

try:
    result = experiment.run()
    if result.fit_quality < 0.95:
        print("Warning: Poor fit quality")
except ExperimentError as e:
    print(f"Experiment failed: {e}")

3. Calibration Tracking

# Save calibration after successful experiment
if result.fit_quality > 0.95:
    dut.set_parameter('f01_frequency', result.fit_params['frequency'])
    dut.save_calibration_log()

4. Reproducibility

• Always set random seeds for stochastic experiments
• Save exact parameter values used
• Include environmental conditions in logs

5. Performance Optimization

• Use appropriate number of averages
• Optimize measurement time vs. precision
• Consider parallel execution for multi-qubit systems

Troubleshooting

Common Issues

Poor Signal-to-Noise: Increase averages or adjust measurement amplitude Calibration Drift: Regular recalibration, track environmental changes
Timing Issues: Check pulse sequence timing and hardware limits Fitting Failures: Verify data quality and fitting bounds

Debugging Tools

# Enable debug logging
import logging
logging.getLogger('leeq').setLevel(logging.DEBUG)

# Inspect pulse sequences
experiment.sequence.plot()

# Check data quality
result.plot_raw_data()

Next Steps

• Learn about calibration workflows
• Explore advanced theory
• Review the Tutorial for step-by-step examples