How duartegroup/mlp-train works
Project type and purpose
• This is a Python library (mlp-train) for building and training machine-learning potentials (MLPs) for molecular systems (GAP, ACE, MACE).
• It provides:
• descriptor construction (SOAP, …)
• wrappers to external potential packages (libgap, Julia-ACE, MACE/CUDA)
• sampling methods (MD, metadynamics, umbrella)
• training workflows (active learning, selection, loss definitions)
• optional OpenMM integration
File-structure analysis
• Top level:
• mlptrain/ ← core package
• examples/ ← user scripts and notebooks
• docs/ ← Sphinx documentation
• tests/ ← pytest suite
• install_*.sh ← env-setup scripts per model (GAP, ACE, MACE)
• config files (.github workflows, pre-commit, environment.yml)
• mlptrain subpackages indicate the logical modules:
• configurations/ ← data I/O and potential evaluation
• descriptor/ ← feature generation
• potentials/ ← model wrappers (ace, gap, mace, nequip)
• sampling/ ← MD, metadynamics, plumed, umbrella, etc.
• training/ ← active learning, selection strategies
• loss/ ← loss‐function implementations
• energy.py, forces.py ← core energy/force API
• utils.py, log.py ← utilities and logging
README insights
• The library supports three backends (GAP, ACE, MACE) each in a separate conda environment.
• ACE backend requires Julia; MACE benefits from CUDA.
• Provides an OpenMM integration layer (mlptrain.md_openmm).
• Usage patterns: call mlptrain API (e.g. al_train, run_mlp_md_openmm) from user scripts.
• User Interface:
– CLI scripts (examples/*.py, notebooks)
– Python API (mlptrain.*)
• Core Package (mlptrain):
– Descriptor Module
– Potential Wrappers (GAP, ACE, MACE)
– Sampling Module (MD, metadynamics, umbrella)
– Training Module (active learning, selection)
– Loss Module
– Utilities & Logging
• External Engines & Libraries:
– GAP (libgap)
– ACE (Julia library)
– MACE (PyPI + CUDA)
– OpenMM / PLUMED
– Conda (environment management)
• Data Storage:
– Configuration files, trajectory files, bias files
– Checkpoints (trained models)
b. Relationships & data‐flow
1. User invokes a script → calls mlptrain API
2. mlptrain.descriptor generates features from XYZ inputs
3. descriptor passes to potential wrapper, which calls external engine → returns energy & forces
4. sampling uses forces to propagate MD or collect biased samples → writes trajectories
5. training consumes features + energies + trajectories → updates model parameters (active learning loop)
6. checkpoints saved to disk; can be re-loaded for inference or further training
7. optional: OpenMM backend plug-in overrides the sampling loop, calling mlptrain.md_openmm.run_mlp_md_openmm()
c. Architectural patterns
• Modular package structure (clear separation: descriptor / potential / sampling / training)
• Strategy pattern for sampling and training algorithms (each sampler/trainer implements a common interface)
• Adapter pattern for external engines (GAP, ACE, MACE, OpenMM)
d. Key technologies & frameworks
• Python 3.8+ package, uses conda environments per model
• Julia (for ACE backend)
• CUDA (for MACE)
• OpenMM, PLUMED (for MD backends)
• pytest, pre-commit, Ruff for CI