Project Asparagus

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

What is this?

• A refined implementation of PhysNet and PainNN (and more atomistic NN to come) in PyTorch.
• A Suit for the automatic construction of Potential Energy Surface (PES) from sampling to production.

How to use?

• Clone the repository
• Requirements:
  • Python 3.8
  • PyTorch 1.10
  • Atomic Simulation Environment (ASE) 3.21
  • Torch-ema 0.3
  • TensorBoardX 2.4
  • numpy, scipy, pandas, ...

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, 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)
• Trainer class:
  • Training of model ensemble
• Tester class:
  • Model and Moddel Ensemble automatic evaluation
• 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
  • 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},
}