This is the final report of my Google Summer of Code experience in 2022. I am very happy that I got selected by QuTiP for this program and that I was able to make meaningful contributions to the project. Special thanks to Simon Cross and Neill Lambert for supporting me throughout this summer. You created a great work environment to contribute to QuTiP and helped me with all my questions and problems.
I think, the project was a great success and I was able to accomplish almost all project goals. It surprised me how quick (only 3 months) I was able to gain deep insights into the development of QuTiP and push the tutorial project to a really good status. There are a few things, which could still be improved, but all large tasks are done. I have also learned a lot about the personal side behind open-source software and I am looking forward to continue my work in open-source in the future :)
This document summarizes my work on QuTiP of the last 3 months and evaluates the current status of the project. Most of my work is located in the qutip-tutorials repository. Additionally, I contributed to the main qutip repository and the qutip-qip repository (see the links to all PRs below). I also wrote a blog about my work, which you can find here.
In my proposal, I described the project in great detail. In short, I wanted to update the notebooks that are supplied with QuTiP as usage examples to work with the current release (version 4) and the upcoming release (version 5) of QuTiP. Along the way, I intended to add automatic testing, style checks and provision of the tutorials to the QuTiP website.
A first step for better compatibility with git features, was to provide the notebooks in the qutip-tutorials repo in a markdown format. To convert between the .ipynb format and the .md format, I decided to use JupyText, which is easy to set up and converts the notebooks reliably. nbmake allows testing the notebooks in the repository automatically, and catches errors in any cell. For better readability, I wanted the notebooks to follow the PEP8 style guide. nbQA is a tool that allows to apply formatting tools to Jupyter notebooks that are usually applied to typical .py files. For verifying the correct code style of a notebook, I can thus use nbQA in combination with flake8. For auto-formatting of the notebooks you can use tools like black or isort in combination with nbQA which is also described in the qutip-tutorials README.
Combining all these feature in a Github Action was the first big step for this project. The full pipeline can now be found in the corresponding YAML file. Any commit and pull request to the repository triggers the CI pipeline and shows any problem in the notebooks.
Making the notebooks compatible with QuTiP 4 and 5 was the main task of the project. For this, I had to take the notebooks from the qutip-notebooks repo, adapt them for the current and upcoming release and add them to the new qutip-tutorials repo. As there are about 100 notebooks in the qutip-notebooksrepo, it was clear from the beginning, that it is not possible to port over all the notebooks in my project. Hence, I focussed on the notebooks that are published on the QuTiP Tutorials Website. Additionally, I ported over the lecture series on QuTiP by Robert Johansson.
Since many of the notebooks were not updated in a few years, the code was outdated, and I had to research a lot about QuTiP functionalities to get the notebooks back to run. Furthermore, I wanted new users to understand these notebooks, and thus I had to add a lot of Markdown text as code explanations. For some notebooks, I decided to rewrite them completely. While updating all these notebooks, I came along quite a few bugs in QuTiP 4 and 5. In most cases, I tracked down the bug and created pull requests for fixes in qutip and qutip-qip. Therefore, this task does not only deliver great and working tutorials to the users, but also improves QuTiP itself.
To keep track of the progress, I created a GitHub project and categorized the notebooks according to their status. Currently, I have ported over 50 notebooks, while roughly 40 remain to be ported. The not ported ones are part of some larger categories:
- Permutational invariant Lindblad dynamics
- Optimal Control
- Tomography
- Hierarchical Equations of Motion
These notebooks need further work to be compatible with the current releases of QuTiP.
The notebooks are published on the QuTiP Tutorials Website. The website contains hard-coded links to the notebooks in the qutip-notebooks repository (passing them through nbviewer.org for good displaying). The overall goal is to change the website to include the contents from the new qutip-tutorials repo. Therefore, I created an automatic publishing pipeline that creates the website directly from the contents of the repo. The website is then published, using the GitHub pages functionality, to qutip.org/qutip-tutorials. I wrote a Python script to build the website from the templates using the Jinja2 templating enginge. The pipeline also ensures that any new notebook in the repository is directly published to the website (after it passes all the tests described above).
The website is built from the templates in the qutip.github.io repo. If the website templates are changed, the new tutorials page automatically uses the new templates. The full workflow for generating and publishing the website is included in the CI YAML file.
The testing pipeline and the style guide are fully in-place and work for every new notebook.
The porting of the notebooks is still in progress, but was expected to not be finished in this project. Until now, the links to the old notebooks remain on the QuTiP Tutorials website. The updated notebooks already have the correct links, which are automatically added from within the pipeline. The GitHub project keeps track of the progress of the notebook porting. There are a few open pull requests waiting for review, that add more notebooks to the qutip-tutorials repo:
The automatic website publishing is done, and the corresponding pull request is ready to be merged. I also created a pull request that updates the qutip.org website to replace the old tutorials website with the new automatically-generated website.
In conclusion, the project is about to be finished. All changes are prepared in pull request and can be merged, after a thorough review. I will continue to work on this project after all changes are merged and ultimately the new tutorials website is published at qutip.org.
This section lists all contributions that I made to repositories related to QuTiP. I do not list the contributions to the qutip-tutorials repository.
- Bug fix for Nonmarkov Transfer Method
- Fix implementation of Orbital Function
- Fix bug in Quantum Circuit plotting
- Build QuTiP PDF documentation using GitHub Actions
- Fix progress bar and return states in HEOM Solver
- Issue for Dicke entropy calculation
- Improve docs of
sesolveandmesolve - Report issue with
qutip.groundstate - Update documentation of
brmesolve - Discussion on transition from v4 to v5
- Bugfix for
floquet_markov_mesolve - Update Floquet Markov documentation
- Adaptive integration steps for Floquet Master Equation Rates
- Report issue on
plot_spin_distribution_2d - Report issue on colorbar in Bloch sphere
- Bugfix for accessing a variable
- Fix wrong element access
- Fix tests of
qutip-qipto work with QuTiP 5 - Guide on superoperators
👍