Plumed

Overview

SPARC integrates the open-source PLUMED library via the ASE PLUMED wrapper to enable enhanced sampling during molecular dynamics. Any PLUMED collective variable (CV) or bias can be used — the examples here are illustrative, not prescriptive.

SPRINT Coordinates

Social Permutation Invariant (SPRINT) coordinates are one example of a CV that works well for reactive and configurational exploration. They are constructed from a contact matrix built on equilibrium distances between atom types, and are invariant to atomic permutation. SPRINT is based on graph theory and provides a universal descriptor of chemical space.

By definition SPRINT coordinates are calculated from the largest eigenvalue \(\lambda\) of an \(n \times n\) adjacency matrix and its corresponding eigenvector \(\bf{V}\):

\[s_{i} = \sqrt{n} \lambda \mathit{v_i}\]

Note

SPRINT is part of the adjmat module and requires PLUMED to be compiled with the correct flag. See the PLUMED section in SPARC Installation Guide.

Tip

SPRINT coordinates combine well with Parallel Bias Metadynamics (PBMetaD) for self-guided exploration of complex chemical and configurational spaces, but any PLUMED bias (metadynamics, harmonic restraints, funnel metadynamics, etc.) can be attached in the same way.

Enabling PLUMED in `input.yaml`

PLUMED can be enabled for both the AIMD stage and the ML-MD stage independently. Set plumed.enabled: true and point to a PLUMED input file:

aimd_setup:
  plumed:
    enabled: true
    plumed_file: "plumed_dft.dat"   # PLUMED input for AIMD stage
    kT: 0.02585                      # kT in eV (300 K)
    restart: false

mlip_setup:
  plumed:
    enabled: true
    plumed_file: "plumed.dat"        # PLUMED input for ML-MD stage
    kT: 0.02585
    restart: false

Umbrella Sampling

SPARC supports umbrella sampling across multiple windows via the umbrella_sampling block inside mlip_setup.plumed. Each window runs an independent ML-MD trajectory with its own pre-equilibrated structure and PLUMED restraint file. Windows execute sequentially; output for window N is written to iter_000000/02.dpmd/window_NNN/.

Recommended directory layout — keep all window structures and PLUMED files in a configs/ subdirectory alongside input.yaml:

Project Root/
├── structure.xyz
├── input.yaml
├── umbrella_sampling.yaml
└── configs/
    ├── config_14.xyz          (structure near CV = 1.4 Å)
    ├── config_17.xyz
    ├── ...
    ├── plumed_window_000.dat  (restraint at 1.4 Å)
    ├── plumed_window_001.dat  (restraint at 1.7 Å)
    └── ...

Step 1 — Enable umbrella sampling in input.yaml

mlip_setup:
  MdSimulation: true
  ensemble: "NVT"
  temperature: 300.0
  timestep_fs: 1.0
  md_steps: 50000                   # steps per window
  log_frequency: 50
  thermostat:
    type: "Nose"
    tdamp: 25.0
  plumed:
    enabled: true
    kT: 0.02585
    umbrella_sampling:
      enabled: true
      config_file: "umbrella_sampling.yaml"

Step 2 — Define windows in umbrella_sampling.yaml

Each entry specifies a starting structure and PLUMED file for that window:

umbrella_windows:
  - structure: "configs/config_14.xyz"
    plumed_file: "configs/plumed_window_000.dat"   # CV centre: 1.4 Å
  - structure: "configs/config_17.xyz"
    plumed_file: "configs/plumed_window_001.dat"   # CV centre: 1.7 Å
  - structure: "configs/config_20.xyz"
    plumed_file: "configs/plumed_window_002.dat"   # CV centre: 2.0 Å

Step 3 — Write a PLUMED restraint file for each window

Use UNITS LENGTH=A TIME=fs ENERGY=eV to match SPARC’s unit convention. Label the restraint so its bias energy is accessible in PRINT:

# plumed_window_001.dat — window centred at 1.7 Å
UNITS LENGTH=A TIME=fs ENERGY=eV

d1: DISTANCE ATOMS=1,8

rest: RESTRAINT ARG=d1 AT=1.7 KAPPA=50.0

PRINT ARG=d1,rest.bias FILE=COLVAR STRIDE=50

FLUSH STRIDE=250

Each window gets a different AT value. Typical KAPPA range: 10–100 eV/Å² depending on required overlap between adjacent windows.

Output

For each window SPARC writes to iter_000000/02.dpmd/window_NNN/:

window_000/
├── input.xyz       (copy of starting structure)
├── COLVAR          (CV value and bias energy vs time)
└── PLUMED.log

COLVAR columns: time [fs], CV [Å], bias [eV]:

#! FIELDS time d1 rest.bias
 0.000000  1.455013  0.075661
 50.000000  1.454005  0.072914

Collect COLVAR files from all windows and pass to WHAM or pymbar to recover the potential of mean force (PMF).

Note

Umbrella sampling can be combined with active learning by setting active_learning: true. SPARC runs QbC model-deviation analysis on each window’s trajectory and collects uncertain structures for DFT labelling, improving model accuracy along the CV path.

Module Contents

PLUMED wrapper module for enhanced sampling MD simulations.

This module provides integration between ASE calculators and PLUMED for enhanced sampling techniques like metadynamics and umbrella sampling.

sparc.src.plumed_wrapper.modify_forces(calculator, system, timestep, kT, restart, plumed_input, iteration, PlumedLog='PLUMED.log')[source]

Set up and return a PLUMED wrapped ASE calculator for molecular dynamics.

This function reads a PLUMED input file and wraps an existing ASE calculator to apply biasing forces during MD. Useful for enhanced sampling simulations.

For more information, see the ASE documentation: https://wiki.fysik.dtu.dk/ase/ase/calculators/plumed.html

Parameters:

calculator (Calculator) – The underlying ASE calculator for the system (e.g., DeepMD, VASP, CP2K)
system (Atoms) – The atomic configuration to which the calculator is applied
timestep (float) – Integration timestep used in the MD simulation (already in ASE units)
kT (Optional[float]) – Thermal energy (k_B * T) in eV. If None, defaults to 300 K (0.02585 eV)
restart (bool) – Restart option for PLUMED
plumed_input (str) – Path to the PLUMED input file (e.g., “plumed.dat”)
iteration (str) – Directory name for PLUMED output files
PlumedLog (str) – PLUMED log filename (default: ‘PLUMED.log’)

Returns:

The PLUMED-wrapped ASE calculator

Return type:

ase.calculators.plumed.Plumed

sparc.src.plumed_wrapper.umbrella(config, us_dir, dp_path, dp_model)[source]

Set up and run umbrella sampling simulations with PLUMED biasing.

This function reads a configuration file defining umbrella sampling windows and applies restraining forces to collective variables for each window. Supports NVE, NVT (Nose-Hoover, Langevin), and NPT ensembles.