Developing & Contributing

Common Development-Oriented Tasks

Create Development Environment

Except CMake and other dependencies specified in Install, the development scripts also require other dependencies. Install Conda (Or Mamba/MicroMamba), and then execute:

conda env create -f env/art_modern.yml

Testing

Some individual modules can be tested using CMake CTest system. Execute ctest in your building directory to test them.

Run make testsmall or make testsmall-release to run the integration tests using executables produced in make debug and make release.

Profiling

We have ./profile.sh ${PROFILER} to perform profiling of the software with profiler ${PROFILER}. Profilers may include:

  • intel-advisor for Intel Advisor. Intel compilers with -mtune=native and -O3 with RelWithDebInfo mode will be used.

  • intel-vtune for Intel VTune Profiler. Intel compilers with -mtune=native and -O3 with RelWithDebInfo mode will be used.

  • valgrind for Valgrind Callgrind. GCC with Debug mode will be used since optimization may produce instructions that are not supported by Valgrind.

  • amd-uprof for AMD uProf. AMD compilers with -mtune=native and -O3 with RelWithDebInfo mode will be used.

Building Documentations

Create the development environment and make the documentation through:

conda activate art_modern
make doc

And the built documentations (HTML and PDF) should be in doc/sphinx.d/_build/html and doc/sphinx.d/_build/latex respectively. Note that for PDF output, you may need latexmk and a working up-to-date LaTeX distribution (e.g., TeXLive, MiKTeX, MacTeX) installed.

Release Cycle

  • Feature freeze: All new features merged into the develop branch.

  • Code freeze: All production code changes (including bug fixes) merged into the develop branch. Run make fmt to format the code. Ensure that integration test passes.

  • Integration test: make testbuild and make testbuild-mpi are executed using GCC, pure LLVM/Clang, and Intel OneAPI C++/DPC++ toolchain to ensure compatibility. Ensure make packing passes without errors.

  • Documentation freeze: All documentation changes merged into the develop branch. Note:

    • Update News.md.

    • Update version number in CMakeLists.txt.

    • Ensure make cleandoc passes without errors.

  • Release: The develop branch is merged into the main branch, tagged with a new version number.

  • Generate artifacts: Run make packing and make cleandoc.

Get Engaged

Issues

You’re welcome to submit issues on GitHub if you’ve encountered any problems while using this software. You’re recommended to take advantage of the bug report templates, which will help us to understand your problem better. You may also submit issues if you’re unclear about the docs or have some ideas for improving the software itself.

Pull Requests (PRs)

You’re welcomed to send pull requests (PRs) to this project using the standard fork-and-pull-request workflow. However, please send an issue first to discuss the changes you’re going to make (except spelling & punctuation & grammar issues). Otherwise, we may not be able to accept your PR.

Before you send a PR, please make sure that:

  • You’ve run make fmt to format the code.

  • All CTest passes.

  • make clean testsmall-release testsmall-release-mpi passes. This test usually requires 6 to 8 minutes.

  • make clean testsmall testsmall-mpi passes. This test usually requires 12 to 18 minutes. Here, the additional tests that are not enabled in release mode will be activated.

  • make testbuild testbuild-mpi passes. This test usually requires 1 to 2 hours.

  • make testbuild-small testbuild-small-mpi passes. This test usually requires 4 to 6 hours.

You may also:

  • Use Valgrind to check for memory leaks.

  • Run the profilers.

Miscellaneous Developer-Oriented Documentation