Contributing to Kwant

We see Kwant not just as a package with fixed functionality, but rather as a framework for implementing different physics-related algorithms using a common set of concepts. Contributions to Kwant are highly welcome. You can help the project not only by writing code, but also by reporting bugs, and fixing/improving the website and the documentation.

Where help is needed

The Kwant issue tracker serves to track bugs in Kwant, but most issues are in fact ideas for enhancements. The issues are categorized with labels, so that it is possible to view all the “easy” issues for example.

Please do feel free to enter new issues yourself. If you are unsure about some aspect It may be a good idea to discuss your idea on the mailing list kwant-discuss@kwant-project.org before filing an issue.

If you already have some code that extends Kwant in a useful way, please consider sharing it. If your extension fits well with Kwant and is of wide enough interest, we will be happy to include it into Kwant proper. For more specialized cases, we will find a solution as well. (We could, for example, add a list of Kwant-related modules to this website.) In any case, external contributions will be clearly marked as such, and relevant papers will be added to the list of suggested acknowledgements.

Getting the source code

The source code of released versions of Kwant is available for download. You can follow the development through the Kwant page of our GitLab instance. The Git repository of Kwant can be cloned directly with the command

git clone https://gitlab.kwant-project.org/kwant/kwant.git

The Kwant git repository has two main branches: The branch master contains the development towards the next release. The branch stable contains the most recent release that is considered stable, and only bugfixes are applied to it.

Setting up for development

When working with the Kwant source, regular build instructions apply. It would be tiresome, however, to have to reinstall the modified Kwant after each modification.

One easy way to avoid this is to build in-place so that there is no need to reinstall after each change. This can be done with the following command

python3 setup.py build_ext -i

No further installation is necessary. The “inner” kwant subdirectory has been turned into a proper Python package that can be imported from the “outer” directory, i.e. the directory where setup.py is located. Any script inside that directory that imports Kwant will get the modified version. (To be able to import the modified Kwant from another directory one can create a symbolic link to the package.)

The above build_ext command does not have to be rerun when a Python file is modified. Recompilation is only necessary whenever a Cython file (.pyx) has been changed.

Modifying the source code

We recommend that you keep each of your changes to Kwant on a separate “topic branch” that starts at master. Try to not mix up unrelated changes in a single branch. To create a topic branch, use the command:

git checkout -b my_topic master

Now you can begin to implement your idea. As you go, register your changes with Git as explained, for example, in the Pro Git book that is freely available online.

Once you feel that you would like to show your work to other interested people (because you would like to receive feedback, or because you consider it ready), it's time to inspect your branch. Run git status to make sure that you have committed all of your changes, then use a tool like gitk to view your branch.

In the following, two methods to share your commits are described. The first will be familiar if you have experience with the popular GitHub service. If you do not, you might prefer the second method, since it is simpler.

Method 1: Using the Kwant GitLab instance

Go the GitLab page of the official Kwant repository. Since you do not have write access to this repository, you have to create an own “fork” of it by clicking on the button just right of the “star” button.

You created a public copy of the Kwant repository that is controlled by you. Add it as a remote repository to the clone of Kwant on your computer:

git remote add own https://gitlab.kwant-project.org/<USERNAME>/kwant.git

You can copy-and-paste your own version of the above URL from the main page of your repository. (If you know about SSH, you may also prefer to upload your public ssh key to GitLab and to use SSH as transport.) The string own is the local name you give to the remote, it can be anything.

Now you can push your topic branch to your repository:

git push own my_branch

This will make your branch appear in GitLab. Now you can let us know about your branch by creating a merge request in GitLab or by sending a message to kwant-discuss@kwant-project.org.

Method 2: Sending patches to the mailing list

Run the command

git format-patch origin/master

This will create a “patch” file for each commit on your branch. Now simply send these patches as email attachments to kwant-discuss@kwant-project.org, together with an explanation of your idea. You do not have to be subscribed to the mailing list.

(Or, even better, use git send-email as shown in this example of usage and this git send-email howto.)

Coding style

  • Please keep the code consistent by adhering to the prevailing naming and formatting conventions. We generally respect the "Style Guide for Python Code". For docstrings, we follow NumPy's "Docstring Standard" and Python's "Docstring Conventions".
  • Write tests for all the important functionality you add. Be sure not to break existing tests.
  • Create a logical sequence of commits with clear commit messages. Each commit message consists of a summary line, and, whenever necessary, a more detailed explanation. Both parts are separated by a blank line and wrapped to 72 characters (unless quoting error messages and such). The summary line should be as clear as possible. The detailed explanation should be included whenever it helps to motivate or understand the commit. Bear in mind that the merge request text and discussions are not part of a commit.