Contributing to the source code

Build up an development environment

Please follow the instruction on the QuTiP contribution guide to build a conda environment. You don’t need to build qutip in the editable mode unless you also want to contribute to qutip. Instead, you need to install qutip-qip by downloading the source code and run

pip install -e .

Docstrings for the code

Each class and function should be accompanied with a docstring explaining the functionality, including input parameters and returned values. The docstring should follow NumPy Style Python Docstrings.

Checking Code Style and Format

In order to check if your code in some_file.py follows PEP8 style guidelines, Black has to be installed.

pip install black

In the directory that contains some_file.py, use

black some_file.py --check
black some_file.py --diff --color
black some_file.py

Using --check will show if any of the file will be reformatted or not.

  • Code 0 means nothing will be reformatted.

  • Code 1 means one or more files could be reformatted. More than one files could be reformatted if black some_directory --check is used.

Using --diff --color will show a difference of the changes that will be made by Black. If you would prefer these changes to be made, use the last line of above code block.

Note

We are currently in the process of checking format of existing code in qutip-qip. Running black existing_file.py will attempt to format existing code. We advise you to create a separate issue for existing_file.py or skip re-formatting existing_file.py in the same PR as your new contribution.

It is advised to keep your new contribution PEP8 compliant.

Checking tests locally

You can run tests and generate code coverage report locally. First make sure required packages have been installed.

pip install pytest pytest-cov

pytest is used to test files containing tests. If you would like to test all the files contained in a directory then specify the path to this directory. In order to run tests in test_something.py then specify the exact path to this file for pytest or navigate to the file before running the tests.

pytest path_to_some_directory
pytest /path_to_test_something/test_something.py
~/path_to_test_something$ pytest test_something.py

A code coverage report in html format can be generated locally for qutip-qip using the code line given below. By default the coverage report is generated in a temporary directory htmlcov. The report can be output in other formats besides html.

pytest --cov-report html --cov=qutip_qip tests/

If you would prefer to check the code coverage of one specific file, specify the location of this file. Same as above the report can be accessed in htmlcov.

pytest --cov-report html --cov=qutip_qip tests/test_something.py