Creating a Development Environment¶
This page describes how to get a QuTiP development environment set up so that you can begin contributing code, documentation or examples to QuTiP. Please stop by to talk to us either in the QuTiP Google group or in the issues page on the main QuTiP repository if you have suggestions for new features, so we can discuss the design and suitability with you.
To contribute to QuTiP development, you will need to have a working knowledge of
git. If you’re not familiar with it, you can read GitHub’s simple
introduction or look at the official
Git book which also has the basics, but
then goes into much more detail if you’re interested.
qutip from source and to run the tests, you will need recent
python(at least version 3.6)
You will also need a working C++ compiler. On Linux or Mac, there should
already be a suitable version of
clang available, but on Windows
you will likely need to use a recent version of the Visual Studio compiler.
You should set up a separate virtual environment to house your development version of QuTiP so it does not interfere with any other installation you might have. This can be done with
conda create -n qutip-dev python>=3.6 setuptools numpy scipy pytest Cython
This will create the virtual environment
qutip-dev, which you can then
switch to by using
conda activate qutip-dev. Note that this does not
install any version of
qutip, because we will be building that from source.
You do not need to use
conda—any suitable virtual environment manager
should work just fine.
Creating a Local Copy¶
At some point you will (hopefully) want to share your changes with us, so you should fork the main repository on GitHub into your account, and then clone that forked copy. If you do not create a fork on GitHub, you will be able to read and install QuTiP, but you will not be able to push any changes you make back to GitHub so you can share them with us.
To create a fork, go to the relevant repository’s page on GitHub (for example, the main QuTiP repository is qutip/qutip on GitHub), and click the fork button in the top right. This will create a linked version of the repository in your own GitHub account. GitHub also has its own documentation on forking.
You can now “clone” your fork onto your local computer. The command will look something like
git clone https://github.com/<user>/qutip
<user> is your GitHub username (i.e. not
qutip). This will
create a folder in your current directory called
qutip which contains the
repository. This is your local copy.
You can put your local copy wherever you like, and call the top-level
directory whatever you like, including moving and renaming it after the
clone operation. As there is more than one QuTiP organisation
repository, you may find it convenient to have
notebooks all in a containing folder called
Building From Source¶
Make sure you have activated your QuTiP development virtual environment that you
set up earlier. You should not have any version of QuTiP installed here. If
you are in the root of the
qutip repository (you should see the file
setup.py), then the command to build is
python setup.py develop
If you need to test OpenMP support, add the flag
--with-openmp to the end of
develop target for
setuptools will compile and
link all of the Cython extensions, package the resulting files into an egg, and
add the package to the Python search path. After you have done this, you should
be able to
import qutip from anywhere as long as you have this development
environment active, and you will get your development environment.
In general, you do not need to re-run
setup.py if you only make changes
to the Python files. These changes should appear immediately when you
qutip, albeit with the standard Python proviso that you may
need to re-open the Python interpreter or use
clear the package cache.
If you make changes to any Cython files, you must
setup.py develop in the same manner, or your extensions will not
You should now be able to run the tests. From the root of the repository, or
qutip/tests, you can simply run
pytest to run
everything. The full test suite will take about 20–30 minutes, depending on
your computer. You can test specific files by passing them as arguments to
pytest, or you can use the
-m "not slow" argument to disable some of the
QuTiP development follows the “GitHub Flow” pattern of using Git. This is a simple triangular workflow, and you have already done the first step by creating a fork. In general, the process for contributing code follows a short list of steps:
Fetch changes from the QuTiP organisation’s copy
Create a new branch for your changes
Add commits with your changes to your new branch
Push your branch to your fork on GitHub
Make a pull request (PR) to the QuTiP repository
While using this pattern, you should keep your
master branch looking the
same as ours, or at least you should not add any commits to it that we do not
have. Always use topic branches, and do not merge them directly into
master. Wait until your PR has been accepted and merged into our version,
then pull down the changes into your
To fetch changes from our copy, you will need to add our version (the repository that you clicked “Fork” on) as a Git remote. The base command is
git remote add upstream https://github.com/qutip/qutip
This will add a remote called
upstream to your local copy. You will not
have write access to this, so you will not be able to push to it. You will,
however, be able to fetch from it. While on
git pull upstream master
Unless you have made changes to your own version of
master, this will bring
you up-to-speed with ours. To create and swap to a new branch to work on, use
git checkout -b <branchname>
You can then swap branches by using
git checkout <branchname> without the
-b option. To add commits to a branch, make the changes you want to make,
git add <file1> [<file2> ...]
on all the files you changed, and do
git commit -m "<your message>"
to commit them. Once you’ve made all the commits you want to make, push them to your GitHub fork with
git push -u origin
and make the PR using the GitHub web interface in the main QuTiP repository.
Please give the pull request a short, clear title that gives us an idea of what your proposed change does. It’s good if this not more ten words, and starts with an imperative verb. Good examples of titles are:
In the body of the PR, please use the template provided. In particular, describe in words what you’ve done and why you’ve done it and link to any issues that are related. Please also write a short comment (about a sentence) for the changelog. If you have made quite a small PR, the changelog can just be a copy-paste of the title.
All PRs will be reviewed by the admin team, and merged subject to their comments. We’re happy to answer questions and help you if we ask for changes. If you have lots of questions before you start, please consider raising an issue on GitHub (on our copy of the repository) first, so we can discuss it with you before you start coding. If you’ve noticed a bug and you have submitted a PR to fix it, you may also want to check it hasn’t been reported before as an issue, and comment on it if it has to let us know you’re working on it.
For any major new features, we strongly recommend creating an issue first, so we can tell you if we think it’s appropriate for the library, or point you to the repository of a more suitable plugin, and organise the design with you before you start coding.
When you make the PR, our continuous integration server will run the full test suite on a variety of machines, and check the code style. You should run the tests locally before you make the PR to check to save you time, because waiting for the CI to complete can take a while if the repository is active. We will not accept any PR with failing tests, unless the failure was not caused by you.
All new Python code should follow the standard PEP 8 style guide. Our CI pipelines will test this when you make a PR, although in limited circumstances we may accept a PR which breaks the 79-character line-length requirement by a small amount if doing so improves readability.
You can locally check that you are following PEP 8 by using the
flake8 (link) tools, which can be installed by either
pip. We strongly recommend that you do this before commiting.
You do not need to fix all existing PEP 8 issues in a file that you are editing. If you want to do so, please ensure that these changes are added as a separate commit, and ideally a completely separate PR. It is difficult to review the meaningful code changes you have made when they are crowded out by minor formatting ones.
All functions, classes and methods should have up-to-date docstrings. We use Sphinx’s autodoc extension to generate API documentation, so please ensure that your docstrings follow the NumPy docstring format.
New or changed functionality should have comprehensive unit tests. Add these
qutip/tests folder, following the conventions in there. Try to add
them to the relevant file if it already exists. We use
pytest to run the
tests, so write your tests in this style; in particular, there is no need for
unittest.TestCase classes with
methods, and multiple tests on similar objects should make use of the
New features should be supported by an example Jupyter notebook in the
qutip-notebooks repository (qutip/qutip-notebooks on GitHub).
This will require making a separate PR to that repository, and it’s helpful if
you add links between the two in the descriptions.
Please use the same parameter and attribute names that are already in use within the library when referring to similar objects, even if to do so would break the PEP 8 rules for new names. Please prefix private attributes and methods in classes with an underscore, and use new classes sparingly; QuTiP is designed for scientific notebook use, and a “pure” object-orientated style does not fit this use case. Please do not change existing public parameter and attribute names without consulting with us first, even if the names are ugly, because many users may depend on the names staying the same.