qick_demos/000_Install_qick_package.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# <center> Installing and testing the qick package </center>\n",
    "\n",
    "This notebook will explain how to install the qick library and use it to program the FPGA.\n",
    "\n",
    "There are multiple ways to do any given thing, and this notebook gives several options.\n",
    "The recommended option is always uncommented and ready for you to execute; alternatives are commented out, and you need to uncomment them (and comment out the recommended option) if you choose to go that route. So it should be safe to just run the whole notebook, and you will end up with a working system.\n",
    "\n",
    "*However we strongly recommend (not only for this notebook, but for all of the demo notebooks) that you read carefully through the notebook and run one cell at a time.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## pynq library\n",
    "Let's check that the Xilinx pynq library is installed: you should see (among things) a version number, which should match the version of the PYNQ Linux image you installed.\n",
    "\n",
    "The QICK software supports pynq versions 2.6.0 and above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "\n",
       "try {\n",
       "require(['notebook/js/codecell'], function(codecell) {\n",
       "  codecell.CodeCell.options_default.highlight_modes[\n",
       "      'magic_text/x-csrc'] = {'reg':[/^%%microblaze/]};\n",
       "  Jupyter.notebook.events.one('kernel_ready.Kernel', function(){\n",
       "      Jupyter.notebook.get_cells().map(function(cell){\n",
       "          if (cell.cell_type == 'code'){ cell.auto_highlight(); } }) ;\n",
       "  });\n",
       "});\n",
       "} catch (e) {};\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/javascript": [
       "\n",
       "try {\n",
       "require(['notebook/js/codecell'], function(codecell) {\n",
       "  codecell.CodeCell.options_default.highlight_modes[\n",
       "      'magic_text/x-csrc'] = {'reg':[/^%%pybind11/]};\n",
       "  Jupyter.notebook.events.one('kernel_ready.Kernel', function(){\n",
       "      Jupyter.notebook.get_cells().map(function(cell){\n",
       "          if (cell.cell_type == 'code'){ cell.auto_highlight(); } }) ;\n",
       "  });\n",
       "});\n",
       "} catch (e) {};\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on package pynq:\n",
      "\n",
      "NAME\n",
      "    pynq\n",
      "\n",
      "DESCRIPTION\n",
      "    #   Copyright (c) 2016, Xilinx, Inc.\n",
      "    #   All rights reserved.\n",
      "    # \n",
      "    #   Redistribution and use in source and binary forms, with or without \n",
      "    #   modification, are permitted provided that the following conditions are met:\n",
      "    #\n",
      "    #   1.  Redistributions of source code must retain the above copyright notice, \n",
      "    #       this list of conditions and the following disclaimer.\n",
      "    #\n",
      "    #   2.  Redistributions in binary form must reproduce the above copyright \n",
      "    #       notice, this list of conditions and the following disclaimer in the \n",
      "    #       documentation and/or other materials provided with the distribution.\n",
      "    #\n",
      "    #   3.  Neither the name of the copyright holder nor the names of its \n",
      "    #       contributors may be used to endorse or promote products derived from \n",
      "    #       this software without specific prior written permission.\n",
      "    #\n",
      "    #   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\n",
      "    #   AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, \n",
      "    #   THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR \n",
      "    #   PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR \n",
      "    #   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, \n",
      "    #   EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, \n",
      "    #   PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;\n",
      "    #   OR BUSINESS INTERRUPTION). HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, \n",
      "    #   WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR \n",
      "    #   OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF \n",
      "    #   ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n",
      "\n",
      "PACKAGE CONTENTS\n",
      "    _3rdparty (package)\n",
      "    _cli (package)\n",
      "    bitstream\n",
      "    buffer\n",
      "    devicetree\n",
      "    gpio\n",
      "    interrupt\n",
      "    lib (package)\n",
      "    mmio\n",
      "    overlay\n",
      "    overlays (package)\n",
      "    pl\n",
      "    pl_server (package)\n",
      "    pmbus\n",
      "    ps\n",
      "    registers\n",
      "    uio\n",
      "    utils\n",
      "\n",
      "DATA\n",
      "    __all__ = ['lib', 'tests']\n",
      "    __copyright__ = 'Copyright 2016, Xilinx'\n",
      "    __email__ = 'pynq_support@xilinx.com'\n",
      "    __git_id__ = '$Id: 285d1457e64c076bbb39844afd54b38f075ad2c7 $'\n",
      "\n",
      "VERSION\n",
      "    2.7.0\n",
      "\n",
      "AUTHOR\n",
      "    Yun Rock Qu\n",
      "\n",
      "FILE\n",
      "    /usr/local/share/pynq-venv/lib/python3.8/site-packages/pynq/__init__.py\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "import pynq\n",
    "help(pynq)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## qick library\n",
    "\n",
    "Now let's install the qick library. The qick library has three dependencies: `pynq`, `numpy`, and `tqdm`. All should already be installed as part of the PYNQ Linux image."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Installing using pip (recommended option)\n",
    "\n",
    "You could run these `pip3` commands from the shell over SSH - they need to be run as root (using `sudo`), and on pynq 2.7 you must additionally enable the pynq `venv`. Running the commands inside a notebook, as we do here, conveniently ensures that the commands run in (and install to) the same environment that the notebook runs in."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Obtaining file:///home/xilinx/jupyter_notebooks/qick\n",
      "  Installing build dependencies ... \u001b[?25ldone\n",
      "\u001b[?25h  Getting requirements to build wheel ... \u001b[?25ldone\n",
      "\u001b[?25h  Installing backend dependencies ... \u001b[?25ldone\n",
      "\u001b[?25h    Preparing wheel metadata ... \u001b[?25ldone\n",
      "\u001b[?25hRequirement already satisfied: numpy in /usr/local/share/pynq-venv/lib/python3.8/site-packages (from qick==1.0.0) (1.20.3)\n",
      "Requirement already satisfied: tqdm in /usr/local/share/pynq-venv/lib/python3.8/site-packages (from qick==1.0.0) (4.62.3)\n",
      "Requirement already satisfied: pynq in /usr/local/share/pynq-venv/lib/python3.8/site-packages (from qick==1.0.0) (2.7.0)\n",
      "Requirement already satisfied: setuptools>=24.2.0 in /usr/local/share/pynq-venv/lib/python3.8/site-packages (from pynq->qick==1.0.0) (44.0.0)\n",
      "Requirement already satisfied: pandas in /usr/local/share/pynq-venv/lib/python3.8/site-packages (from pynq->qick==1.0.0) (1.3.3)\n",
      "Requirement already satisfied: cffi in /usr/local/share/pynq-venv/lib/python3.8/site-packages (from pynq->qick==1.0.0) (1.14.5)\n",
      "Requirement already satisfied: pycparser in /usr/lib/python3/dist-packages (from cffi->pynq->qick==1.0.0) (2.19)\n",
      "Requirement already satisfied: python-dateutil>=2.7.3 in /usr/lib/python3/dist-packages (from pandas->pynq->qick==1.0.0) (2.7.3)\n",
      "Requirement already satisfied: pytz>=2017.3 in /usr/lib/python3/dist-packages (from pandas->pynq->qick==1.0.0) (2019.3)\n",
      "Installing collected packages: qick\n",
      "  Running setup.py develop for qick\n",
      "Successfully installed qick\n",
      "\u001b[33mWARNING: You are using pip version 21.2.1; however, version 22.0.4 is available.\n",
      "You should consider upgrading via the '/usr/local/share/pynq-venv/bin/python3 -m pip install --upgrade pip' command.\u001b[0m\n"
     ]
    }
   ],
   "source": [
    "# Use the line below for an \"editable mode\" install.\n",
    "# This installs a link telling Python to look for the library files in their current location.\n",
    "# It is recommended if you expect to update the git repo, or you want to test changes to the QICK library, \n",
    "# and don't want to reinstall the library every time.\n",
    "\n",
    "!pip3 install -e ../\n",
    "\n",
    "# If your board doesn't have Internet access, you may need to add some extra options:\n",
    "\n",
    "# !pip3 install --no-index --no-build-isolation -e ../\n",
    "\n",
    "# Use the line below instead for a normal pip install, which copies the library files to a central location.\n",
    "# In contrast to an editable install, you will need to re-install whenever you modify or update the qick library;\n",
    "# a normal install is somewhat slower for the initial install and infinitely slower for updates.\n",
    "# This is only recommended if for some reason you want to delete the git repo after installing,\n",
    "# or the git repo is on a temporarily available filesystem (e.g. flash drive).\n",
    "\n",
    "# !pip3 install ../\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's see that the package is installed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Name: qick\r\n",
      "Version: 1.0.0\r\n",
      "Summary: Quantum Instrumentation Controller Kit software library\r\n",
      "Home-page: https://github.com/openquantumhardware/qick\r\n",
      "Author: Open Quantum Hardware\r\n",
      "Author-email: openquantumhardware@gmail.com\r\n",
      "License: UNKNOWN\r\n",
      "Location: /home/xilinx/jupyter_notebooks/qick/qick_lib\r\n",
      "Requires: numpy, tqdm, pynq\r\n",
      "Required-by: \r\n"
     ]
    }
   ],
   "source": [
    "!pip3 show qick"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now you need to restart the Jupyter kernel so it picks up the newly installed library: click the Kernel menu, then Restart."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### How to uninstall"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "# !pip3 uninstall -y qick"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using the qick library without installing it (alternative)\n",
    "\n",
    "If for whatever reason you don't want to install the library (maybe you don't want to risk changing the Python environment for other code that you run on the board?), you can tell Python the path to the library.\n",
    "\n",
    "You would need to take the two lines below and copy them into the beginning of every notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [],
   "source": [
    "# import sys\n",
    "# sys.path.append('../qick_lib/')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Testing the qick library and programming the FPGA"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/javascript": [
       "\n",
       "try {\n",
       "require(['notebook/js/codecell'], function(codecell) {\n",
       "  codecell.CodeCell.options_default.highlight_modes[\n",
       "      'magic_text/x-csrc'] = {'reg':[/^%%microblaze/]};\n",
       "  Jupyter.notebook.events.one('kernel_ready.Kernel', function(){\n",
       "      Jupyter.notebook.get_cells().map(function(cell){\n",
       "          if (cell.cell_type == 'code'){ cell.auto_highlight(); } }) ;\n",
       "  });\n",
       "});\n",
       "} catch (e) {};\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "data": {
      "application/javascript": [
       "\n",
       "try {\n",
       "require(['notebook/js/codecell'], function(codecell) {\n",
       "  codecell.CodeCell.options_default.highlight_modes[\n",
       "      'magic_text/x-csrc'] = {'reg':[/^%%pybind11/]};\n",
       "  Jupyter.notebook.events.one('kernel_ready.Kernel', function(){\n",
       "      Jupyter.notebook.get_cells().map(function(cell){\n",
       "          if (cell.cell_type == 'code'){ cell.auto_highlight(); } }) ;\n",
       "  });\n",
       "});\n",
       "} catch (e) {};\n"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on package qick:\n",
      "\n",
      "NAME\n",
      "    qick\n",
      "\n",
      "PACKAGE CONTENTS\n",
      "    averager_program\n",
      "    envelop_pulse\n",
      "    helpers\n",
      "    parser\n",
      "    qick\n",
      "    qick_asm\n",
      "    rfboard\n",
      "    streamer\n",
      "\n",
      "FUNCTIONS\n",
      "    bitfile_path()\n",
      "\n",
      "FILE\n",
      "    /home/xilinx/jupyter_notebooks/qick/qick_lib/qick/__init__.py\n",
      "\n",
      "\n"
     ]
    }
   ],
   "source": [
    "import qick\n",
    "help(qick)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Normally we import all the Python classes defined by the package - you will see this initialization at the beginning of all the demo notebooks."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "from qick import *"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Initializing the QickSoc class programs the FPGA.\n",
    "Printing the class gives a description of the generator and readout channels in the programmed firmware. You're ready to run the other demo notebooks."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "QICK configuration:\n",
      "\n",
      "\tBoard: ZCU216\n",
      "\n",
      "\tGlobal clocks (MHz): tProcessor 430.080, RF reference 245.760\n",
      "\n",
      "\t7 signal generator channels:\n",
      "\t0:\taxis_signal_gen_v4 - tProc output 1, switch ch 0, maxlen 65536\n",
      "\t\tDAC tile 2, ch 0, 32-bit DDS, fabric=430.080 MHz, fs=6881.280 MHz\n",
      "\t1:\taxis_signal_gen_v4 - tProc output 2, switch ch 1, maxlen 65536\n",
      "\t\tDAC tile 2, ch 1, 32-bit DDS, fabric=430.080 MHz, fs=6881.280 MHz\n",
      "\t2:\taxis_signal_gen_v4 - tProc output 3, switch ch 2, maxlen 65536\n",
      "\t\tDAC tile 2, ch 2, 32-bit DDS, fabric=430.080 MHz, fs=6881.280 MHz\n",
      "\t3:\taxis_signal_gen_v4 - tProc output 4, switch ch 3, maxlen 65536\n",
      "\t\tDAC tile 2, ch 3, 32-bit DDS, fabric=430.080 MHz, fs=6881.280 MHz\n",
      "\t4:\taxis_signal_gen_v4 - tProc output 5, switch ch 4, maxlen 65536\n",
      "\t\tDAC tile 3, ch 0, 32-bit DDS, fabric=430.080 MHz, fs=6881.280 MHz\n",
      "\t5:\taxis_signal_gen_v4 - tProc output 6, switch ch 5, maxlen 65536\n",
      "\t\tDAC tile 3, ch 1, 32-bit DDS, fabric=430.080 MHz, fs=6881.280 MHz\n",
      "\t6:\taxis_signal_gen_v4 - tProc output 7, switch ch 6, maxlen 65536\n",
      "\t\tDAC tile 3, ch 2, 32-bit DDS, fabric=430.080 MHz, fs=6881.280 MHz\n",
      "\n",
      "\t2 readout channels:\n",
      "\t0:\tADC tile 2, ch 0, 32-bit DDS, fabric=307.200 MHz, fs=2457.600 MHz\n",
      "\t\tmaxlen 16384 (avg) 1024 (decimated), trigger 14, tProc input 0\n",
      "\t1:\tADC tile 2, ch 2, 32-bit DDS, fabric=307.200 MHz, fs=2457.600 MHz\n",
      "\t\tmaxlen 16384 (avg) 1024 (decimated), trigger 15, tProc input 1\n",
      "\n",
      "\ttProc: 1048576 words program memory, 4096 words data memory\n",
      "\t\tprogram RAM: 65536 bytes\n"
     ]
    }
   ],
   "source": [
    "soc = QickSoc()\n",
    "print(soc)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}