Components of adcc¶
The adcc project consists of three main components,
namely the adcc python library,
adccore C++ layer as well as
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
libadcfor 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
It makes use of Pybind11
in order to expose the core code to Python.
This allows to use
adccore from Python (via
and directly from C++.
The functionality of adcc has already been described
in Performing calculations with adcc and adcc reference.
In fact many of the functions and classes described
in these chapters are only partly implemented in adcc
and inherit from components defined in
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,
setup.py script of adcc
will take care of downloading and installing the appropriate
binary version of
This is triggered simply by building and testing adcc,
which can be achieved by
Afterwards modifications on the adcc python level can be done
at wish building on the rich interface of functionality
adccore to the python level.
See the Pybind11 extension
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¶
Once you do, configure the url of the
on your system. For this drop a file
in your Home directory with the contents
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
This will automatically clone
adccore into the subfolder
of the adcc source repository and trigger both building and testing
adccore and adcc.
Notice, that in this setup, the build system of
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
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
version by running
git checkout inside the
For example to obtain version
you need to run
git checkout v0.0.0.
This is done to avoid automatically overwriting some development changes
you might have made inside
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
(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:
- Load the MKL modules or activate the MKL in your shell as you usally do.
- Build and install numpy with linkage to this MKL, e.g. Build numpy from source.
- Build adcc and adccore as described in Development setup with access to adccore source code.
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
adccorein 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
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
adccorewill 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.
On the Python end, the repository contains a
which largely defines the code conventions. Use your favourite
to ensure compliance. On the C++-end we provide
such that automatic formatting can be done with
your favourite tool based on