easydiffraction 0.18.0__tar.gz → 0.19.1__tar.gz

easydiffraction-0.19.1/.codecov.yml

@@ -0,0 +1,35 @@
+# Codecov configuration
+# https://docs.codecov.com/docs/codecov-yaml
+
+github_checks:
+  annotations: true
+
+ignore:
+  - 'src/easydiffraction/report/templates/html/vendor/**'
+  - 'src/easydiffraction/report/templates/tex/styles/**'
+  - 'src/easydiffraction/utils/_vendored/jupyter_dark_detect/**'
+
+comment:
+  layout: 'reach, diff, flags, files'
+  behavior: default
+  require_changes: false
+  require_base: false
+  require_head: true
+
+coverage:
+  status:
+    project:
+      default:
+        target: 80%
+        threshold: 1%
+        # Project coverage is the real gate (see ADR
+        # test-suite-and-validation).
+        informational: false
+    patch:
+      default:
+        target: auto
+        threshold: 1%
+        # Non-blocking: patch grades diff lines against unit-only
+        # coverage, so engine/integration-tested code would otherwise
+        # always fail. See ADR test-suite-and-validation.
+        informational: true

easydiffraction-0.19.1/.github/workflows/coverage.yml

@@ -0,0 +1,57 @@
+name: Coverage checks
+
+on:
+  # Trigger the workflow on push to develop
+  push:
+    branches:
+      - develop
+  # Trigger the workflow on pull request
+  pull_request:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Need permissions to trigger the dashboard build workflow
+permissions:
+  actions: write
+  contents: read
+
+# Allow only one concurrent workflow per PR or branch ref.
+# Cancel in-progress runs only for pull requests, but let branch push runs finish.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# Set the environment variables to be used in all jobs defined in this workflow
+env:
+  CI_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+jobs:
+  # Job 1: Run unit tests with coverage and upload to Codecov.
+  # Docstring coverage is gated as a static check in lint-format.yml.
+  unit-tests-coverage:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check-out repository
+        uses: actions/checkout@v6
+
+      - name: Set up pixi
+        uses: ./.github/actions/setup-pixi
+
+      - name: Run unit tests with coverage
+        run: pixi run unit-tests-coverage --cov-report=xml:coverage-unit.xml
+
+      - name: Upload unit tests coverage to Codecov
+        if: ${{ !cancelled() }}
+        uses: ./.github/actions/upload-codecov
+        with:
+          name: unit-tests-job
+          flags: unittests
+          files: ./coverage-unit.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  # Job 4: Build and publish dashboard (reusable workflow)
+  run-reusable-workflows:
+    needs: [unit-tests-coverage] # depend on the previous job
+    uses: ./.github/workflows/dashboard.yml
+    secrets: inherit

easydiffraction-0.19.1/.github/workflows/docs.yml

