easydiffraction 0.16.0__tar.gz → 0.17.0__tar.gz

easydiffraction-0.17.0/.codecov.yml

@@ -0,0 +1,26 @@
+# Codecov configuration
+# https://docs.codecov.com/docs/codecov-yaml
+
+github_checks:
+  annotations: true
+
+comment:
+  layout: 'reach, diff, flags, files'
+  behavior: default
+  require_changes: false
+  require_base: false
+  require_head: true
+
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 1%
+        # Make project coverage informational (won't block PR)
+        informational: true
+    patch:
+      default:
+        target: auto
+        # Require patch coverage but with threshold
+        threshold: 1%

easydiffraction-0.17.0/.copier-answers.yml

@@ -0,0 +1,26 @@
+# WARNING: Do not edit this file manually.
+# Any changes will be overwritten by Copier.
+_commit: v0.11.4
+_src_path: gh:easyscience/templates
+app_docs_url: https://easyscience.github.io/diffraction-app
+app_doi: 10.5281/zenodo.18163581
+app_package_name: easydiffraction_app
+app_python: '3.14'
+app_repo_name: diffraction-app
+home_page_url: https://easyscience.github.io/diffraction
+home_repo_name: diffraction
+lib_docs_url: https://easyscience.github.io/diffraction-lib
+lib_doi: 10.5281/zenodo.18163581
+lib_package_name: easydiffraction
+lib_python_max: '3.14'
+lib_python_min: '3.12'
+lib_repo_name: diffraction-lib
+project_contact_email: support@easydiffraction.org
+project_copyright_years: 2021-2026
+project_extended_description: A software for calculating diffraction patterns based
+    on a structural model and refining its parameters against experimental data
+project_name: EasyDiffraction
+project_short_description: Diffraction data analysis
+project_shortcut: ED
+project_type: both
+template_type: lib

easydiffraction-0.17.0/.github/actions/setup-pixi/action.yml

@@ -0,0 +1,44 @@
+name: 'Setup Pixi Environment'
+description: 'Wrapper for prefix-dev/setup-pixi'
+inputs:
+  environments:
+    description: 'Pixi environments to setup'
+    required: false
+    default: 'default'
+  activate-environment:
+    description: 'Environment to activate'
+    required: false
+    default: 'default'
+  run-install:
+    description: 'Whether to run pixi install'
+    required: false
+    default: 'true'
+  locked:
+    description: 'Whether to run pixi install --locked'
+    required: false
+    default: 'false'
+  frozen:
+    description: 'Whether to run pixi install --frozen'
+    required: false
+    default: 'true'
+  cache:
+    description: 'Whether to use cache'
+    required: false
+    default: 'false'
+  post-cleanup:
+    description: 'Whether to run post cleanup'
+    required: false
+    default: 'false'
+
+runs:
+  using: 'composite'
+  steps:
+    - uses: prefix-dev/setup-pixi@v0.9.5
+      with:
+        environments: ${{ inputs.environments }}
+        activate-environment: ${{ inputs.activate-environment }}
+        run-install: ${{ inputs.run-install }}
+        locked: ${{ inputs.locked }}
+        frozen: ${{ inputs.frozen }}
+        cache: ${{ inputs.cache }}
+        post-cleanup: ${{ inputs.post-cleanup }}

easydiffraction-0.17.0/.github/copilot-instructions.md

