Developer’s notes

Components of adcc

The adcc project consists of two main components, namely the adcc python library and the hybrid C++/Python libadcc library.

The distribution of workload is such that libadcc is responsible for:

  • Interaction with the underlying linear algebra backend, i.e. the tensor library

  • A unified interface to import Hartree-Fock results into the tensor library

In contrast, the adcc Python module

  • Implements iterative numerical solver schemes (e.g. the Davidson diagonalisation)

  • Implements all working equations (Møller-Plesset perturbation theory and ADC matrix expressions)

  • Interacts with Python-based SCF codes

  • Provides high-level functionality and user interaction

  • Orchestrates the workflow of an ADC calculation

  • Implements analysis and visualisation of results.

The libadcc library makes use of Pybind11 to expose the necessary C++ functionality to Python.

The functionality of adcc has already been described in Performing calculations with adcc and Overview of adcc. In fact many of the functions and classes described in these chapters are only partly implemented in adcc and inherit from components defined in libadcc, which is discussed in more detail in libadcc: C++ library.

Obtaining the adcc sources

The entire source code of adcc can be obtained from github, simply by cloning

git clone https://code.adc-connect.org

Building and testing libadcc and adcc can be achieved by

./setup.py test

Afterwards modifications on the adcc python level can be done at wish without re-running any build commands. If you modify source files in libadcc, make sure to re-run the ./setup.py test such that your changes are being compiled into the libadcc shared library.

setup.py reference

The setup.py script of adcc is a largely a typical setuptools script, but has a few additional commands and features worth knowing:

  • setup.py build_ext: Build the C++ part of adcc in the current directory.

  • setup.py cpptests: Build and run the C++ tests for libadcc

Documentation, documentation, documentation

This very document is created with Sphinx and Doxygen extracting parts of the content directly from the source code documentation. Building the documentation locally thus requires both these tools and additionally and a few Sphinx plugins (e.g. breathe). This can be achieved using

pip install adcc[build_docs]

On the Python-side we follow the numpy docstring standard.

Coding conventions

Code conventions are enforced automatically by pre-commit, which runs ruff on the Python code and clang-format on the C++ code. To install the git hook once after cloning:

pip install adcc[lint]
pre-commit install

Both tools rewrite files in place. A commit that violates the conventions is therefore aborted after the offending files have been fixed, and you need to stage the changes and repeat the commit. Only once both tools report no remaining problems will the commit go through.

The exact rules are defined in pyproject.toml ([tool.ruff]) and in the .clang-format files. The linter versions are pinned in .pre-commit-config.yaml and are used by the git hook and by the CI alike, so that both agree; pre-commit autoupdate bumps them. To check the whole repository instead of just the staged files, run pre-commit run --all-files.

What other developers use