Sovereign 8s.is mirror of standardgalactic/amaceing_toolkit
  • Python 61.3%
  • Jupyter Notebook 28.6%
  • C++ 10.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Jonas Hänseroth 78c64406a9 Fix: Improve error comparison in run_eval_error function (switching from norm-based force error evaluation to component wise force error evaluation).
Fixing autocorrelation calculation for vector pairs in default_analyzer.cpp (handling zero-length vectors and self-pairing).
2026-07-31 18:13:50 +02:00
docs Stick to CUDA12: Update PyTorch installation command to specify CUDA index URL 2026-04-28 10:45:26 +02:00
examples Add TRAIN functionality for MACE, GRACE, and SevenNet frameworks 2026-03-05 13:37:17 +01:00
src/amaceing_toolkit Fix: Improve error comparison in run_eval_error function (switching from norm-based force error evaluation to component wise force error evaluation). 2026-07-31 18:13:50 +02:00
tutorials # MAJOR UPDATE: v0.5.0 2025-08-01 10:49:11 +02:00
.gitignore Implemented SevenNet Finetuning (only: 7net-0) 2025-04-17 23:59:05 +02:00
.readthedocs.yaml Fix compiling issues in the docs code 2 2025-04-07 23:31:55 +02:00
LICENSE first commit 2025-04-07 09:14:20 +02:00
MANIFEST.in first commit 2025-04-07 09:14:20 +02:00
pyproject.toml Release v0.7.0 2026-03-05 13:38:19 +01:00
README.md Stick to CUDA12: Update PyTorch installation command to specify CUDA index URL 2026-04-28 10:45:26 +02:00
requirements.txt Update README and documentation for MACE module enhancements; add support for new foundation models and update requirements for mace_torch 2025-09-12 02:05:27 +02:00
setup.py first commit 2025-04-07 09:14:20 +02:00

aMACEing_toolkit

GitHub Release Paper Documentation Status Presentation Beginners Tutorial GitHub Issues or Pull Requests

Table of contents

Description

aMACEing_toolkit is a scientific software package that facilitates the creation, execution, and analysis of molecular dynamics simulations using multiple simulation engines. It provides a unified workflow for quantum-chemical calculations with CP2K and machine-learned interatomic potentials (MLIPs) including MACE, MatterSim, SevenNet, ORB and Grace.

The toolkit offers:

  1. Input Generation: Easy-to-use interactive interfaces and API functions for creating input files for multiple simulation engines
  2. Workflow Management: Consistent workflow across different software packages
  3. Trajectory Analysis: Fast tools for analyzing simulation outputs (RDF, MSD, SMSD, vector autocorrelation)
  4. Model Evaluation: Utilities to assess and compare MLIP performance against reference data
  5. Run Logging: Tracking and documentation of simulation runs and fine-tuned models

Supported calculation types and simulation engines

Engine Simulation/training types File formats
CP2K GEO_OPT, CELL_OPT, MD, REFTRAJ, ENERGY Input files
MACE GEO_OPT, CELL_OPT, MD, MULTI_MD, RECALC, FINETUNE, FINETUNE_MULTIHEAD, TRAIN ASE, LAMMPS
MatterSim GEO_OPT, CELL_OPT, MD, MULTI_MD, RECALC, FINETUNE ASE
SevenNet GEO_OPT, CELL_OPT, MD, MULTI_MD, RECALC, FINETUNE, TRAIN ASE, LAMMPS
ORB GEO_OPT, CELL_OPT, MD, MULTI_MD, RECALC, FINETUNE ASE
Grace GEO_OPT, CELL_OPT, MD, MULTI_MD, RECALC, FINETUNE, TRAIN ASE, LAMMPS

