Contributing to QuTiP Development¶

Building¶

Building the core library from source is typically a bit more difficult than simply installing the package for regular use. You will most likely want to do this in a clean Python environment so that you do not compromise a working installation of a release version, for example by starting from

conda create -n qutip-dev python

Complete instructions for the build are elsewhere in this guide, however beware that you will need to follow the installation from source using setuptools section, not the general installation. You will need all the build and tests “optional” requirements for the package. The build requirements can be found in the pyproject.toml file, and the testing requirements are in the tests key of the options.extras_require section of setup.cfg. You will also need the requirements for any optional features you want to test as well.

Refer to the main instructions for the most up-to-date version, however as of version 4.6 the requirements can be installed into a conda environment with

conda install setuptools wheel 'numpy>=1.16.6,<1.20' 'scipy>=1.0' 'cython>=0.29.20' packaging 'pytest>=5.2' pytest-rerunfailures

Note that qutip should not be installed with conda install.

You will need to make sure you have a functioning C++ compiler to build QuTiP. If you are on Linux or Mac, this is likely already done for you, however if you are on Windows, refer to the Windows installation section of the installation guide.

The command to build QuTiP in editable mode is

python setup.py develop

from the repository directory. If you now load up a Python interpreter, you should be able to import qutip from anywhere as long as the correct Python environment is active. Any changes you make to the Python files in the git repository should be immediately present if you restart your Python interpreter and re-import qutip.

On the first run, the setup command will compile many C++ extension modules built from Cython sources (files ending .pxd and .pyx). Generally the low-level linear algebra routines that QuTiP uses are written in these files, not in pure Python. Unlike Python files, changes you make to Cython files will not appear until you run python setup.py develop again; you will only need to re-run this if you are changing Cython files. Cython will detect and compile only the files that have been changed, so this command will be faster on subsequent runs.

Code Style¶

The biggest concern you should always have is to make it easy for your code to be read and understood by the person who comes next.

All new contributions must follow PEP 8 style; all pull requests will be passed through a linter that will complain if you violate it. You should use the pycodestyle package locally (available on pip) to test you satisfy the requirements before you push your commits, since this is rather faster than pushing 10 different commits trying to fix minor niggles. Keep in mind that there is quite a lot of freedom in this style, especially when it comes to line breaks. If a line is too long, consider the best way to split it up with the aim of making the code readable, not just the first thing that doesn’t generate a warning.

Try to stay consistent with the style of the surrounding code. This includes using the same variable names, especially if they are function arguments, even if these “break” PEP 8 guidelines. Do not change existing parameter, attribute or method names to “match” PEP 8; these are breaking user-facing changes, and cannot be made except in a new major release of QuTiP.

Other than this, general “good-practice” Python standards apply: try not to duplicate code; try to keep functions short, descriptively-named and side-effect free; provide a docstring for every new function; and so on.

Documenting¶

When you make changes in the core library, you should update the relevant documentation if needed. If you are making a bug fix, or other relatively minor changes, you will probably only need to make sure that the docstrings of the modified functions and classes are up-to-date; changes here will propagate through to the documentation the next time it is built. Be sure to follow the Numpy documentation standards (numpydoc) when writing docstrings. All docstrings will be parsed as reStructuredText, and will form the API documentation section of the documentation.

Testing¶

We use pytest as our test runner. The base way to run every test is

pytest /path/to/repo/qutip/tests

This will take around 10 to 30 minutes, depending on your computer and how many of the optional requirements you have installed. It is normal for some tests to be marked as “skip” or “xfail” in yellow; these are not problems. True failures will appear in red and be called “fail” or “error”.

While prototyping and making changes, you might want to use some of the filtering features of pytest. Instead of passing the whole tests directory to the pytest command, you can also pass a list of files. You can also use the -k selector to only run tests whose names include a particular pattern, for example

pytest qutip/tests/test_qobj.py -k "expm"

to run the tests of Qobj.expm.

Changelog Generation¶

We use towncrier for tracking changes and generating a changelog. When making a pull request, we require that you add a towncrier entry along with the code changes. You should create a file named <PR number>.<change type> in the doc/changes directory, where the PR number should be substituted for <PR number>, and <change type> is either feature, bugfix, doc, removal, misc, or deprecation, depending on the type of change included in the PR.

You can also create this file by installing towncrier and running

towncrier create <PR number>.<change type>

Running this will create a file in the doc/changes directory with a filename corresponding to the argument you passed to towncrier create. In this file, you should add a short description of the changes that the PR introduces.

Building¶

The documentation is built using sphinx, matplotlib and numpydoc, with several additional extensions including sphinx-gallery and sphinx-rtd-theme. The most up-to-date instructions and dependencies will be in the README.md file of the documentation directory. You can see the rendered version of this file simply by going to the documentation GitHub page and scrolling down.

Building the documentation can be a little finnicky on occasion. You likely will want to keep a separate Python environment to build the documentation in, because some of the dependencies can have tight requirements that may conflict with your favourite tools for Python development. We recommend creating an empty conda environment containing only Python with

conda create -n qutip-doc python=3.8

and install all further dependencies with pip. There is a requirements.txt file in the repository root that fixes all package versions exactly into a known-good configuration for a completely empty environment, using

pip install -r requirements.txt

This known-good configuration was intended for Python 3.8, though in principle it is possible that other Python versions will work.

The documentation build includes running many components of the main QuTiP library to generate figures and to test the output, and to generate all the API documentation. You therefore need to have a version of QuTiP available in the same Python environment. If you are only interested in updating the users’ guide, you can use a release version of QuTiP, for example by running pip install qutip. If you are also modifying the main library, you need to make your development version accessible in this environment. See the above section on building QuTiP for more details, though the requirements.txt file will have already installed all the build requirements, so you should be able to simply run

python setup.py develop

in the main library repository.

The documentation is built by running the make command. There are several targets to build, but the most useful will be html to build the webpage documentation, latexpdf to build the PDF documentation (you will also need a full pdflatex installation), and clean to remove all built files. The most important command you will want to run is

make html

You should re-run this any time you make changes, and it should only update files that have been changed.

The HTML files will be placed in the _build/html directory. You can open the file _build/html/index.html in your web browser to check the output.

Code Style¶

All user guide pages and docstrings are parsed by Sphinx using reStructuredText. There is a general Sphinx usage guide, which has a lot of information that can sometimes be a little tricky to follow. It may be easier just to look at other .rst files already in the documentation to copy the different styles.

Testing¶

There are unfortunately no automated tests for the documentation. You should ensure that no errors appeared in red when you ran make html. Try not to introduce any new warnings during the build process. The main test is to open the HTML pages you have built (open _build/html/index.html in your web browser), and click through to the relevant pages to make sure everything has rendered the way you expected it to.