Merge branch 'meas-reader-2.0' of https://github.com/scqubits/qfit in…

…to meas-reader-2.0

QFit_Advanced_Tips.ipynb

@@ -17,12 +17,13 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Importing multiple experimental data\n",
+    "## 1. Importing multiple experimental data\n",
     "\n",
-    "#### Requirements for the data files\n",
-    "You may wish to fit parameters with mutiple two-tone spectroscopy data, including (but not limited to) the following scenarios:\n",
+    "#### 1.1 Requirements for the data files\n",
+    "You may wish to fit parameters with mutiple two-tone spectroscopy data, for example in the following scenarios:\n",
     "- You performed a coarse scan over a wide range of DC voltage, and performed a more refined scan near the sweet spot of the qubit to resolve the qubit frequency.\n",
     "- Your device has multiple DC voltage sources to control magnetic flux and/or offset charge, and you need to determine the relation between input DC voltages and the tuning parameters, which has to be fully determined with multiple two-tone spectroscopies.\n",
+    "\n",
     "`QFit` supports loading multiple spectroscopy data files and fit against all of them. There are a few requirements for the data files being loaded together:\n",
     "1. Each data file represent a single run two-tone spectroscopy experiment. It should  contains \n",
     "    - a few 2D spectroscopy arrays with the same shape (usually amplitude and phase) \n",
