pair_style runner: support multiple independent instances

doc/src/pair_runner.rst

@@ -329,9 +329,13 @@ This pair style is part of the ML-RUNNER package.  It is only enabled if
 LAMMPS was built with that package.  See the :doc:`Build package
 <Build_package>` doc page for more info.
 
-Currently, only one instance of ``pair_style runner`` can be initialized
-per simulation.  The style does not support the use of :doc:`pair_style
-hybrid <pair_hybrid>` where multiple ``runner`` instances are defined.
+Multiple instances of ``pair_style runner`` can be active at the same
+time, for example through :doc:`pair_style hybrid <pair_hybrid>`: every
+instance owns an independent RuNNer potential (its own ``input.nn``
+settings, weights, and neighbor lists), so different instances may even
+use entirely different models.  This requires a RuNNer library built
+with the instance-based (handle) interface, LAMMPS interface API
+version 3 or later.
 
 Related commands
 ----------------

examples/PACKAGES/ml-runner/README.txt

@@ -3,6 +3,10 @@ It runs a short NVT molecular dynamics simulation of 192 bulk water molecules.
 
 Files included:
 in.ml-runner.H2O             # LAMMPS input script for the NVT simulation
+in.ml-runner.H2O.single      # Single-instance run-0 reference for the multi-instance check
+in.ml-runner.H2O.multi       # Two pair_style runner instances via hybrid/overlay (run 0)
+check_multi_instance.sh      # Checks that two overlaid instances give exactly twice the
+                             # single-instance pair energy (instance independence)
 H2O.data                     # LAMMPS data file containing 64 bulk water molecules
 
 2G-H2O-HDNNP/                # Directory containing the 2G-HDNNP trained on bulk water reference data
@@ -15,3 +19,9 @@ To run this example, you must compile LAMMPS with the ML-RUNNER package enabled
 and the RuNNer library linked. Then, execute the following command:
 
 lmp -in in.ml-runner.H2O
+
+Every pair_style runner instance owns an independent RuNNer potential, so
+several instances can be combined through pair_style hybrid/overlay. To
+verify this on your build, run:
+
+./check_multi_instance.sh /path/to/lmp

examples/PACKAGES/ml-runner/check_multi_instance.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+# Regression check for multiple pair_style runner instances.
+#
+# Runs the single-instance reference input and the hybrid/overlay input
+# that stacks the same 2G water potential twice, then checks that the
+# overlaid pair energy is exactly twice the single-instance one (within
+# a small relative tolerance for the log formatting). With shared global
+# state, the second instance would have clobbered the first and this
+# invariant would not hold.
+#
+# Usage: ./check_multi_instance.sh /path/to/lmp
+set -e
+
+LMP=${1:?"usage: $0 /path/to/lmp"}
+
+epair () {
+    # Pull epair of step 0 from a run-0 log: the thermo data line follows
+    # the header line that starts with 'Step'.
+    awk '/^ *Step /{getline; print $3; exit}' "$1"
+}
+
+$LMP -in in.ml-runner.H2O.single -log log.single.tmp > /dev/null
+$LMP -in in.ml-runner.H2O.multi -log log.multi.tmp > /dev/null
+
+E1=$(epair log.single.tmp)
+E2=$(epair log.multi.tmp)
+
+echo "single instance : epair = $E1"
+echo "two instances   : epair = $E2"
+
+ok=$(awk -v e1="$E1" -v e2="$E2" 'BEGIN {
+    diff = e2 - 2.0 * e1
+    if (diff < 0.0) diff = -diff
+    ref = 2.0 * e1
+    if (ref < 0.0) ref = -ref
+    print (diff <= 1.0e-8 * ref) ? "yes" : "no"
+}')
+
+rm -f log.single.tmp log.multi.tmp
+
+if [ "$ok" = "yes" ]; then
+    echo "OK: two pair_style runner instances are independent (E2 = 2*E1)."
+else
+    echo "FAILED: expected epair(two instances) = 2 * epair(single instance)."
+    exit 1
+fi

examples/PACKAGES/ml-runner/in.ml-runner.H2O.multi

@@ -0,0 +1,29 @@
+# Two independent instances of pair_style runner in one simulation.
+#
+# Every pair_style runner instance owns an independent RuNNer potential
+# (handle-based library interface), so multiple instances can be combined
+# through pair_style hybrid/overlay. This input overlays the SAME 2G water
+# potential twice: the pair energy must therefore be exactly twice the
+# energy of the single-instance run (in.ml-runner.H2O with run 0), which
+# makes this a sharp correctness check for instance independence.
+
+units metal
+
+boundary p p p
+atom_style atomic
+read_data "H2O.data"
+
+##########################
+#   ML-RuNNer Settings   #
+##########################
+pair_style hybrid/overlay &
+  runner dir 2G-H2O-HDNNP cflength 1.889726124626 cfenergy 0.036749322175655 &
+  runner dir 2G-H2O-HDNNP cflength 1.889726124626 cfenergy 0.036749322175655
+pair_coeff * * runner 1 1 8
+pair_coeff * * runner 2 1 8
+
+thermo 1
+thermo_style custom step temp epair etotal fmax fnorm press
+thermo_modify format line "%8d %8.3f %15.8f %15.8f %9.4f %9.4f %9.2f"
+
+run 0

examples/PACKAGES/ml-runner/in.ml-runner.H2O.single

@@ -0,0 +1,23 @@
+# Single-instance reference for in.ml-runner.H2O.multi.
+#
+# Evaluates the 2G water potential once (run 0). The multi-instance input
+# overlays the same potential twice, so its pair energy must be exactly
+# twice the value obtained here. See check_multi_instance.sh.
+
+units metal
+
+boundary p p p
+atom_style atomic
+read_data "H2O.data"
+
+##########################
+#   ML-RuNNer Settings   #
+##########################
+pair_style runner dir 2G-H2O-HDNNP cflength 1.889726124626 cfenergy 0.036749322175655
+pair_coeff * * 1 8
+
+thermo 1
+thermo_style custom step temp epair etotal fmax fnorm press
+thermo_modify format line "%8d %8.3f %15.8f %15.8f %9.4f %9.4f %9.2f"
+
+run 0