@@ -0,0 +1,201 @@
+# This workflow builds and deploys documentation for the project.
+#
+# Overview:
+#  - Converts tutorial Python scripts to Jupyter notebooks and executes them.
+#  - Builds the documentation site using MkDocs with the Material theme.
+#  - Uploads the built site as an artifact for local inspection.
+#  - Deploys versioned documentation to the gh-pages branch using Mike:
+#    - For release tags (v*): deploys to a versioned folder (e.g., /0.9.1/) and updates /latest/.
+#    - For branches: deploys to /dev/.
+#
+# The action summary page will contain a link to the built artifact for downloading
+# and inspecting, as well as a link to the deployed documentation site.
+
+name: Docs build and deployment
+
+on:
+  # Trigger the workflow on push
+  push:
+    # Selected branches
+    branches: [develop] # master and main are already verified in PR
+    # Runs on creating a new tag starting with 'v', e.g. 'v1.0.3'
+    tags: ['v*']
+  # Trigger the workflow on pull request
+  pull_request:
+    # Selected branches
+    branches: [master, main, develop]
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# - Non-tagged pushes and pull requests all use `docs-dev` group, so
+#   they cancel each other.
+# - Tagged pushes use their own group like docs-v1.2.3, so they do not
+#   cancel non-tagged runs, and non-tagged runs do not cancel them.
+concurrency:
+  group: >-
+    ${{ startsWith(github.ref, 'refs/tags/v')
+      && format('docs-{0}', github.ref_name)
+      || 'docs-dev' }}
+  cancel-in-progress: true
+
+# Set the environment variables to be used in all jobs defined in this workflow
+env:
+  # CI_BRANCH - the branch name (used in mkdocs.yml)
+  # For PRs: github.head_ref is the source branch
+  # For pushes: github.ref_name is the branch
+  # For tags: github.ref_name is the tag name
+  # GITHUB_REPOSITORY - the repository name (used in mkdocs.yml)
+  # NOTEBOOKS_DIR - the directory containing the Jupyter notebooks (used in mkdocs.yml)
+  DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+  DEVELOP_BRANCH: develop
+  CI_BRANCH: ${{ github.head_ref || github.ref_name }}
+  IS_RELEASE_TAG: ${{ startsWith(github.ref, 'refs/tags/v') }}
+  GITHUB_REPOSITORY: ${{ github.repository }}
+  NOTEBOOKS_DIR: tutorials
+
+jobs:
+  # Single job that builds and deploys documentation.
+  # Uses macOS runner for consistent Plotly chart rendering.
+  build-deploy-docs:
+    runs-on: ubuntu-latest # macos-latest
+
+    permissions:
+      contents: write # Required for pushing to the gh-pages branch
+
+    steps:
+      # Setting DOCS_VERSION to be used in mkdocs.yml, and then in the
+      # main.html template. It defines the versioned docs subfolder name
+      # in the gh-pages branch. If it's a release tag, use the version
+      # number without the 'v' prefix, otherwise use 'dev'.
+      # Setting RELEASE_VERSION to be used in mkdocs.yml to show
+      # the latest release version in the index.md file. If it's a
+      # release tag, use the tag name, otherwise use the branch name
+      # for development builds.
+      - name: Set extra env variables
+        shell: bash
+        run: |
+          if [[ "${IS_RELEASE_TAG}" == "true" ]]; then
+            RELEASE_VERSION="${GITHUB_REF_NAME}"
+            DOCS_VERSION="${RELEASE_VERSION#v}"
+          else
+            RELEASE_VERSION="${CI_BRANCH}"
+            DOCS_VERSION="dev"
+          fi
+          echo "RELEASE_VERSION=${RELEASE_VERSION}" >> "$GITHUB_ENV"
+          echo "DOCS_VERSION=${DOCS_VERSION}" >> "$GITHUB_ENV"
+
+      # Check out the repository source code.
+      # Note: The gh-pages branch is fetched separately later for mike deployment.
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          # Full history with tags so versioningit derives the real
+          # version (e.g. 0.18.0+dev40) instead of the v999.0.0 fallback
+          # (tool.versioningit.vcs default-tag), which would otherwise
+          # appear as "edi 999" in the executed notebook outputs rendered
+          # to HTML.
+          fetch-depth: 0
+
+      # Activate dark mode to create documentation with Plotly charts in dark mode
+      # Need a better solution to automatically switch the chart colour theme based on the mkdocs material switcher
+      # Something similar to mkdocs_plotly_plugin https://haoda-li.github.io/mkdocs-plotly-plugin/,
+      # but for generating documentation from notepads
+      #- name: Activate dark mode
+      #  run: |
+      #    brew install dark-mode
+      #    dark-mode status
+      #    dark-mode on
+      #    dark-mode status
+
+      # Set up the pixi package manager and install dependencies from pixi.toml.
+      # Uses frozen lockfile to ensure reproducible builds.
+      - name: Set up pixi
+        uses: ./.github/actions/setup-pixi
+      # Pre-import the main package to exclude info messages from the docs
+      # E.g., Matplotlib may print messages to stdout/stderr when first
+      # imported. This step allows to avoid "Matplotlib is building the font
+      # cache" messages during notebook execution.
+      - name: Pre-build site step
+        run: pixi run python -c "import easydiffraction"
+
+      # Prepare the Jupyter notebooks for documentation (strip output, etc.).
+      - name: Prepare notebooks
+        run: pixi run notebook-prepare
+
+      # Execute all Jupyter notebooks to generate output cells (plots, tables, etc.).
+      # Uses multiple cores for parallel execution to speed up the process.
+      - name: Run notebooks
+        # if: false # Temporarily disabled to speed up the docs build
+        run: pixi run notebook-exec-ci
+
+      # Sync the canonical Three.js snapshot into the docs assets so
+      # MkDocs can serve it (belt-and-braces; docs-build also depends on
+      # this task).
+      - name: Sync vendored JS into docs assets
+        run: pixi run docs-sync-vendored-js
+
+      # Build the static files for the documentation site for local inspection
+      # Input: docs/ directory containing the Markdown files
+      # Output: site/ directory containing the generated HTML files
+      - name: Build site for local check
+        run: pixi run docs-build-local
+
+      # Upload the static files from the site/ directory to be used for
+      # local check
+      - name: Upload built site as artifact
+        uses: ./.github/actions/upload-artifact
+        with:
+          name: site-local_easydiffraction-lib-${{ env.RELEASE_VERSION }}
+          path: docs/site/
+
+      # Create GitHub App token for pushing to gh-pages as easyscience[bot].
+      - name: Setup easyscience[bot]
+        id: bot
+        uses: ./.github/actions/setup-easyscience-bot
+        with:
+          app-id: ${{ vars.EASYSCIENCE_APP_ID }}
+          private-key: ${{ secrets.EASYSCIENCE_APP_KEY }}
+
+      # Configure git identity and remote URL so mike pushes as easyscience[bot].
+      - name: Configure git for pushing
+        run: |
+          set -euo pipefail
+          git config user.name "easyscience[bot]"
+          git config user.email "${{ vars.EASYSCIENCE_APP_ID }}+easyscience[bot]@users.noreply.github.com"
+          git remote set-url origin "https://x-access-token:${{ steps.bot.outputs.token }}@github.com/${{ github.repository }}.git"
+
+      # Fetch the gh-pages branch to ensure mike has the latest remote state.
+      # This is required because the checkout step only fetches the source branch,
+      # not the gh-pages branch that mike needs to update.
+      - name: Fetch gh-pages branch
+        run: |
+          git fetch origin gh-pages:gh-pages 2>/dev/null || true
+
+      # Deploy versioned documentation using mike (MkDocs plugin for versioning).
+      # - For release tags (v*): deploys to versioned folder (e.g., /0.9.1/) and aliases to /latest/.
+      # - For branches: deploys to /dev/.
+      # The "${RELEASE_VERSION#v}" syntax strips the 'v' prefix (v0.9.1 -> 0.9.1).
+      # Also sets 'latest' as the default version for the version selector.
+      - name: Rebuild and deploy docs with mike
+        run: |
+          # Exit on error (-e), undefined vars (-u), and pipeline failures (pipefail)
+          set -euo pipefail
+
+          REPO_NAME="${{ github.event.repository.name }}"
+          BASE_URL="https://easyscience.github.io/${REPO_NAME}"
+
+          # Deploy the release version and update the "latest" alias
+          if [[ "${IS_RELEASE_TAG}" == "true" ]]; then
+            pixi run docs-deploy-pre "${RELEASE_VERSION#v}" latest
+            pixi run docs-set-default-pre latest
+            DEPLOYMENT_URL="${BASE_URL}/latest"
+
+          # Deploy/update the "dev" alias (or whatever your convention is)
+          else
+            pixi run docs-deploy-pre dev
+            DEPLOYMENT_URL="${BASE_URL}/dev"
+
+          fi
+
+          # Add links to the action summary page for easy access
+          echo "🔗 deployment url [${DEPLOYMENT_URL}](${DEPLOYMENT_URL})" >> "${GITHUB_STEP_SUMMARY}"

