Create an empty metatomic-core package

.github/workflows/python-tests.yml

@@ -0,0 +1,96 @@
+name: Python tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    # Check all PR
+
+concurrency:
+  group: python-tests-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  python-tests:
+    runs-on: ${{ matrix.os }}
+    name: ${{ matrix.os }} / Python ${{ matrix.python-version }} / Torch ${{ matrix.torch-version }}
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-24.04
+            python-version: "3.10"
+            torch-version: "2.3"
+            numpy-version-pin: "<2.0"
+            # Do not run docs-tests with python 3.10 since torch-sim-atomistic
+            # is not available for this version of python
+            tox-envs: lint,torch-tests
+          - os: ubuntu-24.04
+            python-version: "3.10"
+            torch-version: "2.12"
+            # See above
+            tox-envs: lint,torch-tests
+          - os: ubuntu-24.04
+            # TorchScript is no longer supported in Python 3.14
+            # so we keep a test with 3.13 to make sure this doesn't break
+            python-version: "3.13"
+            torch-version: "2.12"
+            tox-envs: lint,torch-tests,docs-tests
+          - os: ubuntu-24.04
+            python-version: "3.14"
+            torch-version: "2.12"
+            tox-envs: lint,torch-tests,docs-tests
+          - os: macos-15
+            python-version: "3.14"
+            torch-version: "2.12"
+            tox-envs: lint,torch-tests,docs-tests
+          - os: windows-2022
+            python-version: "3.14"
+            torch-version: "2.12"
+            tox-envs: lint,torch-tests,docs-tests
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: setup rust
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: stable
+
+      - name: Cache Rust dependencies
+        uses: Leafwing-Studios/cargo-cache@v2.6.1
+        with:
+          sweep-cache: true
+
+      - name: Setup sccache
+        if: ${{ !env.ACT }}
+        uses: mozilla-actions/sccache-action@v0.0.10
+        with:
+          version: "v0.10.0"
+
+      - name: setup MSVC command prompt
+        uses: ilammy/msvc-dev-cmd@v1
+
+      - name: Setup sccache environnement variables
+        if: ${{ !env.ACT }}
+        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 ${{ matrix.tox-envs }}
+        env:
+          PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
+          METATOMIC_TESTS_TORCH_VERSION: ${{ matrix.torch-version }}

.github/workflows/torch-tests.yml

@@ -13,81 +13,86 @@ concurrency:
 jobs:
   tests:
     runs-on: ${{ matrix.os }}
-    name: ${{ matrix.os }} / Python ${{ matrix.python-version }} / Torch ${{ matrix.torch-version }}
+    name: ${{ matrix.os }} / Torch ${{ matrix.torch-version }}${{ matrix.extra-name }}
+    container: ${{ matrix.container }}
     strategy:
       matrix:
         include:
           - os: ubuntu-24.04
-            python-version: "3.10"
-            torch-version: "2.3"
-          - os: ubuntu-24.04
-            python-version: "3.10"
             torch-version: "2.12"
-          - os: ubuntu-24.04
-            # Keep a building with Python 3.13 since TorchScript is deprecated
-            # in Python 3.14
-            python-version: "3.13"
-            torch-version: "2.12"
-          - os: ubuntu-24.04
             python-version: "3.14"
-            torch-version: "2.12"
+            cargo-test-flags: --release
+            do-valgrind: true
+
+          # check the build on a stock Ubuntu 22.04, which uses cmake 3.22
+          - os: ubuntu-24.04
+            container: ubuntu:22.04
+            extra-name: ", cmake 3.22"
+            torch-version: "2.3"
+            cargo-test-flags: ""
+
           - os: macos-15
-            python-version: "3.14"
             torch-version: "2.12"
-          - os: windows-2022
             python-version: "3.14"
+            cargo-test-flags: --release
+
+          - os: windows-2022
             torch-version: "2.12"
+            python-version: "3.14"
+            cargo-test-flags: --release
     steps:
+      - name: install dependencies in container
+        if: matrix.container == 'ubuntu:22.04'
+        run: |
+          apt update
+          apt install -y software-properties-common
+          add-apt-repository ppa:deadsnakes/ppa
+          apt install -y cmake make gcc g++ git curl python3.10 python3.10-venv
+
+          update-alternatives --install /usr/local/bin/python python /usr/bin/python3.10 1
+
       - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - name: setup Python
