Implement a C API for metatomic

.github/workflows/build-wheels.yml

@@ -101,8 +101,17 @@ jobs:
           CIBW_BUILD_VERBOSITY: 1
           CIBW_MANYLINUX_X86_64_IMAGE: gcc11-manylinux_2_28_x86_64
           CIBW_MANYLINUX_AARCH64_IMAGE: gcc11-manylinux_2_28_aarch64
+          # METATOMIC_NO_LOCAL_DEPS is set to 1 when building a tag of
+          # metatomic-torch, which will force to use the version of
+          # metatomic-core already released on PyPI. Otherwise, this will use
+          # the version of metatomic-core from git checkout (in case there are
+          # unreleased breaking changes).
+          #
+          # This means that when releasing a breaking change in metatomic-core,
+          # the full release should be available on PyPI before pushing the new
+          # metatomic-torch tag.
           CIBW_ENVIRONMENT: >
-            METATOMIC_NO_LOCAL_DEPS=1
+            METATOMIC_NO_LOCAL_DEPS=${{ startsWith(github.ref, 'refs/tags/metatomic-torch-v') && '1' || '0' }}
             METATOMIC_TORCH_BUILD_WITH_TORCH_VERSION=${{ matrix.torch-version }}.*
             PIP_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cpu
             MACOSX_DEPLOYMENT_TARGET=11
@@ -356,9 +365,9 @@ jobs:
 
       - name: setup libmetatensor
         run: |
-          curl --location -O https://github.com/metatensor/metatensor/releases/download/metatensor-core-v0.2.3/metatensor-core-cxx-0.2.3.tar.gz
-          tar xf metatensor-core-cxx-0.2.3.tar.gz
-          cmake -B build-metatensor -S metatensor-core-cxx-0.2.3 \
+          curl --location -O https://github.com/metatensor/metatensor/releases/download/metatensor-core-v0.2.4/metatensor-core-cxx-0.2.4.tar.gz
+          tar xf metatensor-core-cxx-0.2.4.tar.gz
+          cmake -B build-metatensor -S metatensor-core-cxx-0.2.4 \
                 -DMETATENSOR_INSTALL_BOTH_STATIC_SHARED=OFF \
                 -DCMAKE_INSTALL_PREFIX=$CMAKE_PREFIX_PATH \
                 -DCMAKE_BUILD_TYPE=Debug

.github/workflows/python-tests.yml

@@ -0,0 +1,91 @@
+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.13"
+            # 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.13"
+            tox-envs: lint,torch-tests,docs-tests
+          - os: ubuntu-24.04
+            python-version: "3.14"
+            torch-version: "2.13"
+            tox-envs: lint,torch-tests,docs-tests
+          - os: macos-15
+            python-version: "3.14"
+            torch-version: "2.13"
+            tox-envs: lint,torch-tests,docs-tests
+          - os: windows-2022
+            python-version: "3.14"
+            torch-version: "2.13"
+            tox-envs: lint,torch-tests,docs-tests
+    steps:
+      - uses: actions/checkout@v7
+        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: 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/rust-tests.yml

