Sovereign 8s.is mirror of standardgalactic/DPx-preview
  • PureBasic 97.6%
  • C++ 1.9%
  • Python 0.4%
  • C 0.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-05-14 16:44:05 +08:00
00.software_packages Initial preview release of DPx 2026-05-14 16:44:05 +08:00
01.py_and_cpp_files_4_DP_main Initial preview release of DPx 2026-05-14 16:44:05 +08:00
02.lmp_files Initial preview release of DPx 2026-05-14 16:44:05 +08:00
03.training_example Initial preview release of DPx 2026-05-14 16:44:05 +08:00
04.inference_example Initial preview release of DPx 2026-05-14 16:44:05 +08:00
.gitignore Initial preview release of DPx 2026-05-14 16:44:05 +08:00
README.md Initial preview release of DPx 2026-05-14 16:44:05 +08:00

DPχ Installation & Test Guide

This repository provides a preliminary public version of the DPx code and related scripts for manuscript review and reproducibility checks. The codebase is under active development, and the repository name, structure, and API may be updated in future releases.

  • A patched DeepMD-kit Python interface (training/inference entrypoints)
  • A patched DeepMD C++ shared library (libdeepmd_op.so) required by LAMMPS for DPχ charge-aware inference
  • A patched LAMMPS (stable Aug 2023 release) with modified source files, including USER-DEEPMD and ELECTRODE
  • A small LAMMPS example to validate a successful build
  • The directories 01.py_and_cpp_files_4_DP_main and 02.lmp_files contain the DP-side and LAMMPS-side patch files, respectively; all deviations from the upstream sources are explicitly annotated with AUTHOR MODIFICATION (CJX).

1. Directory Layout

├── 00.software_packages
│   ├── deepmd-kit-2.2.7.zip                 # DeepMD source (for building C++ op library)
│   ├── deepmd-kit-2.2.9-cuda120-Linux-x86_64.sh  # (optional) DeepMD binary installer, not provided. could be downloaded from https://github.com/deepmodeling/deepmd-kit/
│   ├── plumed-2.9.0.tgz                     # PLUMED source (optional)
│   ├── stable_2Aug2023_update2.tar.gz       # LAMMPS stable release (Aug 2023)
│   └── USER-DEEPMD.original_version         # original LAMMPS USER-DEEPMD for reference
├── 01.py_and_cpp_files_4_DP_main
│   ├── cpp                                  # DeepMD C++ modifications by DPχ
│   └── py                                   # DeepMD Python modification by DPχ
├── 02.lmp_files                              # LAMMPS source patches for inference, by DPχ
│   ├── ELECTRODE
│   └── USER-DEEPMD
├── 03.training_example                    # a minimal training example after compilation
│   ├── data
│   ├── readme.md
│   └── train
├── 04.inference_example                    # a minimal inference example after compilation
│   ├── hpc_run.sh
│   ├── pb_coll
│   └── pt64-56h-09k
└── README.md                                 

2. System Requirements (Typical HPC / Linux)

  • Linux x86_64
  • CUDA (if using GPU builds; tested with CUDA 12.x)
  • GCC (>= 9 recommended)
  • MPI (OpenMPI recommended)
  • cmake, make, unzip, tar
  • A Python environment (Conda recommended)

If your cluster uses module systems, please load CUDA/GCC/MPI as needed on your system.


3. Installation Overview

There are two components to install:

  1. DeepMD Python environment (for training and/or providing runtime libs)
  2. LAMMPS + USER-DEEPMD + ELECTRODE (for DPχ inference)

In addition, DPχ requires replacing:

  • a few DeepMD Python package files (step 4)
  • libdeepmd_op.so (step 5), so LAMMPS can access the DPχ charge-related operators.

4. Step-by-step Installation

Step 0: Define paths

Set a working root directory, and define:

  • PKG_DIR: this repository root (where this README is located)
  • DP_DIR: DeepMD installation prefix (Conda env prefix, OR deepmd installer prefix)
  • LMP_DIR: LAMMPS build directory

Example:

export PKG_DIR=/path/to/this/repo
export DP_DIR=/path/to/deepmd_env
export LMP_DIR=/path/to/lammps_build

Step 1: Install DeepMD environment

Option A (recommended, easiest): use the provided DeepMD binary installer (if compatible with your system).

bash ${PKG_DIR}/00.software_packages/deepmd-kit-2.2.9-cuda120-Linux-x86_64.sh -p ${DP_DIR}
source ${DP_DIR}/bin/activate ${DP_DIR}

Option B: install DeepMD via Conda/pip on your system (advanced). Make sure it matches your CUDA/TensorFlow setup.

Version note. We use a DeepMD runtime environment (e.g., 2.2.9) and separately compile the C++ op library from the provided deepmd-kit-2.2.7.zip to generate a compatible libdeepmd_op.so. This is consistent with the original workflow of this package. If you prefer strict version matching, you may rebuild everything from the same DeepMD version.


Step 2: Patch DeepMD Python package (DPχ interface)

After activating the DeepMD environment (source ${DP_DIR}/bin/activate ${DP_DIR}), replace the following files:

