.. _setup: Setup ===== On this page, we are going to look at the installation steps for the various tools needed to operate Qblox hardware. In addition, we will explain how to connect a |qblox_cluster| to your host PC. Qblox Clusters will work out of the box with the ``qblox-instruments`` Python driver. We will take you through the installation steps for creating a virtual programming environment for Python and installing the ``qblox-instruments`` driver package, along with |jupyter| (required to run the tutorials) and :ref:`getting_started_quantify`, a high-level Python framework to carry out quantum computing experiments. .. |qblox_cluster| raw:: html Qblox cluster .. |jupyter| raw:: html Jupyter .. _getting_started_installation: Installation ------------- In this section, we will explain how to install the ``qblox-instruments`` package and set it up for use with Qblox hardware. Qblox Instruments requires |python|. We recommend using Python 3.9, the latest version supported by Quantify currently (see |quantify-core|, |quantify-scheduler|). .. admonition:: Tip for new Python users For users new to Python, we recommend using |anaconda| to set up your programming environment. Please follow the installation instructions provided by Anaconda, and open up an Anaconda prompt when the installation is finished. We will start by creating a new environment, which we will use to install packages independently from other conda or Python environments. We can specify the name and the Python version of the environment. Type the following in Anaconda prompt (we chose `my-env-name` as the name for the environment which could be replaced with another name of your choice): .. code-block:: console $ conda create -n my-env-name python=3.9 Then activate the environment by typing ``conda activate my-env-name``. You are now ready to proceed with the next steps. For a quick overview of useful conda commands, we recommend going through the |conda-sheet|. .. |python| raw:: html Python 3.8 or newer .. |quantify-core| raw:: html quantify-core .. |quantify-scheduler| raw:: html quantify-scheduler .. |anaconda| raw:: html Anaconda .. |conda-sheet| raw:: html conda cheat sheet System dependencies ^^^^^^^^^^^^^^^^^^^ Qblox Instruments has one important system dependency, namely the HDF5 library. If this library is not installed on your system yet, please follow the installation instructions on the |hdf5|. New users of HDF5 should download the latest version for their operating system under the section `Pre-built Binary Distributions`. .. note:: (Windows only) If, after installation of the HDF5 library, you run into errors regarding Visual Studio C++, please install |microsoft_build| as well. .. |hdf5| raw:: html HDF5 website .. |microsoft_build| raw:: html Microsoft C++ Build Tools Qblox Instruments ^^^^^^^^^^^^^^^^^ The ``qblox-instruments`` driver package can be installed through |pip|, by executing the following command (make sure you have activated the correct environment using ``conda activate my-env-name``): .. code-block:: console $ pip install qblox-instruments This will install the most recent version of the driver package. Please make sure that the driver version you install is compatible with your Cluster firmware, verify via the |pypi|. For information on the firmware and driver updating procedure, see section :doc:`/getting_started/updating`. To install a specific version of the driver package, execute the following command: .. code-block:: console $ pip install qblox-instruments== .. tip:: You can query your installed version by executing ``$ pip show qblox-instruments``. With ``qblox-instruments``, two command-line tools will have been installed in your environment: :ref:`Qblox Configuration Manager ` and :ref:`Qblox Plug & Play `. We will be using these tools in the next step of connecting to your device(s): :ref:`connecting`. In addition, you might have noticed the |qcodes| dependency, which is the experiment and data acquisition framework used to control the Qblox hardware. .. |pip| raw:: html pip .. |pypi| raw:: html driver changelog on PyPi .. |qcodes| raw:: html QCoDeS Jupyter-lab ^^^^^^^^^^^ Our tutorials are run on the interactive `ipython` platform called |jupyter|. We recommend installing ``jupyter-lab`` which provides a user-friendly interface for maintaining these notebooks. Following are the steps to install it: * As always, start by activating the conda environment if you haven't already: .. code-block:: console $ # Replace my-env-name with the name of your environment $ conda activate my-env-name * Install jupyter-lab from conda .. code-block:: console $ conda install -c conda-forge jupyterlab * Once installed, run using .. code-block:: console $ jupyter-lab .. _getting_started_quantify: Quantify ^^^^^^^^ Qblox provides an additional open-source software stack, |quantify|, to control experiments on Qblox hardware. It is intended as a high-level interface to the Qblox hardware and contains frameworks to run quantum computing experiments from scratch. .. note:: Please make sure that you install Quantify in the same virtual environment as ``qblox-instruments`` (see :ref:`getting_started_installation`). Quantify is built on top of |qcodes| for handling various instruments and is split up into two packages: - |quantify-core| (|core_info|) is a data acquisition platform offering easy measurement control and data handling, - |quantify-scheduler| (|scheduler-info|) translates high-level descriptions of quantum gates or pulse sequences into programs that can be uploaded and run on Cluster devices. Please refer to the linked pages above for more information and installation instructions. .. |core_info| raw:: html installation and documentation .. |scheduler-info| raw:: html installation and documentation .. |quantify| raw:: html Quantify .. _connecting: Connecting to a Cluster --------------------------------- In this section we will explain how to connect a |cluster| to your host PC. .. figure:: /figures/cluster_overview.png :width: 876px :height: 528px :align: center :alt: . .. |cluster| raw:: html Qblox Cluster Connecting to a single system ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As an example, we will consider a setup composed of: * A laptop (host PC) with an Ethernet port, * A Qblox Cluster, configured to use the default IP configuration ``192.168.0.2/24``. The following steps will allow you to successfully connect the cluster to your local network: 1. Connect the Cluster to your host PC using an Ethernet cable. For a Cluster, the ethernet port is located on the Cluster Management Module (CMM), i.e. module 0, of the cluster. #. Power up the device. The device is ready when all LEDs are on and no LEDs are red (see :ref:`cluster_leds`). #. Configure the network adapter of the host PC, so that its IP address is within subnet ``192.168.0.X`` (where ``X`` is in a range from 3 to 254). Make sure the subnet mask is set to ``255.255.255.0``. .. admonition:: Common mistake :class: warning A common mistake is to configure your host machine's IP address to be the same as the device you want to control. This will cause IP address collision and you will not be able to connect to your device. It is recommended to choose a relatively high number in your subnet (e.g. ``192.168.0.200``) to avoid collisions. .. note:: Configuration of a network adapter varies slightly between operating systems. See section :ref:`network_cfg` for a Windows, Linux, and MacOS description. At this point, your setup will look similar to the example setup in the figure below: .. figure:: /figures/setup_cluster_pc.jpg :width: 666px :height: 500px :align: left :alt: A Qblox Cluster connected to a laptop using a USB Ethernet adapter. After a few seconds, your device should be present on the local network. You can verify this by executing the following command in a terminal of your choice. .. note:: The default IP address of the modules is ``192.168.0.2``. Replace the IP address of any following instruction accordingly if the IP address of the module was ever changed. See section :ref:`ip_addr` in case you do not know the IP address. .. code-block:: console $ ping 192.168.0.2 # Press Ctrl + C to terminate the program If successful, the output should be similar to the following example output: .. code-block:: console PING 192.168.0.2 (192.168.0.2): 56 data bytes 64 bytes from 192.168.0.2: icmp_seq=0 ttl=64 time=0.396 ms 64 bytes from 192.168.0.2: icmp_seq=1 ttl=64 time=0.232 ms 64 bytes from 192.168.0.2: icmp_seq=2 ttl=64 time=0.261 ms #. Finally, connect to the module from your host PC by running the following snippet in an interactive :ref:`Python ` shell or Jupyter Notebook: **Cluster:** .. code-block:: python # Import driver from qblox_instruments import Cluster # Connect to module cluster = Cluster("cluster", "192.168.0.2") .. tip:: Close the connection to the module using ``cluster.close()``. .. toctree:: :hidden: network_adapter_cfg.rst To verify that you are connected to the correct instrument, please see :ref:`the verification section ` below. .. note:: The :ref:`Frontpanel LEDs ` provide a quick way to check the status of your instrument after connection and during experiments. In case of an unexpected LED color, please refer to the :doc:`/cluster/troubleshooting`. section of the Qblox documentation website. Connecting to multiple instruments ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To be able to control multiple instruments we need to follow the steps described above, except now: - Instead of connecting a system directly to the Ethernet adapter of the host PC, we will connect all the systems and the host PC to the same network using, for example, an Ethernet switch. - The IP address of the systems **must** be changed to avoid IP collisions. See section :ref:`ip address and name` for further instructions on updating the IP address of the modules. As an example, we will consider a setup composed of: * A laptop (host PC) with an Ethernet port, * At least two Cluster instruments, * A network switch. The following Python code lets us connect to the instruments in the example setup: .. code-block:: python # Import driver from qblox_instruments import Cluster # Connect to module cluster_0 = Cluster("cluster_0", "192.168.0.2") # This cluster uses the default IP address. cluster_1 = Cluster("cluster_1", "192.168.0.3") # This cluster's IP address was changed. .. note:: When using multiple clusters in your setup, you might need to synchronize the in- and outputs of these participating instruments. See the page :doc:`Synchronization ` to learn how to do this. For clusters in the set up to be synchronised, all clusters need to share the same clock which will be provided by an external source in a star configuration. .. warning:: It is inadvisable to daisy chain the internal reference of one cluster to the other clusters in the set up. The reference clock should be connected to the REF\ :sup:`in` SMA connection of all clusters and the :meth:`~Cluster.reference_source` parameter should be set to external. Once all clusters share the same reference clock, they can be synchronised with each other by connecting them all via the SYNQ cable. This cable daisy chains the cluster as shown in the picture below. Synchronization between sequencers in connected clusters then works as expected. .. figure:: /figures/cluster_clock.png :align: center :width: 346px :height: 519px :alt: cluster_clock image A single Cluster CMM module with an external clock connected and attached SYNQ cable. .. figure:: /figures/cluster_synq.png :align: center :alt: cluster_synq image :width: 511px :height: 437px The entire setup is synchronised when all clusters are connected to a common external clock with equal length cables. .. _ip_addr: Finding the IP address of a module ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The most robust way to address any instrument connected via Ethernet is to configure it using a static IP address and then use that address directly. As we've seen in earlier sections, Clusters ship with IP address ``192.168.0.2`` by default, expecting to be in the ``192.168.0.0/24`` subnet. However, having to remember IP addresses is not very user-friendly, and if the instruments are to be connected through an existing network, static IP addresses may not even be an option: most networks use DHCP to automatically configure the IP addresses of the endpoints connected to it. In the latter case, ask your system administrator to be sure. If you have to use DHCP, or just don't want to have to hardcode IP addresses into your notebooks, you have two options, but both put some requirements on your network infrastructure: - **Addressing instruments by their name or serial number using Qblox Plug & Play.** This will only work when your PC is in the same subnet as the instruments, which is the case if, e.g., you are in the same Local Area Network (LAN). It will *not* work if there is a router or VPN in between. You can find all instruments addressable in this way by executing ``qblox-pnp list``, which will show the IP addresses, names, and serial numbers: .. code-block:: console $ qblox-pnp list Devices: - 192.168.0.3: CLUSTER QRM 0.5.0 with name "test" and serial number 00013_2120_003 Qblox Plug & Play is also available through its :ref:`Python API `, which can be used as follows. .. code-block:: python from qblox_instruments import PlugAndPlay with PlugAndPlay() as p: p.print_devices() - **Addressing instruments by their hostname via (local) DNS.** This requires DHCP and a router with local DNS support. Note that most consumer-grade routers *don't* support this, but enterprise hardware usually does. These four types of addresses (IP address, name, serial number, and DNS hostname) are collectively referred to as device identifiers. They are internally resolved via the :func:`~qblox_instruments.resolve` function; refer to its API documentation for the complete syntax supported by it. Both ``qblox-cfg`` and the Cluster instrument drivers in Python support all types of identifiers. .. _verify_connection: Verifying which instrument you're connected to ********************************************** Once you have a connection, you might want to ensure that you're connected to the right instrument. You can do this with the :meth:`~qblox_instruments.scpi.Cluster.identify` method on an instrument connection object: calling this will make the module blink its front-panel LEDs for a few seconds. You can do the same from the command line using ``qblox-pnp identify ``. Alternatively, if you're not physically near the instrument but you do know what its name is supposed to be, you can use the :meth:`~qblox_instruments.scpi.Cluster.get_name` method to retrieve it from an open connection. Renaming instruments ******************** The Cluster devices come pre-programmed with a default name ``cluster-cmm``. You can change the name using :meth:`~qblox_instruments.scpi.Cluster.set_name` in Python, or using the ``set-name`` subcommand of ``qblox-cfg`` (see :ref:`ip address and name`). Instrument names may be any single line of characters not including backslashes or underscores. .. warning:: Instrument names are case sensitive, so be aware that an instrument named ``A`` is different from an instrument named ``a``. Host names have more stringent requirements. They must be lowercase, at most 63 characters long, and besides letters and numbers only the ``-`` (dash) is allowed. If you want to use local DNS, make sure that you configure a name that complies with these rules to avoid confusion. If you configure a name that isn't a valid hostname, the instrument will change its hostname to a best-effort representation of the invalid name. .. note:: Name changes go into effect immediately for resolution via :ref:`Qblox Plug & Play `, but the hostname will only change after you reboot the instrument. That's it! You are all set to start playing around with the Cluster hardware! We would recommend starting with the tutorials available on this page (:doc:`/tutorials/index`) to get acquainted with the Python interface.