Developer’s notes

Components of adcc

The adcc project consists of three main components, namely the adcc python library, the adccore C++ layer as well as libadcc.

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

  • Interaction with the underlying linear algebra backend, i.e. the tensor library
  • Implementation of the ADC working equations or interface to libadc for more complex expressions.
  • A unified interface to import Hartree-Fock results into the tensor library
  • A unified interface to compute matrix-vector products of the ADC matrix in a contraction-based numerical scheme (e.g. in Python).

In contrast the adcc Python module

  • Implements iterative numerical solver schemes (e.g. the Davidson diagonalisation)
  • 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.

While these first two components thus contain real functionality, libadcc is just a wrapper around adccore. It makes use of Pybind11 in order to expose the core code to Python. This allows to use adccore from Python (via libadcc) and directly from C++.

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 adccore, which is discussed in more detail in adccore: C++ core library.

Obtaining the adcc sources

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

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

Unlike adcc, the the adccore sources are not yet publicly available at the moment. They should not be neccessary for most development work on adcc, since the setup.py script of adcc will take care of downloading and installing the appropriate binary version of adccore automatically. This is triggered simply by building and testing adcc, which can be achieved by

./setup.py test

Afterwards modifications on the adcc python level can be done at wish building on the rich interface of functionality exposed from adccore to the python level. See the Pybind11 extension for details.

In case you need a full source code setup feel free to Contact us and see Development setup with access to adccore source code for setup details.

Development setup with access to adccore source code

If you need to modify both adcc and adccore to implement a new feature, you first need to get access adccore source code, which is not yet publicly available. Feel free to Contact us to discuss this.

Once you do, configure the url of the adccore remote on your system. For this drop a file ~/.adccore.json in your Home directory with the contents

{"upstream": "ssh://location_of_the_adccore_repository.git"}

where location_of_the_adccore_repository.git is appropriately replaced by the url to the adccore remote. Afterwards you can proceed as above, i.e. just clone the adcc sources via

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

and initalise the build via

./setup.py test

This will automatically clone adccore into the subfolder adccore of the adcc source repository and trigger both building and testing of adccore and adcc.

Notice, that in this setup, the build system of adccore is integrated with the setup.py from adcc, such that building adccore is automatically triggered from the setup.py script of the adcc repository. You generally do not need to worry about keeping the two repositories in sync or building them in the correct order: If you modify a file inside adccore the setup.py script from adcc will automatically trigger a compilation of this component for you.

One case, which does require manual work, however, is if adcc requires an newer version of adccore. In this case you will be presented with an error and you have to manually checkout the appropriate adccore version by running git checkout inside the adccore subdirectory. For example to obtain version 0.0.0 of adccore, you need to run

git checkout v0.0.0.

This is done to avoid automatically overwriting some development changes you might have made inside adccore.

Finally, if you want to locally test one of the other methods of obtaining adccore, the automatic checkout of the adccore source code can be disabled by defining the environment variable DISABLE_ADCCORE_CHECKOUT (to any value).

Building adccore with MKL support

If you have full source code access and you are able to follow the Development setup with access to adccore source code, the Intel Math Kernel Library (R) can also be integrated into adccore and thus adcc. In fact this integration happens automatically during the build process of adccore, given that a numpy linked to the MKL was detected. For this reason proceed as follows:

  1. Load the MKL modules or activate the MKL in your shell as you usally do.
  2. Build and install numpy with linkage to this MKL, e.g. Build numpy from source.
  3. Build adcc and adccore as described in Development setup with access to adccore source code.

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. This includes adccore in case you have the source code repository set up as described in Development setup with access to adccore source code.

  • setup.py test: Run the adcc unit tests via pytest. Implies build_ext. This command has a few useful options:

    • -m full: Run the full test suite not only the fast tests

    • -s: Skip updating the testdata

    • -a: Pass additional arguments to pytest (See pytest documentation). This is extremely valuable in combination with the -k and -s flags of pytest. For example

      ./setup.py test -a "-k 'functionality and adc2'"
      

      will run only the tests, which have the keywords “functionality” and “adc2” in their description. Of course in such a case still all changes in adccore will trigger a rebuild of the C++ components of adcc before running these tests …

  • setup.py build_docs: Build the documentation locally using Doxygen and Sphinx. See the section below for details.

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

On the Python end, the repository contains a setup.cfg file, which largely defines the code conventions. Use your favourite flake8-plugin to ensure compliance. On the C++-end we provide .clang-format files, such that automatic formatting can be done with your favourite tool based on clang-format.

What other developers use