Filter calculation tools

CHANGELOG.md

@@ -13,6 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - octave_tools - Added `get_calibration_parameters_from_db` get the most up-to-date correction parameters in the calibration database for the specified values of the Octave LO frequency, intermediate frequency and Octave gain.
 - octave_tools - Added `set_correction_parameters_to_opx` set the most up-to-date correction parameters from the calibration database for the specified values of the Octave LO frequency, intermediate frequency and Octave gain.
 - octave_tools - Added `get_correction_for_each_LO_and_IF` get the correction matrix elements for a set of intermediate frequencies picked equally spaced in a given list in order to update the correction matrix while performing the IF sweep in QUA.
+- digital_filters - Added library of functions allowing the derivation of the digital filter taps to correct distortions.
 - macros - Added `long_wait` convenience macro to simplify waiting for longer than the maximum wait time.
 
 ### Changed

README.md

@@ -45,6 +45,7 @@ storing them in the usual configuration file. It allows defining waveforms in a
   * [ManualOutputControl](qualang_tools/control_panel/README_manual_output_control.md) - This module allows controlling the outputs from the OPX in CW mode. Once created, it has an API for defining which channels are on. Analog channels also have an API for defining their amplitude and frequency.
   * [VNA](qualang_tools/control_panel/README_vna.md) - This module allows to configure the OPX as a VNA for a given element (readout resonator for instance) and operation (readout pulse for instance) already defined in the configuration. Once created, it has an API for defining which measurements are to be run depending on the down-conversion solution used (ED: envelope detector, IR: image rejection mixer, IQ: IQ mixer).
 * [Macros](qualang_tools/macros/README.md) - This module includes convenience functions for encapsulating common QUA code.
+* [Digital filters](qualang_tools/digital_filters/README.md) - Library of functions allowing the derivation of the digital filter taps to correct distortions.
 
 
 ## Installation

qualang_tools/digital_filters/README.md

@@ -0,0 +1,95 @@
+# Digital filter tools
+This library includes tools for deriving the taps of the OPX digital filters (IIR and FIR).
+
+Such filters are generally used to correct for the high-pass filtering occurring on the fast line of a bias-tee, 
+or to correct flux pulses for possible distortions happening on the flux lines of superconducting qubit chips.
+
+More details about these types of filter and how they are implemented on the OPX can be found [here](https://docs.quantum-machines.co/1.1.7/qm-qua-sdk/docs/Guides/output_filter/?h=iir#output-filter)
+
+The goal of the following functions is to allow users to easily implement such filters by deriving the IIR and FIR taps 
+from the measured distortions:
+* [Single exponential correction](#singleexponentialcorrection): correct for a low-pass exponential decay `1 + A * exp(-t/tau)`.
+* [Highpass correction](#highpasscorrection): correct for a high pass exponential decay `exp(-t/tau)`.
+* [Bounce and delay correction](#bounceanddelaycorrection): correct for reflections and delays.
+* [Calc filter taps](#calcfiltertaps): correct for any combination of the aforementioned compensations.
+
+## Usage examples
+
+### single_exponential_correction
+Calculate the best FIR and IIR filter taps to correct for an exponential decay (undershoot or overshoot) of the shape
+`1 + A * exp(-t/tau)`. You can use the `exponential_decay` function for fitting your data as shown below.
+
+#### 
+```python
+from scipy import optimize
+from qualang_tools.digital_filters import exponential_decay, single_exponential_correction
+
+# Fit your data with the exponential_decay function
+[A_lpf, tau_lpf_ns], _ = optimize.curve_fit(
+    exponential_decay,
+    x_data,
+    y_data,
+)
+# Derive the corresponding taps
+feedforward_taps, feedback_tap = single_exponential_correction(A_lpf, tau_lpf_ns)
+# Update the config with the digital filter parameters
+config["controllers"]["con1"]["analog_outputs"][port_number] = {
+    "offset": 0.0, 
+    "filter": {"feedforward": feedforward_taps, "feedback": feedback_tap}}
+```
+
+### highpass_correction
+Calculate the best FIR and IIR filter taps to correct for a highpass decay (high-pass filter) of the shape `exp(-t/tau)`.
+You can use the `high_pass_exponential` function for fitting your data as shown below.
+
+#### 
+```python
+from scipy import optimize
+from qualang_tools.digital_filters import high_pass_exponential, highpass_correction
+
+# Fit your data with the exponential_decay function
+[tau_hpf_ns], _ = optimize.curve_fit(
+    high_pass_exponential,
+    x_data,
+    y_data,
+)
+# Derive the taps from the time constant of the exponential highpass decay tau
+feedforward_taps, feedback_tap = highpass_correction(tau_hpf_ns)
+# Update the config with the digital filter parameters
+config["controllers"]["con1"]["analog_outputs"][port_number] = {
+    "offset": 0.0, 
+    "filter": {"feedforward": feedforward_taps, "feedback": feedback_tap}}
+```
+
+### bounce_and_delay_correction
+Calculate the FIR filter taps to correct for reflections (bounce corrections) and to add a delay.
+
+#### 
+```python
+from qualang_tools.digital_filters import bounce_and_delay_correction
+
+
+
+```
+
+### calc_filter_taps
+Calculate the best FIR and IIR filter taps for a system with any combination of FIR corrections, exponential
+corrections (undershoot or overshoot), high pass compensation, reflections (bounce corrections) and a needed delay on the line.
+
+#### 
+```python
+from qualang_tools.digital_filters import calc_filter_taps
+
+# Derive the taps for correction all the identified distortions (high-pass, low-pass, reflection and delay) 
+feedforward_taps, feedback_tap = calc_filter_taps(
+    fir=None,
+    exponential=list(zip([A_lpf_1, A_lpf_2,...], [tau_lpf_ns_1, tau_lpf_ns_2,...])),
+    highpass=[tau_hpf_ns],
+    bounce=[(a_bounce, tau_bounce),],
+    delay=20,
+)
+# Update the config with the digital filter parameters
+config["controllers"]["con1"]["analog_outputs"][port_number] = {
+    "offset": 0.0, 
+    "filter": {"feedforward": feedforward_taps, "feedback": feedback_tap}}
+```

qualang_tools/digital_filters/__init__.py

@@ -0,0 +1,19 @@
+from qualang_tools.digital_filters.filters import (
+    QOPVersion,
+    calc_filter_taps,
+    exponential_decay,
+    high_pass_exponential,
+    single_exponential_correction,
+    highpass_correction,
+    bounce_and_delay_correction,
+)
+
+__all__ = [
+    "QOPVersion",
+    "calc_filter_taps",
+    "exponential_decay",
+    "high_pass_exponential",
+    "single_exponential_correction",
+    "highpass_correction",
+    "bounce_and_delay_correction",
+]