8.3. C/C++ interface#

Note

See Environment variables for the runtime environment variables.

8.3.1. C++ interface#

The C++ interface of DeePMD-kit is also available for the model interface, which is considered faster than the Python interface. An example infer_water.cpp is given below:

#include "deepmd/DeepPot.h"

int main(){
  deepmd::DeepPot dp ("graph.pb");
  std::vector<double > coord = {1., 0., 0., 0., 0., 1.5, 1. ,0. ,3.};
  std::vector<double > cell = {10., 0., 0., 0., 10., 0., 0., 0., 10.};
  std::vector<int > atype = {1, 0, 1};
  double e;
  std::vector<double > f, v;
  dp.compute (e, f, v, coord, atype, cell);
}

where e, f and v are predicted energy, force and virial of the system, respectively. See deepmd::DeepPot for details.

You can compile infer_water.cpp using gcc:

gcc infer_water.cpp -L $deepmd_root/lib -I $deepmd_root/include -Wl,--no-as-needed -ldeepmd_cc -lstdc++ -Wl,-rpath=$deepmd_root/lib -o infer_water

and then run the program:

./infer_water

8.3.2. Backend plugins#

The C and C++ libraries load backend implementations as runtime plugins. An application links to libdeepmd_cc or libdeepmd_c; it does not need to link directly to TensorFlow, PyTorch, JAX, or Paddle. When a model is opened, DeePMD-kit detects the backend from the model format and loads only the corresponding backend plugin.

The plugin library names are:

  • TensorFlow: libdeepmd_backend_tf.so

  • PyTorch: libdeepmd_backend_pt.so

  • PyTorch exportable: libdeepmd_backend_ptexpt.so

  • JAX: libdeepmd_backend_jax.so

  • Paddle: libdeepmd_backend_pd.so

On macOS the suffix is .dylib; on Windows the libraries use .dll without the lib prefix. Native installs and the pre-compiled C library package place these plugins in the same lib directory as libdeepmd_cc and libdeepmd_c. Python wheels place them in deepmd/lib.

The backend plugin search order is:

  1. directories listed in DP_BACKEND_PLUGIN_PATH, split by : on Unix and ; on Windows;

  2. the directory that contains libdeepmd_cc;

  3. the platform dynamic loader search path for the bare plugin library name.

If the requested plugin or its backend runtime cannot be loaded, only that backend fails with a Unable to load ... backend plugin error. Other backends can still run as long as their own plugins and runtime libraries are available. Install the plugins from the same build as libdeepmd_cc. The entry points a plugin exports carry the version of the backend interface it was built against, so libdeepmd_cc finds none of them in a plugin of another interface version, and that backend fails to load in the same way. This also allows a no-backend libdeepmd_cc or libdeepmd_c build; install or copy the backend plugin next to the library, or set DP_BACKEND_PLUGIN_PATH, before loading a model that uses that backend. Build instructions for this layout are in Install DeePMD-kit’s C++ interface.

DP_PLUGIN_PATH is different: it is used for customized OP plugin libraries after the backend has been selected.

8.3.3. C interface#

Although C is harder to write, the C library will not be affected by different versions of C++ compilers.

An example infer_water.c is given below:

#include <stdio.h>
#include <stdlib.h>
#include "deepmd/c_api.h"

int main(){
  const char* model = "graph.pb";
  double coord[] = {1., 0., 0., 0., 0., 1.5, 1. ,0. ,3.};
  double cell[] = {10., 0., 0., 0., 10., 0., 0., 0., 10.};
  int atype[] = {1, 0, 1};
  // init C pointers with given memory
  double* e = malloc(sizeof(*e));
  double* f = malloc(sizeof(*f) * 9); // natoms * 3
  double* v = malloc(sizeof(*v) * 9);
  double* ae = malloc(sizeof(*ae) * 9); // natoms
  double* av = malloc(sizeof(*av) * 27); // natoms * 9
  // DP model
  DP_DeepPot* dp = DP_NewDeepPot(model);
  DP_DeepPotCompute (dp, 3, coord, atype, cell, e, f, v, ae, av);
  // print results
  printf("energy: %f\n", *e);
  for (int ii = 0; ii < 9; ++ii)
    printf("force[%d]: %f\n", ii, f[ii]);
  for (int ii = 0; ii < 9; ++ii)
    printf("force[%d]: %f\n", ii, v[ii]);
  // free memory
  free(e);
  free(f);
  free(v);
  free(ae);
  free(av);
  DP_DeleteDeepPot(dp);
}

where e, f and v are predicted energy, force and virial of the system, respectively. ae and av are atomic energy and atomic virials, respectively. See DP_DeepPotCompute() for details.

You can compile infer_water.c using gcc:

gcc infer_water.c -L $deepmd_root/lib -I $deepmd_root/include -Wl,--no-as-needed -ldeepmd_c -Wl,-rpath=$deepmd_root/lib -o infer_water

and then run the program:

./infer_water