easydiffraction 0.11.1__tar.gz → 0.12.0__tar.gz

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.copier-answers.yml

@@ -1,11 +1,11 @@
 # WARNING: Do not edit this file manually.
 # Any changes will be overwritten by Copier.
-_commit: v0.10.1-33-g0f85abf
+_commit: v0.10.1-40-g29e2ccf
 _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.13'
+app_python: '3.14'
 app_repo_name: diffraction-app
 home_page_url: https://easyscience.github.io/diffraction
 home_repo_name: diffraction
@@ -13,7 +13,7 @@ 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.11'
+lib_python_min: '3.12'
 lib_repo_name: diffraction-lib
 project_contact_email: support@easydiffraction.org
 project_copyright_years: 2021-2026

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/copilot-instructions.md

@@ -42,7 +42,8 @@
   and UPPER_SNAKE_CASE for constants.
 - Use `from __future__ import annotations` in every module.
 - Type-annotate all public function signatures.
-- Docstrings on all public classes and methods (numpy style).
+- Docstrings on all public classes and methods (numpy style). These must
+  include sections Parameters, Returns and Raises, where applicable.
 - Prefer flat over nested, explicit over clever.
 - Write straightforward code; do not add defensive checks for unlikely
   edge cases.
@@ -59,6 +60,19 @@
   with both getter and setter) or **read-only** (property with getter
   only). If internal code needs to mutate a read-only property, add a
   private `_set_<name>` method instead of exposing a public setter.
+- Lint complexity thresholds (`max-args`, `max-branches`,
+  `max-statements`, `max-locals`, `max-nested-blocks`, etc. in
+  `pyproject.toml`) are intentional code-quality guardrails. They are
+  not arbitrary numbers — the project uses ruff's defaults (with
+  `max-args` and `max-positional-args` set to 6 instead of 5 to account
+  for ruff counting `self`/`cls`). When code violates a threshold, it is
+  a signal that the function or class needs refactoring — not that the
+  threshold needs raising. Do not raise thresholds, add `# noqa`
+  comments, or use any other mechanism to silence complexity violations.
+  Instead, refactor the code (extract helpers, introduce parameter
+  objects, flatten nesting, etc.). For complex refactors that touch many
+  lines or change public API, propose a refactoring plan and wait for
+  approval before proceeding.
 
 ## Architecture
 
@@ -107,6 +121,26 @@
   `*.py` script, then run `pixi run notebook-prepare` to regenerate the
   notebook.
 
