rename package to torch-pme

lab-cosmo · Aug 12, 2024 · 9d94241 · 9d94241
1 parent 12c0e28
commit 9d94241
Show file tree

Hide file tree

Showing 50 changed files with 147 additions and 99 deletions.
diff --git a/.github/workflows/documentation-links.yml b/.github/workflows/documentation-links.yml
@@ -14,4 +14,4 @@ jobs:
     steps:
       - uses: readthedocs/actions/preview@v1
         with:
-          project-slug: meshlode
+          project-slug: torch-pme
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 MeshLODE contributors
+Copyright (c) 2024 torch-pme contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.rst b/README.rst
@@ -1,29 +1,47 @@
-MeshLODE
+torch-pme
 ========
+
 |tests| |codecov| |docs|
 
-Particle-mesh based calculation of Long Distance Equivariants.
+.. marker-introduction
+
+``torch-pme`` enables efficient, auto-differentiable computation of long-range
+interactions in PyTorch. Auto-differentiation is supported for particle *positions*,
+*charges*, and *cell* parameters, allowing not only the automatic computation of forces
+but also enabling applications in machine learning tasks. The library offers classes for
+Particle Mesh Ewald (``PME``), standard ``Ewald``, and non-periodic ``direct`` methods,
+with the flexibility to calculate potentials beyond :math:`1/r` electrostatics,
+including arbitrary order :math:`1/r^p` potentials.
+
+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.
+
+.. _`TorchScriptable`: https://pytorch.org/docs/stable/jit.html
+
+.. marker-documentation
 
 For details, tutorials, and examples, please have a look at our `documentation`_.
 
-.. _`documentation`: https://lab-cosmo.github.io/MeshLODE/latest
+.. _`documentation`: https://lab-cosmo.github.io/torch-pme/latest
 
 .. marker-installation
 
 Installation
 ------------
-You can install *MeshLode* using pip with
+
+You can install *torch-pme* using pip with
 
 .. code-block:: bash
 
-    git clone https://github.com/lab-cosmo/MeshLODE
-    cd MeshLODE
+    git clone https://github.com/lab-cosmo/torch-pme
+    cd torch-pme
     pip install .
 
-You can then ``import meshlode`` and use it in your projects!
+You can then ``import torchpme`` and use it in your projects!
 
 We also provide bindings to `metatensor <https://docs.metatensor.org/latest/>`_ which
-can optionally be installed together and used as ``meshlode.metatensor`` via
+can optionally be installed together and used as ``torchpme.metatensor`` via
 
 .. code-block:: bash
 
@@ -33,28 +51,30 @@ can optionally be installed together and used as ``meshlode.metatensor`` via
 
 Having problems or ideas?
 -------------------------
-Having a problem with MeshLODE? Please let us know by `submitting an issue
-<https://github.com/lab-cosmo/MeshLODE/issues>`_.
+
+Having a problem with torch-pme? Please let us know by `submitting an issue
+<https://github.com/lab-cosmo/torch-pme/issues>`_.
 
 Submit new features or bug fixes through a `pull request
-<https://github.com/lab-cosmo/MeshLODE/pulls>`_.
+<https://github.com/lab-cosmo/torch-pme/pulls>`_.
 
 .. marker-contributing
 
 Contributors
 ------------
-Thanks goes to all people that make MeshLODE possible:
 
-.. image:: https://contrib.rocks/image?repo=lab-cosmo/MeshLODE
-   :target: https://github.com/lab-cosmo/MeshLODE/graphs/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/MeshLODE/workflows/Tests/badge.svg
+.. |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/MeshLODE/actions?query=workflow%3ATests
+   :target: https://github.com/lab-cosmo/torch-pme/actions?query=workflow%3ATests
 
-.. |codecov| image:: https://codecov.io/gh/lab-cosmo/MeshLODE/graph/badge.svg?token=srVKRy7r6m
+.. |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/MeshLODE
+   :target: https://codecov.io/gh/lab-cosmo/torch-pme
 
 .. |docs| image:: https://img.shields.io/badge/documentation-latest-sucess
    :alt: Documentation

diff --git a/docs/src/conf.py b/docs/src/conf.py
@@ -4,7 +4,7 @@
 
 import tomli  # Replace by tomllib from std library once docs are build with Python 3.11
 
-import meshlode
+import torchpme
 
 
 ROOT = os.path.abspath(os.path.join("..", ".."))
@@ -24,7 +24,7 @@
 copyright = f"{datetime.now().date().year}, {author}"
 
 # The full version, including alpha/beta/rc tags
-release = meshlode.__version__
+release = torchpme.__version__
 
 
 # -- General configuration ---------------------------------------------------
@@ -45,8 +45,8 @@
     "examples_dirs": ["../../examples"],
     "gallery_dirs": ["examples"],
     "min_reported_time": 60,
-    "reference_url": {"meshlode": None},
-    "prefer_full_module": ["meshlode"],
+    "reference_url": {"torchpme": None},
+    "prefer_full_module": ["torchpme"],
 }
 
 autoclass_content = "both"

