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 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 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:
- 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
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 includesadccore
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. Impliesbuild_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 topytest
(See pytest documentation). This is extremely valuable in combination with the-k
and-s
flags ofpytest
. 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¶
VIM: For setting up
vim
with this repository, you can use the following plugins: