Split the ASE integration into it's own separate package

Author: Luthaf

.github/workflows/ase-tests.yml

@@ -0,0 +1,60 @@
+name: ASE integration tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    # Check all PR
+
+concurrency:
+  group: ase-tests-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  tests:
+    runs-on: ubuntu-24.04
+    name: ASE
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Setup sccache
+        uses: mozilla-actions/sccache-action@v0.0.9
+        with:
+          version: "v0.10.0"
+
+      - name: Setup sccache environnement variables
+        run: |
+          echo "SCCACHE_GHA_ENABLED=true" >> $GITHUB_ENV
+          echo "RUSTC_WRAPPER=sccache" >> $GITHUB_ENV
+          echo "CMAKE_C_COMPILER_LAUNCHER=sccache" >> $GITHUB_ENV
+          echo "CMAKE_CXX_COMPILER_LAUNCHER=sccache" >> $GITHUB_ENV
+
+      - name: install tests dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install tox coverage
+
+      - name: run tests
+        run: tox -e ase-tests
+        env:
+          PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
+
+      - name: combine Python coverage files
+        shell: bash
+        run: |
+            coverage combine .tox/*/.coverage
+            coverage xml
+
+      - name: upload to codecov.io
+        uses: codecov/codecov-action@v5
+        with:
+          fail_ci_if_error: true
+          files: coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}

AUTHORS

@@ -1,2 +1,4 @@
 Guillaume Fraux
+Philip Loche
 Filippo Bigi
+Qianjun Xu

docs/src/engines/ase.rst

@@ -14,7 +14,7 @@ ASE
 Supported model outputs
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-.. py:currentmodule:: metatomic.torch.ase_calculator
+.. py:currentmodule:: metatomic_ase
 
 - the :ref:`energy <energy-output>`, non-conservative :ref:`forces
   <non-conservative-forces-output>` and :ref:`stress <non-conservative-stress-output>`
@@ -26,16 +26,37 @@ Supported model outputs
 - for non-equivariant architectures like
   `PET <https://docs.metatensor.org/metatrain/latest/architectures/pet.html>`_,
   rotationally-averaged energies, forces, and stresses can be computed using
-  :py:class:`metatomic.torch.ase_calculator.SymmetrizedCalculator`.
+  :py:class:`metatomic_ase.SymmetrizedCalculator`.
 
 How to install the code
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The code is available in the ``metatomic-torch`` package, in the
-:py:class:`metatomic.torch.ase_calculator.MetatomicCalculator` class.
+The code is available in the ``metatomic-ase`` package, which can be installed
+using ``pip install metatomic-ase``.
 
 How to use the code
 ^^^^^^^^^^^^^^^^^^^
 
-See the :ref:`corresponding tutorial <atomistic-tutorial-md>`, and API
-documentation of the :py:class:`MetatomicCalculator` class.
+We offer two ASE calculators: :py:class:`metatomic_ase.MetatomicCalculator` is
+the default one, and support all the features described above, while
+:py:class:`metatomic_ase.SymmetrizedCalculator` is a wrapper around the former
+that allows to compute rotationally-averaged energies, forces, and stresses for
+non-equivariant architectures. Both calculators are designed to be used as
+drop-in replacements for any ASE calculator, and can be used in any ASE
+workflow. You can also check the :ref:`corresponding tutorial
+<atomistic-tutorial-md>`.
+
+.. _ase-integration-api:
+
+API documentation
+-----------------
+
+.. _calculator: https://ase-lib.org/ase/calculators/calculators.html
+
+.. autoclass:: metatomic_ase.MetatomicCalculator
+    :show-inheritance:
+    :members:
+
+.. autoclass:: metatomic_ase.SymmetrizedCalculator
+    :show-inheritance:
+    :members:

docs/src/torch/reference/ase.rst

@@ -1,23 +1,12 @@
 Atomic Simulation Environment (ASE) integration
 ===============================================
 
-.. py:currentmodule:: metatomic.torch
-
-The code in ``metatomic.torch.ase_calculator`` defines a class that
-allows using a :py:class:`AtomisticModel` which predicts the energy and forces of a
-system as an ASE `calculator`_; enabling the use of machine learning interatomic
-potentials to drive calculations compatible with ASE calculators.
-
-Additionally, it allows using arbitrary models with prediction targets which are
-not just the energy, through the
-:py:meth:`ase_calculator.MetatomicCalculator.run_model` function.
-
-.. _calculator: https://ase-lib.org/ase/calculators/calculators.html
-
-.. autoclass:: metatomic.torch.ase_calculator.MetatomicCalculator
-    :show-inheritance:
-    :members:
-
-.. autoclass:: metatomic.torch.ase_calculator.SymmetrizedCalculator
-    :show-inheritance:
-    :members:
+The integration of metatomic with the Atomic Simulation Environment (ASE) was
+moved into it's own package, ``metatomic-ase``, which is available on PyPI. The
+documentation for this package can be found in the :ref:`corresponding section
+of the documentation <ase-integration-api>`.
+
+Both calculators classes are re-exported from the
+``metatomic.torch.ase_calculator`` module for baclwards compatibility, but users
+are encouraged to import them from the ``metatomic_ase`` package instead. The
+old import paths will be removed in a future release.

metatomic-torch/CHANGELOG.md

@@ -28,6 +28,13 @@ a changelog](https://keepachangelog.com/en/1.1.0/) format. This project follows
 - 3-argument `unit_conversion_factor(quantity, from_unit, to_unit)` is
   deprecated; the `quantity` parameter is ignored
 
+- `metatomic.torch.ase_calculator` has been split into a separate
+  `metatomic-ase` package. The code is temporarily re-exported from the old
+  path, but all users are encouraged to update to explicitly requiring
+  `metatomic-ase` as a dependency and changing `from
+  metatomic.torch.ase_calculator import MetatomicCalculator` to `from
+  metatomic_ase import MetatomicCalculator`
+
 ## [Version 0.1.11](https://github.com/metatensor/metatomic/releases/tag/metatomic-torch-v0.1.11) - 2026-02-27
 
 ### Added

pyproject.toml

@@ -78,7 +78,12 @@ ignore = ["B018", "B904"]
 
 [tool.ruff.lint.isort]
 lines-after-imports = 2
-known-first-party = ["metatomic", "metatomic_torchsim", "metatomic_lj_test"]
+known-first-party = [
+    "metatomic",
+    "metatomic_ase",
+    "metatomic_torchsim",
+    "metatomic_lj_test",
+]
 known-third-party = ["torch"]
 
 [tool.ruff.format]

python/examples/2-running-ase-md.py

@@ -42,7 +42,7 @@
 )
 
 # Integration with ASE for metatomic models
-from metatomic.torch.ase_calculator import MetatomicCalculator
+from metatomic_ase import MetatomicCalculator
 
 
 # %%

python/examples/3-atomistic-model-with-nl.py

@@ -59,7 +59,7 @@
     NeighborListOptions,
     System,
 )
-from metatomic.torch.ase_calculator import MetatomicCalculator
+from metatomic_ase import MetatomicCalculator
 
 
 # %%

python/examples/4-profiling.py

@@ -29,7 +29,7 @@
     ModelOutput,
     System,
 )
-from metatomic.torch.ase_calculator import MetatomicCalculator
+from metatomic_ase import MetatomicCalculator
 
 
 # %%

python/metatomic_ase/AUTHORS

@@ -0,0 +1,4 @@
+Guillaume Fraux
+Qianjun Xu
+Filippo Bigi
+Paolo Pegolo