Getting Started#

Prerequisites#

CUQIpy is python package. To install it, you need to have Python installed. We recommend installing python via the anaconda distribution:

Anaconda comes with many useful python libraries pre-installed and makes it easy to run CUQIpy code via the jupyter notebook app. In addition, CUQIpy plugins often require 3rd party libraries that can most easily be installed through anaconda. Miniconda is a lightweight alternative to Anaconda if storage is a concern.

Installation#

Before installing CUQIpy, We highly recommend creating a new Python environment using conda. This will ensure that CUQIpy’s dependencies do not interfere with other Python packages you may have installed. Here we choose cuqipy-env as the environment’s name and also install pip in it with the following command

conda create -n cuqipy-env pip

Then to activate the environment:

conda activate cuqipy-env

Then install CUQIpy and all its dependencies in the activated environment cuqipy-env:

pip install cuqipy

This will install the latest version of CUQIpy and all its dependencies.

We also suggest installing ipykernel to be able to run CUQIpy jupyter notebook examples:

pip install ipykernel

Verification#

To ensure that CUQIpy is installed correctly, launch the python interpreter by typing:

python

then import CUQIpy into your python session by typing:

import cuqi

If no error messages are displayed, CUQIpy is likely installed correctly. The python interpreter can be exited by typing exit().

Start using CUQIpy#

You are now ready to start using CUQIpy! A good place to start is the CUQIpy demos repository containing a number of jupyter notebooks, which is a great way to interactively learn how to use CUQIpy.

To get started with the demos, first download and extract the zip file. Then launch the jupyter notebook app (that came pre-installed with anaconda) either from the Windows start menu or via the terminal by typing:

jupyter notebook

Navigate to the folder where you extracted the zip file using the file browser inside the notebook app, and open one of the notebooks. If you are new to jupyter notebooks, see the Jupyter notebook tutorial for a quick introduction.

More information on CUQIpy can be found in the User Guide.

Plugins (optional)#

CUQIpy can be extended with additional functionality by installing optional plugins. These can be found here: CUQIpy plugins.

Often the plugins use 3rd party libraries that are not compatible with each other, so it is always recommended to install the plugins in a separate environment. We recommended using anaconda to create a new environment and install the plugins in that environment.

Running the Tests (optional)#

To fully make sure that CUQIpy runs as expected on your machine you can run the automatic tests. This requires pytest to be installed. You can install it using pip:

pip install pytest

Then run the tests from the terminal (Linux or Mac) or Anaconda Prompt (Windows) by typing:

python -m pytest -v

Working with VS Code (optional)#

To improve your coding experience with Python in VS Code, we recommend installing the Python and Jupyter extensions in VS Code. In VS Code, don’t forget to select the Python interpreter of the environment in which CUQIpy is installed, cuqipy-env in this case. More information on how to work with Python in VS Code can be found here.