Python library

.github/workflows/publish-to-test-pypi.yml

@@ -0,0 +1,236 @@
+# Workflow developed from Python Package User Guide:
+# https://packaging.python.org/en/latest/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows/
+
+name: Publish Python 🐍 distribution 📦 to PyPI and TestPyPI
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - v*
+  workflow_dispatch:
+
+jobs:
+  check-version-matches:
+    name: Check if version numbers match the GitHub tag
+    runs-on: ubuntu-latest
+    continue-on-error: ${{ github.event_name == 'workflow_dispatch' }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Extract version from fpm.toml
+        id: fpm_version
+        run: echo "ARTEMIS_FPM_VERSION=$(awk -F'"' '/^version/ {print $2}' fpm.toml)" >> $GITHUB_ENV
+
+      - name: Extract version from mod_io_utils.F90
+        id: fortran_version
+        run: echo "ARTEMIS_FORTRAN_VERSION=$(awk -F'"' '/character\(len=\*\), parameter \:\:\ artemis__version__/ {print $2}' src/fortran/lib/mod_io_utils.F90)" >> $GITHUB_ENV
+
+      - name: Extract GitHub tag version
+        id: github_tag
+        run: echo "TAG_VERSION=${GITHUB_REF#refs/tags/v}" >> "$GITHUB_ENV"
+
+      - name: Verify version consistency
+        run: |
+          if [[ "$ARTEMIS_FPM_VERSION" != "$TAG_VERSION" ]]; then
+            echo "❌ Version mismatch: fpm.toml ($ARTEMIS_FPM_VERSION) does not match GitHub tag ($TAG_VERSION)"
+            exit 1
+          fi
+          if [[ "$ARTEMIS_FORTRAN_VERSION" != "$TAG_VERSION" ]]; then
+            echo "❌ Version mismatch: mod_io_utils.F90 ($ARTEMIS_FORTRAN_VERSION) does not match GitHub tag ($TAG_VERSION)"
+            exit 1
+          fi
+          echo "✅ Version numbers match!"
+
+  build_wheel:
+    name: Build wheel distribution 📦
+    runs-on: ${{ matrix.platform[0] }}
+    strategy:
+      fail-fast: false
+      matrix:
+        platform:
+        - [ubuntu-latest, manylinux, x86_64]
+        - [macos-14, macosx, arm64]
+        python-version: [ "3.12" ] # cibuildwheel automatically runs on all versions of Python
+        toolchain:
+        - {fortran-compiler: gcc, fc-version: 13}
+    needs:
+      - check-version-matches
+
+    steps:
+    - name: checkout repo
+      uses: actions/checkout@v4
+
+    - name: Set MACOSX_DEPLOYMENT_TARGET
+      if: startsWith(matrix.platform[0], 'macos')
+      run: echo "MACOSX_DEPLOYMENT_TARGET=$(sw_vers -productVersion | cut -d '.' -f 1-2)" >> $GITHUB_ENV
+
+    - name: Check macOS deployment target
+      if: startsWith(matrix.platform[0], 'macos')
+      run: echo "Deployment target version is ${{ env.MACOSX_DEPLOYMENT_TARGET }} / ${MACOSX_DEPLOYMENT_TARGET}"
+
+    - name: actions-setup-python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: actions-setup-cmake
+      uses: jwlawson/actions-setup-cmake@v2.0.1
+      with:
+        cmake-version: '3.24.x'
+
+    - name: actions-setup-fortran
+      uses: fortran-lang/setup-fortran@v1
+      id: setup-fortran
+      with:
+        compiler: ${{ matrix.toolchain.fortran-compiler }}
+        version: ${{ matrix.toolchain.fc-version }}
+
+    - name: Install OpenMP runtime (Linux only)
+      if: runner.os == 'Linux'
+      run: sudo apt-get update && sudo apt-get install -y libgomp1
+
+    - name: Install OpenMP runtime (macOS only)
+      if: runner.os == 'macOS'
+      run: brew install libomp
+
+    - name: Install python dependencies
+      run: |
+        python --version
+        python -m pip install pip-tools --user
+        python -m pip install build --user
+        python -m piptools compile -o requirements.txt pyproject.toml --all-build-deps
+        python -m pip install -r requirements.txt --user
+        python -m pip install cibuildwheel==2.22.0 --user
+
+    - name: Build a binary wheel distribution
+      run: python -m cibuildwheel --output-dir wheelhouse
+
+    - name: Store the distribution wheels
+      uses: actions/upload-artifact@v4
+      with:
+        name: artemis_materials-wheels-${{ matrix.python-version }}-${{ matrix.platform[0] }}-${{ matrix.toolchain.fortran-compiler }}${{ matrix.toolchain.fc-version }}
+        path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build wheel distribution 📦
+    runs-on: ubuntu-latest
+    steps:
+    - name: checkout repo
+      uses: actions/checkout@v4
+
+    - name: Build sdist
+      run: pipx run build --sdist
+
+    - name: Store the source distribution
+      uses: actions/upload-artifact@v4
+      with:
+        name: artemis_materials-sdist
+        path: dist/*.tar.gz
+
+  publish-to-pypi:
+    name: >-
+      Publish Python 🐍 distribution 📦 to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build_wheel
+    - build_sdist
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/artemis-materials
+    permissions:
+        id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        pattern: artemis_materials-*
+        path: dist
+        merge-multiple: true
+    - name: Publish distribution 📦 to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+
+  # publish-to-testpypi:
+  #   name: Publish Python 🐍 distribution 📦 to TestPyPI
+  #   if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+  #   needs:
+  #   - build_wheel
+  #   - build_sdist
+  #   runs-on: ubuntu-latest
+
+  #   environment:
+  #     name: testpypi
+  #     url: https://test.pypi.org/p/artemis-materials
+
+  #   permissions:
+  #     id-token: write  # IMPORTANT: mandatory for trusted publishing
+
+  #   steps:
+  #   - name: Download all the dists
+  #     uses: actions/download-artifact@v4
+  #     with:
+  #       pattern: artemis_materials-*
+  #       path: dist
+  #       merge-multiple: true
+  #   - name: Publish distribution 📦 to TestPyPI
+  #     uses: pypa/gh-action-pypi-publish@release/v1
+  #     with:
+  #       verbose: true
+  #       repository-url: https://test.pypi.org/legacy/
+
+  github-release:
+    name: >-
+      Sign the Python 🐍 distribution 📦 with Sigstore
+      and upload them to GitHub Release
+    needs:
+    - publish-to-pypi
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # IMPORTANT: mandatory for making GitHub Releases
+      id-token: write  # IMPORTANT: mandatory for sigstore
+
+    steps:
+    - name: Check if GitHub release already exists
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: |
+        if gh release view '${{ github.ref_name }}' --repo '${{ github.repository }}' > /dev/null 2>&1; then
+          echo "Release already exists for tag '${{ github.ref_name }}'. Skipping release creation."
+          exit 0
+        fi
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        pattern: artemis_materials-*
+        path: dist
+        merge-multiple: true
+    - name: Sign the dists with Sigstore
+      uses: sigstore/gh-action-sigstore-python@v3.0.0
+      with:
+        inputs: >-
+          ./dist/*.tar.gz
+          ./dist/*.whl
+    - name: Create GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: >-
+        gh release create
+        '${{ github.ref_name }}'
+        --repo '${{ github.repository }}'
+        --notes ""
+    - name: Upload artifact signatures to GitHub Release
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+        # Upload to GitHub Release using the `gh` CLI.
+        # `dist/` contains the built packages, and the
+        # sigstore-produced signatures and certificates.
+      run: >-
+        gh release upload
+        '${{ github.ref_name }}' dist/**
+        --repo '${{ github.repository }}'
+

.gitignore

@@ -6,4 +6,10 @@ obj/
 tests/*/*.txt
 tests/*/*.out
 tests/*/DINTERFACES
-tests/*/DTERMINATIONS
+tests/*/DTERMINATIONS
+build/
+dist/
+wheelhouse/
+*.egg-info/
+*.egg
+*.pyc

.readthedocs.yaml

@@ -0,0 +1,23 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/requirements.txt

CITATION.cff

@@ -0,0 +1,47 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
+cff-version: 1.2.0
+title: >-
+  ARTEMIS: Ab Initio Restructuring Tool Enabling Modelling
+  of Interface Structures
+message: >-
+  If you use this software, please cite it using the
+  metadata from this file.
+type: software
+authors:
+  - given-names: Ned Thaddeus
+    family-names: Taylor
+    orcid: 'https://orcid.org/0000-0002-9134-9712'
+    affiliation: University of Exeter
+  - given-names: Francis Huw
+    family-names: Davies
+    orcid: 'https://orcid.org/0000-0003-0786-2773'
+    affiliation: University of Exeter
+  - given-names: Isiah Edward Mikel
+    family-names: Rudkin
+  - given-names: Conor Jason
+    family-names: Price
+    orcid: 'https://orcid.org/0000-0002-1430-3294'
+  - given-names: Tsz Hin
+    family-names: Chan
+    orcid: 'https://orcid.org/0000-0003-1126-6579'
+  - given-names: Steven Paul
+    family-names: Hepplestone
+    affiliation: University of Exeter
+    orcid: 'https://orcid.org/0000-0002-2528-1270'
+identifiers:
+  - type: doi
+    value: 10.1016/j.cpc.2020.107515
+    description: Paper detailing the first code release
+repository-code: 'https://github.com/ExeQuantCode/ARTEMIS'
+abstract: >-
+  ARTEMIS is a software package for the generation and
+  modelling of interfaces between materials.
+keywords:
+  - materials science
+  - interfaces
+  - material interfaces
+  - structure generation
+license: GPL-3.0
+version: 1.0.2