@@ -0,0 +1,224 @@
+# Copilot Instructions for EasyDiffraction
+
+## Project Context
+
+- Python library for crystallographic diffraction analysis (refining
+  structural models against experimental data).
+- Domain axes: `sample_form` (powder, single crystal), `beam_mode`
+  (time-of-flight, constant wavelength), `radiation_probe` (neutron,
+  x-ray), `scattering_type` (bragg, total).
+- Calculation backends: `cryspy` and `crysfml` (Bragg), `pdffit2` (total
+  scattering).
+- CIF maps to `DatablockItem`/`DatablockCollection` and
+  `CategoryItem`/`CategoryCollection` (loops). Follow CIF naming;
+  deviate only for a clearly better API.
+- Metadata via frozen dataclasses: `TypeInfo`, `Compatibility`,
+  `CalculatorSupport`.
+- Audience is scientists, often non-programmers: prioritize
+  discoverability, clear errors, and safe defaults over developer
+  ergonomics.
+- Critical-software rigor: every code path tested, edge cases handled
+  explicitly, no silent failures.
+
+## Code Style
+
+- snake_case (functions/vars), PascalCase (classes), UPPER_SNAKE_CASE
+  (constants).
+- `from __future__ import annotations` in every module. Type-annotate
+  all public signatures.
+- Numpy-style docstrings on all public classes/methods (Parameters /
+  Returns / Raises where applicable). Summary is one line ≤72 chars
+  (`max-doc-length`); shorten wording rather than wrap.
+- Flat over nested, explicit over clever, composition over deep
+  inheritance. No defensive checks for unlikely edge cases.
+- One class per file when substantial; group small related classes.
+- No `**kwargs` — use explicit keyword arguments.
+- No string-based dispatch (e.g. `getattr(self, f'_{name}')`); write
+  named methods (`_set_sample_form`, `_set_beam_mode`). Narrow framework
+  metadata lookups are allowed when the attribute name is a class-level
+  declaration, is not user input, and is validated in one central place;
+  for example, `CategoryItem._category_entry_name`.
+- Public attrs are either editable (getter+setter property) or read-only
+  (getter only). For internal mutation of read-only props, use a private
+  `_set_<name>` method, not a public setter.
+- Lint complexity thresholds in `pyproject.toml` (`max-args`,
+  `max-branches`, `max-statements`, `max-locals`, `max-nested-blocks`,
+  …) are guardrails. A violation means refactor (extract helpers,
+  parameter objects, flatten) — do not raise thresholds, add `# noqa`,
+  or otherwise silence them. For complex refactors touching many lines
+  or public API, propose a plan and wait for approval.
+
+## Architecture
+
+- Eager top-of-module imports by default. Lazy imports only to break
+  circular deps or to keep `core/` free of heavy imports on rarely-
+  called paths (e.g. `help()`).
+- No `pkgutil`/`importlib` auto-discovery, no background threads, no
+  monkey-patching or runtime class mutation.
+- No `__all__`; control public API via explicit `__init__.py` imports.
+  No redundant `import X as X` aliases.
+- Concrete classes use `@Factory.register`. Each package's `__init__.py`
+  must explicitly import every concrete class to trigger registration —
+  always update it when adding a class.
+- Switchable categories (factory-swappable at runtime) follow this fixed
+  API on the owner (experiment / structure / analysis): `<category>`
+  (read-only), `<category>_type` (getter+setter),
+  `show_supported_<category>_types()`, `show_current_<category>_type()`.
+  The owner owns the type setter and show methods; show methods delegate
+  to `Factory.show_supported(...)`. Required even if only one
+  implementation exists.
+- Categories are flat siblings within their owner. Never nest a category
+  as a child of another category of a different type; cross-reference
+  via IDs instead.
+- Every finite, closed set of values (factory tags, axes, enumerated
+  descriptors) is a `(str, Enum)`; compare against members, not raw
+  strings.
+- Keep `core/` free of domain logic (base classes and utilities only).
+- Don't introduce abstractions before a concrete second use case. Don't
+  add dependencies without asking.
+
+## Testing
+
+- Every new module, class, or bug fix ships with tests. See
+  `docs/dev/adrs/accepted/test-strategy.md` for the full strategy.
+- Unit tests mirror the source tree:
+  `src/easydiffraction/<pkg>/<mod>.py` →
+  `tests/unit/easydiffraction/<pkg>/test_<mod>.py`. Verify with
+  `pixi run test-structure-check`. Supplementary tests:
+  `test_<mod>_coverage.py`. Category packages with only
+  `default.py`/`factory.py` may use one parent-level
+  `test_<package>.py`.
+- Tests expecting `log.error()` to raise must `monkeypatch` Logger to
+  RAISE mode (another test may have leaked WARN mode).
+- `@typechecked` setters raise `typeguard.TypeCheckError`, not
+  `TypeError`.
+- No test-ordering dependence, no network, no sleeping, no real
+  calculation engines in unit tests.
+
+## Tutorials
+
+- Notebooks in `docs/docs/tutorials/*.ipynb` are generated artifacts.
+  Edit only the corresponding `*.py`, then run
+  `pixi run notebook-prepare`.
+
+## Change Discipline
+
+- Before any structural/design change (new categories, factories,
+  switchable-category wiring, datablocks, CIF serialisation), read
+  `docs/dev/adrs/index.md` and the relevant accepted ADRs. Localised bug
+  fixes or test updates need only this file.
+- Development documentation lives under `docs/dev/`. Use
+  `docs/dev/adrs/index.md` as the architecture and decision navigation
+  surface; there is no separate `architecture.md` source of truth.
+- Project is in beta: no legacy shims, no deprecation warnings — update
+  tests and tutorials to the current API.
+- Minimal diffs; don't reformat working code. Fix only what's asked;
+  flag adjacent issues as comments. Don't add features or refactor
+  unless asked. Don't remove TODOs or comments unless the change fully
+  resolves them.
+- Never remove or replace existing functionality without explicit
+  confirmation — highlight every removal and wait for approval.
+- When renaming or auditing usages, search the entire project (code,
+  tests, tutorials, docs). Use `git grep -n` because all contributors
+  have Git; do not assume `rg` is installed. If `git grep` is
+  unavailable, fall back to `find ... -type f` plus `grep -n`.
+- Each change is atomic and single-commit-sized: make one change,
+  suggest the commit message, then stop and wait for confirmation.
+- When in doubt, ask.
+
+## Commits
+
+- Suggest a commit message after each change: code block, ≤72 chars,
+  imperative mood, no type prefix, no `Co-authored-by: Copilot`.
+  Examples:
+  - Add ChebyshevPolynomialBackground class
+  - Implement background_type setter on Experiment
+  - Standardize switchable-category naming convention
+- Stage only the files modified for the step, using explicit paths where
+  practical. Do not include data, project, CIF, or other generated
+  artifacts produced by integration/script/notebook tests unless the
+  user explicitly asked to update them.
+- Before each commit, inspect the worktree and avoid staging unrelated
+  user changes. If unrelated dirty files exist, leave them untouched and
+  mention them only when relevant.
+
+## Workflow
+
+Non-trivial changes use a two-phase workflow:
+
+- **Phase 1 — Implementation.** Code and docs updates only. Update ADRs
+  when the change affects architecture or documented decisions. Do not
+  create or run tests unless the user explicitly asks. When done,
+  present for review and iterate until approved.
+- **Phase 2 — Verification.** Add/update tests, then run `pixi run fix`,
+  `pixi run check`, `pixi run unit-tests`, `pixi run integration-tests`,
+  `pixi run script-tests`.
+
+Notes:
+
+- `pixi run fix` regenerates `docs/dev/package-structure/full.md` and
+  `docs/dev/package-structure/short.md` automatically — never edit those
+  by hand. Don't review auto-fixes; accept and move on. Then
+  `pixi run check` until clean.
+- When a check command needs saved output for analysis, capture the log
+  and preserve the command exit code with a zsh-safe variable name:
+  `pixi run check > /tmp/easydiffraction-check.log 2>&1; check_exit_code=$?; tail -n 200 /tmp/easydiffraction-check.log; exit $check_exit_code`.
+  Never assign to `status` in zsh; it is readonly. Use task-specific
+  names such as `check_exit_code`, `unit_tests_exit_code`, or
+  `script_tests_exit_code`.
+- Open issues / design questions / planned improvements live in
+  `docs/dev/issues/open.md` (priority-ordered). On resolution, move to
+  `docs/dev/issues/closed.md` and update the relevant ADR or
+  `docs/dev/adrs/index.md` if affected.
+
+### Planning
+
+When asked to create a plan:
+
+- Start the plan by referencing this file:
+  `.github/copilot-instructions.md`. State any deliberate exception to
+  these instructions in the plan itself.
+- First gather enough repository context to make the plan concrete. Ask
+  all ambiguous or unclear questions in one concise batch; record
+  unresolved questions in the plan if the user wants it saved before
+  answering them.
+- Save plans as `docs/dev/plans/<feature-name>.md` (lowercase,
+  dash-separated, e.g. `docs/dev/plans/background-refactor.md`). When a
+  plan implements one ADR, use the same slug as the ADR file; for
+  example, `docs/dev/adrs/suggestions/foo.md` maps to
+  `docs/dev/plans/foo.md`. If a plan has no corresponding ADR or spans
+  multiple ADRs, choose a concise feature slug and list all related ADRs
+  in the plan. Use the same `<feature-name>` for the implementation
+  branch (`feature/<feature-name>`). Do not push the branch unless
+  asked.
+- Include a status checklist with `[ ]` items; mark `[x]` as completed
+  during implementation.
+- Apply the two-phase workflow (Phase 1 implementation, Phase 2
+  verification) to non-trivial plans. Stop after Phase 1 and ask the
+  user to review before starting Phase 2.
+- The plan must explicitly state that, when an AI agent follows it,
+  every completed Phase 1 implementation step must be staged with
+  explicit paths and committed locally before moving to the next
+  implementation step or the Phase 1 review gate. Follow the rules in
+  **Commits**. Keep commits atomic, single-purpose, and aligned with
+  plan steps.
+- If implementation uncovers a serious requirement, risk, design issue,
+  or scope change not covered by the plan, stop and ask the user for
+  clarification or approval before proceeding. Record the unresolved
+  issue in the plan when useful.
+- The plan should be easy to maintain while working: include concrete
+  files likely to change, decisions already made, open questions,
+  verification commands for Phase 2, and a short suggested commit
+  message or branch name when useful.
+- Verification commands in plans must include the zsh-safe log-capture
+  pattern from **Workflow** whenever saved output is needed for later
+  analysis.
+- Before saving a plan, verify that referenced files, directories,
+  scripts, and task names exist locally when that is practical. If a
+  referenced tool is optional or missing, include an available fallback.
+- End every plan with a "Suggested Pull Request" section containing a
+  short PR title and a brief end-user-oriented description. Keep this
+  section non-technical enough for scientists and other users to
+  understand the benefit. Update it during implementation if extra
+  approved changes become important enough to mention in the PR title or
+  description.

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

