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 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. 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: For those who are interested in the source code, the following figure shows the structure of the source code. 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. We use We use https://pre-commit.ci/ to format the code. It is performed after pushing new commits to a PR. You might need to pull the changes before adding new commits. To use pre-commit locally (generally not required): Please install the pre-commit tool by running the following command: Then, run the following command to install the pre-commit hooks: We use GoogleTest as our test framework. Write your test under the corresponding module folder at Add a folder named Append the content below to Add a blank To add a unit test: Write your test under Add your testing source code with suffix Append the content below to Build with Follow the installing procedure of CMake. The tests will move to Considering Compiling ABACUS with unit tests. In order to run unit tests, ABACUS needs to be configured with then build ABACUS and unit testing with It is import to run the folloing command before running unit tests: to install mandatory supporting input files for unit tests. If you modified the unit tests to add new tests or learn how to write unit tests, it is convenient to run to build a specific unit test. And please remember to run Running unit tests The test cases are located in You can run a single test in the specific directory. For example, run under the directory of The results will be shown as Note that the first one is integrated test, which is not a unit test. It is the test suite for testing the whole ABACUS package. The examples are located in the To run a subset of tests, run the following command For example, For example, in the The integrate test is a test suite for testing the whole ABACUS package. The examples are located in the Add a new directory under Prepare the input files for the new test. The input files should be placed in the new directory. Pseudopotential files and orbital files should be placed in The running time of the new test should not exceed 20 seconds. You can try to reduce the time by below methods (on the premise of ensuring the effectiveness of the test): Reduce the number of atoms in the unit cell (1~2 atoms). Reduce the number of k-points ( Reduce ecutwfc (20~50 Ry). Reduce the number of steps for relax or md job (2~3 steps). Reduce the basis set for LCAO calculations (DZP orbital and 6 a.u. cutoff). For PW calculations, should set Generate the reference results for the new test. Run the new test with GNU compiler and 4 MPI processes 2 OpenMP threads. The command is Execute tests/integrate/tools/catch_properties.sh script to generate the reference results. At the new test directory, run If you want to test the correctness of some output files, you need to do extra below steps: add the corresponding comparison method in Add the reference file (such as: Add the reference comparison result to the Add a Add the new test to Enter directory tests/integrate and run For the unexpected results when developing ABACUS, GDB will come in handy. Compile ABACUS with debug mode. After building and installing the executable, enter the input directory, and launch the debug session with 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, For segmentation faults, ABACUS can be built with Address Sanitizer to locate the bugs. 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. ABACUS uses CMake as its default building system. To add a new building component: Add an Add the new component. For example: Add the required third-party libraries to Dockerfiles. After the changes above are merged, submit another PR to build and test the new component in the CI pipeline. For integration test and unit test: add For building test: add This feature requires using GCC compiler. We use Add 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. If configuration fails unfortunately, you can find required files (including three *.cmake and llvm-cov-wrapper), and copy these four files into Generate HTML report. Now you can copy 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. 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: Coding your patch, including appropriate test cases and docs. To run a subset of unit test, use After tests passed, commit your changes with a proper message. Push your branch to GitHub: In GitHub, send a pull request (PR) with If more changes are needed, you can add more commits to your branch and push them to GitHub. Your PR will be updated automatically. 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: Check out the master branch: Delete the local branch: Update your master with the latest upstream version: 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: Header type: The general intention of this commit scope: optional, could be the module which this commit changes; for example, 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:Table of Contents
Got a question?
Structure of the package
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 a test
folder for its unit tests;tests
: End-to-end test cases;tools
: the script for generating the numerical atomic orbitals.|-- module_base A basic module including
| | (1) Mathematical library interface functions: BLAS, LAPACK, Scalapack;
| | (2) Custom data classes: matrix, vector definitions and related functions;
| | (3) Parallelization functions: MPI, OpenMP;
| | (4) Utility functions: timer, random number generator, etc.
| | (5) Global parameters: input parameters, element names, mathematical and physical constants.
| |-- module_container The container module for storing data and performing operations on them and on different architectures.
|-- module_basis Basis means the basis set to expand the wave function.
| |-- module_ao Atomic orbital basis set to be refactored.
| |-- module_nao New numerical atomic orbital basis set for two-center integrals in LCAO calculations
| `-- module_pw Data structures and relevant methods for planewave involved calculations
|-- module_cell The module for defining the unit cell and its operations, and reading pseudopotentials.
| |-- module_neighbor The module for finding the neighbors of each atom in the unit cell.
| |-- module_paw The module for performing PAW calculations.
| |-- module_symmetry The module for finding the symmetry operations of the unit cell.
|-- module_elecstate The module for defining the electronic state and its operations.
| |-- module_charge The module for calculating the charge density, charge mixing
| |-- potentials The module for calculating the potentials, including Hartree, exchange-correlation, local pseudopotential, etc.
|-- module_esolver The module defining task-specific driver of corresponding workflow for evaluating energies, forces, etc., including lj, dp, ks, sdft, ofdft, etc.
| | TDDFT, Orbital-free DFT, etc.
|-- module_hamilt_general The module for defining general Hamiltonian that can be used both in PW and LCAO calculations.
| |-- module_ewald The module for calculating the Ewald summation.
| |-- module_surchem The module for calculating the surface charge correction.
| |-- module_vdw The module for calculating the van der Waals correction.
| |-- module_xc The module for calculating the exchange-correlation energy and potential.
|-- module_hamilt_lcao The module for defining the Hamiltonian in LCAO calculations.
| |-- hamilt_lcaodft The module for defining the Hamiltonian in LCAO-DFT calculations.
| | |-- operator_lcao The module for defining the operators in LCAO-DFT calculations.
| |-- module_deepks The module for defining the Hamiltonian in DeepKS calculations.
| |-- module_dftu The module for defining the Hamiltonian in DFT+U calculations.
| |-- module_gint The module for performing grid integral in LCAO calculations.
| |-- module_hcontainer The module for storing the Hamiltonian matrix in LCAO calculations.
| `-- module_tddft The module for defining the Hamiltonian in TDDFT calculations.
|-- module_hamilt_pw The module for defining the Hamiltonian in PW calculations.
| |-- hamilt_ofdft The module for defining the Hamiltonian in OFDFT calculations.
| |-- hamilt_pwdft The module for defining the Hamiltonian in PW-DFT calculations.
| | |-- operator_pw The module for defining the operators in PW-DFT calculations.
| `-- hamilt_stodft The module for defining the Hamiltonian in STODFT calculations.
|-- module_hsolver The module for solving the Hamiltonian with different diagonalization methods, including CG, Davidson in PW
| | calculations, and scalapack and genelpa in LCAO calculations.
|-- module_io The module for reading of INPUT files and output properties including band structure, density of states, charge density, etc.
|-- module_md The module for performing molecular dynamics.
|-- module_psi The module for defining the wave function and its operations.
|-- module_relax The module for performing structural optimization.
| |-- relax_new The module for performing structural optimization with new algorithm, optimized for cell and ion simultaneously.
| `-- relax_old The module for performing structural optimization with old algorithm, optimized for cell and ion separately.
|-- module_ri The module for performing RI calculations.
Submitting an Issue
Code formatting style
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.pip install pre-commit
pip install clang-tidy clang-format # if you haven't installed them
pre-commit install
Adding a unit test
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.test
under the module.CMakeLists.txt
of the module:IF (BUILD_TESTING)
add_subdirectory(test)
endif()
CMakeLists.txt
under module*/test
.GoogleTest
framework.*_test.cpp
in test
directory.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.
)
-D BUILD_TESTING=1
flag, cmake
will look for GoogleTest
in the default path (usually /usr/local
); if not found, you can specify the path with -D GTEST_DIR
. You can find built testing programs under build/source/<module_name>/test
.build/test
.-D BUILD_TESTING=1
, the compilation will be slower compared with the case -D BUILD_TESTING=0
.Running unit tests
-D BUILD_TESTING=ON
flag. For example:cmake -B build -DBUILD_TESTING=ON
cmake --build build -j${number of processors}
cmake --install build
cmake --build build -j${number of processors} --target ${unit test name}
cmake --install build
after building the unit test if the unit test requires supporting input files.build/source/${module_name}/test
directory. Note that there are other directory names for unit tests, for example, test_parallel
for running parallel unit tests, test_pw
for running unit tests only used in plane wave basis calculation../cell_unitcell_test
build/source/module_cell/test
to run the test cell_unitcell_test
. However, it is more convenient to run unit tests with ctest
command under the build
directory. You can check all unit tests byctest -N
Test project /root/abacus/build
Test #1: integrated_test
Test #2: Container_UTs
Test #3: base_blas_connector
Test #4: base_blacs_connector
Test #5: base_timer
...
tests/integrate
directory.ctest -R <test-match-pattern> -V
ctest -R cell
will perform tests with name matched by cell
. You can also run a single test withctest -R <test-name>
ctest -R cell_unitcell_test_readpp
will perform test cell_unitcell_test_readpp
. To run all the unit tests, together with the integrated test, runcmake --build build --target test ARGS="-V --timeout 21600"
abacus-develop
directory.Adding an integrate test
tests/integrate
directory. Before adding a new test, please firstly read README.md
in tests/integrate
to understand the structure of the integrate test. To add an integrate test:tests/integrate
for the new test.tests/PP_ORB
. You should define the correct pseudo_dir
and orb_dir
(if need orbital files) in INPUT with the relative path to the tests/PP_ORB
directory, and be sure the new test can be run successfully.1 1 1
or 2 2 2
).pw_seed 1
in INPUT file to ensure the reproducibility of the test.OMP_NUM_THREADS=2 mpirun -np 4 abacus > log.txt
.bash ../tools/catch_properties.sh result.ref
. A result.ref
file may be like: etotref -3439.007931317310
etotperatomref -3439.0079313173
totaltimeref 2.78
catch_properties.sh
. For example, to verify whether the output of the BANDS_1.dat file is correct, you need to add the following code in catch_properties.sh
:has_band=$(awk '$1=="out_band" {a=$2} END{print a}' INPUT) # check if the BAND is outputed
if ! test -z "$has_band" && [ $has_band == 1 ]; then # if band is outputed, then check if the band is correct
bandref=refBANDS_1.dat # this file should be prepared in new test directory
bandcal=OUT.autotest/BANDS_1.dat # this file is generated by each run of test
python3 ../tools/CompareFile.py $bandref $bandcal 8 # compare the new band file with the reference file
echo "CompareBand_pass $?" >>$1 # record the comparison result, $? is the return value of last command
fi
CompareFile.py
is used to determine if two files are identical. It accepts three arguments: the first two are the files to be compared, and the third specifies the precision for comparing numerical values. The comparison fails if the difference between any two corresponding numerical values exceeds 1e-{precision} (such as: 1e-8 in previous case). If the files are identical, the script returns 0; otherwise, it returns 1.refBANDS_1.dat
in previous case) to the new test directory.result.ref
file. For example, CompareBand_pass 0
means the comparison of the band file is passed. (This statement should be added before the totaltimeref
line)jd
file in the new test directory, which is one setence to describe the new test.tests/integrate/CASES_CPU.txt
file (or tests/integrate/CASES_GPU.txt
file if it is for GPU verion).bash Autotest.sh -r <the-new-test-name>
to check if the new test can be run successfully.Debugging the codes
cmake -B build -DCMAKE_BUILD_TYPE=Debug
gdb abacus
. For debugging in Visual Studio Code, please set cwd to the input directory, and program to the path of ABACUS executable.mpirun -n 1 gdb abacus : -n 3 abacus
will attach GDB to the master process, and launch 3 other MPI processes.cmake -B build -DENABLE_ASAN=1
Adding a new building component
OPTION
to toggle the component to the CMakeLists.txt
file under root directory. For example:OPTION(ENABLE_NEW_COMPONENT "Enable new component" OFF)
IF (ENABLE_NEW_COMPONENT)
add_subdirectory(module_my_new_feature) # if the feature is implemented in a subdirectory
find_package(NewComponent REQUIRED) # if third-party libs are required
target_link_libraries(${ABACUS_BIN_NAME} PRIVATE NewComponent) # if the component is linked
include_directories(${NewComponent_INCLUDE_DIRS}) # if the component is included
endif()
-DENABLE_NEW_COMPONENT=ON
to the building step at .github/workflows/test.yml
.-DENABLE_NEW_COMPONENT=ON
as a new configuration at .github/workflows/build_test_cmake.yml
.Generating code coverage report
gcov
and lcov
to generate code coverage report.-DENABLE_COVERAGE=ON
for CMake configure command.cmake -B build -DBUILD_TESTING=ON -DENABLE_COVERAGE=ON
cmake --build build --target test ARGS="-V --timeout 21600"
/abacus-develop/cmake
. Alternatively, you can define the path with option -D CMAKE_CURRENT_SOURCE_DIR
.cd build/
make lcov
build/lcov
to your local device, and view build/lcov/html/all_targets/index.html
.Submitting a Pull Request
git checkout -b my-fix-branch
ctest -R <test-match-pattern>
to perform tests with name matched by given pattern.git push origin my-fix-branch
deepmodeling/abacus-develop:develop
as the base repository. It is required to document your PR following our guidelines.git push origin --delete my-fix-branch
git checkout develop -f
git branch -D my-fix-branch
git pull --ff upstream develop
Commit message guidelines
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
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 commitsorbital
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.