Code guidelines¶

Two general places to find information on C++-specific questions are cppreference and learncpp. For Kokkos-related questions, one can refer to the Kokkos documentation as well as the Kokkos tutorials for practical examples. For ADIOS2-related issues, refer to the ADIOS2 documentation, and the examples on their github.

When not sure what a specific function does, or how to include a particular module, first check the documentation (you can do a keyword search). Another good option to figure things out on your own, is to look at how the particular modules/functions in questions are used in the unit tests (in the corresponding tests/ directories). If non of that answers your questions, please feel free to open a github issue.

Submitting a github issue

When submitting a github issue, please make sure to include all the parameters of the simulation as well as the code version tag and the git hash of the commit you are using. These are automatically printed into stdout at the beginning of the simulation, and are also saved into <simname>.info file. If you believe the problem is coming from your problem generator, please also include the problem generator file.

Testing¶

The code is tested using the ./dev/scripts/tests.sh script which compiles and runs all the unit tests using ctest:

./dev/scripts/tests.sh --build build_dir --flags "-D mpi=ON" --with_tests

All the unit tests are inside the tests/ directory each within the respective subdirectory; e.g., tests for src/kernels are in tests/kernels. When testing, build the tests both with and without MPI and, ideally, with and without GPU (when available).

You can also compile all the problem generators and run the ones from the examples directory and automatically create plots to check the validity of the code (requires nt2py to be installed via pip):

./dev/scripts/tests.sh --build build_dir --flags "-D mpi=ON" --with_pgens --make_plots

Code guidelines¶

Formatting¶

To maintain coherence throughout the source code, we use clang-format to enforce a uniform style. A corresponding .clang-format file with all the style-related settings can be found in the root directory of the code. To use this, one needs to have the clang-format executable (typically provided with the llvm package). After installing the clang-format itself (check by running clang-format --version), you can use it either manually by running clang-format . in the route directory of the code, or attach it to your favorite code editor to run on save. For VSCode, the recommended extension is xaver.clang-format, for vim -- rhysd/vim-clang-format, for nvim -- stevearc/conform.nvim, for emacs.

You can run the formatting on all files with ./dev/scripts/format.sh.

Best practices are also enforced using clang-tidy; to generate recommendations for all the files, run ./dev/scripts/tidy.sh --build build_dir where build_dir is the directory where the code was built, or for specific files: ./dev/scripts/tidy.sh --build build_dir --files "(file1|file2).cpp" or only for the changed files: ./dev/scripts/tidy.sh --build build_dir --changed. The recommendations will be in the tidy/ directory.

General guidelines¶

Use const and auto declarations where possible.
For real-valued literals, use ONE, ZERO, HALF etc. instead of 1.0, 0.0, 0.5 to ensure the compiler will not need to cast. If the value is not defined as a macro, use static_cast<real_t>(123.4).

Use {} in declarations to signify a null (placeholder) value for the given variable:

auto a { -1 }; // <- value of `a` *will* be changed later (-1 is a placeholder)
auto b = -1; // <- value of `b` is known at the time of declaration (but *may* change later)
const auto b = -1; // <- value of `b` is not expected to change later

Each header file has to have a description at the top, consisting of the following fields:
- @file [required] the name of the file (as it should be included in other files)
- @brief [required] brief description of what the file contains
- @implements list of class/function/macros implementations
  - structs/classes in this section have no prefix (templates are marked with <>)
  - functions are marked with their return type, e.g. -> void
  - type aliases have a prefix type
  - enums or enum-like objects are marked with enum
  - macros have a prefix macro
  - all of the above are also marked with their respective namespaces (if any): namespace::
- @cpp: list of cpp files that implement the header
- @namespaces: list of namespaces defined in the file
- @macros: list of macros that the file depends on
- @note any additional notes (stack as many as necessary)
#ifdef/#define macros should be avoided. Use C++20 concept and if constexpr () expressions to specialize functions and classes instead (ideally, specialize them explicitly). #ifdef-s are only acceptable in platform/library-specific parts of the code (e.g., MPI_ENABLED, GPU_ENABLED, DEBUG, etc.), or for major shortcuts.
Header files should start with #ifndef ... #define ... and end with #endif; do not use #pragma guards. The name of the macro should be the same as the name of the file in uppercase, with underscores instead of dots and slashes. For example, for global/utils/formatting.h, the macro should be GLOBAL_UTILS_FORMATTING_H.
There is no difference between .h and .hpp files as both indicate C++ header files. As a consistency convention, we use .h for common headers which may be included from multiple .cpp files (e.g., metrics), while .hpp are very specific headers for only a single (or a couple of) .cpp file (e.g. kernels).
Do assertions on parameters and quantities whenever possible. Outside the kernels, use raise::Error(message, HERE) and raise::ErrorIf(condition, message, HERE) to throw exceptions. Inside the kernels, use raise::KernelError(HERE, message, **args). To enable compile-time errors, use static_assert(condition, message). The HERE keyword is macro that includes the filename and line number in the error message.