@@ -0,0 +1,94 @@
+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 docstring coverage
+  docstring-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 docstring coverage
+        run: pixi run docstring-coverage
+
+  # Job 2: Run unit tests with coverage and upload to Codecov
+  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 2: Run integration tests with coverage and upload to Codecov
+  integration-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 integration tests with coverage
+        run:
+          pixi run integration-tests-coverage --cov-report=xml:coverage-integration.xml
+
+      - name: Upload integration tests coverage to Codecov
+        if: ${{ !cancelled() }}
+        uses: ./.github/actions/upload-codecov
+        with:
+          name: integration-tests-job
+          flags: integration
+          files: ./coverage-integration.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  # Job 4: Build and publish dashboard (reusable workflow)
+  run-reusable-workflows:
+    needs: [docstring-coverage, unit-tests-coverage, integration-tests-coverage] # depend on the previous jobs
+    uses: ./.github/workflows/dashboard.yml
+    secrets: inherit

easydiffraction-0.17.0/.github/workflows/dashboard.yml

@@ -0,0 +1,115 @@
+name: Dashboard build and publish
+
+on:
+  workflow_dispatch:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: dashboard-publish-${{ github.repository }}
+  cancel-in-progress: false
+
+# Set the environment variables to be used in all jobs defined in this workflow
+env:
+  CI_BRANCH: ${{ github.head_ref || github.ref_name }}
+  DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+  DEVELOP_BRANCH: develop
+  REPO_OWNER: ${{ github.repository_owner }}
+  REPO_NAME: ${{ github.event.repository.name }}
+
+jobs:
+  dashboard:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Set up pixi
+        uses: ./.github/actions/setup-pixi
+
+      # Install badgery into the active Pixi environment without modifying
+      # pixi.toml/pixi.lock. Using `pixi add` here re-solves the whole project
+      # and rebuilds the local editable package, which can cause intermittent
+      # Linux CI failures (`Text file busy`, os error 26).
+      - name: Install badgery
+        shell: bash
+        run: pixi run python -m pip install git+https://github.com/enhantica/badgery
+
+      - name: Run docstring coverage and code complexity/maintainability checks
+        run: |
+          for BRANCH in $DEFAULT_BRANCH $DEVELOP_BRANCH $CI_BRANCH; do
+            echo
+            echo "🔹🔸🔹🔸🔹 Processing branch $BRANCH 🔹🔸🔹🔸🔹"
+            if [ -d "../$BRANCH" ]; then
+              echo "Branch $BRANCH already processed, skipping"
+              continue
+            fi
+
+            git worktree add ../$BRANCH origin/$BRANCH
+            mkdir -p reports/$BRANCH
+
+            echo "Docstring coverage for branch $BRANCH"
+            pixi run interrogate -c pyproject.toml --fail-under=0 ../$BRANCH/src > reports/$BRANCH/coverage-docstring.txt
+
+            echo "Cyclomatic complexity for branch $BRANCH"
+            pixi run radon cc -s -j ../$BRANCH/src > reports/$BRANCH/cyclomatic-complexity.json
+
+            echo "Maintainability index for branch $BRANCH"
+            pixi run radon mi -j ../$BRANCH/src > reports/$BRANCH/maintainability-index.json
+
+            echo "Raw metrics for branch $BRANCH"
+            pixi run radon raw -s -j ../$BRANCH/src > reports/$BRANCH/raw-metrics.json
+          done
+
+      - name: Generate dashboard HTML
+        run: >
+          pixi run python -m badgery --config .badgery.yaml --repo ${{ github.repository
+          }} --branch ${{ env.CI_BRANCH }} --output index.html
+
+      - name: Prepare publish directory
+        run: |
+          mkdir -p _dashboard_publish/${{ env.REPO_NAME }}/${{ env.CI_BRANCH }}
+          cp index.html _dashboard_publish/${{ env.REPO_NAME }}/${{ env.CI_BRANCH }}
+
+      # Create GitHub App token for pushing to external dashboard repo.
+      # The 'repositories' parameter is required to grant access to repos
+      # other than the one where the workflow is running.
+      - 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 }}
+          repositories: |
+            ${{ github.event.repository.name }}
+            dashboard
+
+      # Push to external dashboard repository with retry logic.
+      # Retry is needed to handle transient GitHub API/authentication issues
+      # that occasionally cause 403 errors when multiple workflows push concurrently.
+      # Uses personal_token (not github_token) as GITHUB_TOKEN cannot access external repos.
+      - name:
+          Push to ${{ env.REPO_OWNER }}/dashboard/${{ env.REPO_NAME }}/${{ env.CI_BRANCH
+          }}
+        shell: bash
+        env:
+          DASHBOARD_COMMIT_MESSAGE: ${{ env.CI_BRANCH }}
+          DASHBOARD_GIT_USER_EMAIL:
+            ${{ vars.EASYSCIENCE_APP_ID }}+easyscience[bot]@users.noreply.github.com
+          DASHBOARD_PUSH_ATTEMPTS: '3'
+          DASHBOARD_PUSH_DELAY_SECONDS: '15'
+          DASHBOARD_PUBLISH_BRANCH: master
+          DASHBOARD_REMOTE_REPOSITORY: ${{ env.REPO_OWNER }}/dashboard
+          DASHBOARD_SOURCE_DIR: ./_dashboard_publish
+          DASHBOARD_TOKEN: ${{ steps.bot.outputs.token }}
+        run: bash ./.github/scripts/publish-dashboard.sh
+
+      - name: Add dashboard link to summary
+        run: |
+          URL="https://${{ env.REPO_OWNER }}.github.io/dashboard/${{ env.REPO_NAME }}/${{ env.CI_BRANCH }}"
+          echo "Dashboard link: [$URL]($URL)" >> $GITHUB_STEP_SUMMARY