diff --git a/docs/src/index.rst b/docs/src/index.rst
@@ -1,7 +1,9 @@
-MeshLODE
-########
+torch-pme
+#########
 
-Particle-mesh based calculation of Long Distance Equivariants.
+.. include:: ../../README.rst
+    :start-after: marker-introduction
+    :end-before: marker-documentation
 
 .. toctree::
    :hidden:

diff --git a/docs/src/references/base.rst b/docs/src/references/base.rst
@@ -5,10 +5,10 @@ Base classes
 
 General Base classes all calculators build on top.
 
-.. automodule:: meshlode.calculators.base
+.. automodule:: torchpme.calculators.base
     :members:
     :undoc-members:
 
-.. automodule:: meshlode.metatensor.base
+.. automodule:: torchpme.metatensor.base
     :members:
     :undoc-members:
diff --git a/docs/src/references/calculators/directpotential.rst b/docs/src/references/calculators/directpotential.rst
@@ -1,6 +1,6 @@
 DirectPotential
 ###############
 
-.. autoclass:: meshlode.DirectPotential
+.. autoclass:: torchpme.DirectPotential
     :members:
     :undoc-members:
diff --git a/docs/src/references/calculators/ewaldpotential.rst b/docs/src/references/calculators/ewaldpotential.rst
@@ -1,6 +1,6 @@
 EwaldPotential
 ##############
 
-.. autoclass:: meshlode.EwaldPotential
+.. autoclass:: torchpme.EwaldPotential
     :members:
     :undoc-members:
diff --git a/docs/src/references/calculators/index.rst b/docs/src/references/calculators/index.rst
@@ -3,9 +3,9 @@
 Calculators
 ###########
 
-Below is a list of all calculators available. Calculators are the core of MeshLODE and
-are algorithms for transforming Cartesian coordinates into representations suitable for
-machine learning.
+Below is a list of all calculators available. Calculators are the core of ``torch-pme``
+and are algorithms for transforming Cartesian coordinates into representations suitable
+for machine learning.
 
 Our calculator API follows the `rascaline <https://luthaf.fr/rascaline>`_ API and coding
 guidelines to promote usability and interoperability with existing workflows.
@@ -14,6 +14,19 @@ Calculators return the representations as a :py:obj:`List` of :py:class:`torch.T
 We also provide a return values as a :py:class:`metatensor.TensorMap` in
 :ref:`metatensor`.
 
+.. note::
+
+   All calculators compute the potential, from which the "atom-wise" energy :math:`E`
+   can be determined by multiplying the potential :math:`V_i` with the charges :math:`q`
+   and dividing by 2.
+
+   .. math::
+
+      E = \frac{1}{2} q_i \cdot V_i
+
+Implemented Calculators
+-----------------------
+
 .. toctree::
    :maxdepth: 1
    :glob:

diff --git a/docs/src/references/calculators/pmepotential.rst b/docs/src/references/calculators/pmepotential.rst
@@ -1,6 +1,6 @@
 PMEPotential
 ############
 
-.. autoclass:: meshlode.PMEPotential
+.. autoclass:: torchpme.PMEPotential
     :members:
     :undoc-members:
diff --git a/docs/src/references/index.rst b/docs/src/references/index.rst
@@ -3,10 +3,9 @@
 API reference
 =============
 
-The main references for public functions and classes inside ``MeshLODE``. Most of the
+The main references for public functions and classes inside ``torch-pme``. Most of the
 function contain a little example. If you are looking for recipes how to stack the
-functions toegther you might take a look at the :ref:`userdoc-how-to` section.
-
+functions together you might take a look at the :ref:`userdoc-how-to` section.
 
 .. toctree::
     :maxdepth: 1

diff --git a/docs/src/references/lib/fourier_convolution.rst b/docs/src/references/lib/fourier_convolution.rst
@@ -1,6 +1,6 @@
 Fourier Convolution
 ===================
 
-.. autoclass:: meshlode.lib.FourierSpaceConvolution
+.. autoclass:: torchpme.lib.FourierSpaceConvolution
     :members:
     :undoc-members:
diff --git a/docs/src/references/lib/kvectors.rst b/docs/src/references/lib/kvectors.rst
@@ -1,6 +1,6 @@
 Kvectors
 ========
 
-.. automodule:: meshlode.lib.kvectors
+.. automodule:: torchpme.lib.kvectors
     :members:
     :undoc-members:
diff --git a/docs/src/references/lib/mesh_interpolator.rst b/docs/src/references/lib/mesh_interpolator.rst
@@ -1,6 +1,6 @@
 Mesh Interpolator
 =================
 
-.. autoclass:: meshlode.lib.MeshInterpolator
+.. autoclass:: torchpme.lib.MeshInterpolator
     :members:
     :undoc-members:
diff --git a/docs/src/references/metatensor/directpotential.rst b/docs/src/references/metatensor/directpotential.rst
@@ -1,6 +1,6 @@
 DirectPotential
 ###############
 
-.. autoclass:: meshlode.metatensor.DirectPotential
+.. autoclass:: torchpme.metatensor.DirectPotential
     :members: compute, forward
     :undoc-members:
diff --git a/docs/src/references/metatensor/ewaldpotential.rst b/docs/src/references/metatensor/ewaldpotential.rst
@@ -1,6 +1,6 @@
 EwaldPotential
 ##############
 
-.. autoclass:: meshlode.metatensor.EwaldPotential
+.. autoclass:: torchpme.metatensor.EwaldPotential
     :members: compute, forward
     :undoc-members:
diff --git a/docs/src/references/metatensor/index.rst b/docs/src/references/metatensor/index.rst
@@ -3,7 +3,7 @@
 Metatensor Bindings
 ###################
 
-MeshLODE calculators returning representations as :py:class:`metatensor.TensorMap`.
+torch-pme calculators returning representations as :py:class:`metatensor.TensorMap`.
 For using these bindings you need to install the ``metatensor.torch`` optional
 dependencies.
 
@@ -13,6 +13,9 @@ dependencies.
 
 For a plain :py:class:`torch.Tensor` refer to :ref:`calculators`.
 
+Implemented Calculators
+-----------------------
+
 .. toctree::
    :maxdepth: 1
    :glob:

diff --git a/docs/src/references/metatensor/pmepotential.rst b/docs/src/references/metatensor/pmepotential.rst
@@ -1,6 +1,6 @@
 PMEPotential
 ############
 
-.. autoclass:: meshlode.metatensor.PMEPotential
+.. autoclass:: torchpme.metatensor.PMEPotential
     :members: compute, forward
     :undoc-members:
diff --git a/examples/README.rst b/examples/README.rst
@@ -4,7 +4,7 @@ Examples
 ========
 
 This section list introductory examples and recipes to the various classes and functions
-of ``MeshLODE``. For details on the API specification of the functions take a look at
+of ``torch-pme``. For details on the API specification of the functions take a look at
 the :ref:`userdoc-reference` section.
 
 For running the all examples install with the ``examples`` and ``metatensor`` optional

diff --git a/examples/charges_example.py b/examples/charges_example.py
@@ -31,7 +31,7 @@
 from metatensor.torch.atomistic import NeighborListOptions, System
 from vesin import NeighborList
 
-import meshlode
+import torchpme
 
 
 # %%
@@ -67,7 +67,7 @@
 # *1* for electrostatic interactions between the two atoms. This calculator
 # will be used to *compute* the potential energy of the system.
 
-calculator = meshlode.PMEPotential(exponent=1.0)
+calculator = torchpme.PMEPotential(exponent=1.0)
 
 # %%
 # Single Charge Channel
@@ -158,7 +158,7 @@
 # Next, we will perform the same exercise with the Metatensor interface. This involves
 # creating a new calculator with the metatensor interface.
 
-calculator_metatensor = meshlode.metatensor.PMEPotential(exponent=1.0)
+calculator_metatensor = torchpme.metatensor.PMEPotential(exponent=1.0)
 
 # %%
 # Computation with metatensor involves using Metatensor's :py:class:`System