cp ${PKG_DIR}/01.py_and_cpp_files_4_DP_main/py/deepmd/entrypoints/* \
   ${DP_DIR}/lib/python3.11/site-packages/deepmd/entrypoints/

cp ${PKG_DIR}/01.py_and_cpp_files_4_DP_main/py/deepmd/infer/* \
   ${DP_DIR}/lib/python3.11/site-packages/deepmd/infer/

cp ${PKG_DIR}/01.py_and_cpp_files_4_DP_main/py/deepmd_utils/utils/* \
   ${DP_DIR}/lib/python3.11/site-packages/deepmd_utils/utils/

✅ At this point, DPχ training interfaces should be available in the DeepMD Python environment.


Step 3: Build DeepMD C++ op library (libdeepmd_op.so)

This step generates a shared library that will be used by LAMMPS inference.

  1. Unpack DeepMD source:
export DP_SO_SRC=${PKG_DIR}/_build_deepmd_op
mkdir -p ${DP_SO_SRC}
unzip ${PKG_DIR}/00.software_packages/deepmd-kit-2.2.7.zip -d ${DP_SO_SRC}
  1. Build with CMake:
cd ${DP_SO_SRC}/deepmd-kit-2.2.7/source
mkdir -p build install_prefix
cd build

cmake -DUSE_TF_PYTHON_LIBS=TRUE \
      -DCMAKE_INSTALL_PREFIX=../install_prefix \
      ../

make -j
make install
  1. Replace libdeepmd_op.so in your DeepMD env:
cp ${DP_SO_SRC}/deepmd-kit-2.2.7/source/install_prefix/lib/libdeepmd_op.so \
   ${DP_DIR}/lib/python3.11/site-packages/deepmd/lib/

Step 4: Build LAMMPS (stable Aug 2023) with patches

  1. Unpack LAMMPS:
mkdir -p ${LMP_DIR}
tar -xvf ${PKG_DIR}/00.software_packages/stable_2Aug2023_update2.tar.gz -C ${LMP_DIR} --strip-components=1
  1. Restore original USER-DEEPMD folder (baseline), then patch:
cp -r ${PKG_DIR}/00.software_packages/USER-DEEPMD.original_version \
      ${LMP_DIR}/src/USER-DEEPMD
  1. Edit env.sh to point to your DeepMD env Open:
vim ${LMP_DIR}/src/USER-DEEPMD/env.sh

Set:

DEEPMD_ROOT="${DP_DIR}/"
  1. Copy LAMMPS source patches:
cp ${PKG_DIR}/02.lmp_files/*                 ${LMP_DIR}/src/
cp ${PKG_DIR}/02.lmp_files/ELECTRODE/*       ${LMP_DIR}/src/ELECTRODE/
cp ${PKG_DIR}/02.lmp_files/USER-DEEPMD/*     ${LMP_DIR}/src/USER-DEEPMD/
  1. Build LAMMPS libraries and compile:
cd ${LMP_DIR}/src

make lib-electrode args="-m mpi"
make lib-linalg    args="-m mpi"

make yes-KSPACE
make yes-ELECTRODE
make yes-MOLECULE
make yes-EXTRA-FIX
make yes-USER-DEEPMD

# PLUMED support (optional)
# If PLUMED support is enabled, DO NOT remove fix_plumed.cpp.
# Instead, build the PLUMED library and enable the PLUMED package:
#   make lib-plumed args="-b"
#   make yes-PLUMED
#
# If PLUMED support is NOT needed, remove fix_plumed.cpp to avoid
# unresolved PLUMED dependencies during compilation:
rm fix_plumed.cpp
#
# Note:
# If PLUMED support is required later, the original fix_plumed.cpp
# can be restored from:
#   ${PKG_DIR}/02.lmp_files/USER-DEEPMD/


make mpi -j4

After compilation, the executable is typically:

  • ${LMP_DIR}/src/lmp_mpi

5. Quick Test (Example)

This section provides a minimal end-to-end test to verify that the DPx workflow (training → frozen models → inference) runs correctly.

(1) trainning After building DP, run the provided test case:

cd ${PKG_DIR}/03.trainning_example/train
./hpc_run.sh

This script sequentially trains the four DP components in the recommended order:

01.dipole/ (DP2: R -> D) 02.charge/ (DP1: R -> Q) 02.charge.chemcharge/ (DP4: R -> Q_chem) 03.pot_modify/ (DP3: R -> E_ns, F_ns)

Upon successful completion, the frozen models required for inference will be generated as:

02.charge.chemcharge/ae.pb 03.pot_modify/ener_mod.pb

Note. On HPC systems, hpc_run.sh may invoke a job scheduler (e.g., Slurm or PBS). If the scheduler is not available, please run the training commands interactively or adapt the submission lines accordingly.

(2) Inference test

After building LAMMPS, run the provided inference example:

cd ${PKG_DIR}/04.inference_example
bash ./hpc_run.sh

Notes on the example inputs

The *.pb files in pb_coll/ are the force fields used in the paper. They are not compressed yet, so the runtime may be slower than a production-optimized setup.

The folder pt64-56h-09k/ corresponds to a system including both auxiliary electrode (AE) and working electrode (WE). Here, pt64 indicates 64 Pt atoms on the surface, while 56h and 09k denote the counts of adsorbed hydrogen (nHad = 56) and potassium ions (nK+ = 9), respectively.

A successful run should:

start LAMMPS normally,

load pair_style deepmd (or the DPχ pair style),

proceed without missing-symbol / shared-library errors.


6. Common Issues

(1) libdeepmd_op.so not found / symbol errors

  • Ensure ${DP_DIR}/lib/python3.11/site-packages/deepmd/lib/libdeepmd_op.so exists
  • Ensure env.sh in LAMMPS USER-DEEPMD points to the same ${DP_DIR}

(2) Python version mismatch in site-packages path

This README uses:

  • ${DP_DIR}/lib/python3.11/site-packages/...

If your environment uses Python 3.10/3.9, update the path accordingly.

(3) PLUMED build failures

PLUMED is optional for the basic DPχ installation test. If needed, compile PLUMED separately and point make lib-plumed to it.


7. Contact

For any review-time issues, please contact the corresponding author.