Skip to content
general-molecular-simulationsPublic

About

SO3LR Tauri: machine-learned force fields for reactive (bio)molecular simulations, from H to At

Topics

Resources

Stars

299 stars

Watchers

5 watching

Forks

Latest commit

 

History

1,048 Commits

Folders and files

Repository files navigation

workflow-test-ci docs Open In Colab cite-link preprint-link paper-link data

SO3LR Tauri

About

SO3LR - pronounced Solar - is a pretrained machine-learned force field for (bio)molecular simulations. It integrates the fast and stable SO3krates neural network for semi-local interactions with universal pairwise force fields designed for short-range repulsion, long-range electrostatics, and dispersion interactions.

Installation

Try SO3LR without any local installation using our light web version or Colab notebook.

We recommend installing SO3LR with uv (it's magical):

git clone https://github.com/general-molecular-simulations/so3lr.git
cd so3lr
uv sync --locked --extra cuda12   # GPU; drop --extra cuda12 for CPU
source .venv/bin/activate
so3lr --help

If JAX is already installed on your cluster (CUDA or ROCm), install SO3LR into that environment:

git clone https://github.com/general-molecular-simulations/so3lr.git
cd so3lr
uv pip install ".[cuda12]"   # NVIDIA GPU; ROCm or CPU: uv pip install .
so3lr --help

See the installation guide for optional extras. More details about JAX installation can be found here.

Quick start

SO3LR provides a command-line interface for geometry optimization, molecular dynamics and evaluation. Each command can be run with --help to see all available options.

# Geometry optimization
so3lr opt --input geometry.xyz --force-conv 0.05

# NVT and NPT molecular dynamics
so3lr nvt --input geometry.xyz --temperature 300 --dt 0.5 --md-cycles 100 --md-steps 100
so3lr npt --input geometry.xyz --temperature 300 --pressure 1.0 --dt 0.5 --md-cycles 100 --md-steps 100

# Evaluation on a dataset
so3lr eval --datafile dataset.extxyz --lr-cutoff 100 --save-to predictions.extxyz

For longer simulations, use a settings file, so3lr --settings settings.yaml (see molecular dynamics).

To use SO3LR as an ASE calculator:

from ase.io import read
from so3lr import So3lrCalculator

atoms = read("geometry.xyz")
atoms.info["charge"] = 0          # total charge; 0 if unset
atoms.calc = So3lrCalculator(model="so3lr-tauri-m", lr_cutoff=100)

energy = atoms.get_potential_energy()
forces = atoms.get_forces()

Units are eV and Å. On the command line, periodic structures use PME for electrostatics and dispersion with a 10 Å real-space cutoff (2 Å smearing, 1.55 Å mesh), as in the paper's liquid and scaling simulations. The Python calculators default to 12 Å without k-space. For gas-phase simulations, we suggest using --lr-cutoff 100.

Models

The models are bundled with the package and selected by name. The SO3LR Tauri models cover H to At (Z = 1–85) and are described in the SO3LR Tauri preprint.

  • so3lr-tauri-m (default): start here; the model we use for biomolecular MD.
  • so3lr-tauri-l: the most accurate, recommended for reactions; 3.7× slower than -m.
  • so3lr-tauri-s: 1.4× faster than -m.
  • so3lr: the original model from the JACS paper, for H, C, N, O, F, P, S and Cl, kept to reproduce published results.

Use the same name on the command line (--model) and in settings files (model:), or pass a path to a fine-tuned model. To pin a release for papers and benchmarks, add its date: so3lr-tauri-m-2606.

Documentation

The full documentation is at so3lr.github.io, including:

Datasets

The quantum mechanical datasets used for training and testing SO3LR Tauri are available on Zenodo: 10.5281/zenodo.22920714. The data for the legacy SO3LR model are at 10.5281/zenodo.14779793.

Contributing

The code and models are still evolving, and your feedback is invaluable. We would appreciate if you open an issue for any errors, inconsistencies or feature ideas. See DEVELOPERS.md for development environments and tests.

Citation

If you use SO3LR, please cite the papers below:

@article{kabylda2026so3lr,
  title = {{SO3LR Tauri: Generally Applicable Force Fields for Reactive (Bio)Molecular Simulations Covering the Periodic Table}},
  author = {Kabylda, Adil and Br{\"{u}}nig, Florian N. and Gallegos, Miguel and Frank, J. Thorben and Moerman, Evgeny and Unke, Oliver T. and Chmiela, Stefan and M{\"{u}}ller, Klaus-Robert and Tkatchenko, Alexandre},
  journal = {arXiv preprint arXiv:2611.06237},
  year = {2026},
  doi = {10.48550/arXiv.2611.06237},
  url = {https://arxiv.org/abs/2611.06237},
}

@article{kabylda2025molecular,
  title={Molecular Simulations with a Pretrained Neural Network and Universal Pairwise Force Fields},
  author={Kabylda, Adil and Frank, J Thorben and Su{\'a}rez-Dou, Sergio and Khabibrakhmanov, Almaz and Medrano Sandonas, Leonardo and Unke, Oliver T and Chmiela, Stefan and M{\"u}ller, Klaus-Robert and Tkatchenko, Alexandre},
  journal={Journal of the American Chemical Society},
  volume={147},
  number={37},
  pages={33723},
  year={2025},
  doi={10.1021/jacs.5c09558}
}

@article{frank2024euclidean,
  title={A Euclidean transformer for fast and stable machine learned force fields},
  author={Frank, Thorben and Unke, Oliver and M{\"u}ller, Klaus-Robert and Chmiela, Stefan},
  journal={Nature Communications},
  volume={15},
  number={1},
  pages={6539},
  year={2024},
  doi={10.1038/s41467-024-50620-6}
}

License

The code and the legacy SO3LR model weights are released under the MIT License, and the SO3LR Tauri weights under CC BY-NC 4.0. See NOTICES for details.

About

SO3LR Tauri: machine-learned force fields for reactive (bio)molecular simulations, from H to At

Topics

Resources

Stars

299 stars

Watchers

5 watching

Forks

Releases

Used by

Contributors

Languages