@@ -36,53 +37,137 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "#### Importing data files\n",
-    "You are given two piece of spectroscopy data on a fluxonium qubit. One scan contains a wide range of frequencies and flux biases, while the other scan is a zoom-in one around the qubit's sweet spot. Your goal is to fit the two scans together to extract the qubit's parameters."
+    "#### 1.2 Importing data files\n",
+    "Assume you have a circuit design for fluxonium, and you have two DC flux bias lines nearby. You performed two experiments that sweeps along two different lines in the $(V_1, V_2)$ space, named `joint_qubit_twotone_ct1.h5` and `joint_qubit_twotone_ct2.h5`. The first dataset is obtained by sweeping $V_1$ and keeping $V_2$ fixed, while in the second dataset $V_1$ is fixed while $V_2$ is swept. Here we show you two ways to import these data files."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "##### Method 1: provide a list of file paths for initiating the `Fit` class instance"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": null,
+   "execution_count": 1,
    "metadata": {},
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "qt.qpa.fonts: Populating font family aliases took 132 ms. Replace uses of missing font family \"Roboto Medium\" with one that exists to avoid this cost. \n",
+      "UserWarning: Attempting to set identical low and high ylims makes transformation singular; automatically expanding.\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/qfit/qfit/qfit/widgets/mpl_canvas.py: 634"
+     ]
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "RuntimeWarning: invalid value encountered in scalar divide\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/qfit/qfit/qfit/widgets/mpl_canvas.py: 608Traceback (most recent call last):\n",
+      "  File \"/Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/qfit/qfit/qfit/widgets/mpl_canvas.py\", line 982, in updateElement\n",
+      "    self._plotElement(name, draw=True, **kwargs)\n",
+      "  File \"/Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/qfit/qfit/qfit/widgets/mpl_canvas.py\", line 958, in _plotElement\n",
+      "    self._restoreXYLim()\n",
+      "  File \"/Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/qfit/qfit/qfit/widgets/mpl_canvas.py\", line 650, in _restoreXYLim\n",
+      "    yAx.set_ylim(*self._dispLimByPrcplLim(\n",
+      "  File \"/Users/pacosynthesis/miniforge3/envs/scqubits_ARM/lib/python3.11/site-packages/matplotlib/axes/_base.py\", line 3898, in set_ylim\n",
+      "    return self.yaxis._set_lim(bottom, top, emit=emit, auto=auto)\n",
+      "           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n",
+      "  File \"/Users/pacosynthesis/miniforge3/envs/scqubits_ARM/lib/python3.11/site-packages/matplotlib/axis.py\", line 1210, in _set_lim\n",
+      "    v0 = self.axes._validate_converted_limits(v0, self.convert_units)\n",
+      "         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n",
+      "  File \"/Users/pacosynthesis/miniforge3/envs/scqubits_ARM/lib/python3.11/site-packages/matplotlib/axes/_base.py\", line 3585, in _validate_converted_limits\n",
+      "    raise ValueError(\"Axis limits cannot be NaN or Inf\")\n",
+      "ValueError: Axis limits cannot be NaN or Inf\n",
+      "Warning: [scqubits] Some quantum system parameters have been changed and generated spectrum data could be outdated, potentially leading to incorrect results. Spectral data can be refreshed via <HilbertSpace>.generate_lookup() or <ParameterSweep>.run()\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/Codes/scqubits_Tianpu/scqubits/utils/misc.py: 174Warning: [scqubits] Some quantum system parameters have been changed and generated spectrum data could be outdated, potentially leading to incorrect results. Spectral data can be refreshed via <HilbertSpace>.generate_lookup() or <ParameterSweep>.run()\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/Codes/scqubits_Tianpu/scqubits/utils/misc.py: 174Warning: [scqubits] Some quantum system parameters have been changed and generated spectrum data could be outdated, potentially leading to incorrect results. Spectral data can be refreshed via <HilbertSpace>.generate_lookup() or <ParameterSweep>.run()\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/Codes/scqubits_Tianpu/scqubits/utils/misc.py: 174Warning: [scqubits] Some quantum system parameters have been changed and generated spectrum data could be outdated, potentially leading to incorrect results. Spectral data can be refreshed via <HilbertSpace>.generate_lookup() or <ParameterSweep>.run()\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/Codes/scqubits_Tianpu/scqubits/utils/misc.py: 174Warning: [scqubits] Some quantum system parameters have been changed and generated spectrum data could be outdated, potentially leading to incorrect results. Spectral data can be refreshed via <HilbertSpace>.generate_lookup() or <ParameterSweep>.run()\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/Codes/scqubits_Tianpu/scqubits/utils/misc.py: 174Warning: [scqubits] Some quantum system parameters have been changed and generated spectrum data could be outdated, potentially leading to incorrect results. Spectral data can be refreshed via <HilbertSpace>.generate_lookup() or <ParameterSweep>.run()\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/Codes/scqubits_Tianpu/scqubits/utils/misc.py: 174Warning: [scqubits] Some quantum system parameters have been changed and generated spectrum data could be outdated, potentially leading to incorrect results. Spectral data can be refreshed via <HilbertSpace>.generate_lookup() or <ParameterSweep>.run()\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/Codes/scqubits_Tianpu/scqubits/utils/misc.py: 174Warning: [scqubits] Some quantum system parameters have been changed and generated spectrum data could be outdated, potentially leading to incorrect results. Spectral data can be refreshed via <HilbertSpace>.generate_lookup() or <ParameterSweep>.run()\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/Codes/scqubits_Tianpu/scqubits/utils/misc.py: 174Warning: [scqubits] Some quantum system parameters have been changed and generated spectrum data could be outdated, potentially leading to incorrect results. Spectral data can be refreshed via <HilbertSpace>.generate_lookup() or <ParameterSweep>.run()\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/Codes/scqubits_Tianpu/scqubits/utils/misc.py: 174Warning: [scqubits] Some quantum system parameters have been changed and generated spectrum data could be outdated, potentially leading to incorrect results. Spectral data can be refreshed via <HilbertSpace>.generate_lookup() or <ParameterSweep>.run()\n",
+      " /Users/pacosynthesis/Desktop/ScienceTech/Research/Superconducting_qubit_NU/Codes/scqubits_Tianpu/scqubits/utils/misc.py: 174"
+     ]
+    }
+   ],
    "source": [
     "# Quantum model for a single fluxonium\n",
     "import scqubits as scq\n",
+    "\n",
     "fluxonium = scq.Fluxonium(\n",
-    "    EJ = 3.0,\n",
-    "    EC = 0.9,\n",
-    "    EL = 0.25,\n",
-    "    flux = 0.5,\n",
-    "    cutoff = 100,\n",
-    "    truncated_dim = 5,\n",
-    "    id_str = \"Fluxonium\"\n",
+    "    EJ=3.0, EC=0.9, EL=0.25, flux=0.5, cutoff=100, truncated_dim=5, id_str=\"Fluxonium\"\n",
     ")\n",
     "hilbert_space = scq.HilbertSpace([fluxonium])\n",
     "\n",
     "# spectroscopy data\n",
     "data = [\n",
-    "    './example_data/joint_qubit_twotone.h5',       # the broad scan\n",
-    "    './example_data/trans_twotone.h5'              # the zoom-in scan\n",
+    "    \"./example_data/joint_qubit_twotone_ct1.h5\",\n",
+    "    \"./example_data/joint_qubit_twotone_ct2.h5\",\n",
     "]\n",
     "\n",
-    "# launch QFit. \n",
+    "# launch QFit.\n",
     "from qfit import Fit\n",
+    "\n",
     "fit = Fit(hilbert_space, data)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "After launching `QFit`, two images are already loaded in the file tabs, where you can switch between files, add and remove files.\n",
+    "This way, you directly import two figures. You may add and remove figures, and switch between tabs for viewing different figures.\n",
+    "\n",
     "<p align=\"center\">\n",
     "  <img width=\"400\" src=\"resources/images/tip_file_tabs.png\">\n",
-    "</p>  \n",
+    "</p>  "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "##### Method 2: load figure after initiating `Fit` instance\n",
+    "\n",
+    "You may also run `fit = Fit(hs)` directly, and a window will pop up and ask you for the file you wish to import."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### 1.3 Configuring the data"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "After loading the data, you will see a panel showing <span style=\"color:rgb(190, 130, 250);\">METADATA</span> of the data that is currently presented on the right. \n",
+    "\n",
+    "<p align=\"center\">\n",
+    "  <img width=\"400\" src=\"resources/images/adv_tip_metadata.png\">\n",
+    "</p>  "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`QFit` automatically detects candidate axes that are stored in the h5 file, however you need to tell `QFit` which axes are for the x-axis (the input DC voltages on flux bias lines in our case), and which axis is for the y-axis (the frequency). Since both $V_1$ and $V_2$ are swept in the two datasets, we specify `voltage_1` and `voltage_2` as x coordinates and \"frequency\" as the y coordinate. \n",
+    "<p align=\"center\">\n",
+    "  <img width=\"300\" src=\"resources/images/adv_tip_select_axes.png\">\n",
+    "</p> \n",
     "\n",
-    "#### 1.3 Configuring the data\n",
-    "Although `QFit` automatically detects the compatible x and y coordinates, as shown in the <span style=\"color:rgb(190, 130, 250);\">METADATA</span> panel, you need to tell `QFit` what are ones that are actually used during the fitting. In this case, we specify \"voltage\" as the only x coordinate and \"frequency\" as the y coordinate. \n",
+    "Then you will see the figures oriented correctly.\n",
     "<p align=\"center\">\n",
-    "  <img width=\"300\" src=\"resources/images/example_axes_select.png\">\n",
+    "  <img width=\"300\" src=\"resources/images/adv_tip_correct_orientation.png\">\n",
     "</p> \n",
     "\n",
     "There are a few things to note:\n",
@@ -95,11 +180,68 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## 2. Calibrate flux crosstalk\n",
+    "## 2. Calibrate flux crosstalk"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In our example, voltages of the input DC sources for the two flux bias lines both can contribute to the external flux of the fluxonium $\\Phi_{\\text{ext}}$:\n",
     "\n",
-    "To be completed soon..."
+    "$$\n",
+    "\\Phi_{\\text{ext}} = \\alpha_1 V_1 + \\alpha_2 V_2 + \\beta .\n",
+    "$$\n",
+    "\n",
+    "To fully calibrate the relation between the voltages $V_1$, $V_2$ and the external flux $\\Phi_{\\text{ext}}$, we have to determine $\\alpha_1$, $\\alpha_2$ and $\\beta$. One such way to calibrate for these coefficients is to perform two two-tone spectroscopies that sweep along two (non-colinear) lines in the $(V_1, V_2)$ space.\n",
+    "Since we have three unknowns, we have to provide three sets of $(V_1, V_2, \\Phi_{\\text{ext}})$. Labelling them as $(V_1^{(i)}, V_2^{(i)}, \\Phi_{\\text{ext}}^{(i)})$, with $i = 1,2,3$, we end up with three linear equations:\n",
+    "$$\n",
+    "\\Phi_{\\text{ext}}^{(1)} = \\alpha_1 V_1^{(1)} + \\alpha_2 V_2^{(1)} + \\beta \\\\\n",
+    "\\Phi_{\\text{ext}}^{(2)} = \\alpha_1 V_1^{(2)} + \\alpha_2 V_2^{(2)} + \\beta \\\\\n",
+    "\\Phi_{\\text{ext}}^{(3)} = \\alpha_1 V_1^{(3)} + \\alpha_2 V_2^{(3)} + \\beta .\n",
+    "$$\n",
+    "\n",
+    "This also explains why we need two two-tone sweeps that are not co-linear: we need the above three equations not linearly-dependent, so that we can obtain a unique solution to those coefficients. This is only possible if we pick up three $(V_1, V_2)$ coordinates that are not all the same line.  \n",
+    "\n",
+    "The <span style=\"color:rgb(190, 130, 250);\">CALIBRATE</span> step helps you identify three such points. We can see in the ct1 figure there are two sweet spots that looks like $\\Phi_{\\text{ext}} = 0$ and $0.5$, then we extract $(V_1, V_2)$ at these sweet spots and then provide the corresponding external flux values:\n",
+    "\n",
+    "<p align=\"center\">\n",
+    "  <img width=\"600\" src=\"resources/images/adv_tip_calibrate_1.png\">\n",
+    "</p> \n",
+    "\n",
+    "and the third point is obtained from the ct2 figure:\n",
+    "<p align=\"center\">\n",
+    "  <img width=\"600\" src=\"resources/images/adv_tip_calibrate_2.png\">\n",
+    "</p> "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then you successfully calibrate for the relation between voltages and the external flux. The calibration for circuits with multiple tuning knobs can be performed in a similar way in `QFit`."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Please notice that the extracted data points for these two figures are grouped separately:\n",
+    "<p align=\"center\">\n",
+    "  <img width=\"600\" src=\"resources/images/adv_tip_extract_1.png\">\n",
+    "</p> \n",
+    "<p align=\"center\">\n",
+    "  <img width=\"600\" src=\"resources/images/adv_tip_extract_2.png\">\n",
+    "</p> "
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
   {
    "cell_type": "markdown",
    "metadata": {},