torch-pme

Particle-mesh based calculations of long-range interactions in PyTorch

Science Score: 75.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 6 DOI reference(s) in README
○
Academic publication links
✓
Committers with academic emails
2 of 10 committers (20.0%) from academic institutions
✓
Institutional organization owner
Organization lab-cosmo has institutional domain (cosmo.epfl.ch)
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (13.9%) to scientific vocabulary

Keywords

electrostatics fast-fourier-transform machine-learning material-science molecular-dynamics particle-mesh-ewald pytorch

Keywords from Contributors

computational-chemistry molecular-dynamics-simulation interactive network-simulation hacking embedded optim standardization projection generic

Last synced: 6 months ago · JSON representation ·

Repository

Particle-mesh based calculations of long-range interactions in PyTorch

Basic Info

Host: GitHub
Owner: lab-cosmo
License: bsd-3-clause
Language: Python
Default Branch: main
Homepage: https://lab-cosmo.github.io/torch-pme/
Size: 9.56 MB

Statistics

Stars: 59
Watchers: 17
Forks: 6
Open Issues: 15
Releases: 5

Topics

electrostatics fast-fourier-transform machine-learning material-science molecular-dynamics particle-mesh-ewald pytorch

Created over 2 years ago · Last pushed 6 months ago

Metadata Files

Readme Contributing License Code of conduct Citation

README.rst

torch-pme
=========

.. image:: https://raw.githubusercontent.com/lab-cosmo/torch-pme/refs/heads/main/docs/logo/torch-pme.svg
   :width: 200 px
   :align: left

|tests| |codecov| |docs|

.. marker-introduction

``torch-pme`` enables efficient and auto-differentiable computation of long-range
interactions in *PyTorch*. Auto-differentiation is supported for particle *positions*,

