PIConGPU Commit Rulez

We agree on the following simple rules to make our lives easier :)

  • Stick to the style below for commit messages

  • Commit compiling patches for the dev branch, you can be less strict for (unshared) topic branches

  • Follow the code style and formatting which is democratically evolved in Contributing.

Pre-commit

Compliance with the coding style can be ensured (as much as automatically possible) by using pre-commit hooks (based on the more general but harder to use git hooks). After the following installation this little tool will run a number of checks prior to every commit, reject the commit, if they don’t succeed, and potentially apply fixes.

pre-commit is a Python tool, so you need a working version of python3, e.g. from conda, your favorite package manager or directly from the website. For installation, we provide requirements_pre-commit.txt and you can use

# set up a virtual environment if you prefer, then:
$ python3 -m pip install -r requirements_pre-commit.txt

# run this inside of your local clone of the repo:
$ pre-commit install

From now on, each commit in this clone of the repo will be checked. See pre-commit for usage details. Some hints:

  • You can run all hooks on all files via pre-commit run --all-files [--hook-stage manual]. The last argument --hook-stage manual includes rather slow additional tests that are run by the CI but are considered too heavy-weight to run before each commit.

  • If a check fails, the fixes are often applied automatically (e.g., run clang-format). If there are no unstaged files, these changes will appear as unstaged changes in your working tree. To make the commit pass, you have to git add all changed files.

  • In urgent cases, you can skip the checks via git commit [...] --no-verify. Be aware that similar things will be checked in CI during your PR and fail then at latest.

Manually Formatting Code

For C++ code, we provide .clang-format file in the root directory. Python code must adhere to PEP 8 guidelines. Following both of these is automated in pre-commit. If you are not able or willing to use pre-commit, you can instead do the following manually to get close to the same result:

For Python code, install black and run

black -l 120

The following describes formatting of C++ code.

  • Install ClangFormat 12 from LLVM 12.0.1

  • To format all files in your working copy, you can run this command in bash from the root folder of PIConGPU:

    find include/ share/picongpu/ share/pmacc -iname "*.def" \
-o -iname "*.h" -o -iname "*.cpp" -o -iname "*.cu" \
-o -iname "*.hpp" -o -iname "*.tpp" -o -iname "*.kernel" \
-o -iname "*.loader" -o -iname "*.param" -o -iname "*.unitless" \
| xargs clang-format-12 -i

Instead of using the bash command above you can use Git together with ClangFormat to format your patched code only. Before applying this command, you must extend your local git configuration once with all file endings used in PIConGPU:

git config --local clangFormat.extensions def,h,cpp,cu,hpp,tpp,kernel,loader,param,unitless

For only formatting lines you added using git add, call git clang-format-12 before you create a commit. Please be aware that un-staged changes will not be formatted.

Commit Messages

Let’s go for an example:

Use the 1st line as a topic, stay <= 50 chars

  • the blank line between the “topic” and this “body” is MANDATORY

  • use several key points with - or * for additional information

  • stay <= 72 characters in this “body” section

  • avoid blank lines in the body

  • Why? Pls refer to http://stopwritingramblingcommitmessages.com/

Compile Tests

We provide an (interactive/automated) script that compiles all examples within the examples/ directory in your branch.

This helps a lot to maintain various combinations of options in the code (like different solvers, boundary conditions, …).

PIConGPU CompileTest

Assume

  • repo=<pathToYourPIConGPUgitDirectory>

  • tmpPath=<tmpFolder>

Now run the tests with

  • $repo/compile -l $repo/examples/ $tmpPath

Further options are:

  • -q    : continue on errors

  • -j <N> : run <N> tests in parallel (note: do NOT omit the number <N>)

If you ran your test with, let’s say -l -q -j 4, and you got errors like

[compileSuite] [error] In PIC_EXTENSION_PATH:PATH=…/params/KelvinHelmholtz/cmakePreset_0: CMAKE_INSTALL_PREFIX:PATH=…/params/KelvinHelmholtz/cmakePreset_0 (…/build) make install

check the specific test’s output (in this case examples/KelvinHelmholtz with CMake preset #0) with:

  • less -R $tmpPath/build/build_ThermalTest_cmakePreset_0/compile.log

Compile Tests - Single Example

Compile all CMake presets of a single example with:

  • $repo/compile $repo/examples/ $tmpPath

Compile Tests - Cluster Example:

  • Request an interactive job (to release some load from the head node) qsub -I -q laser -lwalltime=03:00:00 -lnodes=1:ppn=64

  • Use a non-home directory, e.g. tmpPath=/net/cns/projects/HPL/<yourTeam>/<yourName>/tmp_tests/

  • Compile like a boss! <pathToYourPIConGPUgitDirectory>/compile -l -q -j 60 <pathToYourPIConGPUgitDirectory>/examples/ $tmpPath

  • Wait for the thumbs up/down :)