+## Testing
+
+- Every new module, class, or bug fix must ship with tests. See
+  `docs/architecture/architecture.md` §10 for the full test strategy.
+- **Unit tests mirror the source tree:**
+  `src/easydiffraction/<pkg>/<mod>.py` →
+  `tests/unit/easydiffraction/<pkg>/test_<mod>.py`. Run
+  `pixi run test-structure-check` to verify.
+- Category packages with only `default.py`/`factory.py` may use a single
+  parent-level `test_<package>.py` instead of per-file tests.
+- Supplementary test files use the pattern `test_<mod>_coverage.py`.
+- Tests that expect `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.
+- After adding or modifying tests, run `pixi run unit-tests` and confirm
+  all tests pass.
+
 ## Changes
 
 - Before implementing any structural or design change (new categories,
@@ -147,6 +181,8 @@
   `docs/architecture/architecture.md`.
 - After changes, run linting and formatting fixes with `pixi run fix`.
   Do not check what was auto-fixed, just accept the fixes and move on.
+  Then, run linting and formatting checks with `pixi run check` and
+  address any remaining issues until the code is clean.
 - After changes, run unit tests with `pixi run unit-tests`.
 - After changes, run integration tests with
   `pixi run integration-tests`.

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/backmerge.yml

@@ -20,6 +20,11 @@ concurrency:
   group: backmerge-master-into-develop
   cancel-in-progress: false
 
+# Opt into Node.js 24 for all JavaScript actions.
+# Remove once all referenced actions natively target Node 24.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   backmerge:
     runs-on: ubuntu-latest

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/cleanup.yml

@@ -61,6 +61,11 @@ on:
           - 'false'
           - 'true'
 
+# Opt into Node.js 24 for all JavaScript actions.
+# Remove once all referenced actions natively target Node 24.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   del-runs:
     runs-on: ubuntu-latest

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/coverage.yml

@@ -1,8 +1,10 @@
 name: Coverage checks
 
 on:
-  # Trigger the workflow on push
+  # Trigger the workflow on push to develop
   push:
+    branches:
+      - develop
     # Do not run on version tags (those are handled by other workflows)
     tags-ignore: ['v*']
   # Trigger the workflow on pull request
@@ -15,15 +17,18 @@ permissions:
   actions: write
   contents: read
 
-# Allow only one concurrent workflow, skipping runs queued between the run
-# in-progress and latest queued. And cancel in-progress runs.
+# 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: true
+  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 }}
+  # Opt into Node.js 24 for all JavaScript actions.
+  # Remove once all referenced actions natively target Node 24.
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   # Job 1: Run docstring coverage

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/dashboard.yml

@@ -14,6 +14,9 @@ env:
   DEVELOP_BRANCH: develop
   REPO_OWNER: ${{ github.repository_owner }}
   REPO_NAME: ${{ github.event.repository.name }}
+  # Opt into Node.js 24 for all JavaScript actions.
+  # Remove once all referenced actions natively target Node 24.
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   dashboard:

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/docs.yml

@@ -48,6 +48,9 @@ env:
   IS_RELEASE_TAG: ${{ startsWith(github.ref, 'refs/tags/v') }}
   GITHUB_REPOSITORY: ${{ github.repository }}
   NOTEBOOKS_DIR: tutorials
+  # Opt into Node.js 24 for all JavaScript actions.
+  # Remove once all referenced actions natively target Node 24.
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   # Single job that builds and deploys documentation.

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/issues-labels.yml

@@ -11,10 +11,21 @@ on:
 permissions:
   issues: write
 
+# Opt into Node.js 24 for all JavaScript actions.
+# Remove once all referenced actions natively target Node 24.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   check-labels:
+    if: github.actor != 'easyscience[bot]'
+
     runs-on: ubuntu-latest
 
+    concurrency:
+      group: issue-labels-${{ github.event.issue.number }}
+      cancel-in-progress: true
+
     steps:
       - name: Checkout repository
         uses: actions/checkout@v5

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/lint-format.yml

@@ -34,6 +34,9 @@ permissions:
 # Set the environment variables to be used in all jobs defined in this workflow
 env:
   CI_BRANCH: ${{ github.head_ref || github.ref_name }}
+  # Opt into Node.js 24 for all JavaScript actions.
+  # Remove once all referenced actions natively target Node 24.
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   lint-format:

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/pypi-publish.yml

@@ -10,6 +10,11 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
+# Opt into Node.js 24 for all JavaScript actions.
+# Remove once all referenced actions natively target Node 24.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   pypi-publish:
     runs-on: ubuntu-latest

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/pypi-test.yml

@@ -20,6 +20,9 @@ permissions:
 env:
   CI_BRANCH: ${{ github.head_ref || github.ref_name }}
   DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+  # Opt into Node.js 24 for all JavaScript actions.
+  # Remove once all referenced actions natively target Node 24.
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   # Job 1: Test installation from PyPI on multiple OS
@@ -45,30 +48,38 @@ jobs:
       - name: Init pixi project
         run: pixi init easydiffraction
 
+      - name: Set the minimum system requirements
+        run: pixi project system-requirements add macos 14.0
+
       - name: Add Python 3.14 from Conda
         working-directory: easydiffraction
         run: pixi add "python=3.14"
 
       - name: Add other Conda dependencies
         working-directory: easydiffraction
-        run: pixi add gsl
-
-      - name: Add easydiffraction from PyPI
-        working-directory: easydiffraction
-        run: pixi add --pypi "easydiffraction"
+        run: |
+          pixi add gsl
+          pixi add --platform osx-arm64 libcxx
 
-      - name: Add dev dependencies from PyPI
+      - name: Add pycrysfml calculator from custom PyPI index
         working-directory: easydiffraction
-        run: pixi add --pypi pytest pytest-xdist
+        run: |
+          echo '' >> pixi.toml
+          echo '[pypi-dependencies]' >> pixi.toml
+          echo 'pycrysfml = { version = ">=0.2.1", index = "https://easyscience.github.io/pypi/" }' >> pixi.toml
 
-      - name: Add Pixi task as a shortcut
+      - name: Add easydiffraction (with dev dependencies) from PyPI
         working-directory: easydiffraction
-        run: pixi task add easydiffraction "python -m 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
+        working-directory: easydiffraction
+        run: pixi run python -m pytest ../tests/functional/ --color=yes -v
+
       - name: Run integration tests to verify the installation
         working-directory: easydiffraction
         run: pixi run python -m pytest ../tests/integration/ --color=yes -n auto

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/release-notes.yml

@@ -10,6 +10,11 @@ on:
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
+# Opt into Node.js 24 for all JavaScript actions.
+# Remove once all referenced actions natively target Node 24.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   draft-release-notes:
     permissions:

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/release-pr.yml

@@ -24,6 +24,9 @@ permissions:
 env:
   DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
   SOURCE_BRANCH: ${{ inputs.source_branch || 'develop' }}
+  # Opt into Node.js 24 for all JavaScript actions.
+  # Remove once all referenced actions natively target Node 24.
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   create-pull-request:

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/security.yml

@@ -44,6 +44,11 @@ permissions:
   contents: read
   security-events: write
 
+# Opt into Node.js 24 for all JavaScript actions.
+# Remove once all referenced actions natively target Node 24.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   codeql:
     name: Code scanning

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/test-trigger.yml

@@ -10,6 +10,11 @@ on:
 permissions:
   contents: read
 
+# Opt into Node.js 24 for all JavaScript actions.
+# Remove once all referenced actions natively target Node 24.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   code-tests-trigger:
     runs-on: ubuntu-latest

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/test.yml

@@ -44,8 +44,11 @@ concurrency:
 # Set the environment variables to be used in all jobs defined in this workflow
 env:
   CI_BRANCH: ${{ github.head_ref || github.ref_name }}
-  PY_VERSIONS: '3.11 3.14'
-  PIXI_ENVS: 'py-311-env py-314-env'
+  PY_VERSIONS: '3.12 3.14'
+  PIXI_ENVS: 'py-312-env py-314-env'
+  # Opt into Node.js 24 for all JavaScript actions.
+  # Remove once all referenced actions natively target Node 24.
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   # Job 1: Set up environment variables
@@ -214,7 +217,14 @@ jobs:
             # platform-specific deps so this is a no-op on Linux/Windows.
             echo "Adding libc++ for macOS (required by diffpy.pdffit2)"
             pixi add --platform osx-arm64 libcxx
-            pixi add --platform osx-64 libcxx
+
+            # Doing this in a hacky way, as pixi does not support adding 
+            # dependencies from a custom PyPI index with a CLI command without
+            # specifying full wheel name.
+            echo "Adding pycrysfml from custom PyPI index"
+            echo '' >> pixi.toml
+            echo '[pypi-dependencies]' >> pixi.toml
+            echo 'pycrysfml = { version = ">=0.2.1", index = "https://easyscience.github.io/pypi/" }' >> pixi.toml
 
             echo "Looking for wheel in ../dist/py$py_ver/"
             ls -l "../dist/py$py_ver/"

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/tutorial-tests-trigger.yml

@@ -10,6 +10,11 @@ on:
 permissions:
   contents: read
 
+# Opt into Node.js 24 for all JavaScript actions.
+# Remove once all referenced actions natively target Node 24.
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   tutorial-tests-trigger:
     runs-on: ubuntu-latest

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.github/workflows/tutorial-tests.yml

@@ -27,6 +27,9 @@ concurrency:
 # Set the environment variables to be used in all jobs defined in this workflow
 env:
   CI_BRANCH: ${{ github.head_ref || github.ref_name }}
+  # Opt into Node.js 24 for all JavaScript actions.
+  # Remove once all referenced actions natively target Node 24.
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
 jobs:
   # Job 1: Test tutorials as scripts and notebooks on multiple OS

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.gitignore

@@ -44,3 +44,8 @@ CMakeLists.txt.user*
 .cache/
 *.log
 *.zip
+
+# ED
+# Used to fetch tutorials data during their runtime. Need to have '/' at
+# the beginning to avoid ignoring 'data' module in the src/.
+/data/

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/.pre-commit-config.yaml

@@ -53,9 +53,23 @@ repos:
         pass_filenames: false
         stages: [manual]
 
+      - id: pixi-test-structure-check
+        name: pixi run test-structure-check
+        entry: pixi run test-structure-check
+        language: system
+        pass_filenames: false
+        stages: [manual]
+
       - id: pixi-unit-tests
         name: pixi run unit-tests
         entry: pixi run unit-tests
         language: system
         pass_filenames: false
         stages: [manual]
+
+      - id: pixi-functional-tests
+        name: pixi run functional-tests
+        entry: pixi run functional-tests
+        language: system
+        pass_filenames: false
+        stages: [manual]

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: easydiffraction
-Version: 0.11.1
+Version: 0.12.0
 Summary: Diffraction data analysis
 Project-URL: Homepage, https://easydiffraction.org
 Project-URL: Documentation, https://easyscience.github.io/diffraction-lib
@@ -15,12 +15,11 @@ Classifier: License :: OSI Approved :: BSD License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering
-Requires-Python: >=3.11
+Requires-Python: >=3.12
 Requires-Dist: asciichartpy
 Requires-Dist: asteval
 Requires-Dist: bumps
@@ -32,11 +31,9 @@ Requires-Dist: diffpy-pdffit2
 Requires-Dist: diffpy-utils
 Requires-Dist: essdiffraction
 Requires-Dist: gemmi
-Requires-Dist: jupyterlab
 Requires-Dist: lmfit
 Requires-Dist: numpy
 Requires-Dist: pandas
-Requires-Dist: pixi-kernel
 Requires-Dist: plotly
 Requires-Dist: pooch
 Requires-Dist: py3dmol
@@ -51,6 +48,7 @@ Requires-Dist: varname
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: copier; extra == 'dev'
+Requires-Dist: docstripy; extra == 'dev'
 Requires-Dist: format-docstring; extra == 'dev'
 Requires-Dist: gitpython; extra == 'dev'
 Requires-Dist: interrogate; extra == 'dev'

{easydiffraction-0.11.1 → easydiffraction-0.12.0}/docs/architecture/architecture.md

@@ -188,7 +188,7 @@ GuardedBase
 └── GenericDescriptorBase               # name, value (validated via AttributeSpec), description
     ├── GenericStringDescriptor         # _value_type = DataTypes.STRING
     └── GenericNumericDescriptor        # _value_type = DataTypes.NUMERIC, + units
-        └── GenericParameter            # + free, uncertainty, fit_min, fit_max, constrained, uid
+        └── GenericParameter            # + free, uncertainty, fit_min, fit_max, constrained
 ```
 
 CIF-bound concrete classes add a `CifHandler` for serialisation:
