Installation

Python API

Requires Python >= 3.9 and a C++17-capable compiler (GCC/Clang/MSVC). Linux/Windows also require OpenMP; macOS builds without it.

git clone https://github.com/MoseyQAQ/ferrodispcalc.git
cd ferrodispcalc
pip install -e .

This installs the core dependencies (numpy, matplotlib, ase, pymatgen, dpdata, scienceplots) and compiles the C++ backend.

For the optional 3-D visualisation tools (pyvista):

pip install -e ".[vis]"

LAMMPS API

The LAMMPS API provides a file-based compute disp/atom runtime plugin. It outputs displacement and displacement velocity from a user-provided neighbor list.

Prerequisites

A C++ compiler with MPI and OpenMP support, plus the LAMMPS source tree.

Warning

The LAMMPS source version used to compile the plugin should match the LAMMPS binary you run simulations with. Likewise, the compiler (and its version) must be the same in both cases — a mismatch will cause runtime errors when loading the plugin.

If you do not have the source locally:

wget https://github.com/lammps/lammps/archive/stable_2Aug2023_update3.tar.gz
tar -xzf stable_2Aug2023_update3.tar.gz

Compile

Load the required modules (example for a cluster with environment modules):

module purge
module load lammps/29aug2024-dpv3

Edit Makefile and set the two -I flags to your actual LAMMPS source paths:

CXX      = mpicxx
CXXFLAGS = -I/path/to/lammps/src -Wall -Wextra -O3 -fPIC \
           -I/path/to/lammps/src/OPENMP -fopenmp
LD       = $(CXX) -shared -rdynamic -fopenmp
DSOEXT   = .so

include Makefile.common

Then build:

make

On success, dispplugin.so appears in the current directory.

Verify

In a LAMMPS input file, load the plugin and confirm it is registered:

plugin load /path/to/dispplugin.so
plugin list

plugin list should show only disp/atom from this plugin:

Loading plugin: compute disp/atom by Denan Li (lidenan@westlake.edu.cn)
Currently loaded plugins: 1
   1: compute style plugin disp/atom

A minimal input setup for displacement only is:

atom_modify map array
plugin load /path/to/dispplugin.so
compute d all disp/atom nnfile nn.dat

This returns three per-atom columns: c_d[1]-c_d[3] are r_center - mean(r_neighbors).

To also output the displacement velocity, enable ghost velocity communication and pass vel yes:

atom_modify map array
comm_modify vel yes
plugin load /path/to/dispplugin.so
compute d all disp/atom nnfile nn.dat vel yes

With vel yes, the compute returns six per-atom columns. c_d[4]-c_d[6] are v_center - mean(v_neighbors).