-        uses: actions/setup-python@v6
+      - name: Configure git safe directory
+        if: matrix.container == 'ubuntu:22.04'
+        run: git config --global --add safe.directory /__w/metatomic/metatomic
+
+      - name: setup rust
+        uses: dtolnay/rust-toolchain@master
         with:
-          python-version: ${{ matrix.python-version }}
+          toolchain: stable
+
+      - name: Cache Rust dependencies
+        uses: Leafwing-Studios/cargo-cache@v2.6.1
+        with:
+          sweep-cache: true
+
+      - name: install valgrind
+        if: matrix.do-valgrind
+        run: |
+          sudo apt-get install -y valgrind
 
       - name: Setup sccache
+        if: ${{ !env.ACT }}
         uses: mozilla-actions/sccache-action@v0.0.10
         with:
           version: "v0.10.0"
 
-      - name: setup MSVC command prompt
-        uses: ilammy/msvc-dev-cmd@v1
-
       - name: Setup sccache environnement variables
+        if: ${{ !env.ACT }}
         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 Python tests
-        run: tox -e lint,torch-tests,docs-tests
+      - name: run TorchScript C++ tests
+        run: cargo test --package metatomic-torch ${{ matrix.cargo-test-flags }}
         env:
+          # Use the CPU only version of torch when building/running the code
           PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
           METATOMIC_TESTS_TORCH_VERSION: ${{ matrix.torch-version }}