Installation

  1. Create a virtual environment:

    conda create -n atk python=3.12
    conda activate atk
    
  2. Install PyTorch:

    pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
    

    For CPU-only systems:

    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
    
  3. Install aMACEing_toolkit:

    git clone https://github.com/jhaens/amaceing_toolkit.git
    cd amaceing_toolkit
    pip install -r requirements.txt
    pip install .
    
  4. (Optional) For accelerated MACE performance on CUDA systems:

    # CUDA 11
    pip install cuequivariance cuequivariance-torch cuequivariance-ops-torch-cu11
    # CUDA 12
    pip install cuequivariance cuequivariance-torch cuequivariance-ops-torch-cu12
    # Older Mace Versions (< 0.3.11):
    pip install cuequivariance==0.1.0 cuequivariance-torch==0.1.0 cuequivariance-ops-torch-cu12==0.1.0
    
  5. (Optional) For MatterSim and SevenNet, create a separate environment:

    conda create -n atk_ms7n python=3.9
    conda activate atk_ms7n
    pip install torch torchvision torchaudio
    pip install mattersim==1.1.2 sevenn==0.11.2.post1
    
  6. (Optional) For ORB models, create a separate environment:

    conda create -n atk_orb python=3.10
    conda activate atk_orb
    git clone https://github.com/orbital-materials/orb-models.git
    cd orb-models
    pip install .
    
  7. (Optional) For Grace models, create a separate environment:

    conda create -n atk_grace python=3.11
    conda activate atk_grace
    pip install tensorpotential
    

(ii) Installation via pip

conda create -n atk python=3.12
conda activate atk
pip install torch torchvision torchaudio
pip install amaceing_toolkit

Note: The pip installation does not support running MatterSim and SevenNet simulations directly through the toolkit (only input file creation).

Usage

Command line interface

Each functionality can be accessed through dedicated command line tools:

# Access through interactive Q&A sessions
amaceing_cp2k           # CP2K input creation
amaceing_mace           # MACE input creation
amaceing_mattersim      # MatterSim input creation
amaceing_sevennet       # SevenNet input creation
amaceing_orb            # ORB model input creation
amaceing_grace          # Grace model input creation
amaceing_ana            # Trajectory analysis
amaceing_utils          # Utility functions

# Or with direct arguments for non-interactive use
amaceing_cp2k -rt="GEO_OPT" -c="{'project_name': 'test', 'coord_file': 'system.xyz', 'pbc_list': [10 0 0 0 10 0 0 0 10]}"

Python API

from amaceing_toolkit.workflow import cp2k_api

# Example: Generate a CP2K geometry optimization input
config = {
    'project_name': 'system_geoopt',
    'coord_file': 'system.xyz',
    'pbc_list': [14.2, 0, 0, 0, 14.2, 0, 0, 0, 14.2],
    'max_iter': 10,
    'xc_functional': 'BLYP',
}
cp2k_api(run_type='GEO_OPT', config=config)

Logger

The package includes a run and model logger to track simulation runs and fine-tuned models. This ensures reproducibility and easy access to past runs.

amaceing_utils --logger=run         # Get an overview of runs
amaceing_utils --logger=runexport   # Export run logger to PDF
amaceing_utils --logger=model       # Get an overview of models

Documentation

Complete documentation is available at ReadTheDocs.

The documentation provides:

  • Comprehensive installation instructions
  • Detailed API reference
  • User guides for all supported simulation engines
  • Configuration guides
  • Example workflows
  • Tutorials for common use cases:

Examples

Example systems and scripts are provided in the examples/ directory:

  • 4KOH_92H2O_333K - Potassium hydroxide in water
  • CsH2PO4 - Cesium dihydrogen phosphate
  • analyzer - Trajectory analysis examples
  • api_examples - Python API usage examples

Citation

If you use aMACEing_toolkit in your research, please cite:

Hänseroth, J. and Flötotto, A. and Qaisrani, M. N. and Dreßler, C. "Fine-Tuning Unifies Foundational Machine-learned Interatomic Potential Architectures at ab initio Accuracy." arXiv preprint arXiv:2511.05337 (2025).

@misc{hänseroth2025amaceingtoolkit,
      title={Fine-Tuning Unifies Foundational Machine-learned Interatomic Potential Architectures at ab initio Accuracy}, 
      author={Jonas Hänseroth and Aaron Flötotto and Muhammad Nawaz Qaisrani and Christian Dreßler},
      year={2025},
      eprint={2511.05337},
      archivePrefix={arXiv},
      primaryClass={physics.chem-ph},
      url={https://arxiv.org/abs/2511.05337}, 
}

License

This project is licensed under the MIT License (Non-Commercial Use Only).