docs: add onboarding documentation and update contributing guide

docs/onboarding/calibration-procedures.md

@@ -0,0 +1,373 @@
+# Calibration Procedures Catalog
+
+This document provides detailed information about each calibration procedure, including physics background, implementation details, and troubleshooting guides.
+
+## Calibration Categories
+
+Calibrations are organized into three main categories:
+
+1. **Initial Setup**: Hardware characterization and basic calibrations
+2. **Single-Qubit Calibrations**: Qubit-specific parameters and gates
+3. **Two-Qubit Calibrations**: Entangling gate calibration
+
+## Initial Setup Calibrations
+
+### Time of Flight
+
+**File**: `calibrations/1Q_calibrations/01a_time_of_flight.py`
+
+**Physics**: The time of flight is the delay between sending a readout pulse and when the signal arrives at the ADC. This includes:
+- Internal processing time in the OPX
+- Propagation delay through cables and components
+- Signal processing delays
+
+**Purpose**: Calibrate the acquisition window offset to properly time the readout measurement.
+
+**Inputs**:
+- `time_of_flight_in_ns`: Initial guess (typically 28 ns)
+- `readout_amplitude_in_v`: Readout pulse amplitude
+- `readout_length_in_ns`: Readout pulse duration
+
+**Outputs**:
+- `qubit.resonator.time_of_flight`: Calibrated time of flight
+- `qubit.resonator.opx_input_I.offset`: I channel DC offset
+- `qubit.resonator.opx_input_Q.offset`: Q channel DC offset
+
+**Troubleshooting**:
+- **No signal**: Check readout line connection, increase amplitude
+- **Signal too weak**: Increase readout amplitude or input gain
+- **Signal saturates**: Decrease readout amplitude or adjust input gain
+- **Inconsistent results**: Check for loose connections, increase averaging
+
+---
+
+### Mixer Calibration
+
+**File**: `calibrations/1Q_calibrations/01a_mixer_calibration.py`
+
+**Physics**: IQ mixers can have imperfections (amplitude imbalance, phase error, DC offsets) that cause leakage and distortion. Calibration compensates for these.
+
+**Purpose**: Calibrate IQ mixer to minimize LO leakage and image rejection.
+
+**Inputs**:
+- `calibrate_drive`: Whether to calibrate drive mixer
+- `calibrate_resonator`: Whether to calibrate readout mixer
+
+**Outputs**: Mixer calibration parameters stored in qubit/resonator configuration
+
+**Troubleshooting**:
+- **High leakage**: Check mixer connections, verify LO power
+- **Poor image rejection**: Re-run calibration with more iterations
+
+---
+
+### Resonator Spectroscopy
+
+**File**: `calibrations/1Q_calibrations/02a_resonator_spectroscopy.py`
+
+**Physics**: The readout resonator has a characteristic resonance frequency determined by its geometry and coupling. Spectroscopy measures the transmission/reflection to find this frequency.
+
+**Purpose**: Find the resonator frequency for optimal readout.
+
+**Inputs**:
+- `intermediate_frequency_range`: Frequency sweep range
+
+**Outputs**:
+- `qubit.resonator.frequency`: Resonator frequency
+- `qubit.resonator.intermediate_frequency`: Intermediate frequency
+
+**Troubleshooting**:
+- **No resonance found**: Widen frequency range, check resonator connection
+- **Multiple peaks**: Identify correct peak based on expected frequency from design
+- **Broad resonance**: May indicate poor quality factor or coupling issues
+
+---
+
+## Single-Qubit Calibrations
+
+### Qubit Spectroscopy
+
+**File**: `calibrations/1Q_calibrations/03a_qubit_spectroscopy.py`
+
+**Physics**: The qubit transition frequency |0⟩ ↔ |1⟩ is determined by the Josephson energy and charging energy. Spectroscopy measures the qubit response to find this frequency.
+
+**Purpose**: Find the qubit transition frequency for gate operations.
+
+**Inputs**:
+- `intermediate_frequency_range`: Frequency sweep range
+- `drive_scaling_amp`: Drive amplitude
+
+**Outputs**:
+- `qubit.xy.frequency`: Qubit frequency
+- `qubit.xy.intermediate_frequency`: Intermediate frequency
+
+**Troubleshooting**:
+- **No resonance**: Widen frequency range, check drive line connection
+- **Multiple peaks**: Identify |0⟩↔|1⟩ transition (usually strongest, at expected frequency)
+- **Broad linewidth**: May indicate short T2* or strong noise
+
+---
+
+### Power Rabi
+
+**File**: `calibrations/1Q_calibrations/04b_power_rabi.py`
+
+**Physics**: Rabi oscillations occur when driving a qubit at its resonance frequency. The population oscillates between |0⟩ and |1⟩ with frequency proportional to drive amplitude. A π-pulse corresponds to a full oscillation (180° rotation).
+
+**Purpose**: Calibrate the π-pulse amplitude for X180 gate.
+
+**Inputs**:
+- `amp_scaling_range`: Amplitude sweep range
+- `operation`: Which gate to calibrate ("x180" or "x90")
+
+**Outputs**:
+- `qubit.xy.operations["x180"].amplitude`: π-pulse amplitude
+- `qubit.xy.operations["x90"].amplitude`: π/2-pulse amplitude (if calibrated)
+
+**Troubleshooting**:
+- **No oscillations**: Increase amplitude range, check drive line, verify qubit frequency
+- **Multiple π-pulses**: Use first π-pulse amplitude
+- **Decaying oscillations**: May indicate T1/T2 issues, reduce measurement delay
+
+---
+
+### Ramsey
+
+**File**: `calibrations/1Q_calibrations/06a_ramsey.py`
+
+**Physics**: Ramsey interferometry measures qubit frequency by preparing a superposition state and letting it evolve. The phase evolution causes oscillations at the detuning frequency. The decay envelope gives T2*.
+
+**Purpose**: Fine-tune qubit frequency and measure T2* dephasing time.
+
+**Inputs**:
+- `evolution_times`: Free evolution time array
+- `detuning_freqs`: Optional detuning frequencies
+
+**Outputs**:
+- `qubit.xy.frequency`: Fine-tuned qubit frequency
+- `qubit.T2*`: Dephasing time (if measured)
+
+**Troubleshooting**:
+- **No oscillations**: Check detuning, increase evolution time range
+- **Fast decay**: Qubit may have short T2*, check for noise sources
+- **Frequency drift**: May need to re-run if qubit frequency has drifted
+
+---
+
+### T1 Measurement
+
+**File**: `calibrations/1Q_calibrations/05_T1.py`
+
+**Physics**: T1 is the energy relaxation time, measuring how long the qubit takes to decay from |1⟩ to |0⟩. This is an exponential decay process.
+
+**Purpose**: Measure qubit energy relaxation time.
+
+**Inputs**:
+- `wait_times`: Wait time array after exciting qubit
+
+**Outputs**:
+- `qubit.T1`: T1 relaxation time
+
+**Troubleshooting**:
+- **T1 too short**: Check qubit environment, connections, may indicate heating or noise
+- **Poor fit**: Increase wait time range, use more shots
+- **Non-exponential decay**: May indicate measurement issues or state preparation problems
+
+---
+
+### DRAG Calibration
+
+**File**: `calibrations/1Q_calibrations/10b_drag_calibration_180_minus_180.py`
+
+**Physics**: DRAG (Derivative Reduction by Adiabatic Gate) reduces phase errors and leakage to higher levels by adding a derivative component to the pulse envelope.
+
+**Purpose**: Calibrate DRAG coefficient to minimize phase errors.
+
+**Inputs**:
+- `drag_amp_values`: DRAG coefficient sweep range
+- `num_of_repetitions`: Number of repetitions
+
+**Outputs**:
+- `qubit.xy.operations["x180"].drag_coefficient`: Optimal DRAG coefficient
+
+**Troubleshooting**:
+- **No clear optimum**: Use default DRAG coefficient, may need to adjust pulse length
+- **Phase error persists**: Check pulse length, increase DRAG range, verify qubit frequency
+
+---
+
+### IQ Blobs
+
+**File**: `calibrations/1Q_calibrations/07_iq_blobs.py`
+
+**Physics**: When measuring a qubit in |0⟩ or |1⟩, the readout signal appears as a distribution (blob) in IQ space. Optimal state discrimination requires separating these blobs.
+
+**Purpose**: Measure IQ distributions and calibrate state discrimination.
+
+**Inputs**:
+- `num_shots`: Number of measurements
+
+**Outputs**:
+- `qubit.resonator.IQ_rotation_angle`: Rotation angle for optimal discrimination
+- `qubit.resonator.ge_discrimination_threshold`: State discrimination threshold
+
+**Troubleshooting**:
+- **Overlapping blobs**: Improve readout optimization, increase measurement time
+- **Blobs not separated**: Check readout frequency and power, may need better readout calibration
+
+---
+
+### Randomized Benchmarking
+
+**File**: `calibrations/1Q_calibrations/11a_single_qubit_randomized_benchmarking.py`
+
+**Physics**: Randomized benchmarking measures average gate fidelity by applying random sequences of Clifford gates and measuring the final state. The fidelity decays exponentially with sequence length.
+
+**Purpose**: Measure single-qubit gate fidelity.
+
+**Inputs**:
+- `circuit_depth`: Maximum sequence length
+- `num_random_sequence`: Number of random sequences
+
+**Outputs**:
+- `qubit.gate_fidelity["averaged"]`: Average gate fidelity
+- `SQ_error_per_gate`: Error per gate
+
+**Troubleshooting**:
+- **Fidelity too low**: Check previous calibrations, especially DRAG and frequency
+- **No decay visible**: Increase circuit depth, check readout calibration
+- **Long execution time**: Reduce circuit depth or number of sequences
+
+---
+
+## Two-Qubit Calibrations
+
+### CZ Gate - Chevron
+
+**File**: `calibrations/CZ_calibration_fixed_couplers/19_chevron_11_02.py`
+
+**Physics**: The CZ gate uses the |11⟩ ↔ |02⟩ avoided crossing. By pulsing the qubit frequency to this crossing, a conditional phase accumulates. The Chevron pattern shows the oscillation between these states.
+
+**Purpose**: Find initial CZ gate parameters (amplitude and duration).
+
+**Inputs**:
+- `flux_amplitude`: Flux amplitude range
+- `gate_time`: Gate duration range
+
+**Outputs**:
+- `qubit.flux_amp`: Initial qubit flux amplitude
+- `coupler.flux_amp`: Initial coupler flux amplitude
+
+**Troubleshooting**:
+- **No Chevron pattern**: Check flux line connections, widen parameter ranges
+- **Unclear pattern**: Increase resolution, check qubit frequencies
+
+---
+
+### CZ Gate - Conditional Phase
+
+**File**: `calibrations/CZ_calibration_fixed_couplers/20_cz_conditional_phase.py`
+
+**Physics**: The conditional phase is the phase acquired by the target qubit when the control qubit is in |1⟩. For a perfect CZ, this should be π.
+
+**Purpose**: Fine-tune CZ gate amplitude to achieve π conditional phase.
+
+**Inputs**:
+- `qubit_flux_amplitude`: Flux amplitude range
+
+**Outputs**:
+- `qubit.flux_amp`: Refined qubit flux amplitude
+
+**Troubleshooting**:
+- **Phase not π**: Adjust amplitude range, check previous calibrations
+- **Poor fit**: Increase measurement statistics, check state preparation
+
+---
+
+### CZ Gate - Phase Compensation
+
+**File**: `calibrations/CZ_calibration_fixed_couplers/21_cz_phase_compensation.py`
+
+**Physics**: During the CZ pulse, both qubits acquire additional phases due to frequency shifts. These must be compensated with virtual Z rotations.
+
+**Purpose**: Measure and compensate for single-qubit phases during CZ.
+
+**Inputs**:
+- `frame_rotation`: Frame rotation range
+
+**Outputs**:
+- `qubit.phase_cor_qij`: Phase correction for qubit i when interacting with qubit j
+
+**Troubleshooting**:
+- **Large phase corrections**: May indicate issues with CZ calibration
+- **Unstable phases**: Check qubit frequencies and flux stability
+
+---
+
+### Two-Qubit Randomized Benchmarking
+
+**File**: `calibrations/CZ_calibration_fixed_couplers/22_two_qubit_standard_rb.py`
+
+**Physics**: Similar to single-qubit RB, but uses two-qubit Clifford gates including CZ. Measures the fidelity of the two-qubit gate set.
+
+**Purpose**: Measure two-qubit gate fidelity.
+
+**Inputs**:
+- `circuit_depth`: Maximum sequence length
+
+**Outputs**:
+- `2q_fid`: Two-qubit gate fidelity
+- `CZ_error_per_gate`: CZ gate error rate
+
+**Troubleshooting**:
+- **Fidelity too low**: Re-calibrate CZ gate parameters, check single-qubit gates
+- **Long execution time**: Reduce circuit depth or number of sequences
+
+---
+
+## Parameter Ranges
+
+### Typical Values
+
+| Parameter | Typical Range | Units |
+|-----------|---------------|-------|
+| Qubit frequency | 3-7 | GHz |
+| Resonator frequency | 5-8 | GHz |
+| Readout amplitude | 0.01-0.1 | V |
+| Drive amplitude (π-pulse) | 0.1-0.5 | (normalized) |
+| Time of flight | 20-50 | ns |
+| T1 | 10-100 | μs |
+| T2* | 1-50 | μs |
+| Gate fidelity | >99% | - |
+
+### Sweep Ranges
+
+- **Frequency sweeps**: ±50 MHz around expected value
+- **Amplitude sweeps**: 0.5× to 1.5× expected value
+- **Time sweeps**: 0 to 5×T1 or T2*
+
+## Common Failure Modes
+
+### Hardware Issues
+
+- **No signal**: Check connections, verify hardware power
+- **Inconsistent results**: Check for loose connections, temperature stability
+- **Saturation**: Reduce signal amplitude or adjust gain
+
+### Calibration Issues
+
+- **Poor fits**: Increase statistics, check parameter ranges
+- **Unstable parameters**: Check for drift, may need to re-run calibrations
+- **Dependencies not met**: Ensure prerequisite calibrations completed successfully
+
+### Physics Issues
+
+- **Short coherence times**: Check environment, may indicate noise sources
+- **Frequency drift**: May need frequent re-calibration
+- **Leakage**: Check pulse shapes, may need better DRAG calibration
+
+## Next Steps
+
+- Review [Calibration Workflow](calibration-workflow-detailed.md) for execution order
+- Study [Code Patterns](code-patterns.md) for implementation details
+- Explore [Example Walkthrough](example-walkthrough.md) for hands-on learning