local: run/build scripts, retargeted at the staging tree

Personal dev-loop scripts plus the sample .dat inputs they use. They had rotted:
they pointed at GROMACS 2025.3, Eigen 3.4.0, kenref/debug/AVX_512 (a layout that
no longer exists), plumed-dev/master/<build> (missing the kenref-version level
the staging tree now has), and three "-asan" tiers that exist in neither tree.

Rewritten around a sourced _env.sh so every path is derived from a handful of
variables, each overridable from the caller:

    KN_BUILD=release ./runPlumed.sh
    KN_ACCEL=AVX2_256 KN_VER=1.0.0 ./buildPlumed.sh

Targets the STAGING tree, which is the hierarchical one:
    kenref-dev/<ver>/<build>/<accel>
    plumed-dev/<plumed-branch>/<kenref-ver>/<build>/<accel>
    gromacs-4-plumed-dev/<year>/<gmx-ver>/<build>/<accel>
The deployment tree is flat and named differently (kenref/2.0.0_AVX_512), so
these do not drive it -- deliberate, since development happens against staging.

Two further fixes while there:
- the PLUMED source directory is derived from the script's own location instead
  of being hardcoded to /home/amr/git/plumed2, so they work in any checkout;
- kn_require() checks every path up front and, on a miss, prints what was
  selected and which kenref builds actually exist. The old scripts failed late
  and cryptically when a tier had been reorganised away.

buildPlumed.sh also maps KN_ACCEL to the matching -march, since Eigen's
alignment is part of libkenref_core's ABI and a mismatch trips the SIMD guard.

Verified: all four scripts pass `bash -n`, and every derived path resolves for
KN_BUILD in {debug,release,relwithdebinfo} x KN_ACCEL in {AVX_512,AVX2_256,AVX_256}.
The -asan invocations are kept, commented, with a note that the tier is gone.

Author: aalhossary

src/kenref/runFiles/_env.sh

