[For Third-party Developers] Migrate from C++ library to C library

[njzjz]

Starting from v2.2.0.b0, DeePMD-kit will add a C library (libdeepmd_c.so) along with a header-only C++ API (deepmd/deepmd.hpp). Meanwhile, a C library binary (libdeepmd_c.tar.gz) is built and packed with CUDA 11 support (but can fall back to the CPU mode) for each build and will be provided on the release page.

Currently, this package can be downloaded from each GitHub Actions build, for example, here.

Advantages

C++ ABI is not stable as it is dependent on C++ standards (e.g., C++11) and the compiler ABI. This means one may need to use the same compiler, the same C++ standard, and the same flag to compile all of the libraries. Otherwise, errors may be thrown. OS platforms use the same compiler environment to build a so-called "release version" and conda is doing a similar thing.
Compared to the C++ ABI, C is ABI stable on almost all platforms, so one can use different compilers and standards to compile different libraries of an application.
Benefiting this feature, it is possible to distribute the C library binary. libdeepmd_c.tar.gz is built on CentOS 7 and only relies on the system libraries, including GNU C Library >=2.17 and GNU C++ Library >=6.0.19. One does not need to build the DeePMD-kit by itself.
Some C libraries are distributed in the same way, such as TensorFlow C library and cuDNN.

Changes

To migrate from the C++ library to the C library, the following changes should be made:

1. Header: include the HPP file

- #include <deepmd/DeepPot.h>
+ #include <deepmd/deepmd.hpp>

2. Namespace

- using deepmd::DeepPot;
+ using deepmd::hpp::DeepPot;

3. link the C library instead of the C++ library.

- -ldeepmd_cc
+ -ldeepmd_c

or do the corresponding changes in the CMake.
4. Any other C++-related flags are not necessary anymore.

- -std=c++11 -D_GLIBCXX_USE_CXX11_ABI=0 -DHIGH_PREC

6. Update the documentation and provide a link to libdeepmd_c.tar.gz.

To be discussed

It's unclear whether it is necessary to keep compatibility with the old C++ API. The benefits of doing so are not obvious.

[wanghan-iapcm]

I would prefer preserving the C++ API, because the usage is easier than the C API.

[njzjz]

Here I want to discuss for a third-party application should support the interface of both new and old APIs (so the old version will also be supported) or only support new APIs (requires a new version). If both APIs are supported, one may need to write as below

#ifdef DP_CXX_API
#include <deepmd/DeepPot.h>
using deepmd::DeepPot;
#else
#include <deepmd/deepmd.hpp>
using deepmd::hpp::DeepPot;
#endif

and define DP_CXX_API in the CMake when the old version is detected.

[dingye18]

Can we provide an API interface that accepts the pointer address of tensors variables (in CUDA or CPU) as positions input?
Thus, we can make the optimize the communication of MD engine and DP without message passing between CPU and GPU devices.

[njzjz]

I think the current custom descriptor OP implementation will always copy data from the host to the device. @wanghan-iapcm @denghuilu please correct me if I am wrong.

deepmd-kit/source/op/prod_env_mat_multi_device.cc

Lines 1156 to 1160 in 30920ab

	_prepare_coord_nlist_gpu<FPTYPE>(
	context, &tensor_list[0], &coord, coord_cpy, &f_type, type_cpy, idx_mapping,
	gpu_inlist, ilist, numneigh, firstneigh, jlist, nbor_list_dev,
	frame_nall, mem_cpy, mem_nnei, max_nbor_size,
	box, mesh_tensor.flat<int>().data(), mesh_tensor_size, nloc, nei_mode, rcut_r, max_cpy_trial, max_nnei_trial);

[njzjz]

Do you find performance degrade?

[wanghan-iapcm]

I think so. The amount of data transferred is not large ( same order as the number of atoms N ). The computational load is N x N_nei, which is significantly larger than N.

[dingye18]

Do you find performance degrade?

I did not conduct a benchmark test on performance decline. I'm trying to optimize the communication between OpenMM and DP.
It looks like that I need to implement a custom OP without copy data from the host to device.......