@@ -714,12 +714,13 @@ Projects are saved as a directory of CIF files:
 ```shell
 project_dir/
 ├── project.cif          # ProjectInfo
-├── analysis.cif         # Analysis settings
 ├── summary.cif          # Summary report
 ├── structures/
 │   └── lbco.cif         # One file per structure
-└── experiments/
-    └── hrpt.cif         # One file per experiment
+├── experiments/
+│   └── hrpt.cif         # One file per experiment
+└── analysis/
+    └── analysis.cif     # Analysis settings
 ```
 
 ### 7.3 Verbosity
@@ -856,7 +857,7 @@ project.experiments['hrpt'].calculator_type = 'cryspy'
 project.analysis.current_minimizer = 'lmfit'
 
 # Plot before fitting
-project.plot_meas_vs_calc(expt_name='hrpt', show_residual=True)
+project.plotter.plot_meas_vs_calc(expt_name='hrpt', show_residual=True)
 
 # Select free parameters
 project.structures['lbco'].cell.length_a.free = True
@@ -865,14 +866,14 @@ project.experiments['hrpt'].instrument.calib_twotheta_offset.free = True
 project.experiments['hrpt'].background['10'].y.free = True
 
 # Inspect free parameters
-project.analysis.show_free_params()
+project.analysis.display.free_params()
 
 # Fit and show results
 project.analysis.fit()
