mat-sample-pes-by-md

Sample PES by MD

Goal

To generate diverse and representative atomic configurations from a starting structure to augment training data for Machine Learning Interatomic Potentials (MLIPs). This is achieved through MD-based sampling with crystal feature clustering.

Instructions

1. Prepare a Foundation Potential: Select an appropriate MLIP model for sampling.

   • Recommended: M3GNet-PES-MatPES-PBE-2025.2 (MatGL) or MACE-MP-small (MACE) for general inorganic materials.

2. Off-Equilibrium Sampling (MD-Clustering):

   • Use the unified sampling script to run a short MD trajectory and pick representative configurations via K-Means clustering of latent features.

   Using MatGL (CHGNet):

   # Env: matgl-agent
   python .agents/skills/mat-sample-pes-by-md/scripts/run_sampling.py input.cif \
       --model_type matgl --model_name CHGNet-PES-MatPES-PBE-2025.2.10 \
       --total_steps 2000 --temperature 1000 --n_clusters 10 --output_dir sampling_results
   

   Using MACE:

   # Env: mace-agent
   python .agents/skills/mat-sample-pes-by-md/scripts/run_sampling.py input.cif \
       --model_type mace --model_name MACE-OMAT-0-small \
       --total_steps 2000 --temperature 1000 --n_clusters 10 --output_dir sampling_results
   

Supercell Expansion

The script automatically expands small cells (e.g., primitive cells) to supercells containing ~50 atoms (close-to-cubic) before simulation. This ensures adequate system size and local environment diversity.

• Customize: Set --target_atoms in the script call (recommended: 40-70 atoms for VASP efficiency).
• Limit: Maximum atoms capped at 120 to prevent OOM in subsequent DFT calculations.

Standalone Usage (Python API)

For integration into other Python workflows, use the OffEquilibriumSampler class directly.

from .agents.skills.mat_sample_pes_by_md.scripts.sampler import OffEquilibriumSampler
from .agents.skills.mat_sample_pes_by_md.scripts.feature_calculators import MatGLCrystalFeatureCalculator
from matgl import load_model

# Setup calculator
model = load_model("M3GNet-PES-MatPES-PBE-2025.2")
calc = MatGLCrystalFeatureCalculator(potential=model)

# Initialize and run sampler
sampler = OffEquilibriumSampler(
    calculator=calc,
    atoms=initial_atoms,
    total_steps=1000,
    temperature=800,
    n_clusters=20
)
structures, metadata = sampler.sample()