Getting Started¶

Requirements¶

You need a working python 3.9 installation, as the minimum Python version, to be able to use QCoDeS. We highly recommend installing Miniconda, which takes care of installing Python and managing packages. In the following it will be assumed that you use Miniconda. Download and install it from here. Make sure to download the latest version with python 3.9 or newer.

Once you download, install Miniconda according to the instructions on screen, choosing the single user installation option.

The next section will guide you through the installation of QCoDeS on Windows, although most of the things also work for macOS and Linux.

Installation¶

Before you install QCoDeS you have to decide whether you want to install the latest stable release or if you want to get the developer version from GitHub.

Stable versions of QCoDeS are distributed via both PyPi and CondaForge to be installed with pip and conda respectively. Below we will cover both installation types. For new users we recommend installing QCoDeS from conda-forge.

Installing the latest QCoDeS release with pip¶

Next launch an Anaconda Prompt (start typing anaconda in the start menu and click on Anaconda Prompt).

Here type in the prompt:

conda create -n qcodes python=3.9
conda activate qcodes
pip install qcodes

The first line creates a new conda environment that is called qcodes with python 3.9. The second line activates this freshly created environment, so that the command in the third line will install qcodes for this environment.

Installing the latest QCoDeS release with conda¶

To install QCoDeS using Conda from conda-forge type the following into a prompt.

conda create -n qcodes
conda activate qcodes
conda config --add channels conda-forge --env
conda config --set channel_priority strict --env
conda install qcodes

First we crate a new environment to install QCoDeS into and then we set that environment up to install packages from conda-forge since QCoDeS is not available in the default channel. As recommended by the conda-forge maintainers we set channel_priority to strict to prefer all packages to be installed from the conda-forge channel. Note that we use the –env flag to only set these settings for the QCoDeS env. We do this to not change the settings for any other environment that you may have created. Finally we install QCoDeS into this environment.

Installing QCoDeS from GitHub¶

Clone the QCoDeS repository and submodules from GitHub from https://github.com/QCoDeS/Qcodes

git clone --recurse-submodules https://github.com/QCoDeS/Qcodes <path-to-repository>

Finally install QCoDeS add the repository via

pip install -e <path-to-repository>

This will perform an editable install such that any changes of QCoDeS in your local git clone are automatically available without having to reinstall QCoDeS.

Note that if you wish to run the QCoDeS test you will also need to install the testing dependencies. This can be done by installing QCoDeS using the test extra target.

pip install -e <path-to-repository>[test]

Installing QCoDeS from a Forked GitHub Repository¶

If you’ve forked the QCoDeS repository, make sure to also fetch the tags from the upstream repository for accurate versioning, especially if you wish to install with test dependencies. Not doing so may result in version conflicts.

# Add the original QCoDeS repository as the 'upstream' remote
git remote add upstream https://github.com/QCoDeS/Qcodes.git

# Fetch all tags from the 'upstream' repository
git fetch --tags upstream

After fetching the tags, proceed with the installation as usual:

pip install -e <path-to-forked-repository>
# Or with test dependencies
pip install -e <path-to-forked-repository>[test]

Other dependencies¶

To connect to many instruments (All instruments that are subclasses of VisaInstrument ) you need a working VISA implementation installed. There are several of these available from instrument vendors and other sources.

We recommend you to install the Keysight IO Libraries Suite from here. To download it, you will need to provide your e-mail id, name and location but the download is free of charge.

See the PyVISA documentation for more information.

Updating QCoDeS¶

If you have installed with pip, run the following to update:

pip install --upgrade qcodes

If you have installed from conda-forge

conda update qcodes

in principle, there should be a new release out roughly every month.

If you have installed with git, pull the QCoDeS repository using your favourite method (git bash, git shell, github desktop, …). There are new commits to the repository daily.

Keeping your environment up to date¶

Additional dependencies are periodically added to the QCoDeS and new versions of packages that QCoDeS depends on are released.

Installing a new version of QCoDeS will automatically upgrade any dependency if required. However you may wish to upgrade some of the dependency to a newer version than the minimum version required by QCoDeS

If you have installed QCoDeS using pip you can upgrade each package individually. E.g. to upgrade numpy you would do.

pip install --upgrade numpy

You can list all outdated packages using

pip list --outdated

If you have installed QCoDeS using conda upgrading all packages can be done by:

conda update -n base conda -c defaults
conda update --all

The first line ensures that the conda package manager it self is up to date and the second line will ensure that the latest versions of the packages used by QCoDeS are installed.

If you using QCoDeS from an editable install you should also reinstall QCoDeS using

pip install -e <path-to-repository>

After upgrading the environment to make sure that dependencies are tracked correctly.

Note that if you install packages yourself into the same environment it is preferable to install them using the same package manager that you install QCoDeS with. There is a chance that mixing packages from conda and pip will produce a broken environment. Especially if the same package is installed using both pip and conda.

Using QCoDes¶

For using QCoDeS, as with any other python library, it is useful to use an application that facilitates the editing and execution of python files. There are two widely used options:

Jupyter, a browser based notebook

Spyder, an integrated development environment

Both can be installed using conda or pip in the created conda environment for QCoDeS. Then installation can be simply done by activating the QCoDeS environment in the terminal and running the following:

pip install spyder
pip install jupyter

If you prefer jupyterlab over classic jupyter notebook, you should install it separately:

pip install jupyterlab

If you installed QCoDeS using conda-forge, you may want to install above using conda install rather than pip install. After installation, they could be easily called in your QCoDeS-activated conda terminal.

For running spyder:

spyder

or for jupyter notebook:

jupyter notebook

or jupyter lab:

jupyter lab

Note

Note that Spyder ships with functionality to automatically reload modules that are installed editable. This functionality called User Module Reloader is known to not work well with QCoDeS. If you install QCoDeS editable (with -e flag) we strongly recommend users to exclude QCoDeS from UMR. QCoDeS used to attempt to automatically disable this feature. However, as Spyder does not provide a public API for doing this this relied on a private API in Spyder and broke with the last Spyder release. If at some point this becomes possible to do with a public API QCoDeS may again disable this automatically.

For other options from the terminal you can activate the QCoDeS in that terminal then start any other application, such as IPython or just plain old Python.

It is also possible to install Anaconda for managing conda environments, however, you should be mindful about using it as Anaconda installs a wide verity of packages in the root environment upon installation. It comes with a GUI called Anaconda Navigator to work with. If you rather to use this GUI over the conda terminal, make sure to select the QCoDeS environment in the program, then you could be able to run the packages installed in that environment. The reason is because by default, Anaconda Navigator starts with the base(root) environment.

Working example notebooks¶

For a more hands-on approach to learning about QCoDeS, have a look at 15 minutes to Qcodes.

We also have a library of examples notebooks that detail more specific features of the software suite.