*charges*/*dipoles*, and *cell* parameters, allowing not only the automatic computation
of forces but also enabling general applications in machine learning tasks. For
**monopoles** the library offers classes for Particle-Particle Particle-Mesh Ewald
(``P3M``), Particle Mesh Ewald (``PME``), standard ``Ewald``, and non-periodic methods.
The library has the flexibility to calculate potentials beyond :math:`1/r`
electrostatics, including arbitrary order :math:`1/r^p` potentials. For **dipolar**
interaction we offer to calculate the :math:`1/r^3` potential using the standard
``Ewald`` method.

Optimized for both CPU and GPU devices, ``torch-pme`` is fully `TorchScriptable`_,
allowing it to be converted into a format that runs independently of Python, such as in
C++, making it ideal for high-performance production environments.

We also provide an experimental implementation for *JAX* in `jax-pme`_.

.. _`TorchScriptable`: https://pytorch.org/docs/stable/jit.html
.. _`jax-pme`: https://github.com/lab-cosmo/jax-pme

.. marker-documentation

Documentation
-------------

For details, tutorials, and examples, please have a look at our `documentation`_.

.. _`documentation`: https://lab-cosmo.github.io/torch-pme

.. marker-installation

Installation
------------

You can install *torch-pme* using pip with

.. code-block:: bash

    pip install torch-pme

or conda

.. code-block:: bash

    conda install -c conda-forge torch-pme

and ``import torchpme`` to use it in your projects!

We also provide bindings to `metatensor `_ which can
optionally be installed together and used as ``torchpme.metatensor`` via

.. code-block:: bash

    pip install torch-pme[metatensor]

.. marker-quickstart

Quickstart
----------

Here is a simple example to get started with *torch-pme*:

.. code-block:: python

   >>> import torch
   >>> import torchpme

   >>> # Single charge in a cubic box
   >>> positions = torch.zeros((1, 3))
   >>> cell = 8 * torch.eye(3)
   >>> charges = torch.tensor([[1.0]])

   >>> # No neighbors for a single atom; use `vesin` for neighbors if needed
   >>> neighbor_indices = torch.zeros((0, 2), dtype=torch.int64)
   >>> neighbor_distances = torch.zeros((0,))

   >>> # Tune P3M parameters
   >>> smearing, p3m_parameters, _ = torchpme.tuning.tune_p3m(
   ...    charges=charges,
   ...    cell=cell,
   ...    positions=positions,
   ...    cutoff=5.0,
   ...    neighbor_indices=neighbor_indices,
   ...    neighbor_distances=neighbor_distances,
   ... )

   >>> # Initialize potential and calculator
   >>> potential = torchpme.CoulombPotential(smearing)
   >>> calculator = torchpme.P3MCalculator(potential, **p3m_parameters)

   >>> # Start recording operations done to ``positions``
   >>> _ = positions.requires_grad_()

   >>> # Compute (per-atom) potentials
   >>> potentials = calculator.forward(
   ...    charges=charges,
   ...    cell=cell,
   ...    positions=positions,
   ...    neighbor_indices=neighbor_indices,
   ...    neighbor_distances=neighbor_distances,
   ... )

   >>> # Calculate total energy and forces
   >>> energy = torch.sum(charges * potentials)
   >>> energy.backward()
   >>> forces = -positions.grad

For more examples and details, please refer to the `documentation`_.

.. marker-issues

Having problems or ideas?
-------------------------

Having a problem with *torch-pme*? Please let us know by `submitting an issue
`_.

Submit new features or bug fixes through a `pull request
`_.

.. marker-cite

Reference
---------

If you use *torch-pme* for your work, please read and cite our publication available on
`JCP`_.

.. code-block::

   @article{10.1063/5.0251713,
      title = {Fast and flexible long-range models for atomistic machine learning},
      author = {Loche, Philip and Huguenin-Dumittan, Kevin K. and Honarmand, Melika and Xu, Qianjun and Rumiantsev, Egor and How, Wei Bin and Langer, Marcel F. and Ceriotti, Michele},
      journal = {The Journal of Chemical Physics},
      volume = {162},
      number = {14},
      pages = {142501},
      year = {2025},
      month = {04},
      issn = {0021-9606},
      doi = {10.1063/5.0251713},
      url = {https://doi.org/10.1063/5.0251713},
   }

.. _`JCP`: https://doi.org/10.1063/5.0251713

.. marker-contributing

Contributors
------------

Thanks goes to all people that make *torch-pme* possible:

.. image:: https://contrib.rocks/image?repo=lab-cosmo/torch-pme
   :target: https://github.com/lab-cosmo/torch-pme/graphs/contributors

.. |tests| image:: https://github.com/lab-cosmo/torch-pme/workflows/Tests/badge.svg
   :alt: Github Actions Tests Job Status
   :target: https://github.com/lab-cosmo/torch-pme/actions?query=branch%3Amain

.. |codecov| image:: https://codecov.io/gh/lab-cosmo/torch-pme/graph/badge.svg?token=srVKRy7r6m
   :alt: Code coverage
   :target: https://codecov.io/gh/lab-cosmo/torch-pme

.. |docs| image:: https://img.shields.io/badge/📚_documentation-latest-sucess
   :alt: Documentation
   :target: `documentation`_

Owner

Name: Laboratory of Computational Science and Modeling
Login: lab-cosmo
Kind: organization
Location: EPFL - STI - Institute of Materials

Website: http://cosmo.epfl.ch
Twitter: lab_COSMO
Repositories: 44
Profile: https://github.com/lab-cosmo

Public repositories for code developed at the L-COSMO

Citation (CITATION.cff)

cff-version: 1.2.0
message: "If you use torch-pme for your work, please read and cite it as below."
title: >-
  Fast and flexible long-range models for atomistic machine learning
abstract: |
  Most atomistic machine learning (ML) models rely on a locality ansatz and decompose the energy into a sum of short-ranged, atom-centered contributions. This leads to clear limitations when trying to describe problems that are dominated by long-range physical effects—most notably electrostatics. Many approaches have been proposed to overcome these limitations, but efforts to make them efficient and widely available are hampered by the need to incorporate an ad hoc implementation of methods to treat long-range interactions. We develop a framework aiming to bring some of the established algorithms to evaluate non-bonded interactions—including Ewald summation, classical particle–mesh Ewald, and particle–particle/particle–mesh Ewald—into atomistic ML. We provide a reference implementation for PyTorch as well as an experimental one for JAX. Beyond Coulomb and more general long-range potentials, we introduce purified descriptors that disregard the immediate neighborhood of each atom and are more suitable for general long-range ML applications. Our implementations are fast, feature-rich, and modular: They provide an accurate evaluation of physical long-range forces that can be used in the construction of (semi)empirical baseline potentials; they exploit the availability of automatic differentiation to seamlessly combine long-range models with conventional, local ML schemes; and they are sufficiently flexible to implement more complex architectures that use physical interactions as building blocks. We benchmark and demonstrate our torch-pme and jax-pme libraries to perform molecular dynamics simulations, train ML potentials, and evaluate long-range equivariant descriptors of atomic structures.
type: journalArticle
database: Silverchair
date-accessed: 2025-04-08T19:34:56Z
issn: 0021-9606
issue: 14
journal: The Journal of Chemical Physics
pages: 142501
volume: 162
url: https://doi.org/10.1063/5.0251713
authors: 
  - family-names: Loche
    given-names: Philip
  - family-names: Huguenin-Dumittan
    given-names: Kevin K.
  - family-names: Honarmand
    given-names: Melika
  - family-names: Xu
    given-names: Qianjun
  - family-names: Rumiantsev
    given-names: Egor
  - family-names: How
    given-names: Wei Bin
  - family-names: Langer
    given-names: Marcel F.
  - family-names: Ceriotti
    given-names: Michele
editors: 
  - family-names: Loche
    given-names: Philip
  - family-names: Huguenin-Dumittan
    given-names: Kevin K.
  - family-names: Honarmand
    given-names: Melika
  - family-names: Xu
    given-names: Qianjun
  - family-names: Rumiantsev
    given-names: Egor
  - family-names: How
    given-names: Wei Bin
  - family-names: Langer
    given-names: Marcel F.
  - family-names: Ceriotti
    given-names: Michele
recipients: 
  - family-names: Loche
    given-names: Philip
  - family-names: Huguenin-Dumittan
    given-names: Kevin K.
  - family-names: Honarmand
    given-names: Melika
  - family-names: Xu
    given-names: Qianjun
  - family-names: Rumiantsev
    given-names: Egor
  - family-names: How
    given-names: Wei Bin
  - family-names: Langer
    given-names: Marcel F.
  - family-names: Ceriotti
    given-names: Michele
translators: 
  - family-names: Loche
    given-names: Philip
  - family-names: Huguenin-Dumittan
    given-names: Kevin K.
  - family-names: Honarmand
    given-names: Melika
  - family-names: Xu
    given-names: Qianjun
  - family-names: Rumiantsev
    given-names: Egor
  - family-names: How
    given-names: Wei Bin
  - family-names: Langer
    given-names: Marcel F.
  - family-names: Ceriotti
    given-names: Michele
date-published: 2025-04-08
identifiers: 
  - type: doi
    value: 10.1063/5.0251713

GitHub Events

Total

Create event: 60
Release event: 4
Issues event: 39
Watch event: 52
Delete event: 58
Issue comment event: 104
Public event: 1
Push event: 389
Pull request review event: 159
Pull request review comment event: 143
Pull request event: 110
Fork event: 5

Last Year

Create event: 60
Release event: 4
Issues event: 39
Watch event: 52
Delete event: 58
Issue comment event: 104
Public event: 1
Push event: 389
Pull request review event: 159
Pull request review comment event: 143
Pull request event: 110
Fork event: 5

Committers

Last synced: 9 months ago

All Time

Total Commits: 255
Total Committers: 10
Avg Commits per committer: 25.5
Development Distribution Score (DDS): 0.569

Past Year

Commits: 220
Committers: 10
Avg Commits per committer: 22.0
Development Distribution Score (DDS): 0.582

Top Committers

Name	Email	Commits
Philip Loche	p**e@p**e	110
Michele Ceriotti	m**i@g**m	57
E-Rum	r**9@i**u	41
Qianjun Xu	9****X	15
Kevin Kazuki Huguenin-Dumittan	k**n@g**m	15
kvhuguenin	7****n	7
Marcel	me@s****m	6
dependabot[bot]	4****]	2
Tulga-Erdene Sodjargal	1****n	1
Guillaume Fraux	g**x@e**h	1

Committer Domains (Top 20 + Academic)

epfl.ch: 1 sirmarcel.com: 1 internet.ru: 1 physik.fu-berlin.de: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 34
Total pull requests: 123
Average time to close issues: about 2 months
Average time to close pull requests: 5 days
Total issue authors: 12
Total pull request authors: 8
Average comments per issue: 1.97
Average comments per pull request: 0.93
Merged pull requests: 109
Bot issues: 0
Bot pull requests: 1

Past Year

Issues: 34
Pull requests: 123
Average time to close issues: about 2 months
Average time to close pull requests: 5 days
Issue authors: 12
Pull request authors: 8
Average comments per issue: 1.97
Average comments per pull request: 0.93
Merged pull requests: 109
Bot issues: 0
Bot pull requests: 1

View more stats

Top Authors

Issue Authors

GardevoirX (7)
PicoCentauri (6)
kvhuguenin (4)
YuchiGuo (3)
ceriottm (3)
E-Rum (3)
tulga-rdn (2)
frostedoyster (2)
sirmarcel (1)
EliaStocco (1)
atulcthakur (1)
fbruenig (1)

Pull Request Authors

PicoCentauri (81)
E-Rum (22)
GardevoirX (16)
ceriottm (10)
kvhuguenin (4)
sirmarcel (2)
tulga-rdn (2)
dependabot[bot] (1)

Top Labels

Issue Labels

bug (7) enhancement (4) good first issue (3) question (2) help wanted (2) tests (1)

Pull Request Labels

dependencies (1)

Packages

Total packages: 1
Total downloads:
- pypi 1,895 last-month

Total dependent packages: 0
Total dependent repositories: 0
Total versions: 7
Total maintainers: 2

pypi.org: torch-pme

Particle-mesh based calculations of long-range interactions in PyTorch

Documentation: https://torch-pme.readthedocs.io/
License: bsd-3-clause
Latest release: 0.3.1
published 9 months ago

Versions: 7
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 1,895 Last month

Rankings

Dependent packages count: 10.6%

Average: 35.2%

Dependent repos count: 59.9%

Maintainers (2)

PicoCentauri Luthaf

Last synced: 6 months ago

Dependencies

.github/workflows/build.yml actions

actions/checkout v4 composite
actions/setup-python v5 composite

.github/workflows/docs.yml actions

actions/checkout v4 composite
actions/setup-python v5 composite

.github/workflows/documentation-links.yml actions

readthedocs/actions/preview v1 composite

.github/workflows/lint.yml actions

actions/checkout v4 composite
actions/setup-python v5 composite

.github/workflows/tests.yml actions

actions/checkout v4 composite
actions/setup-python v5 composite
codecov/codecov-action v4 composite

docs/requirements.txt pypi

furo *
sphinx >7.0
sphinx-gallery *
sphinx-toggleprompt *
tomli *

pyproject.toml pypi

torch >=2.3

tests/requirements.txt pypi

ase >=3.23 test
coverage * test
pytest * test
pytest-cov * test
scipy * test
vesin-torch >=0.2.0 test

.github/workflows/release.yml actions

actions/checkout v4 composite
actions/setup-python v5 composite
pypa/gh-action-pypi-publish release/v1 composite
softprops/action-gh-release v2 composite