-
-      - name: run C++ tests
-        run: tox -e torch-tests-cxx,torch-install-tests-cxx
-        env:
-          PIP_EXTRA_INDEX_URL: https://download.pytorch.org/whl/cpu
-          METATOMIC_TESTS_TORCH_VERSION: ${{ matrix.torch-version }}
-
-      - name: combine Python coverage files
-        shell: bash
-        run: |
-            coverage combine .tox/*/.coverage
-            coverage xml
-
-      - name: upload to codecov.io
-        uses: codecov/codecov-action@v6
-        with:
-          fail_ci_if_error: true
-          files: coverage.xml
-          token: ${{ secrets.CODECOV_TOKEN }}
+          CXXFLAGS: ${{ matrix.cxx-flags }}
+          RUST_BACKTRACE: full

.gitignore

@@ -7,3 +7,6 @@ build/
 htmlcov/
 .coverage*
 coverage.xml
+
+Cargo.lock
+target/

CONTRIBUTING.rst

@@ -16,6 +16,10 @@ on metatomic:
 
 - **git**: the software we use for version control of the source code. See
   https://git-scm.com/downloads for installation instructions.
+- **the rust compiler**: you will need both ``rustc`` (the compiler) and
+  ``cargo`` (associated build tool). You can install both using `rustup`_, or
+  use a version provided by your operating system. We need at least Rust version
+  1.74 to build metatomic.
 - **Python**: you can install ``Python`` and ``pip`` on your operating system.
   We require a Python version of at least 3.9.
 - **tox**: a Python test runner, see https://tox.readthedocs.io/en/latest/. You
@@ -28,17 +32,21 @@ not have to interact with them directly:
 - **a C++ compiler** we need a compiler supporting C++11. GCC >= 7, clang >= 5
   and MSVC >= 19 should all work, although MSVC is not yet tested continuously.
 
+.. _rustup: https://rustup.rs
+.. _`cargo` : https://doc.rust-lang.org/cargo/
+.. _tox: https://tox.readthedocs.io/en/latest
+
 .. admonition:: Optional tools
 
   Depending on which part of the code you are working on, you might experience a
-  lot of time spent re-compiling code, even if you did not directly change them.
-  For faster builds (and in turn faster tests), you can use compiler cache, like
-  `sccache`_ or the classic `ccache`_ to reduce the recompilation of unchanged
-  source code. To do this, you should install and configure one of these tools
-  (we suggest ``sccache`` since it also supports Rust), and then configure
-  ``cmake`` and ``cargo`` to use them by setting environnement variables. On
-  Linux and macOS, you should set the following (look up how to do set
-  environment variable with your shell):
+  lot of time spend re-compiling Rust or C++ code, even if you did not change
+  them. If you'd like faster builds (and in turn faster tests), you can use
+  `sccache`_ or the classic `ccache`_ to only re-run the compiler if the
+  corresponding source code changed. To do this, you should install and configure
+  one of these tools (we suggest sccache since it also supports Rust), and then
+  configure cmake and cargo to use them by setting environnement variables. On
+  Linux and macOS, you should set the following (look up how to do set environment
+  variable with your shell):
 
   .. code-block:: bash
 
@@ -88,32 +96,70 @@ changes:
 Running tests
 -------------
 
-The continuous integration pipeline is based on `tox`_. You can run all tests
+The continuous integration pipeline is based on `cargo`_. You can run all tests
 with:
 
 .. code-block:: bash
 
     cd <path/to/metatomic/repo>
-    tox
+    cargo test  # or cargo test --release to run tests in release mode
 
-These are exactly the same tests that will be performed online in our Github CI
+These are exactly the same tests that will be performed online in our GitHub CI
 workflows. You can also run only a subset of tests with one of these commands:
 
+- ``cargo test`` runs everything
+
+- ``cargo test --package=metatomic-torch`` to run the C++ TorchScript tests only;
+
+  - ``cargo test --test=run-torch-tests`` will run the unit tests for the
+    TorchScript C++ extension;
+  - ``cargo test --test=check-cxx-install`` will build the C++ TorchScript
+    extension, install it and then try to build a basic project depending on
+    this extension with CMake;
+
+- ``cargo test --package=metatomic-python`` (or ``tox`` directly, see below) to
+  run Python tests only;
+- ``cargo test --lib`` to run unit tests;
+- ``cargo test --doc`` to run documentation tests;
+- ``cargo bench --test`` compiles and run the benchmarks once, to quickly ensure
+  they still work.
+
+You can add some flags to any of above commands to further refine which tests
+should run:
+
+- ``--release`` to run tests in release mode (default is to run tests in debug mode)
+- ``-- <filter>`` to only run tests whose name contains filter, for example ``cargo test -- system``
+
+Also, you can run individual Python tests using `tox`_ if you wish to run a
+subset of Python tests, for example:
+
 .. code-block:: bash
 
     tox -e lint                           # check files for formatting errors
 
     tox -e torch-tests                    # unit tests for metatomic-torch, in Python
-    tox -e torch-tests-cxx                # unit tests for metatomic-torch, in C++
-    tox -e torch-install-tests-cxx        # testing that the C++ code is a valid CMake package
+    tox -e ase-tests                      # unit tests for metatomic-ase, in Python
+    tox -e torchsim-tests                 # unit tests for metatomic-torchsim, in Python
     tox -e docs-tests                     # doctests (checking inline examples) for all packages
-    tox -e lint                           # code style
 
     tox -e format                         # format all files
 
-The last command ``tox -e format`` will use ``tox`` to do actual formatting
-instead of just checking it, you can use this to automatically fix some of the
-issues detected by ``tox -e lint``.
+The last command ``tox -e format`` will use tox to do actual formatting instead
+of just checking it, you can use to automatically fix some of the issues
+detected by ``tox -e lint``.
+
+You can run only a subset of the tests with ``tox -e tests -- <test/file.py>``,
+replacing ``<test/file.py>`` with the path to the files you want to test, e.g.
+``tox -e tests -- python/tests/operations/abs.py``.
+
+To get the release build for ``tox`` runs, set the environment variable.
+
+.. code-block:: bash
+
+    METATOMIC_BUILD_TYPE="release" tox -e torch-tests
+
+This corresponds to running ``cargo test --package-metatensor-python --release``
+but on the subset of interest.
 
 You can run only a subset of the tests with ``tox -e torch-tests --
 <test/file.py>``, replacing ``<test/file.py>`` with the path to the files you

Cargo.toml

@@ -0,0 +1,8 @@
+[workspace]
+resolver = "2"
+
+members = [
+    "metatomic-core",
+    "metatomic-torch",
+    "python",
+]

docs/src/devdoc/get-started.rst

@@ -0,0 +1,6 @@
+.. _devdoc-get-started:
+
+Getting started
+===============
+
+.. include:: ../../../CONTRIBUTING.rst