Contributing to ABACUS
First of all, thank you for taking time to make contributions to ABACUS! This file provides the more technical guidelines on how to realize it. For more non-technical aspects, please refer to the ABACUS Contribution Guide
Table of Contents
Got a question?
Please referring to our GitHub issue tracker, and our developers are willing to help. If you find a bug, you can help us by submitting an issue to our GitHub Repository. Even better, you can submit a Pull Request with a patch. You can request a new feature by submitting an issue to our GitHub Repository. If you would like to implement a new feature, please submit an issue with a proposal for your work first, and that ensures your work collaborates with our development road map well. For a major feature, first open an issue and outline your proposal so that it can be discussed. This will also allow us to better coordinate our efforts, prevent duplication of work, and help you to craft the change so that it is successfully accepted into the project.
Structure of the package
Please refer to our instructions on how to installing ABACUS. The source code of ABACUS is based on several modules. Under the ABACUS root directory, there are the following folders:
cmake
: relevant files for finding required packages when compiling the code with cmake;docs
: documents and supplementary info about ABACUS;examples
: some examples showing the usage of ABACUS;source
: the source code in separated modules, under which atest
folder for its unit tests;tests
: End-to-end test cases;tools
: the script for generating the numerical atomic orbitals.
Submitting an Issue
Before you submit an issue, please search the issue tracker, and maybe your problem has been discussed and fixed. You can submit new issues by filling our issue forms. To help us reproduce and confirm a bug, please provide a test case and building environment in your issue.
Code formatting style
We use clang-format
as our code formatter. The .clang-format
file in root directory describes the rules to conform with. For Visual Studio Code developers, the official extension of C/C++ provided by Microsoft can help you format your codes following the rules. With this extension installed, format your code with shift+command/alt+f
. Configure your VS Code settings as "C_Cpp.clang_format_style": "file"
(you can look up this option by pasting it into the search box of VS Code settings page), and all this stuff will take into effect. You may also set "editor.formatOnSave": true
to avoid formatting files everytime manually.
Adding a unit test
We use GoogleTest as our test framework. Write your test under the corresponding module folder at abacus-develop/tests
, then append the test to tests/CMakeLists.txt
. If there are currently no unit tests provided for the module, do as follows. module_base
provides a simple demonstration.
Add a folder named
test
under the module.Append the content below to
CMakeLists.txt
of the module:IF (BUILD_TESTING) add_subdirectory(test) endif()
Add a blank
CMakeLists.txt
undermodule*/test
.
To add a unit test:
Write your test under
GoogleTest
framework.Add your testing source code with suffix
*_test.cpp
intest
directory.Append the content below to
CMakeLists.txt
of the module:AddTest( TARGET <module_name>_<test_name> # this is the executable file name of the test SOURCES <test_name>.cpp # OPTIONAL: if this test requires external libraries, add them with "LIBS" statement. LIBS math_libs # `math_libs` includes all math libraries in ABACUS. )
Build with
-D BUILD_TESTING=1
flag. You can find built testing programs underbuild/source/<module_name>/test
.Follow the installing procedure of CMake. The tests will move to
build/test
.
Debugging the codes
For the unexpected results when developing ABACUS, GDB will come in handy.
Compile ABACUS with debug mode.
cmake -B build -DCMAKE_BUILD_TYPE=Debug
After building and installing the executable, enter the input directory, and launch the debug session with
gdb abacus
. For debugging in Visual Studio Code, please set cwd to the input directory, and program to the path of ABACUS executable.Set breakpoints, and run ABACUS by typing “run” in GDB command line interface. If the program hits the breakpoints or exception is throwed, GDB will stop at the erroneous code line. Type “where” to show the stack backtrace, and “print i” to get the value of variable i.
For debugging ABACUS in multiprocessing situation,
mpirun -n 1 gdb abacus : -n 3 abacus
will attach GDB to the master process, and launch 3 other MPI processes.
For segmentation faults, ABACUS can be built with Address Sanitizer to locate the bugs. This feature requires a GCC or Clang compiler, and does not support Intel compiler.
cmake -B build -DENABLE_ASAN=1
Run ABACUS as usual, and it will automatically detect the buffer overflow problems and memory leaks. It is also possible to use GDB with binaries built by Address Sanitizer.
Valgrind is another option for performing dynamic analysis.
Generating code coverage report
This feature requires using GCC compiler. We use gcov
and lcov
to generate code coverage report.
Add
-DENABLE_COVERAGE=ON
for CMake configure command.cmake -B build -DBUILD_TESTING=ON -DENABLE_COVERAGE=ON
Build, install ABACUS, and run test cases. Please note that since all optimizations are disabled to gather running status line by line, the performance is drastically decreased. Set a longer time out to ensure all tests are executed.
cmake --build build --target test ARGS="-V --timeout 21600"
Generate HTML report.
cd build/ make lcov
Now you can copy build/lcov
to your local device, and view build/lcov/html/all_targets/index.html
.
We use Codecov to host and visualize our code coverage report. Analysis is scheduled after a new version releases; this action can also be manually triggered.
Submitting a Pull Request
Fork the ABACUS repository. If you already had an existing fork, sync the fork to keep your modification up-to-date.
Pull your forked repository, create a new git branch, and make your changes in it:
git checkout -b my-fix-branch
Coding your patch, including appropriate test cases and docs. To run a subset of unit test, use
ctest -R <test-match-pattern>
to perform tests with name matched by given pattern.After tests passed, commit your changes with a proper message.
Push your branch to GitHub:
git push origin my-fix-branch
In GitHub, send a pull request (PR) with
deepmodeling/abacus-develop:develop
as the base repository. It is required to document your PR following our guidelines.After your pull request is merged, you can safely delete your branch and sync the changes from the main (upstream) repository:
Delete the remote branch on GitHub either through the GitHub web UI or your local shell as follows:
git push origin --delete my-fix-branch
Check out the master branch:
git checkout develop -f
Delete the local branch:
git branch -D my-fix-branch
Update your master with the latest upstream version:
git pull --ff upstream develop
Commit message guidelines
A well-formatted commit message leads a more readable history when we look through some changes, and helps us generate change log. We follow up The Conventional Commits specification for commit message format. This format is also required for PR title and message. The commit message should be structured as follows:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Header
type: The general intention of this commit
Feature
: A new featureFix
: A bug fixDocs
: Only documentation changesStyle
: Changes that do not affect the meaning of the codeRefactor
: A code change that neither fixes a bug nor adds a featurePerf
: A code change that improves performanceTest
: Adding missing tests or correcting existing testsBuild
: Changes that affect the build system or external dependenciesCI
: Changes to our CI configuration files and scriptsRevert
: Reverting commits
scope: optional, could be the module which this commit changes; for example,
orbital
description: A short summary of the code changes: tell others what you did in one sentence.
Body: optional, providing detailed, additional, or contextual information about the code changes, e.g. the motivation of this commit, referenced materials, the coding implementation, and so on.
Footer: optional, reference GitHub issues or PRs that this commit closes or is related to. Use a keyword to close an issue, e.g. “Fix #753”.
Here is an example:
Fix(lcao): use correct scalapack interface.
`pzgemv_` and `pzgemm_` used `double*` for alpha and beta parameters but not `complex*` , this would cause error in GNU compiler.
Fix #753.
Comment style for documentation
ABACUS uses Doxygen to generate docs directly from
.h
and.cpp
code files.For comments that need to be shown in documents, these formats should be used – Javadoc style (as follow) is recommended, though Qt style is also ok. See it in official manual.
A helpful VS Code extension – Doxygen Documentation Generator, can help you formating comments.
An practical example is class LCAO_Deepks, the effects can be seen on readthedocs page
Tips
Only comments in .h file will be visible in generated by Doxygen + Sphinx;
Private class members will not be documented;
Use Markdown features, such as using a empty new line for a new paragraph.
Detailed Comment Block
Brief + Detailed Comment Block
Comments After the Item: Add a “<”
Parameters usage:
[in],[out],[in,out] description
e.g.or use
@param
command.Formula
inline:
\f$myformula\f$
separate line:
\f[myformula\f]
environment:
\f{environment}{myformula}
e.g.