easydiffraction-0.19.1/.github/workflows/lint-format.yml

@@ -0,0 +1,164 @@
+# The workflow checks
+#  - the validity of pyproject.toml,
+#  - the presence and correctness of SPDX license headers,
+#  - linting and formatting of Python code,
+#  - linting and formatting of docstrings in Python code,
+#  - formatting of non-Python files (like markdown and toml).
+#  - linting of Python code in Jupyter notebooks (for library template).
+#
+# A summary of the checks is added to the GitHub Actions summary.
+
+name: Lint and format checks
+
+on:
+  # Trigger the workflow on push
+  push:
+    branches-ignore: [master, main] # Already verified in PR
+    # Do not run this workflow on creating a new tag starting with
+    # 'v', e.g. 'v1.0.3' (see publish-pypi.yml)
+    tags-ignore: ['v*']
+  # Trigger the workflow on pull request
+  pull_request:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Allow only one concurrent workflow, skipping runs queued between the run
+# in-progress and latest queued. And cancel in-progress runs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+# Set the environment variables to be used in all jobs defined in this workflow
+env:
+  CI_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+jobs:
+  lint-format:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up pixi
+        uses: ./.github/actions/setup-pixi
+
+      - name: Run post-install developer steps
+        run: pixi run post-install
+
+      - name: Check validity of pyproject.toml
+        id: pyproject
+        continue-on-error: true
+        shell: bash
+        run: pixi run pyproject-check
+
+      - name: Check SPDX license headers
+        id: license_headers
+        continue-on-error: true
+        shell: bash
+        run: pixi run license-check
+
+      - name: Check linting of Python code
+        id: py_lint
+        continue-on-error: true
+        shell: bash
+        run: pixi run py-lint-check
+
+      - name: Check formatting of Python code
+        id: py_format
+        continue-on-error: true
+        shell: bash
+        run: pixi run py-format-check
+
+      - name: Check linting of docstrings in Python code
+        id: docstring_lint
+        continue-on-error: true
+        shell: bash
+        run: pixi run docstring-lint-check
+
+      - name: Check docstring coverage (interrogate)
+        id: docstring_coverage
+        continue-on-error: true
+        shell: bash
+        run: pixi run docstring-coverage
+
+      - name: Check formatting of non-Python files (md, toml, etc.)
+        id: nonpy_format
+        continue-on-error: true
+        shell: bash
+        run: pixi run nonpy-format-check
+
+      - name: Check linting of Python code in Jupyter notebooks (ipynb)
+        id: notebook_lint
+        continue-on-error: true
+        shell: bash
+        run: pixi run notebook-lint-check
+
+      - name: Check unit-test directory mirrors src/ structure
+        id: test_structure
+        continue-on-error: true
+        shell: bash
+        run: pixi run test-structure-check
+
+      - name: Check spelling (codespell)
+        id: spell
+        continue-on-error: true
+        shell: bash
+        run: pixi run spell-check
+
+      - name: Check documentation links (lychee)
+        id: link
+        continue-on-error: true
+        shell: bash
+        run: pixi run link-check
+
+      - name: Build documentation strictly (no tutorial execution)
+        id: docs_build
+        continue-on-error: true
+        shell: bash
+        run: pixi run docs-build
+
+      # Add summary
+      - name: Add quality checks summary
+        if: always()
+        shell: bash
+        run: |
+          {
+            echo "## 🧪 Checks Summary"
+            echo ""
+            echo "| Check | Status |"
+            echo "|-------|--------|"
+            echo "| pyproject.toml   | ${{ steps.pyproject.outcome == 'success' && '✅' || '❌' }} |"
+            echo "| license headers  | ${{ steps.license_headers.outcome == 'success' && '✅'  || '❌' }} |"
+            echo "| py lint          | ${{ steps.py_lint.outcome == 'success' && '✅' || '❌' }} |"
+            echo "| py format        | ${{ steps.py_format.outcome == 'success' && '✅' || '❌' }} |"
+            echo "| docstring lint   | ${{ steps.docstring_lint.outcome == 'success' && '✅' || '❌' }} |"
+            echo "| docstring cover  | ${{ steps.docstring_coverage.outcome == 'success' && '✅' || '❌' }} |"
+            echo "| nonpy format     | ${{ steps.nonpy_format.outcome == 'success' && '✅' || '❌' }} |"
+            echo "| notebooks lint   | ${{ steps.notebook_lint.outcome == 'success' && '✅' || '❌' }} |"
+            echo "| test structure   | ${{ steps.test_structure.outcome == 'success' && '✅' || '❌' }} |"
+            echo "| spelling         | ${{ steps.spell.outcome == 'success' && '✅' || '❌' }} |"
+            echo "| doc links        | ${{ steps.link.outcome == 'success' && '✅' || '❌' }} |"
+            echo "| docs strict build| ${{ steps.docs_build.outcome == 'success' && '✅' || '❌' }} |"
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      # Fail job if any check failed
+      - name: Fail job if any check failed
+        if: |
+          steps.pyproject.outcome == 'failure'
+          || steps.license_headers.outcome == 'failure'
+          || steps.py_lint.outcome == 'failure'
+          || steps.py_format.outcome == 'failure'
+          || steps.docstring_lint.outcome == 'failure'
+          || steps.docstring_coverage.outcome == 'failure'
+          || steps.nonpy_format.outcome == 'failure'
+          || steps.notebook_lint.outcome == 'failure'
+          || steps.test_structure.outcome == 'failure'
+          || steps.spell.outcome == 'failure'
+          || steps.link.outcome == 'failure'
+          || steps.docs_build.outcome == 'failure'
+        shell: bash
+        run: exit 1

easydiffraction-0.19.1/.github/workflows/nightly-test.yml

@@ -0,0 +1,71 @@
+# Nightly run of the FULL test suite across all cost tiers (default, pr,
+# and nightly), plus the performance benchmarks. The per-push and per-PR
+# runs in test.yml deselect the pr/nightly tiers; the nightly run does
+# not. See ADR test-suite-and-validation.
+
+name: Nightly tests
+
+on:
+  # Run the nightly-tier tests on a daily schedule
+  schedule:
+    - cron: '0 3 * * *' # 03:00 UTC daily
+  # Allow manual runs from the Actions tab
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Allow only one concurrent nightly run per ref.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  nightly-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check-out repository
+        uses: actions/checkout@v6
+        with:
+          # Full history with tags so versioningit derives the real
+          # version instead of the v999.0.0 fallback in notebook output.
+          fetch-depth: 0
+
+      - name: Set up pixi
+        uses: ./.github/actions/setup-pixi
+
+      # Run each tier as its own step for per-suite visibility. The two
+      # tutorial steps must stay sequential — they share
+      # tmp/tutorials/projects/ — so they run as ordered steps rather than
+      # a single depends-on aggregate. `if: ${{ !cancelled() }}` lets a
+      # failure in one tier still report the others.
+      - name: Unit tests
+        run: pixi run unit-tests
+
+      - name: Functional tests
+        if: ${{ !cancelled() }}
+        run: pixi run functional-tests
+
+      - name: Integration tests
+        if: ${{ !cancelled() }}
+        run: pixi run integration-tests
+
+      - name: Tutorials as scripts + output check
+        if: ${{ !cancelled() }}
+        run: pixi run script-tests-checked
+
+      - name: Tutorials + verification notebooks + output check
+        if: ${{ !cancelled() }}
+        run: pixi run notebook-tests-checked
+
+      - name: Run performance benchmarks
+        if: ${{ !cancelled() }}
+        run: pixi run benchmarks
+
+      - name: Upload benchmark results
+        if: ${{ !cancelled() }}
+        uses: ./.github/actions/upload-artifact
+        with:
+          name: benchmark-results
+          path: benchmark.json

easydiffraction-0.19.1/.github/workflows/pypi-test.yml

@@ -0,0 +1,102 @@
+name: PyPI package tests
+
+on:
+  # Run daily, at 00:00.
+  schedule:
+    - cron: '0 0 * * *'
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Allow only one concurrent workflow, skipping runs queued between the run
+# in-progress and latest queued. And cancel in-progress runs.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  # Job 1: Test installation from PyPI on multiple OS
+  pypi-package-tests:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+
+      - name: Set up pixi
+        uses: ./.github/actions/setup-pixi
+        with:
+          environments: ''
+          activate-environment: ''
+          run-install: false
+          frozen: false
+
+      - name: Init pixi project
+        run: pixi init easydiffraction
+
+      - name: Configure Pixi platforms
+        working-directory: easydiffraction
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          case "$RUNNER_OS" in
+            Linux)
+              pixi_platforms='[{ name = "linux-64-glibc-2-35", platform = "linux-64", glibc = "2.35" }]'
+              ;;
+            macOS)
+              pixi_platforms='[{ name = "osx-arm64-macos-14-0", platform = "osx-arm64", macos = "14.0" }]'
+              ;;
+            Windows)
+              pixi_platforms='["win-64"]'
+              ;;
+            *)
+              echo "Unsupported runner OS: $RUNNER_OS"
+              exit 1
+              ;;
+          esac
+
+          PIXI_PLATFORMS="$pixi_platforms" python -c 'import os, pathlib; path = pathlib.Path("pixi.toml"); text = path.read_text(); path.write_text(text.replace(text.split("platforms = ", 1)[1].split("\n", 1)[0], os.environ["PIXI_PLATFORMS"], 1))'
+          pixi workspace platform list
+
+      - name: Add Python 3.14
+        working-directory: easydiffraction
+        run: pixi add "python=3.14"
+
+      # GNU Scientific Library (required by diffpy.pdffit2)
+      # libc++ for macOS (required by diffpy.pdffit2)
+      - name: Add other Conda dependencies
+        working-directory: easydiffraction
+        run: |
+          pixi add gsl
+          pixi add --platform osx-arm64 libcxx
+
+      - name: Add easydiffraction (with dev dependencies) from PyPI
+        working-directory: easydiffraction
+        run: pixi add --pypi "easydiffraction[dev]"
+
+      - name: Run unit tests to verify the installation
+        working-directory: easydiffraction
+        run: pixi run python -m pytest ../tests/unit/ --color=yes -v
+
+      - name: Run functional tests to verify the installation
+        if: ${{ !cancelled() }}
+        working-directory: easydiffraction
+        run: pixi run python -m pytest ../tests/functional/ --color=yes -v
+
+      - name: Run integration tests to verify the installation
+        if: ${{ !cancelled() }}
+        working-directory: easydiffraction
+        run: pixi run python -m pytest ../tests/integration/ --color=yes -n auto
+
+  # Job 2: Build and publish dashboard (reusable workflow)
+  run-reusable-workflows:
+    needs: pypi-package-tests # depend on previous job
+    uses: ./.github/workflows/dashboard.yml
+    secrets: inherit