diff --git a/examples/library-tutorial.py b/examples/library-tutorial.py
@@ -2,7 +2,7 @@
 Basic Tutorial for Library functions
 ====================================
 This examples provides an illustration of the functioning of the underlaying library
-functions of ``meshlode`` and the construction LODE descriptors (`Grisafi 2019
+functions of ``torchpme`` and the construction LODE descriptors (`Grisafi 2019
 <https://doi.org/10.1063/1.5128375>`__, `Grisafi 2021
 <https://doi.org/10.1039/D0SC04934D>`__, `Huguenin 2023
 <10.1021/acs.jpclett.3c02375>`__). It builds the (simple and weighted) atom density for
@@ -19,7 +19,7 @@
 import torch
 from metatensor.torch.atomistic import System
 
-import meshlode
+import torchpme
 
 
 torch.set_default_dtype(torch.float64)
@@ -90,7 +90,7 @@ def sliceplot(mesh, sz=12, cmap="viridis", vmin=None, vmax=None):
 # list of atom weights to yield the mesh values.
 #
 
-interpol = meshlode.lib.mesh_interpolator.MeshInterpolator(
+interpol = torchpme.lib.mesh_interpolator.MeshInterpolator(
     system.cell, torch.tensor([16, 16, 16]), interpolation_order=3
 )
 
@@ -127,7 +127,7 @@ def sliceplot(mesh, sz=12, cmap="viridis", vmin=None, vmax=None):
 # be easily extended to compute an arbitrary filter
 #
 
-fsc = meshlode.lib.fourier_convolution.FourierSpaceConvolution()
+fsc = torchpme.lib.fourier_convolution.FourierSpaceConvolution()
 
 # %%
 # plain atomic_smearing
@@ -167,7 +167,7 @@ def sliceplot(mesh, sz=12, cmap="viridis", vmin=None, vmax=None):
 # ``interpolation_order``, if wanted.
 #
 
-interpol_slice = meshlode.lib.mesh_interpolator.MeshInterpolator(
+interpol_slice = torchpme.lib.mesh_interpolator.MeshInterpolator(
     system.cell, torch.tensor([16, 16, 16]), interpolation_order=4
 )