Project Asparagus

Authors: K. Toepfer, L.I. Vazquez-Salazar

Latest Developments

• A bug in the AMP model potential was fixed that lead to different atomic force predictions between the non-compiled model applied for training (and ASE, CHARMM interfaces) and the TorchScript compiled version applied in the OpenMM interface. Retrainingis required.

What is this?

• A refined implementation of PhysNet, PainNN and AMP (and more atomistic NN to come) in PyTorch.
• A Suit for the automatic construction of Potential Energy Surface (PES) from sampling to production.
• Provides interfaces for trained PES for use with ASE, PyCHARMM, OpenMM

How to use?

• Clone the repository
• Requirements:
  • Python 3.8
  • PyTorch 1.10
  • Atomic Simulation Environment (ASE)
  • Torch-ema 0.3
  • TensorBoardX 2.4
  • numpy, scipy, pandas, ...
  • OpenMM, OpenMM-ML (for OpenMM potential model interface)
  • pyCHARMM API of the CHARMM MD program (for (py)CHARMM potential model interface)

Setting up the environment

We recommend to use Mamba for the creation of a virtual environment.

Once in mamba, you can create a virtual enviroment called asparagus

mamba create --name asparagus python=3.8

To activate the virtual environment use the command:

mamba activate asparagus

Installation

Installation must be done in the virtual environment through pip. It is important to mention that the path where you are working will be added to the PYTHONPATH, so you can import the modules from anywhere.

Install via pip:

python -m pip install .

Alternatively, but deprecated and will probably fail, install via setup.py:

python setup.py install

BEWARE: With this command any modification that is done to the code in the folder asparagus will be automatically reflected in the modules that you import.

NOTE: Everytime you want to import the module, you must use the following command:

from asparagus import Asparagus

Then Asparagus is a function that takes some arguments.

Documentation

Please check our documentation here

What needs to be added?

• Add more NN architectures (Low priority)
• Add sampling methods:
  • MD
  • MC
  • Normal Model Sampling
  • Normal Model Scanning
  • Metadynamics Sampling
  • Umbrella Sampling (Low priority)
• Electronic structure calculations:
  • ASE calculator
  • Custom Calculators (via shell run or slurm batch files)
• Model potentials:
  • PhysNet
  • PaiNN
  • AMP
  • MACE
• Trainer class:
  • Training of model ensemble
• Tester class:
  • Model and Moddel Ensemble automatic evaluation
  • Model automatic evaluation for data with different multiple fragments (e.g. in ML/MM)
• Active learning
  • Adaptive Sampling (first iteration)
  • Uncertainty calculations
    • via Model Ensembles
    • via Deep Evidential Regression (Low priority)
• Tools class:
  • Normal mode calculation (via ASE)
  • Minimum energy path and Minimum dynamic path
  • Diffusion Monte-Carlo
  • Others(?)
• Production:
  • ASE calculator
  • PyCharmm interface
  • OpenMM interface
  • Gaussian interface
• Documentation:
  • Improve documentation
  • Add examples
  • Add tutorials
• Others
  • Create a conda package
  • Create a pip package

Contact

For any questions, please open an issue in the repository.

How to cite

If you find this work useful in your research, please cite it as:

@article{asparagus_cpc,
title = {Asparagus: A toolkit for autonomous, user-guided construction of machine-learned potential energy surfaces},
author = {Kai Töpfer and Luis Itza Vazquez-Salazar and Markus Meuwly},
journal = {Computer Physics Communications},
volume = {308},
pages = {109446},
year = {2025},
issn = {0010-4655},
doi = {https://doi.org/10.1016/j.cpc.2024.109446},
url = {https://www.sciencedirect.com/science/article/pii/S0010465524003692},
keywords = {Machine learning, Neural networks, Potential energy surfaces},
}