@@ -0,0 +1,189 @@
+name: Rust tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    # Check all PR
+
+concurrency:
+  group: rust-tests-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+jobs:
+  rust-tests:
+    name: ${{ matrix.os }} / Rust ${{ matrix.rust-version }}${{ matrix.extra-name }}
+    runs-on: ${{ matrix.os }}
+    container: ${{ matrix.container }}
+    defaults:
+      run:
+        shell: "bash"
+    env:
+      CMAKE_CXX_COMPILER: ${{ matrix.cxx }}
+      CMAKE_C_COMPILER: ${{ matrix.cc }}
+      CMAKE_GENERATOR: ${{ matrix.cmake-generator }}
+    strategy:
+      matrix:
+        include:
+          # test our MSRV
+          - os: ubuntu-24.04
+            rust-version: 1.88
+            rust-target: x86_64-unknown-linux-gnu
+            cxx: g++
+            cc: gcc
+            cargo: cargo
+            cmake-generator: Unix Makefiles
+
+          # check the build on a stock Ubuntu 22.04, which uses cmake 3.22, and
+          # using cargo/rustc from APT
+          - os: ubuntu-24.04
+            rust-version: from APT
+            container: ubuntu:22.04
+            rust-target: x86_64-unknown-linux-gnu
+            extra-name: ", cmake 3.22"
+            cxx: g++
+            cc: gcc
+            cargo: cargo-1.89
+            cmake-generator: Unix Makefiles
+
+          - os: macos-15
+            rust-version: stable
+            rust-target: aarch64-apple-darwin
+            cxx: clang++
+            cc: clang
+            cargo: cargo
+            cmake-generator: Unix Makefiles
+
+          - os: windows-2022
+            rust-version: stable
+            rust-target: x86_64-pc-windows-msvc
+            extra-name: " / MSVC"
+            cxx: cl.exe
+            cc: cl.exe
+            cargo: cargo
+            cmake-generator: Visual Studio 17 2022
+
+          - os: windows-2022
+            rust-version: stable
+            rust-target: x86_64-pc-windows-gnu
+            extra-name: " / MinGW"
+            cxx: g++.exe
+            cc: gcc.exe
+            cargo: cargo
+            cmake-generator: MinGW Makefiles
+    steps:
+      - name: install dependencies in container
+        if: matrix.container == 'ubuntu:22.04'
+        run: |
+          apt update
+          apt install -y software-properties-common
+          apt install -y cmake make gcc g++ git curl python3-venv cargo-1.89
+
+          # for some reason, cargo-1.89 from APT tries to find `rustdoc` and
+          # not `rustdoc-1.89`, so we force it to use the correct one
+          echo "RUSTDOC=rustdoc-1.89" >> "$GITHUB_ENV"
+
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - 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
+        if: matrix.container == null
+        with:
+          toolchain: ${{ matrix.rust-version }}
+          target: ${{ matrix.rust-target }}
+
+      - name: setup Python
+        uses: actions/setup-python@v6
+        if: matrix.container == null
+        with:
+          python-version: "3.14"
+
+      - name: install valgrind
+        if: matrix.do-valgrind
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y valgrind
+
+      - name: Setup sccache
+        if: ${{ !env.ACT }}
+        uses: mozilla-actions/sccache-action@v0.0.10
+        with:
+          version: "v0.15.0"
+
+      - 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: run tests
+        env:
+          RUST_BACKTRACE: full
+        run: |
+          ${{ matrix.cargo }} test --package metatomic-core --target ${{ matrix.rust-target }}
+
+      - name: check that the header was already up to date
+        run: |
+          git diff --exit-code
+
+  # check that the C API declarations are correctly documented and used
+  prevent-bitrot:
+    runs-on: ubuntu-24.04
+    name: check C API declarations
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.14"
+
+      - name: install python dependencies
+        run: |
+          pip install pycparser
+
+      - name: check that C API functions are all documented
+        run: |
+          python scripts/check-c-api-docs.py
+
+  # make sure no debug print stays in the code
+  check-debug-prints:
+    runs-on: ubuntu-24.04
+    name: check leftover debug print
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: install ripgrep
+        run: |
+          wget https://github.com/BurntSushi/ripgrep/releases/download/13.0.0/ripgrep-13.0.0-x86_64-unknown-linux-musl.tar.gz
+          tar xf ripgrep-13.0.0-x86_64-unknown-linux-musl.tar.gz
+          echo "$(pwd)/ripgrep-13.0.0-x86_64-unknown-linux-musl" >> $GITHUB_PATH
+
+      - name: check for leftover dbg!
+        run: |
+          # use ripgrep (rg) to check for instances of `dbg!` in rust files.
+          # rg will return 1 if it fails to find a match, so we invert it again
+          # with the `!` builtin to get the error/success in CI
+
+          ! rg "dbg!" --type=rust --quiet
+
+      - name: check for leftover \#include <iostream>
+        run: |
+          ! rg "<iostream>" --iglob "\!metatomic-core/tests/cpp/external/catch/catch.hpp" --quiet
+
+      - name: check for leftover std::cout
+        run: |
+          ! rg "cout" --iglob "\!metatomic-core/tests/cpp/external/catch/catch.hpp" --quiet
+
+      - name: check for leftover std::cerr
+        run: |
+          ! rg "cerr" --iglob "\!metatomic-core/tests/cpp/external/catch/catch.hpp" --quiet