-project.analysis.show_fit_results()
+project.analysis.display.fit_results()
 
 # Plot after fitting
-project.plot_meas_vs_calc(expt_name='hrpt', show_residual=True)
+project.plotter.plot_meas_vs_calc(expt_name='hrpt', show_residual=True)
 
 # Save
 project.save()
@@ -919,6 +920,10 @@ project.experiments['xray_pdf'].peak_profile_type = 'gaussian-damped-sinc'
 - `DatablockItem` = one CIF `data_` block, `DatablockCollection` = set
   of blocks.
 - `CategoryItem` = one CIF category, `CategoryCollection` = CIF loop.
+- **Free-flag encoding**: A parameter's free/fixed status is encoded in
+  CIF via uncertainty brackets. `3.89` = fixed, `3.89(2)` = free with
+  esd, `3.89()` = free without esd. There is no separate list of free
+  parameters; the brackets are the single source of truth.
 
 ### 9.2 Immutability of Experiment Type
 
@@ -1165,9 +1170,130 @@ def length_a(self) -> Parameter:
 - The CI tool `pixi run param-consistency-check` validates compliance;
   `pixi run param-consistency-fix` auto-fixes violations.
 
+### 9.9 Lint Complexity Thresholds
+
+The Pylint-style complexity limits in `pyproject.toml` are **intentional
+code-quality guardrails**, not arbitrary numbers. A violation is a
+signal that the function or class needs refactoring — not that the
+threshold needs raising.
+
+The project uses **ruff's defaults** for all PLR thresholds, with one
+exception: `max-args` and `max-positional-args` are set to **6** instead
+of the ruff default of 5, because ruff counts `self`/`cls` while
+traditional pylint does not. Setting 6 in ruff matches pylint's standard
+limit of 5 real parameters per function.
+
+| Threshold             | Value | Rule    |
+| --------------------- | ----- | ------- |
+| `max-args`            | 6     | PLR0913 |
+| `max-positional-args` | 6     | PLR0917 |
+| `max-branches`        | 12    | PLR0912 |
+| `max-statements`      | 50    | PLR0915 |
+| `max-locals`          | 15    | PLR0914 |
+| `max-nested-blocks`   | 5     | PLR1702 |
+| `max-returns`         | 6     | PLR0911 |
+| `max-public-methods`  | 20    | PLR0904 |
+
+**Rules:**
+
+- **Do not raise thresholds.** The current values represent the
+  project's design intent for maximum acceptable complexity.
+- **Do not add `# noqa` comments** (or any other mechanism) to silence
+  complexity rules such as `PLR0912`, `PLR0913`, `PLR0914`, `PLR0915`,
+  `PLR0917`, `PLR1702`.
+- **Refactor the code instead:** extract helper functions, introduce
+  parameter objects, flatten nesting, use early returns, etc.
+- **For complex refactors** that touch many lines or change public API,
+  propose a refactoring plan and wait for approval before proceeding.
+
+---
+
+## 10. Test Strategy
+
+Every new feature, category, factory, or bug fix must ship with tests.
+The project enforces a multi-layered testing approach that catches
+regressions at different levels of abstraction.
+
+### 10.1 Test Layers
+
+| Layer                 | Location                | Runner command               | Scope                                                                                                                |
+| --------------------- | ----------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **Unit**              | `tests/unit/`           | `pixi run unit-tests`        | Single class or function in isolation. Fast, no I/O, no external engines.                                            |
+| **Functional**        | `tests/functional/`     | `pixi run functional-tests`  | Multi-component workflows (e.g. create experiment → load data → fit). No external data files beyond tiny test stubs. |
+| **Integration**       | `tests/integration/`    | `pixi run integration-tests` | End-to-end pipelines using real calculation engines (cryspy, crysfml, pdffit2) and real data files from `data/`.     |
+| **Script (tutorial)** | `tools/test_scripts.py` | `pixi run script-tests`      | Runs each tutorial `*.py` script under `docs/docs/tutorials/` as a subprocess and checks for a zero exit code.       |
+| **Notebook**          | `docs/docs/tutorials/`  | `pixi run notebook-tests`    | Executes every Jupyter notebook end-to-end via `nbmake`.                                                             |
+
+### 10.2 Directory Structure Convention
+
+The unit-test tree **mirrors** the source tree:
+
+```
+src/easydiffraction/<pkg>/<module>.py
+    → tests/unit/easydiffraction/<pkg>/test_<module>.py
+```
+
+Two additional patterns are recognised:
+
+1. **Supplementary coverage files** — `test_<module>_coverage.py`,
+   `test_<module>_more.py`, etc. sit beside the main test file and add
+   extra scenarios.
+2. **Parent-level roll-up** — for category packages that contain only
+   `default.py` and `factory.py`, a single `test_<package_name>.py` one
+   directory up covers the whole package (e.g.
+   `categories/test_experiment_type.py` covers
+   `categories/experiment_type/default.py` and
+   `categories/experiment_type/factory.py`).
+
+The CI tool `pixi run test-structure-check` validates that every source
+module has a corresponding test file and reports any gaps. Explicit name
+aliases (e.g. `variable.py` tested by `test_parameters.py`) are declared
+in `KNOWN_ALIASES` inside the tool script.
+
+### 10.3 What to Test per Source Module Type
+
+| Source module type               | Required tests                                                                                                                                             |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Core base class** (`core/`)    | Instantiation, public properties, validation edge cases, identity wiring.                                                                                  |
+| **Factory** (`factory.py`)       | Registration check, `supported_tags()`, `default_tag()`, `create()` for each tag, `show_supported()` output, invalid-tag handling.                         |
+| **Category** (`default.py`)      | Instantiation, all public properties (read + write where applicable), CIF round-trip (`as_cif` → `from_cif`), parameter enumeration.                       |
+| **Enum** (`enums.py`)            | Membership of all members, `default()` method, `description()` for every member, `StrEnum` string equality.                                                |
+| **Datablock item** (`base.py`)   | Construction, switchable-category full API (`<cat>`, `<cat>_type` get/set, `show_supported_<cat>_types`, `show_current_<cat>_type`), `show`/`show_as_cif`. |
+| **Collection** (`collection.py`) | `create`, `add`, `remove`, `names`, `show_names`, `show_params`, iteration, duplicate-name handling.                                                       |
+| **Calculator / Minimizer**       | `can_handle()` with compatible and incompatible experiment types, `_compute()` stub or mock.                                                               |
+| **Display / IO**                 | Input → output for representative cases; file-not-found and malformed-input error paths.                                                                   |
+
+### 10.4 Test Conventions
+
+- **No test-ordering dependence.** Each test must be self-contained. Use
+  `monkeypatch` to set `Logger._reaction` when the test expects a raised
+  exception (another test may have leaked WARN mode via the global
+  `Logger` singleton).
+- **Error paths are tested explicitly.** Use `pytest.raises()` (with
+  `monkeypatch` for Logger RAISE mode) for `log.error()` calls that
+  specify `exc_type`.
+- **`@typechecked` setters raise `typeguard.TypeCheckError`**, not
+  `TypeError`. Tests must catch the correct exception.
+- **Use `capsys` / `capfd`** for asserting console output from `show_*`
+  methods.
+- **Prefer `tmp_path`** (pytest fixture) for file-system tests.
+- **No sleeping, no network calls, no real calculation engines** in unit
+  tests.
+- Test files carry the SPDX license header and a module-level docstring.
+  They are exempt from most lint rules (ANN, D, DOC, INP001, S101, etc.)
+  per `pyproject.toml`.
+
+### 10.5 Coverage Threshold
+
+The minimum line-coverage threshold is **70 %** (`fail_under = 70` in
+`pyproject.toml`). The project aspires to test every code path; the
+threshold is a safety net, not a target.
+
+Run `pixi run unit-tests-coverage` for a per-module report.
+
 ---
 
-## 10. Issues
+## 11. Issues
 
 - **Open:** [`issues_open.md`](issues_open.md) — prioritised backlog.
 - **Closed:** [`issues_closed.md`](issues_closed.md) — resolved items