Split ase integration into a separate metatomic-ase package

.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

python/metatomic_ase/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to metatomic-ase are documented here, following the
+[keep a changelog](https://keepachangelog.com/en/1.1.0/) format. This project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!-- Possible sections for each package:
+### Added
+
+### Fixed
+
+### Changed
+
+### Removed
+-->
+
+## [Unreleased](https://github.com/metatensor/metatomic/)
+
+- `metatomic-ase` is now a standalone package, containing the ASE integration
+  for metatomic models.

python/metatomic_ase/LICENSE

@@ -0,0 +1 @@
+../../LICENSE

python/metatomic_ase/MANIFEST.in

@@ -0,0 +1,2 @@
+include AUTHORS
+include git_version_info

python/metatomic_ase/README.md

@@ -0,0 +1,33 @@
+# `metatomic-ase`
+
+[ASE](https://ase-lib.org/) integration for metatomic models.
+
+This package allows you to use metatomic models as ASE
+[`Calculator`](https://ase-lib.org/ase/calculators/calculators.html), integrating with any workflow based on ASE.
+
+## Installation
+
+```bash
+pip install metatomic-ase
+```
+
+## Usage
+
+```python
+import ase.io
+from metatomic_ase import MetatomicCalculator
+
+# load atoms
+atoms = ase.io.read("...")
+
+# create a calculator from a saved .pt model
+atoms.calc = MetatomicCalculator("model.pt", device="cuda")
+
+# from here, all the normal ASE functionality is available
+print(atoms.get_forces())
+print(atoms.get_potential_energies())
+```
+
+For full documentation, see the [ASE engine
+page](https://docs.metatensor.org/metatomic/latest/engines/ase.html) in
+metatomic documentation.

python/metatomic_ase/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "metatomic-ase"
+dynamic = ["version", "authors", "dependencies"]
+requires-python = ">=3.10"
+
+readme = "README.md"
+license = "BSD-3-Clause"
+description = "ASE interface to use metatomic atomistic machine learning models"
+
+keywords = ["machine learning", "molecular modeling", "ase"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Operating System :: POSIX",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+homepage = "https://docs.metatensor.org/metatomic/latest/engines/ase.html"
+documentation = "https://docs.metatensor.org/metatomic/latest/engines/ase.html"
+repository = "https://github.com/metatensor/metatomic/blob/main/python/metatomic_ase"
+changelog = "https://github.com/metatensor/metatomic/blob/main/python/metatomic_ase/CHANGELOG.md"
+
+### ======================================================================== ###
+[build-system]
+requires = [
+    "setuptools >=77",
+    "packaging >=23",
+]
+build-backend = "setuptools.build_meta"
+
+### ======================================================================== ###
+[tool.pytest.ini_options]
+python_files = ["*.py"]
+testpaths = ["tests"]
+filterwarnings = [
+    "error",
+    "ignore:`torch.jit.script` is deprecated. Please switch to `torch.compile` or `torch.export`:DeprecationWarning",
+    "ignore:`torch.jit.script_method` is deprecated. Please switch to `torch.compile` or `torch.export`:DeprecationWarning",
+    "ignore:`torch.jit.save` is deprecated. Please switch to `torch.export`:DeprecationWarning",
+    "ignore:`torch.jit.load` is deprecated. Please switch to `torch.export`:DeprecationWarning",
+    "ignore:.*vesin.metatomic was only tested with metatomic.torch >=0.1.3,<0.2.*:UserWarning",
+]