@@ -0,0 +1,54 @@
+# Shared environment for the runFiles scripts. Source it; do not execute it.
+#
+# Every path used by these scripts is derived from the few variables below, so a version bump is one
+# edit here instead of a hunt through four scripts. Each is overridable from the caller's environment:
+#
+#   KN_BUILD=release ./runPlumed.sh
+#   KN_ACCEL=AVX2_256 KN_VER=1.0.0 ./buildPlumed.sh
+#
+# These point at the STAGING tree (/smithlab/opt/*-dev), which is the hierarchical one:
+#   kenref-dev/<ver>/<build>/<accel>
+#   plumed-dev/<plumed-branch>/<kenref-ver>/<build>/<accel>
+#   gromacs-4-plumed-dev/<year>/<gmx-ver>/<build>/<accel>
+# The DEPLOYMENT tree is flat and named differently (kenref/2.0.0_AVX_512), so these scripts do not
+# work against it unchanged -- that is deliberate, since you develop against staging.
+
+KN_VER="${KN_VER:-2.0.0}"                     # kenref version dimension
+KN_BUILD="${KN_BUILD:-debug}"                 # debug | relwithdebinfo | release
+KN_ACCEL="${KN_ACCEL:-AVX_512}"               # AVX_512 | AVX2_256 | AVX_256
+KN_PLUMED_BRANCH="${KN_PLUMED_BRANCH:-master}"
+KN_GMX_YEAR="${KN_GMX_YEAR:-2025}"
+KN_GMX_VER="${KN_GMX_VER:-2025.4}"
+KN_EIGEN_VER="${KN_EIGEN_VER:-5.0.1}"
+KN_LLVM="${KN_LLVM:-/smithlab/opt/llvm/20.1.1}"
+
+KN_OPT="${KN_OPT:-/smithlab/opt}"
+
+# The PLUMED source tree: derived from this file's own location, so the scripts work in any checkout
+# rather than only in the one they were written in.
+KN_PLUMED_SRC="${KN_PLUMED_SRC:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)}"
+
+# Overridable so you can point at a kenref built somewhere else (a scratch prefix, a release-tier
+# install) without editing this file:  KN_KENREF_PREFIX=/path/to/prefix ./buildPlumed.sh
+KN_KENREF_PREFIX="${KN_KENREF_PREFIX:-${KN_OPT}/kenref-dev/${KN_VER}/${KN_BUILD}/${KN_ACCEL}}"
+KN_PLUMED_PREFIX="${KN_PLUMED_PREFIX:-${KN_OPT}/plumed-dev/${KN_PLUMED_BRANCH}/${KN_VER}/${KN_BUILD}/${KN_ACCEL}}"
+KN_GMXRC="${KN_OPT}/gromacs-4-plumed-dev/${KN_GMX_YEAR}/${KN_GMX_VER}/${KN_BUILD}/${KN_ACCEL}/bin/GMXRC"
+KN_EIGEN_PC="${KN_EIGEN_PC:-${KN_OPT}/eigen/${KN_EIGEN_VER}/${KN_BUILD}/share/pkgconfig}"
+KN_PLUMED_KERNEL="${KN_PLUMED_PREFIX}/lib/libplumedKernel.so"
+
+# Fail loudly and early. These scripts used to point at paths that had been reorganised away
+# (gromacs 2025.3, eigen 3.4.0, plumed-dev/master/<build> without the kenref-version level, and the
+# -asan tiers), and the failures that produced were confusing and late.
+kn_require() {
+    local missing=0 p
+    for p in "$@"; do
+        [ -e "$p" ] || { echo "MISSING: $p" >&2; missing=1; }
+    done
+    if [ "$missing" = 1 ]; then
+        echo "" >&2
+        echo "Current selection: KN_VER=$KN_VER KN_BUILD=$KN_BUILD KN_ACCEL=$KN_ACCEL" >&2
+        echo "Available kenref builds:" >&2
+        ls -d "${KN_OPT}/kenref-dev/${KN_VER}"/*/* 2>/dev/null | sed 's/^/  /' >&2
+        return 1
+    fi
+}

src/kenref/runFiles/buildPlumed.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# Configure and build PLUMED with the kenref module, against a STAGING kenref install.
+# Paths come from _env.sh -- override on the command line, e.g. KN_BUILD=release ./buildPlumed.sh
+set -e
+source "$(dirname "${BASH_SOURCE[0]}")/_env.sh"
+
+kn_require "${KN_KENREF_PREFIX}/lib/pkgconfig" "${KN_EIGEN_PC}"
+
+cd "${KN_PLUMED_SRC}"
+
+export PKG_CONFIG_PATH="${KN_KENREF_PREFIX}/lib/pkgconfig:${KN_EIGEN_PC}:${PKG_CONFIG_PATH}"
+
+# The linker must be able to FIND libkenref_core.so when it links the `plumed` executable against
+# libplumedKernel.so, and --enable-rpath must record that directory so the binaries are
+# self-contained. src/kenref/_common.sh does this; this hand-rolled script did not, which produced:
+#   ld: warning: libkenref_core.so.2, needed by libplumedKernel.so, not found
+#   libplumedKernel.so: undefined reference to `kenref::bootstrapModels()'
+# Safe alongside pkg-config because PLUMED's configure queries --libs with
+# PKG_CONFIG_ALLOW_SYSTEM_LIBS=1; otherwise pkg-config would suppress -L for a directory that is
+# on LIBRARY_PATH and the captured link line would silently stop being self-contained.
+export LIBRARY_PATH="${KN_KENREF_PREFIX}/lib:${LIBRARY_PATH}"
+export LD_LIBRARY_PATH="${KN_KENREF_PREFIX}/lib:${LD_LIBRARY_PATH}"
+
+# -march must match the kenref build's ACCEL tier: Eigen's alignment is part of libkenref_core's ABI,
+# so a mismatch trips the SIMD/Eigen guard. kenref_core.pc now carries the right -march itself, so this
+# is belt-and-braces rather than the only source of truth.
+case "${KN_ACCEL}" in
+  AVX_512)  KN_MARCH=skylake-avx512 ;;
+  AVX2_256) KN_MARCH=haswell ;;
+  AVX_256)  KN_MARCH=sandybridge ;;
+  *) echo "unknown KN_ACCEL=${KN_ACCEL}" >&2; exit 2 ;;
+esac
+
+# autoconf 2.69 reproduces PLUMED's committed `configure` byte-for-byte; 2.72 rewrites the whole script
+# (~10k lines of unrelated churn), which in a git checkout shows up as a huge spurious diff. Pin the
+# version, and only regenerate when configure.ac is actually newer -- `autoreconf --force` unconditionally
+# rewrote it before, and on this machine /usr/local/bin/autoconf (2.72) precedes /usr/bin/autoconf (2.69).
+KN_AUTOCONF="${KN_AUTOCONF:-/usr/bin/autoconf}"
+if ! "${KN_AUTOCONF}" --version | head -1 | grep -q '2\.69'; then
+    echo "WARNING: ${KN_AUTOCONF} is not autoconf 2.69 -- regenerating configure may rewrite it wholesale." >&2
+fi
+if [ configure.ac -nt configure ] || [ ! -f configure ]; then
+    echo "==> regenerating configure with $(${KN_AUTOCONF} --version | head -1)"
+    "${KN_AUTOCONF}" -o configure configure.ac
+else
+    echo "==> configure is up to date; skipping autoreconf"
+fi
+
+./configure \
+    CXXFLAGS="-stdlib=libc++ -O0 -g -fPIC -Wall -pedantic -std=c++17 -march=${KN_MARCH}" \
+    LDFLAGS="-L${KN_LLVM}/lib/x86_64-unknown-linux-gnu" \
+    LIBS="-Wl,--push-state,--no-as-needed -lc++ -lc++abi -lunwind -Wl,--pop-state -lpthread -ldl" \
+    --prefix="${KN_PLUMED_PREFIX}" \
+    --enable-modules=reset:+kenref \
+    CXX=mpicxx CC=mpicc FC=mpif90
+
+make clean
+make -j"${KN_JOBS:-18}"
+# sudo make install

src/kenref/runFiles/ener.edr

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Single-replica run against the STAGING GROMACS-4-PLUMED build.
+set -e
+source "$(dirname "${BASH_SOURCE[0]}")/_env.sh"
+
+kn_require "${KN_GMXRC}" "${KN_PLUMED_SRC}/sourceme.sh"
+
+source "${KN_GMXRC}"
+source "${KN_PLUMED_SRC}/sourceme.sh"
+
+if [ -z "$PLUMED_KERNEL" ]; then
+    echo "ERROR: PLUMED_KERNEL not set. Please check the PLUMED installation." >&2
+    exit 1
+fi
+echo "PLUMED_KERNEL=$PLUMED_KERNEL"
+
+# TPR to run. Override with KN_TPR=... ; the default is the committed single-replica test set.
+KN_TPR="${KN_TPR:-${KN_PLUMED_SRC}/src/kenref/run-output/repl_01/topol.tpr}"
+kn_require "${KN_TPR}"
+
+# For multi-replica runs the input must sit in a relative folder (see runPlumed_double.sh).
+gmx_mpi mdrun -s "${KN_TPR}" -nsteps "${KN_NSTEPS:-50}" -plumed ../runFiles/test_single.dat

src/kenref/runFiles/runPlumed.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Two-replica run against the STAGING GROMACS-4-PLUMED build.
+set -e
+source "$(dirname "${BASH_SOURCE[0]}")/_env.sh"
+
+kn_require "${KN_GMXRC}" "${KN_PLUMED_SRC}/sourceme.sh"
+
+source "${KN_GMXRC}"
+source "${KN_PLUMED_SRC}/sourceme.sh"
+
+if [ -z "$PLUMED_KERNEL" ]; then
+    echo "ERROR: PLUMED_KERNEL not set. Please check the PLUMED installation." >&2
+    exit 1
+fi
+echo "PLUMED_KERNEL=$PLUMED_KERNEL"
+
+# -multidir needs the tpr named relatively and one directory per replica; run this from the directory
+# that contains repl_01/ and repl_02/.
+mpirun -n 2 gmx_mpi mdrun -s topol.tpr -multidir repl_01 repl_02 \
+    -nsteps "${KN_NSTEPS:-50}" -plumed ../../runFiles/test_double.dat

src/kenref/runFiles/runPlumed_double.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Longer ubiquitin run, used for debugging/profiling against the STAGING tree.
+#
+# NOTE: this script previously pointed at "-asan" tiers
+# (gromacs-4-plumed/2025/2025.3/relwithdebinfo-asan, plumed-dev/master/{asan,relwithdebinfo-asan}).
+# Those tiers no longer exist in either the staging or the deployment tree, so the sanitizer lines are
+# kept commented and expressed in terms of _env.sh -- set KN_BUILD=relwithdebinfo for the closest
+# equivalent, and re-add a sanitizer tier to the build scripts if you need one again.
+set -e
+source "$(dirname "${BASH_SOURCE[0]}")/_env.sh"
+
+kn_require "${KN_GMXRC}" "${KN_PLUMED_KERNEL}"
+
+source "${KN_GMXRC}"
+export PLUMED_KERNEL="${KN_PLUMED_KERNEL}"
+
+if [ -z "$PLUMED_KERNEL" ]; then
+    echo "ERROR: PLUMED_KERNEL not set. Please check the PLUMED installation." >&2
+    exit 1
+fi
+echo "PLUMED_KERNEL=$PLUMED_KERNEL"
+
+# Sanitizer support (needs a sanitizer-enabled PLUMED build; see the note above):
+# export ASAN_OPTIONS="detect_leaks=0:log_path=./asan.log:abort_on_error=1"
+# export LD_PRELOAD=${KN_LLVM}/lib/clang/20/lib/x86_64-unknown-linux-gnu/libclang_rt.asan.so
+export ASAN_OPTIONS=detect_leaks=0:halt_on_error=1:log_path=asan.log
+
+export PLUMED_LOAD_NODEEPBIND=1
+
+# The trajectory this was written against. Override with KN_TPR=...
+KN_TPR="${KN_TPR:-/smithlab/home/aalhossary/ubiquitin-plateaus-plumed/10nsstart+fitting/alef.tpr}"
+kn_require "${KN_TPR}"
+
+gmx_mpi mdrun -cpi -pin on -ntomp "${KN_NTOMP:-20}" -cpt 30 \
+    -plumed ../runFiles/ubiquitin_1e8_.25_999_A.dat \
+    -deffnm test \
+    -s "${KN_TPR}"
+
+# Under valgrind:
+# valgrind --tool=memcheck --error-exitcode=1 --leak-check=no --track-origins=yes \
+#     --num-callers=30 --log-file=valgrind.%p.log \
+#     gmx_mpi mdrun -cpi -pin on -ntomp 1 -cpt 30 \
+#         -plumed ../runFiles/ubiquitin_1e8_.25_999_A.dat -deffnm test -s "${KN_TPR}"
+#
+# Under rr:
+# rr record gmx_mpi mdrun -cpi -pin on -ntomp 1 -cpt 30 \
+#     -plumed ../runFiles/ubiquitin_1e8_.25_999_A.dat -deffnm test -s "${KN_TPR}"

src/kenref/runFiles/test.edr

@@ -0,0 +1,31 @@
+#N.B. Don't put your folder names in quotes
+
+KENREF ...
+    LABEL=kenref
+#    STRIDE=5
+    MODEL=SIGMA
+    K=1.0
+    N=0.25
+
+#========= SIGMA RELATED ======================
+    EXP_DATA_FOLDER=/smithlab/home/nblangdon/GB3/KEnRef-GB3/gb3-kenref-sigma/start_KEnRef_sigma/input_2
+    PROTON_MHZ=700.0
+#    RATES=XXXXXXXXXXXXXXXXXX (TODO change it to a RATES file location)
+#===============================================
+#========= PLATEAUS RELATED ====================
+#    EXP_DATA_FILE=XXXXXXXXXXXXXXXXXX
+#===============================================
+    GUIDE_ATOMS=39,60,82,101,117,234,241,256,270,284,358,368,383,397,407,422,444,454,474,496,513,534,544,558,626,642,666,680,701,771,785,805,819
+    REF=/smithlab/home/nblangdon/GB3/KEnRef-GB3/gb3-kenref-sigma/start_KEnRef_sigma/alef.pdb
+    ATOMNAME_MAPPING=/smithlab/home/nblangdon/GB3/KEnRef-GB3/gb3-kenref-sigma/start_KEnRef_sigma/alef.pdb
+
+    MAX_FORCE=999
+    FIT_TO_REFERENCE
+    SATURATE_FORCES
+
+#    UPDATE_FROM=50
+#    UPDATE_UNTIL = 100
+... KENREF
+
+# Access the components
+PRINT ARG=kenref.bias,kenref.energy,kenref.rmsd FILE=kenref.out STRIDE=10

src/kenref/runFiles/testPlumed.sh

@@ -0,0 +1,31 @@
+#N.B. Don't put your folder names in quotes
+
+KENREF ...
+    LABEL=kenref
+#    STRIDE=5
+    MODEL=SIGMA
+    K=1.0
+    N=0.25
+
+#========= SIGMA RELATED ======================
+    EXP_DATA_FOLDER=/smithlab/home/nblangdon/GB3/KEnRef-GB3/gb3-kenref-sigma/start_KEnRef_sigma/input_1
+    PROTON_MHZ=700.0
+#    RATES=XXXXXXXXXXXXXXXXXX (TODO change it to a RATES file location)
+#===============================================
+#========= PLATEAUS RELATED ====================
+#    EXP_DATA_FILE=XXXXXXXXXXXXXXXXXX
+#===============================================
+    GUIDE_ATOMS=39,60,82,101,117,234,241,256,270,284,358,368,383,397,407,422,444,454,474,496,513,534,544,558,626,642,666,680,701,771,785,805,819
+    REF=/smithlab/home/nblangdon/GB3/KEnRef-GB3/gb3-kenref-sigma/start_KEnRef_sigma/alef.pdb
+    ATOMNAME_MAPPING=/smithlab/home/nblangdon/GB3/KEnRef-GB3/gb3-kenref-sigma/start_KEnRef_sigma/alef.pdb
+
+    MAX_FORCE=999
+    FIT_TO_REFERENCE
+    SATURATE_FORCES
+
+#    UPDATE_FROM=50
+#    UPDATE_UNTIL = 100
+... KENREF
+
+# Access the components
+PRINT ARG=kenref.bias,kenref.energy,kenref.rmsd FILE=kenref.out STRIDE=10

src/kenref/runFiles/test_double.dat

@@ -0,0 +1,33 @@
+#N.B. Don't put your folder names in quotes
+
+KENREF ...
+    LABEL=kenref
+#    STRIDE=5
+    MODEL=PLATEAUS
+#    MODEL=SIGMA
+    K=1e8
+    N=0.25
+
+#========= SIGMA RELATED ======================
+#    EXP_DATA_FOLDER=/smithlab/home/nblangdon/GB3/KEnRef-GB3/gb3-kenref-sigma/start_KEnRef_sigma/input_2
+#    PROTON_MHZ=700.0
+##    RATES=XXXXXXXXXXXXXXXXXX (TODO change it to a RATES file location)
+#===============================================
+#========= PLATEAUS RELATED ====================
+    EXP_DATA_FILE=/smithlab/home/aalhossary/ubiquitin-plateaus-plumed/10nsstart+fitting/singleton_data_10nsstart+fit_3-5_1977pairs_80_A.csv
+#===============================================
+    GUIDE_ATOMS=5,22,39,58,78,94,116,130,149,163,170,192,206,225,239,258,273,289,312,318,329,341,355,374,389,403,419,441,451,473,492,509,521,543,558,565,592,606,612,624,641,658,682,701,720,740,750,757,779,796,815,830,842,849,873,887,906,917,929,950,964,983,1000,1022,1037,1048,1062,1081,1098
+
+    REF=/smithlab/home/aalhossary/ubiquitin-plateaus-plumed/10nsstart+fitting/alef.pdb
+    ATOMNAME_MAPPING=/smithlab/home/aalhossary/ubiquitin-plateaus-plumed/10nsstart+fitting/alef.pdb
+
+    MAX_FORCE=999
+    FIT_TO_REFERENCE
+    SATURATE_FORCES
+
+#    UPDATE_FROM=50
+#    UPDATE_UNTIL = 100
+... KENREF
+
+# Access the components
+PRINT ARG=kenref.bias,kenref.energy,kenref.rmsd FILE=kenref.out STRIDE=100