diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 00000000..21a321f3 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,142 @@ +# Build DiffuseCode with the Python module and run the tests. +# +# 1. pytest tests/python – diffuse package, suite_python, golden data, demo +# 2. legacy macro tests – tools/run_legacy_tests.py, tags fast and mc +# 3. documentation – Sphinx (docs/), uploaded as the "docs-html" +# artifact; not published anywhere yet +# +# Development happens on claude-python-app until the first release of the +# Python package; feature branches (claude/**) merge into it. +name: tests + +on: + push: + branches: [claude-python-app, "claude/**"] + pull_request: + branches: [claude-python-app] + workflow_dispatch: + +concurrency: + group: tests-${{ github.ref }} + cancel-in-progress: true + +jobs: + linux: + runs-on: ubuntu-24.04 + timeout-minutes: 60 + env: + FC: gfortran + CC: gcc + CXX: g++ + steps: + - uses: actions/checkout@v4 + + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y --no-install-recommends \ + gfortran cmake make libfftw3-dev libhdf5-dev libreadline-dev \ + libpng-dev libx11-dev zlib1g-dev pgplot5 xvfb \ + python3-dev python3-numpy python3-pytest python3-matplotlib python3-venv + + - name: Configure + run: | + cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \ + -DDIFFUSE_PYTHON=ON -DPGPLOT_DIR=/usr/lib/pgplot5 \ + -DPYTHON_EXECUTABLE=/usr/bin/python3 -Wno-dev + + - name: Build + run: cmake --build build -j "$(nproc)" + + - name: Python tests (pytest) + env: + DIFFUSE_PYTHON_PATH: ${{ github.workspace }}/build/python + DIFFUSE_REQUIRE_PYTHON: "1" + MPLBACKEND: Agg + # DISCUS_SUITE is not set here, so the legacy macro tests inside + # pytest are skipped; the next step runs them in parallel. + run: python3 -m pytest tests/python -v --junitxml=pytest-results.xml + + - name: Legacy macro tests + # Tests tagged mc run with "seed 1234" on one thread (repeatable). A + # failed mc test is still re-run: 04.sro3 rarely gets a broken Fourier + # result (WP0 log). A pass on retry is reported as flaky; a real break + # still fails. + run: | + python3 tools/run_legacy_tests.py \ + --exe build/suite/prog/discus_suite -j "$(nproc)" \ + --tags fast,mc --retry-mc 2 --junit legacy-results.xml --workdir legacy-work + + - name: Documentation + if: success() || failure() + env: + DIFFUSE_PYTHON_PATH: ${{ github.workspace }}/build/python + MPLBACKEND: Agg + # Warnings are errors, so broken docstrings or links fail the build. + # --system-site-packages: use the apt NumPy/matplotlib that the + # compiled module was built against. + run: | + python3 -m venv --system-site-packages .venv-docs + .venv-docs/bin/pip install --quiet -r docs/requirements.txt + .venv-docs/bin/python -m sphinx -W --keep-going -b html docs docs/_build/html + + - name: Upload documentation + if: success() || failure() + uses: actions/upload-artifact@v4 + with: + name: docs-html + path: docs/_build/html + if-no-files-found: ignore + + - name: Upload results + if: always() + uses: actions/upload-artifact@v4 + with: + name: test-results + path: | + pytest-results.xml + legacy-results.xml + legacy-work/**/*.log + if-no-files-found: ignore + + # Publish the docs to https://tproffen.github.io/DiffuseCode/python-docs/ + # The gh-pages branch is the DISCUS homepage: tools/publish_docs.sh only + # replaces python-docs/ (plus an empty .nojekyll at the root) and refuses + # to publish if anything else would change. + publish-docs: + needs: linux + if: github.event_name == 'push' && github.ref == 'refs/heads/claude-python-app' + runs-on: ubuntu-24.04 + timeout-minutes: 10 + permissions: + contents: write + concurrency: + group: publish-docs + cancel-in-progress: false + steps: + - uses: actions/checkout@v4 + + - uses: actions/download-artifact@v4 + with: + name: docs-html + path: docs-html + + - uses: actions/checkout@v4 + with: + ref: gh-pages + path: gh-pages + + - name: Put the docs into gh-pages/python-docs + run: tools/publish_docs.sh docs-html gh-pages + + - name: Commit and push + working-directory: gh-pages + run: | + if git diff --cached --quiet; then + echo "Docs unchanged." + exit 0 + fi + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git commit -m "Python docs from ${GITHUB_SHA::7} (claude-python-app)" + git push origin HEAD:gh-pages diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..55a7f332 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,41 @@ +# DiffuseCode – notes for Claude Code sessions + +## Branches + +Until the first release of the Python package, **all migration work is built +against and merged into `claude-python-app`**, not `master`. Start feature +branches from `origin/claude-python-app` and target pull requests at it. + +## Plan and progress + +- `migration/DiffuseCode_Python_Migration_Plan.md` – overall plan (option B, + work packages WP0–WP10). +- `migration/WP0_Test_Baseline.md` – test baseline tasks and progress log. +- `tests/README.md` – how to run the tests. + +## Build and test + +```bash +FC=gfortran CC=gcc CXX=g++ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \ + -DDIFFUSE_PYTHON=ON -DPGPLOT_DIR=/usr/lib/pgplot5 +cmake --build build -j +DIFFUSE_PYTHON_PATH=build/python python3 -m pytest tests/python +python3 tools/run_legacy_tests.py --exe build/suite/prog/discus_suite -j 4 --tags fast,mc +``` + +CMake needs `FC` set. Keep build trees outside `tests/`. + +## Documentation + +Sphinx in `docs/` (MyST Markdown, autodoc + napoleon, sphinx-gallery over +`python/examples/`). Build with +`DIFFUSE_PYTHON_PATH=build/python python3 -m sphinx -W -b html docs docs/_build/html` +(`DIFFUSE_DOCS_OFFLINE=1` without network). New public API needs a NumPy-style +docstring, an entry in `docs/api.md`, and an example in `python/examples/`. +CI uploads the HTML as the `docs-html` artifact, and pushes to +`claude-python-app` publish it to +https://tproffen.github.io/DiffuseCode/python-docs/ (job `publish-docs`). +The `gh-pages` branch holds the DISCUS homepage: publishing may only change +`python-docs/` and the empty root `.nojekyll` (agreed with the owner, Nov +2026). `tools/publish_docs.sh` enforces this; keep it that way, and do not +link the docs from the homepage. diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..540b03f2 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,4 @@ +_build/ +_generated/ +gallery/ +sg_execution_times.rst diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 00000000..f13f8c2c --- /dev/null +++ b/docs/api.md @@ -0,0 +1,42 @@ +# API reference + +```{eval-rst} +.. currentmodule:: diffuse +``` + +## Structures + +```{eval-rst} +.. autofunction:: read_structure + +.. autoclass:: Crystal + :members: atoms, positions, volume, a +``` + +## Powder diffraction + +```{eval-rst} +.. autofunction:: powder + +.. autoclass:: PowderPattern + :members: two_theta, plot +``` + +## Running DISCUS directly + +```{eval-rst} +.. autofunction:: run_macro + +.. autofunction:: session + +.. autoclass:: Session + :members: run, value, dataset, dataset_2d, workdir, last_output +``` + +## Errors + +```{eval-rst} +.. autoexception:: DiffuseError + +.. autoexception:: MacroError +``` diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..4afb9bcd --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,100 @@ +"""Sphinx configuration for the DiffuseCode Python documentation. + +Build (from the repository root): + + pip install -r docs/requirements.txt + DIFFUSE_PYTHON_PATH=build/python python3 -m sphinx -W -b html docs docs/_build/html + +The example gallery runs python/examples/*.py and needs the suite_python +module (DIFFUSE_PYTHON_PATH). Without it, set DIFFUSE_DOCS_NO_GALLERY=1 to +build everything except the gallery. Without network access, set +DIFFUSE_DOCS_OFFLINE=1 (no links into the Python/NumPy/matplotlib docs). +""" + +import os +import shutil +import sys +from pathlib import Path + +DOCS = Path(__file__).resolve().parent +REPO = DOCS.parent +sys.path.insert(0, str(REPO / "python")) + +project = "DiffuseCode Python" +author = "The DiffuseCode developers" +copyright = "DiffuseCode developers" + +extensions = [ + "myst_parser", # Markdown pages + "sphinx.ext.autodoc", # API pages from docstrings + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", # NumPy-style docstrings + "sphinx.ext.intersphinx", # links to the NumPy, matplotlib, Python docs + "sphinx.ext.viewcode", +] + +source_suffix = {".rst": "restructuredtext", ".md": "markdown"} +exclude_patterns = ["_build", "**.ipynb_checkpoints"] +myst_heading_anchors = 3 + +# -- API docs ----------------------------------------------------------------- +autodoc_member_order = "bysource" +autodoc_typehints = "description" +autodoc_default_options = {"members": True} +napoleon_google_docstring = False +napoleon_numpy_docstring = True +napoleon_use_rtype = False +# diffuse loads suite_python only when a session starts, so importing it for +# the API pages works without the compiled module. + +intersphinx_mapping = { + "python": ("https://docs.python.org/3", None), + "numpy": ("https://numpy.org/doc/stable/", None), + "matplotlib": ("https://matplotlib.org/stable/", None), +} +if os.environ.get("DIFFUSE_DOCS_OFFLINE"): # no network: no outside links + intersphinx_mapping = {} + +# The migration documents skip heading levels in places; that is fine there. +suppress_warnings = ["myst.header"] + +# -- Pages taken from elsewhere in the repository ------------------------------- +# The migration documents stay in migration/ (one source of truth); copy them +# into the docs tree so that the links between them keep working. +_generated = DOCS / "_generated" +shutil.rmtree(_generated, ignore_errors=True) +(_generated / "migration").mkdir(parents=True) +for md in sorted((REPO / "migration").glob("*.md")): + shutil.copy(md, _generated / "migration" / md.name) +shutil.copy(REPO / "tests" / "README.md", _generated / "testing.md") + +# -- Example gallery ------------------------------------------------------------ +if not os.environ.get("DIFFUSE_DOCS_NO_GALLERY"): + extensions.append("sphinx_gallery.gen_gallery") + sphinx_gallery_conf = { + "examples_dirs": str(REPO / "python" / "examples"), + "gallery_dirs": "gallery", + "filename_pattern": r"\.py$", # run every example + "download_all_examples": False, + "matplotlib_animations": False, + "image_scrapers": ("matplotlib",), + } +else: + # Keep the table of contents valid: a placeholder instead of the gallery. + shutil.rmtree(DOCS / "gallery", ignore_errors=True) + (DOCS / "gallery").mkdir() + (DOCS / "gallery" / "index.md").write_text( + "# Examples\n\nThe example gallery was not built " + "(`DIFFUSE_DOCS_NO_GALLERY` was set).\n") + exclude_patterns.append("sg_execution_times.rst") + +# -- HTML ------------------------------------------------------------------------- +html_theme = "pydata_sphinx_theme" +html_title = "DiffuseCode Python" +html_theme_options = { + "github_url": "https://github.com/tproffen/DiffuseCode", + "navigation_with_keys": False, + "show_toc_level": 2, + "header_links_before_dropdown": 3, +} +html_static_path = [] diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..f4055714 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,38 @@ +# DiffuseCode from Python + +```{warning} +This is an early preview. The Python interface covers a small set of DISCUS +commands so far, and the API may still change. It is built from the +`claude-python-app` branch. +``` + +The `diffuse` package runs [DISCUS](https://github.com/tproffen/DiffuseCode) +from Python. You read a structure, run a calculation, and get the results back +as NumPy arrays, ready for matplotlib, SciPy or your own analysis. + +```python +import diffuse as dc + +cr = dc.read_structure("anatase.cif", supercell=(10, 10, 4)) +p = dc.powder(cr, qmin=0.5, qmax=10, dq=0.005, radiation="xray") +p.plot() +``` + +```{toctree} +:maxdepth: 2 +:caption: Using it + +install +gallery/index +api +``` + +```{toctree} +:maxdepth: 1 +:caption: Development + +_generated/testing +_generated/migration/DiffuseCode_Python_Migration_Plan +_generated/migration/WP0_Test_Baseline +_generated/migration/WP0_Test_Coverage_Gaps +``` diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 00000000..aad0d4be --- /dev/null +++ b/docs/install.md @@ -0,0 +1,63 @@ +# Installation + +There is no `pip install` yet (that comes with the packaging work, WP1 in +the migration plan). For now, build DiffuseCode with its Python module and +point Python at the build. + +## Build + +On Debian or Ubuntu, install the build dependencies: + +```bash +sudo apt-get install -y gfortran cmake libfftw3-dev libhdf5-dev libreadline-dev \ + libpng-dev libx11-dev zlib1g-dev pgplot5 python3-dev python3-numpy python3-matplotlib +``` + +Then, from the repository root: + +```bash +FC=gfortran CC=gcc CXX=g++ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \ + -DDIFFUSE_PYTHON=ON -DPGPLOT_DIR=/usr/lib/pgplot5 +cmake --build build -j +``` + +This builds `discus_suite` and the Python module `build/python/suite_python*.so`. + +## Use + +Two settings tell Python where things are: + +* `DIFFUSE_PYTHON_PATH`: the folder with the compiled module (`build/python`). +* the `python/` folder of the repository on the Python path, for the + `diffuse` package. + +```bash +export DIFFUSE_PYTHON_PATH=$PWD/build/python +export PYTHONPATH=$PWD/python +python3 python/examples/powder_demo.py +``` + +In a Jupyter notebook, set them before `import diffuse`: + +```python +import os, sys +os.environ["DIFFUSE_PYTHON_PATH"] = "/path/to/DiffuseCode/build/python" +sys.path.insert(0, "/path/to/DiffuseCode/python") +import diffuse as dc +``` + +## How it works, and its limits + +This version drives DISCUS through the f2py module `suite_python`: Python +writes the commands to a small macro, DISCUS runs it in the same process, and +the results come back through files or KUPLOT data sets. + +* DISCUS holds **one structure at a time** per process. A {class}`~diffuse.Crystal` + remembers how it was made, and {func}`~diffuse.powder` reads it in again if + another structure was loaded since. +* DISCUS output is captured, not printed. Set `DIFFUSE_ECHO=1`, or call + `dc.session(echo=True)`, to see it; the last output is in + `dc.session().last_output`. +* A failed DISCUS command raises {class}`~diffuse.MacroError` with DISCUS's + own error lines. +* {func}`~diffuse.run_macro` runs any DISCUS commands that are not wrapped yet. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..51a24da2 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +# Documentation build (see docs/conf.py) +sphinx>=7.2 +myst-parser>=2.0 +pydata-sphinx-theme>=0.15 +sphinx-gallery>=0.15 +matplotlib +numpy diff --git a/lib_f90/random_state_mod.f90 b/lib_f90/random_state_mod.f90 index d799aea1..4129a3de 100644 --- a/lib_f90/random_state_mod.f90 +++ b/lib_f90/random_state_mod.f90 @@ -112,6 +112,13 @@ SUBROUTINE ini_ran_ix(np, iwerte, iaddit) DO i=1, MIN(np,nseeds) ! Loop over all seeds or all provided values seed_vals(i) = iwerte(i) ENDDO +! The compiler's generator state usually has more words than the user gave +! (gfortran: 8). Fill the rest from the user's values, so that the same +! "seed" command always gives the same sequence. Before, these words kept +! their clock-based values from the start-up initialisation. + DO i=np+1, nseeds + seed_vals(i) = 2*MOD(IABS(iwerte(MOD(i-1,np)+1))+INIT(1)*i, INIT(2)) - INIT(2) + i + ENDDO CALL RANDOM_SEED(PUT=seed_vals) ! idum = 0 ! User provided three numbers ENDIF diff --git a/migration/DiffuseCode_Python_Migration_Plan.md b/migration/DiffuseCode_Python_Migration_Plan.md index aa1814b5..086148c3 100644 --- a/migration/DiffuseCode_Python_Migration_Plan.md +++ b/migration/DiffuseCode_Python_Migration_Plan.md @@ -2,6 +2,8 @@ A high-level look at the current Fortran code and options for separating compute from the command language, graphics and I/O, with a web front end as a later goal. +> **Branches:** until the first release of the Python package, all migration work is built against and merged into the **`claude-python-app`** branch, not `master`. Feature branches start from `claude-python-app`, and pull requests target it. CI (`.github/workflows/tests.yml`) runs on pushes to it and on pull requests into it. + > **Related documents:** progress on WP0 is tracked in [`WP0_Test_Baseline.md`](WP0_Test_Baseline.md); test gaps are in [`WP0_Test_Coverage_Gaps.md`](WP0_Test_Coverage_Gaps.md). `mixscat` is deprecated and not part of the migration. 1. [What the code is today](#1-what-the-code-is-today) diff --git a/migration/WP0_Test_Baseline.md b/migration/WP0_Test_Baseline.md index bf7b7015..09a6995e 100644 --- a/migration/WP0_Test_Baseline.md +++ b/migration/WP0_Test_Baseline.md @@ -162,15 +162,16 @@ tests/ # existing macro tests stay where they are test_all.mac # kept for interactive use (unchanged) manifest.toml # [done] list of tests (TOML: read by Python's standard library) README.md # [done] how to run the tests - golden/ # 0.6: reference outputs, one folder per test id + golden/ # 0.6: [started] reference outputs, one folder per test id python/ # pytest harness conftest.py # [done] registers the manifest tags as markers test_legacy_macros.py # [done] one test per manifest entry + manifest checks - compare.py # 0.6: numeric comparisons (R-value, max-abs, atom sets) + compare.py # [started] R-value, golden .npz read/write (0.6) + test_suite_python.py # [done] in-process Python tests against RESULTS/ and golden/ tools/ run_legacy_tests.py # [done] runner -> console table, JUnit XML, JSON .github/workflows/ - legacy-tests.yml # 0.9: build + run on every push to claude-python-app + tests.yml # [done] 0.9: build + pytest + legacy tests on claude-python-app ``` ### Tasks @@ -186,7 +187,7 @@ tools/ | 0.6 | **Golden data capture** | For each test, copy key outputs (intensities, powder, PDF, 3D-PDF, final structure/CIF, histograms) into `tests/golden//` with a `meta.json` (DiffuseCode version, git commit, compiler, flags, date). Python compares with NumPy (R-value, max-abs, atom-set match) using tolerances from the manifest. Keep the macro self-checks as a second line of defence. | Every test has at least one golden numeric output | 3–4 d | | 0.7 | **Coverage expansion** | Confirm the uncovered-command list from 1.3, then add short, deterministic tests for the commands that WP3–WP8 will wrap first: space-group expansion / `wyckoff`, `patterson`, `inverse`, `rmc`, `molecularize`/`demolecularize`, `perioditize`, `storage`/`super`, `bragg`, and kuplot `fit`. | All commands planned for WP3–WP8 have at least one test | 5–8 d | | 0.8 | **Build fixes** | Make `suite/prog/CMakeLists.txt` honour `DIFFUSE_GRAPHICS`. Make the PGPLOT install paths configurable / optional. Drop the hard `FC` requirement in favour of CMake's normal compiler detection. | `cmake -DDIFFUSE_GRAPHICS=OFF` builds and the suite passes | 1–2 d | -| 0.9 | **CI** | GitHub Actions on `ubuntu-24.04`: apt (gfortran, FFTW, HDF5, readline, PNG, X11, pgplot5, xvfb), build, run `tools/run_legacy_tests.py --tags fast,mc`, upload JUnit + logs. Nightly job for `slow`/`mpi`. Add a macOS job once Linux is stable. | Red/green status on every push to `claude-python-app` | 1–2 d | +| 0.9 ✅ | **CI** | GitHub Actions on `ubuntu-24.04`: apt (gfortran, FFTW, HDF5, readline, PNG, X11, pgplot5, xvfb), build, run `tools/run_legacy_tests.py --tags fast,mc`, upload JUnit + logs. Nightly job for `slow`/`mpi`. Add a macOS job once Linux is stable. | Red/green status on every push to `claude-python-app` | 1–2 d | | 0.10 | **Repo hygiene** | Run `cleanup.mac` logic, remove committed generated outputs, add a `.gitignore` for them, and keep only inputs + `RESULTS/` + `golden/`. Consider Git LFS for golden files larger than ~1 MB. | `git status` is clean after a test run | 1 d | **Total: about 4–6 weeks for one developer.** That fits the "months 0–3" @@ -278,3 +279,137 @@ Checked: | Display already taken | retried on another display, PASS | | Runner and pytest at the same time | all pass; no display clashes | | `test_all.mac` (interactive mode) | all 13 sections SUCCESS | + +### 0.9 (and start of 0.6) – CI and Python-interface tests + +* **Build fix:** `python/CMakeLists.txt` linked `experi_all` after + `discus_all`. `experi_kdo` calls `exp3_pdf`, so the f2py module built but + failed on import with `undefined symbol: __exp3_pdf_menu_MOD_exp3_pdf`. + `experi_all` now comes first. +* A test helper wraps `suite_python` (now `diffuse.session()`, see below). `run()` + writes a driver macro that `cd`s into the test folder (the suite keeps its + own working directory, so `os.chdir` is not enough) and sets `r[499]` on + its last line. A command error ends the whole macro run, so a flag that is + not set raises `MacroError`. `dataset()` / `dataset_2d()` return KUPLOT + data sets as NumPy arrays. +* `tests/python/test_suite_python.py`: expressions, error detection, crystal + build, 1-D Fourier, 2-D Fourier and Debye powder, run in-process. The + 1-D Fourier and powder results are compared with the legacy `RESULTS/` + files (R < 1e-3; actual about 1e-6) and all three with golden data. +* `tests/python/compare.py` and `tests/golden//` (`.npz` + `meta.json`): + first golden data for `02.1d`, `02.2d`, `02.powder`. Rewrite with + `DIFFUSE_UPDATE_GOLDEN=1`. +* `.github/workflows/tests.yml`: Ubuntu 24.04, apt dependencies, build with + `-DDIFFUSE_PYTHON=ON`, then pytest (`DIFFUSE_REQUIRE_PYTHON=1`, so a broken + module fails instead of skipping), then the legacy runner with + `--tags fast,mc`. JUnit XML and logs are uploaded. + +Limits of the f2py module that the tests work around (to fix in WP2): +`execute_macro` reports errors only as text; `set_value` only works on +user-defined variables, not `r[]`; data come back as single precision. + +Checked (gfortran 13, 4 cores): + +| Run | Result | +|---|---| +| `pytest tests/python`, `OMP_NUM_THREADS` 1 and 4 | 9 passed (33 legacy macro tests skipped, no `DISCUS_SUITE`), under 1 s | +| Same build, `run_legacy_tests.py -j 4 --tags fast,mc` | 29 PASS, 1 RAN, 2 SKIPPED | + +### Demo API: `python/diffuse/` (ahead of WP3/WP5) + +A first Python package for the demo, built on `suite_python`: +`read_structure()` (CIF, `.cell`, `.stru`, with supercells), `Crystal.atoms()`, +`powder()` returning NumPy arrays, `PowderPattern.plot()` with matplotlib, +and `run_macro()` for everything else. See `python/README.md`. + +* The test helper moved into the package (`diffuse/_session.py`), and the + `suite` fixture now returns `diffuse.session()`. The session also captures + DISCUS output (stdout/stderr go to a temporary file during each call, with + `GFORTRAN_UNBUFFERED_PRECONNECTED=y` so nothing is flushed late), and + `MacroError` carries the `***` error lines. +* `n[]` and `lat[]` are only defined inside the `discus` section; the read + macro copies them to `r[490]`–`r[496]`, which are reserved for the package + (`r[499]` is the completion flag). +* Reading a CIF makes DISCUS write a `.stru` file next to the input, so + inputs are copied to a scratch folder first. +* `python/examples/powder_demo.py`: anatase from `anatase.cif` (COD 1010942), + X-ray vs neutron and crystal-size broadening, saved as a PNG. Peak positions + were checked against the allowed I4₁/amd reflections ((101) strongest for + X-rays at Q = 1.81 Å⁻¹). +* `tests/python/test_diffuse_api.py`: 12 tests (reading, supercells, errors, + powder grid and (101) position, X-ray/neutron golden data, reloading an + older `Crystal`, plotting, the demo script). CI installs matplotlib. + +Checked: `pytest tests/python` gives 21 passed (33 legacy macro tests skipped +without `DISCUS_SUITE`), about 2 s, with `OMP_NUM_THREADS` 1 and 4. + +### Flaky Monte-Carlo test in CI + +CI run 2 failed on `04.sro3` (FAIL from its own check) with exactly the code +that passed in run 1; locally it passed 8 times in a row. MMC does not use +the value set with `seed` (known bug, task 0.5a), so tests tagged `mc` are +random and checked against statistical limits (R < 0.38, correlations +within ±0.08), and they can fail by chance. + +Until 0.5a is fixed, `run_legacy_tests.py --retry-mc N` re-runs a failed +`mc` test up to N times. A pass on retry is counted as PASS, with the +message `flaky: passed on retry k; first run ...` in the summary and the +JUnit report. A real regression fails every attempt, and the run still +fails. CI uses `--retry-mc 2`. Once `seed` works, the `mc` tests should get +fixed seeds and the retry should be removed. + +### 0.5a – `seed` (first half fixed) + +**Cause 1 (fixed): `seed` set only part of the generator state.** DISCUS uses +the Fortran intrinsic `random_number`. gfortran's state has 8 integers +(`random_seed(size=...)`). `ini_ran_ix` (`lib_f90/random_state_mod.f90`) +copied only the values the user gave (`seed 1234` gives one) and left the +other words at their clock-based values from start-up, so every run was +different. The remaining words are now derived from the user's values. + +**Cause 2 (open): OpenMP.** With threads, MMC is still not reproducible. +`random_number` keeps one state per thread, and `random_seed(put=...)` only +resets the calling thread's; the worker threads keep their own. The threads +also change the shared crystal while others evaluate their moves, so the +result depends on timing. A fix needs per-thread streams seeded from the +`seed` value, plus a fixed order for applying the moves. + +Checked with `04.SRO/SRO_0/sro.0.mac 0.7,1.5`, `seed` directly before the +macro, comparing `example0.stru`: + +| Setting | Same seed twice | Different seed | +|---|---|---| +| before the fix, `useomp:serial` | different | – | +| after the fix, `useomp:serial` | **identical** | different | +| after the fix, `nthreads:4` | different (cause 2) | different | + +The earlier test (section 1.3, finding 4) used `OMP_NUM_THREADS=1`, but the +SRO macros call `set parallel, nthreads:all`, which overrides it, so that +run was threaded. After the fix, `pytest tests/python` and the legacy runner +(`--tags fast,mc`) pass as before. + +### 0.5 – seeded Monte-Carlo tests + +`run_legacy_tests.py` now runs every test tagged `mc` with `seed 1234` (option +`--seed`, or a test's own `seed` in the manifest) and with +`OMP_THREAD_LIMIT=1`. The limit also caps `set parallel, nthreads:all` in the +SRO macros (DISCUS reports "maximum threads 1"). `--no-seed` gives the old +behaviour. Seeded tests run on one thread, so the `exclusive` tests no longer +need to run alone. + +Checked by running all 16 enabled `mc` tests twice (`--keep`) and comparing +every output file: **byte-identical** in both runs, apart from the generated +driver macro (it contains the work-folder path) and one `04.sro3` run, see +below. All pass with seed 1234. + +**New finding: rare broken Fourier result in `04.sro3`.** In one of the two +runs, `04.sro3` aborted. Its MC structure (`example3.stru`) was identical +to the other run's, but the Fourier step (`fourier.mac`: random `lots` +plus `set technique:nufft`) wrote 1530 `Infinity` values and blocks of zeros +to `example3.inte`, and NaN to `example3.3DPDF`; `kex3.mac` then failed on +`zmax[3]`. 14 more seeded runs (6 serial, 8 with 4 at a time) all gave the +same correct result, so it is rare (1 in about 17 so far). It may also +explain the original CI failure of `04.sro3` (run 2). Needs its own +investigation: uninitialised memory or a race in the lots/NUFFT path are +candidates. Until then, CI keeps `--retry-mc 2`. + diff --git a/python/CMakeLists.txt b/python/CMakeLists.txt index 62a3f4e2..18688f4f 100644 --- a/python/CMakeLists.txt +++ b/python/CMakeLists.txt @@ -5,7 +5,7 @@ find_package(F2PY REQUIRED) message(STATUS "F2PY included from: ${F2PY_INCLUDE_DIR}") -set(PYLINK_LIBS discus_suite_all diffev_all refine_all discus_all kuplot_all experi_all) +set(PYLINK_LIBS discus_suite_all diffev_all refine_all experi_all discus_all kuplot_all) set(PYLINK_LIBS ${PYLINK_LIBS} lib_f90 lib_f90c finufft_lib) set(PYLINK_LIBS ${PYLINK_LIBS} ${DIFFUSE_LIBS} ${MPI_Fortran_LIBRARIES}) set(PYLINK_LIBS ${PYLINK_LIBS} ${PGPLOT_PGPLOT_LIBRARY} ${X11_X11_LIB} ${PNG_LIBRARY} ${HDF5_LIBRARIES}) diff --git a/python/README.md b/python/README.md new file mode 100644 index 00000000..b17de2d1 --- /dev/null +++ b/python/README.md @@ -0,0 +1,119 @@ +# DiffuseCode from Python + +`python/diffuse/` is an early Python API for DISCUS. It currently covers a +small set of commands: reading a structure and calculating a powder pattern. +The results are NumPy arrays, so they can be plotted with matplotlib or any +other library. + +```python +import diffuse as dc + +cr = dc.read_structure("examples/anatase.cif", supercell=(10, 10, 4)) +print(cr) # Crystal('anatase.cif', supercell=(10, 10, 4), natoms=4800, ...) + +p = dc.powder(cr, qmin=0.5, qmax=10, dq=0.005, radiation="xray") +p.q, p.intensity # NumPy arrays +p.plot() # matplotlib; p.plot(x="tth") for 2-theta +``` + +The documentation (installation, API reference and an example gallery with +plots) is built from `docs/`; see "Documentation" below. + +## Running the demo + +Build DiffuseCode with the Python module (from the repository root): + +```bash +FC=gfortran CC=gcc CXX=g++ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \ + -DDIFFUSE_PYTHON=ON -DPGPLOT_DIR=/usr/lib/pgplot5 +``` + +```bash +cmake --build build -j +``` + +Then run the demo (needs NumPy and matplotlib): + +```bash +DIFFUSE_PYTHON_PATH=build/python PYTHONPATH=python python3 python/examples/powder_demo.py +``` + +It reads `examples/anatase.cif`, calculates X-ray and neutron patterns for a +10×10×4 supercell and an X-ray pattern for a 3×3×1 crystal, and shows the +plot. + +For Jupyter, set the two variables before starting it, or at the top of the +notebook before `import diffuse`: + +```python +import os, sys +os.environ["DIFFUSE_PYTHON_PATH"] = "/path/to/build/python" +sys.path.insert(0, "/path/to/DiffuseCode/python") +import diffuse as dc +``` + +## What is in the API + +| Call | What it does | +|---|---| +| `read_structure(path, supercell=None)` | Reads `.cif` or `.cell` (asymmetric unit; space group applied, `supercell` cells built) or `.stru` (whole crystal, read as is). Returns a `Crystal`. | +| `Crystal.natoms`, `.lattice`, `.volume` | Atom count, `(a, b, c, alpha, beta, gamma)`, cell volume | +| `Crystal.atoms()`, `.positions()` | Atom names and fractional coordinates as arrays | +| `powder(crystal, qmin, qmax, dq, radiation, wavelength, method, temperature, lp_correction)` | Powder pattern on a Q grid. `radiation`: `"xray"`, `"neutron"`, `"electron"`; `method`: `"debye"` or `"complete"`. Returns a `PowderPattern`. | +| `PowderPattern.q`, `.intensity`, `.two_theta()`, `.plot()` | Results and a quick matplotlib plot | +| `run_macro(text)` | Runs any DISCUS macro text, for commands that are not wrapped yet | +| `MacroError` | Raised when a DISCUS command fails; the message holds the `***` error lines | + +## How it works, and its limits + +This version drives the existing f2py module `suite_python` +(`python/suite_python.f90`). Python writes the commands to a small macro, +DISCUS runs it in the same process, and the results come back through +files or KUPLOT data sets. See `diffuse/_session.py`. + +* DISCUS holds **one structure at a time** per process. A `Crystal` remembers + how it was made, and `powder()` reads it in again if another structure was + loaded since. +* DISCUS output is captured, not printed. Set `DIFFUSE_ECHO=1`, or call + `dc.session(echo=True)`, to see it. The last output is in + `dc.session().last_output`. +* Input files are copied to a scratch folder first, because DISCUS writes + converted files (for example `.stru` from `.cif`) next to its input. + +The migration plan (`migration/DiffuseCode_Python_Migration_Plan.md`, +WP1–WP5) replaces `suite_python` underneath with a `bind(C)` core and a +proper `pip install`. The aim is to keep this API while doing so. + +## Documentation + +Sphinx sources are in `docs/`: Markdown pages, the API reference generated +from the docstrings (NumPy style), and a gallery made by running every script +in `python/examples/`. To build it: + +```bash +pip install -r docs/requirements.txt +``` + +```bash +DIFFUSE_PYTHON_PATH=build/python python3 -m sphinx -W -b html docs docs/_build/html +``` + +`DIFFUSE_DOCS_NO_GALLERY=1` skips the gallery (no compiled module needed); +`DIFFUSE_DOCS_OFFLINE=1` skips the links into the NumPy/matplotlib docs. +CI builds the docs on every push and keeps the HTML as the `docs-html` +artifact of the run. Pushes to `claude-python-app` also publish them at +https://tproffen.github.io/DiffuseCode/python-docs/. The `gh-pages` branch +is the DISCUS homepage, so `tools/publish_docs.sh` only replaces the +`python-docs/` folder (plus an empty `.nojekyll` at the root, which Sphinx +output needs) and refuses to publish if anything else would change. The +docs are not linked from the homepage. + +When adding to the API: give every public function a NumPy-style docstring +(Parameters, Returns, Raises, Examples), list it in `docs/api.md`, and add an +example script to `python/examples/` for each new capability (it becomes a +gallery page and is run by the tests). + +## Tests + +`tests/python/test_diffuse_api.py` covers this API, and CI runs it together +with the demo script. See `tests/README.md`. diff --git a/python/diffuse/__init__.py b/python/diffuse/__init__.py new file mode 100644 index 00000000..e243a317 --- /dev/null +++ b/python/diffuse/__init__.py @@ -0,0 +1,27 @@ +"""DiffuseCode from Python (early demo API). + + import diffuse as dc + + cr = dc.read_structure("anatase.cif", supercell=(6, 6, 3)) + p = dc.powder(cr, qmin=0.5, qmax=10, dq=0.005, radiation="xray") + p.plot() + +This first version drives DISCUS through the f2py module ``suite_python`` +(build with ``-DDIFFUSE_PYTHON=ON`` and set ``DIFFUSE_PYTHON_PATH`` to +``/python``). DISCUS holds one structure at a time, in this process. +See migration/DiffuseCode_Python_Migration_Plan.md for where this is going. +""" + +from ._session import DiffuseError, MacroError, Session, session +from .crystal import Crystal, read_structure +from .powder import PowderPattern, powder + +__all__ = [ + "Crystal", "DiffuseError", "MacroError", "PowderPattern", "Session", + "powder", "read_structure", "run_macro", "session", +] + + +def run_macro(commands: str, cwd=None) -> str: + """Run DISCUS macro text (escape hatch for commands not wrapped yet).""" + return session().run(commands, cwd) diff --git a/python/diffuse/_session.py b/python/diffuse/_session.py new file mode 100644 index 00000000..5fa33c56 --- /dev/null +++ b/python/diffuse/_session.py @@ -0,0 +1,214 @@ +"""The one DISCUS suite that lives in this Python process. + +For now everything runs through the f2py module ``suite_python`` (built with +``-DDIFFUSE_PYTHON=ON``): Python writes the commands to a small macro and +the suite runs it. The planned bind(C) core (migration plan, WP2) will +replace this module; the public API in ``diffuse`` is meant to stay the same. + +What this layer adds on top of ``suite_python``: + +* **Errors become exceptions.** A command error ends the whole macro run. + Every macro written here sets a flag on its last line; if the flag is not + set, ``run()`` raises ``MacroError`` with the ``***...***`` error lines. +* **Output is captured.** The suite writes to the process's stdout/stderr. + ``run()`` sends both file descriptors to a temporary file while the macro + runs, and keeps the text in ``Session.last_output``. Pass ``echo=True`` + (or set ``DIFFUSE_ECHO=1``) to print it as well. +* **Working directory.** The suite keeps its own working directory, so each + macro starts with ``cd ``. +""" + +from __future__ import annotations + +import atexit +import importlib +import itertools +import os +import re +import shutil +import sys +import tempfile +from pathlib import Path + +import numpy as np + +# Must be set before libgfortran is loaded, so that output written while +# stdout is redirected is not flushed later, after it has been restored. +os.environ.setdefault("GFORTRAN_UNBUFFERED_PRECONNECTED", "y") + +# r[] runs from 0 to MAXPAR = 500 (lib_f90/param_mod.f90); the top entry is +# reserved for the completion flag. +FLAG = "r[499]" +_ANSI = re.compile(r"\x1b\[[0-9;]*m") + + +class DiffuseError(RuntimeError): + """Base class for errors raised by the diffuse package.""" + + +class MacroError(DiffuseError): + """A command failed inside DISCUS. + + The message holds DISCUS's ``***`` error lines; ``output`` holds all + the text DISCUS wrote during the failed call. + """ + + def __init__(self, message: str, output: str = ""): + super().__init__(message) + self.output = output + + +def _import_suite_python(): + path = os.environ.get("DIFFUSE_PYTHON_PATH") + if path and path not in sys.path: + sys.path.insert(0, path) + try: + return importlib.import_module("suite_python").suite + except ImportError as exc: + raise ImportError( + "The DISCUS Python module 'suite_python' was not found. Build " + "DiffuseCode with -DDIFFUSE_PYTHON=ON and set " + "DIFFUSE_PYTHON_PATH=/python.") from exc + + +class _Capture: + """Send file descriptors 1 and 2 to a temporary file. + + ``flush`` writes out what the Fortran runtime still buffers. Setting + GFORTRAN_UNBUFFERED_PRECONNECTED is not enough on its own: libgfortran + reads it once, when it is first loaded, and NumPy (through OpenBLAS) may + have loaded it before this module. + """ + + def __init__(self, flush=None): + self.text = "" + self._flush = flush + + def __enter__(self): + if self._flush is not None: + self._flush() # output from before the capture + sys.stdout.flush() + sys.stderr.flush() + self._file = tempfile.TemporaryFile(mode="w+b") + self._saved = [os.dup(1), os.dup(2)] + os.dup2(self._file.fileno(), 1) + os.dup2(self._file.fileno(), 2) + return self + + def __exit__(self, *exc): + if self._flush is not None: + self._flush() + os.dup2(self._saved[0], 1) + os.dup2(self._saved[1], 2) + for fd in self._saved: + os.close(fd) + self._file.seek(0) + self.text = _ANSI.sub("", self._file.read().decode(errors="replace")) + self._file.close() + return False + + +class Session: + """Wrapper around the in-process DISCUS suite. Use ``diffuse.session()``.""" + + def __init__(self, echo: bool | None = None): + self.echo = bool(os.environ.get("DIFFUSE_ECHO")) if echo is None else echo + self.last_output = "" + self._s = _import_suite_python() + self._count = itertools.count() + self._workdir = Path(tempfile.mkdtemp(prefix="diffuse_")) + atexit.register(shutil.rmtree, self._workdir, ignore_errors=True) + self.current_crystal = None # the Crystal now held by DISCUS + # flush_output() is in suite_python.f90 since the demo API; builds + # without it rely on GFORTRAN_UNBUFFERED_PRECONNECTED alone. + self._flush = getattr(self._s, "flush_output", None) + with self._capture() as cap: + self._s.initialize_suite() + self._show(cap.text) + + def _capture(self) -> _Capture: + return _Capture(self._flush) + + def _show(self, text: str) -> None: + self.last_output = text + if self.echo and text: + print(text, end="" if text.endswith("\n") else "\n") + + @property + def workdir(self) -> Path: + """Scratch folder for files written by DISCUS.""" + return self._workdir + + def run(self, commands: str, cwd: str | os.PathLike | None = None) -> str: + """Run macro text with ``cwd`` as working directory; return the output. + + Raises MacroError if a command error stopped the macro. + """ + cwd = Path(cwd or self._workdir).resolve() + driver = self._workdir / f"_driver_{next(self._count)}.mac" + driver.write_text( + f"cd {cwd}\n" + f"{FLAG} = 0\n" + f"{commands.strip()}\n" + f"{FLAG} = 1\n") + with self._capture() as cap: + self._s.execute_macro("@" + str(driver)) + ok = self._s.get_value(FLAG) == 1.0 + self._show(cap.text) + if not ok: + errors = [line.strip() for line in cap.text.splitlines() if "***" in line] + raise MacroError("DISCUS command failed:\n " + "\n ".join(errors or ["(no message)"]), + cap.text) + return cap.text + + def value(self, expression: str) -> float: + """Value of a DISCUS expression, e.g. ``n[1]`` or ``lat[1]``.""" + with self._capture() as cap: + v = float(self._s.get_value(expression)) + if "***" in cap.text: + raise MacroError(f"cannot evaluate '{expression}':\n " + cap.text.strip(), cap.text) + return v + + # -- KUPLOT data sets ------------------------------------------------- + def n_datasets(self) -> int: + return int(self._s.get_data_sets()) + + def dataset(self, ik: int) -> tuple[np.ndarray, np.ndarray]: + """KUPLOT data set ``ik`` (1-based) as float32 arrays ``(x, y)``.""" + self._check_ik(ik) + n = int(self._s.get_data_length(ik)) + x = np.empty(n, np.float32) + y = np.empty(n, np.float32) + self._s.get_data(ik, x, y) + return x, y + + def dataset_2d(self, ik: int) -> tuple[np.ndarray, np.ndarray, np.ndarray]: + """KUPLOT grid data set ``ik`` as ``(x[nx], y[ny], z[nx, ny])``.""" + self._check_ik(ik) + n = int(self._s.get_data_length(ik)) + x, y, z = (np.empty(n, np.float32) for _ in range(3)) + nx = np.zeros(1, np.int32) + ny = np.zeros(1, np.int32) + self._s.get_data_3d(ik, x, y, z, nx, ny) + nx, ny = int(nx[0]), int(ny[0]) + if nx * ny != n: + raise ValueError(f"data set {ik} is not a grid ({nx} x {ny} != {n})") + return x[::ny].copy(), y[:ny].copy(), z.reshape(nx, ny) + + def _check_ik(self, ik: int) -> None: + if not 1 <= ik <= self.n_datasets(): + raise IndexError(f"KUPLOT data set {ik} does not exist " + f"({self.n_datasets()} loaded)") + + +_SESSION: Session | None = None + + +def session(echo: bool | None = None) -> Session: + """The process-wide Session (created on first use).""" + global _SESSION + if _SESSION is None: + _SESSION = Session(echo=echo) + elif echo is not None: + _SESSION.echo = echo + return _SESSION diff --git a/python/diffuse/crystal.py b/python/diffuse/crystal.py new file mode 100644 index 00000000..b81edaa2 --- /dev/null +++ b/python/diffuse/crystal.py @@ -0,0 +1,198 @@ +"""Reading structures into DISCUS.""" + +from __future__ import annotations + +import os +import shutil +from dataclasses import dataclass, field +from pathlib import Path + +import numpy as np + +from ._session import DiffuseError, session + +# Files that DISCUS reads as an asymmetric unit (then applies the space +# group and builds the supercell) and files it reads as a whole crystal. +_CELL_SUFFIXES = {".cell", ".cif"} +_STRU_SUFFIXES = {".stru"} + + +@dataclass(eq=False) +class Crystal: + """A structure loaded into DISCUS. Create it with :func:`read_structure`. + + DISCUS holds one structure at a time. A ``Crystal`` remembers how it was + made, so a calculation on an older ``Crystal`` reads it in again first. + + Attributes + ---------- + path : pathlib.Path + The structure file it was read from. + supercell : tuple of int or None + Number of unit cells along a, b and c, or None for a ``.stru`` file + read as it is. + natoms : int + Number of atoms in the whole crystal. + lattice : tuple of float + ``(a, b, c, alpha, beta, gamma)`` in Å and degrees. + """ + + path: Path + supercell: tuple[int, int, int] | None + natoms: int + lattice: tuple[float, float, float, float, float, float] # a, b, c, alpha, beta, gamma + _atoms: tuple[np.ndarray, np.ndarray] | None = field(default=None, repr=False) + + @property + def a(self) -> float: + """Lattice parameter a in Å.""" + return self.lattice[0] + + @property + def volume(self) -> float: + """Volume of one unit cell in Å^3.""" + a, b, c, al, be, ga = self.lattice + ca, cb, cg = np.cos(np.radians([al, be, ga])) + return float(a * b * c * np.sqrt(1 - ca**2 - cb**2 - cg**2 + 2 * ca * cb * cg)) + + def atoms(self) -> tuple[np.ndarray, np.ndarray]: + """Atom names and fractional coordinates. + + Returns + ------- + names : numpy.ndarray of str, shape (natoms,) + Atom names as DISCUS uses them, for example ``"TI4+"``. + xyz : numpy.ndarray of float, shape (natoms, 3) + Fractional coordinates in units of the unit cell. + + Notes + ----- + DISCUS saves the crystal to a ``.stru`` file, which is read back. + The result is cached on the ``Crystal``. + """ + if self._atoms is None: + _ensure_loaded(self) + s = session() + out = s.workdir / "atoms.stru" + out.unlink(missing_ok=True) + s.run(f"discus\n save\n outfile {out.name}\n write all\n run\n exit\nexit", + cwd=s.workdir) + lines = out.read_text().splitlines() + start = next(i for i, line in enumerate(lines) if line.split()[:1] == ["atoms"]) + 1 + rows = [line.replace(",", " ").split() for line in lines[start:] if line.strip()] + names = np.array([r[0] for r in rows]) + xyz = np.array([[float(v) for v in r[1:4]] for r in rows]) + if len(names) != self.natoms: + raise DiffuseError(f"saved structure has {len(names)} atoms, expected {self.natoms}") + self._atoms = (names, xyz) + return self._atoms + + def positions(self) -> np.ndarray: + """Fractional coordinates, shape (natoms, 3). See :meth:`atoms`.""" + return self.atoms()[1] + + def __repr__(self) -> str: + cell = ", ".join(f"{v:g}" for v in self.lattice) + sc = f", supercell={self.supercell}" if self.supercell else "" + return f"Crystal('{self.path.name}'{sc}, natoms={self.natoms}, lattice=({cell}))" + + +def read_structure(path: str | os.PathLike, + supercell: tuple[int, int, int] | int | None = None) -> Crystal: + """Read a structure file into DISCUS. + + Parameters + ---------- + path : str or os.PathLike + A ``.cif`` or ``.cell`` file (an asymmetric unit: DISCUS applies the + space group) or a ``.stru`` file (a whole crystal). + supercell : int or tuple of 3 int, optional + Number of unit cells along a, b and c; an int means the same along + all three. Default: 1 x 1 x 1 for ``.cif``/``.cell``, and a ``.stru`` + file is read as it is. + + Returns + ------- + Crystal + The structure, now held by DISCUS. + + Raises + ------ + FileNotFoundError + If ``path`` does not exist. + DiffuseError + If the file type is not supported. + MacroError + If DISCUS cannot read the file. + + Examples + -------- + >>> import diffuse as dc + >>> cr = dc.read_structure("anatase.cif", supercell=(10, 10, 4)) # doctest: +SKIP + >>> cr.natoms # doctest: +SKIP + 4800 + """ + path = Path(path).expanduser().resolve() + if not path.is_file(): + raise FileNotFoundError(path) + suffix = path.suffix.lower() + if suffix not in _CELL_SUFFIXES | _STRU_SUFFIXES: + raise DiffuseError(f"unsupported structure file '{path.name}' " + f"(use {', '.join(sorted(_CELL_SUFFIXES | _STRU_SUFFIXES))})") + if isinstance(supercell, int): + supercell = (supercell,) * 3 + if supercell is not None: + supercell = tuple(int(n) for n in supercell) + if len(supercell) != 3 or min(supercell) < 1: + raise ValueError(f"supercell must be three positive integers, not {supercell}") + + if suffix in _STRU_SUFFIXES and supercell is None: + command = f"stru {path.name}" + else: + nx, ny, nz = supercell or (1, 1, 1) + command = f"cell {path.name}, {nx}, {ny}, {nz}" + + # DISCUS may write files next to the input (a CIF is converted to .stru + # first), so read a copy in the session's scratch folder. + s = session() + inputs = s.workdir / "input" + shutil.rmtree(inputs, ignore_errors=True) + inputs.mkdir() + shutil.copy(path, inputs / ("structure" + suffix)) + command = command.replace(path.name, "structure" + suffix, 1) + + # n[] and lat[] exist only inside the discus section: copy them to the + # r[] entries reserved for this package (r[490] ... r[498]). + s.run(f""" +discus + read + {command} + r[490] = n[1] + r[491] = lat[1] + r[492] = lat[2] + r[493] = lat[3] + r[494] = lat[4] + r[495] = lat[5] + r[496] = lat[6] +exit +""", cwd=inputs) + crystal = Crystal( + path=path, + supercell=supercell, + natoms=int(s.value("r[490]")), + lattice=tuple(s.value(f"r[{i}]") for i in range(491, 497)), + ) + s.current_crystal = crystal + return crystal + + +def _ensure_loaded(crystal: Crystal) -> None: + """Make ``crystal`` the structure DISCUS holds, reading it again if needed.""" + s = session() + if s.current_crystal is crystal: + return + fresh = read_structure(crystal.path, crystal.supercell) + if fresh.natoms != crystal.natoms: + raise DiffuseError(f"{crystal.path.name} now gives {fresh.natoms} atoms, " + f"not {crystal.natoms}; has the file changed?") + s.current_crystal = crystal diff --git a/python/diffuse/powder.py b/python/diffuse/powder.py new file mode 100644 index 00000000..7a903bce --- /dev/null +++ b/python/diffuse/powder.py @@ -0,0 +1,167 @@ +"""Powder diffraction patterns.""" + +from __future__ import annotations + +from dataclasses import dataclass, field + +import numpy as np + +from ._session import session +from .crystal import Crystal, _ensure_loaded + +_RADIATION = {"xray": "xray", "x-ray": "xray", "neutron": "neutron", "electron": "electron"} +_METHOD = {"debye": "debye", "complete": "compl"} + + +@dataclass +class PowderPattern: + """A calculated powder pattern on an evenly spaced Q grid. See :func:`powder`. + + Attributes + ---------- + q : numpy.ndarray + Momentum transfer Q in Å⁻¹. + intensity : numpy.ndarray + Intensity at each Q, arbitrary units. + settings : dict + The arguments the pattern was calculated with. + crystal : Crystal or None + The structure it was calculated for. + """ + + q: np.ndarray # Å^-1 + intensity: np.ndarray + settings: dict = field(default_factory=dict) + crystal: Crystal | None = None + + def two_theta(self, wavelength: float | None = None) -> np.ndarray: + """Scattering angle 2θ in degrees. + + Parameters + ---------- + wavelength : float, optional + Wavelength in Å. Default: the one the pattern was calculated with. + """ + lam = wavelength or self.settings["wavelength"] + return np.degrees(2 * np.arcsin(np.clip(self.q * lam / (4 * np.pi), -1, 1))) + + def plot(self, ax=None, *, x: str = "q", **kwargs): + """Plot the pattern with matplotlib. + + Parameters + ---------- + ax : matplotlib.axes.Axes, optional + Axes to draw into. Default: a new figure. + x : {"q", "tth"} + Plot against Q or against 2θ. + **kwargs + Passed on to :meth:`matplotlib.axes.Axes.plot`. + + Returns + ------- + matplotlib.axes.Axes + """ + import matplotlib.pyplot as plt + + if ax is None: + _, ax = plt.subplots(figsize=(8, 4.5)) + if x == "q": + xs, label = self.q, r"$Q$ (Å$^{-1}$)" + elif x == "tth": + xs, label = self.two_theta(), r"$2\theta$ (°)" + f", λ = {self.settings['wavelength']} Å" + else: + raise ValueError("x must be 'q' or 'tth'") + kwargs.setdefault("lw", 1.0) + kwargs.setdefault("label", self.crystal.path.stem if self.crystal else None) + ax.plot(xs, self.intensity, **kwargs) + ax.set_xlabel(label) + ax.set_ylabel("Intensity (arb. units)") + ax.set_xlim(xs[0], xs[-1]) + return ax + + +def powder(crystal: Crystal, *, qmin: float = 0.5, qmax: float = 10.0, dq: float = 0.005, + radiation: str = "xray", wavelength: float = 0.2, method: str = "debye", + temperature: bool = True, lp_correction: str = "none") -> PowderPattern: + """Calculate the powder pattern of a crystal with DISCUS. + + Parameters + ---------- + crystal : Crystal + The structure, from :func:`read_structure`. + qmin, qmax, dq : float + Q range and step in Å⁻¹. + radiation : {"xray", "neutron", "electron"} + Radiation type; selects the atomic form factors or scattering lengths. + wavelength : float + Wavelength in Å, used for the Lorentz-polarisation factor and for + :meth:`PowderPattern.two_theta`. + method : {"debye", "complete"} + ``"debye"``: Debye equation, for any structure, including finite + particles. ``"complete"``: Fourier transform on a reciprocal-space + grid, for periodic crystals. + temperature : bool + Apply the atomic displacement parameters. + lp_correction : {"none", "bragg", "neutron"} + Lorentz-polarisation correction. + + Returns + ------- + PowderPattern + + Raises + ------ + ValueError + For an unknown ``radiation`` or ``method``, or an invalid Q range. + MacroError + If the calculation fails inside DISCUS. + + Examples + -------- + >>> p = dc.powder(cr, qmin=0.5, qmax=10, dq=0.005, radiation="neutron") # doctest: +SKIP + >>> p.plot() # doctest: +SKIP + """ + try: + rad = _RADIATION[radiation.lower()] + calc = _METHOD[method.lower()] + except KeyError as exc: + raise ValueError(f"unknown option {exc}; radiation: {sorted(set(_RADIATION))}, " + f"method: {sorted(_METHOD)}") from None + if not 0 < qmin < qmax or dq <= 0: + raise ValueError("need 0 < qmin < qmax and dq > 0") + + _ensure_loaded(crystal) + s = session() + out = s.workdir / "powder.dat" + out.unlink(missing_ok=True) + s.run(f""" +discus + powder + reset + {rad} + set axis, q + set calc, {calc} + set disp, off + set delta, 0.0 + set qmin, {qmin} + set qmax, {qmax} + set dq, {dq} + set profile, off + set temp, {"use" if temperature else "ignore"} + set wvle, {wavelength} + set four, four + set lpcor, {lp_correction} + run + exit + output + outf {out.name} + value inte + form powder, q + run + exit +exit +""", cwd=s.workdir) + data = np.loadtxt(out, comments="#", ndmin=2) + settings = dict(qmin=qmin, qmax=qmax, dq=dq, radiation=rad, wavelength=wavelength, + method=method, temperature=temperature, lp_correction=lp_correction) + return PowderPattern(q=data[:, 0], intensity=data[:, 1], settings=settings, crystal=crystal) diff --git a/python/examples/README.rst b/python/examples/README.rst new file mode 100644 index 00000000..541c5d8c --- /dev/null +++ b/python/examples/README.rst @@ -0,0 +1,5 @@ +Examples +======== + +Short scripts that use the ``diffuse`` package. Each one runs DISCUS when the +documentation is built, so the output and plots here are real results. diff --git a/python/examples/anatase.cif b/python/examples/anatase.cif new file mode 100644 index 00000000..3fb0c357 --- /dev/null +++ b/python/examples/anatase.cif @@ -0,0 +1,101 @@ +#------------------------------------------------------------------------------ +#$Date: 2016-02-18 15:37:37 +0000 (Thu, 18 Feb 2016) $ +#$Revision: 176729 $ +#$URL: file:///home/coder/svn-repositories/cod/cif/1/01/09/1010942.cif $ +#------------------------------------------------------------------------------ +# +# This file is available in the Crystallography Open Database (COD), +# http://www.crystallography.net/ +# +# All data on this site have been placed in the public domain by the +# contributors. +# +data_1010942 +loop_ +_publ_author_name +'Parker, R L' +_publ_section_title +; +Zur Kristallstruktur von Anastas und Rutil. (II. Teil. Die +Anastasstruktur). +; +_journal_coden_ASTM ZEKGAX +_journal_name_full +; +Zeitschrift fuer Kristallographie, Kristallgeometrie, Kristallphysik, +Kristallchemie (-144,1977) +; +_journal_page_first 1 +_journal_page_last 54 +_journal_volume 59 +_journal_year 1924 +_chemical_formula_structural 'Ti O2' +_chemical_formula_sum 'O2 Ti' +_chemical_name_mineral Anatase +_chemical_name_systematic 'Titanium oxide' +_space_group_IT_number 141 +_symmetry_cell_setting tetragonal +_symmetry_space_group_name_Hall 'I 4bw 2bw -1bw' +_symmetry_space_group_name_H-M 'I 41/a m d ' +_cell_angle_alpha 90 +_cell_angle_beta 90 +_cell_angle_gamma 90 +_cell_formula_units_Z 4 +_cell_length_a 3.73 +_cell_length_b 3.73 +_cell_length_c 9.37 +_cell_volume 130.4 +_cod_original_sg_symbol_H-M 'I 41/a m d S' +_cod_database_code 1010942 +loop_ +_symmetry_equiv_pos_as_xyz +x,y,z +-x,-y,z +x,1/2+y,1/4-z +-x,1/2-y,1/4-z +-x,y,z +x,-y,z +-x,1/2+y,1/4-z +x,1/2-y,1/4-z +y,x,-z +-y,-x,-z +y,1/2+x,1/4+z +-y,1/2-x,1/4+z +-y,x,-z +y,-x,-z +-y,1/2+x,1/4+z +y,1/2-x,1/4+z +1/2+x,1/2+y,1/2+z +1/2-x,1/2-y,1/2+z +1/2+x,y,3/4-z +1/2-x,-y,3/4-z +1/2-x,1/2+y,1/2+z +1/2+x,1/2-y,1/2+z +1/2-x,y,3/4-z +1/2+x,-y,3/4-z +1/2+y,1/2+x,1/2-z +1/2-y,1/2-x,1/2-z +1/2+y,x,3/4+z +1/2-y,-x,3/4+z +1/2-y,1/2+x,1/2-z +1/2+y,1/2-x,1/2-z +1/2-y,x,3/4+z +1/2+y,-x,3/4+z +loop_ +_atom_site_label +_atom_site_type_symbol +_atom_site_symmetry_multiplicity +_atom_site_Wyckoff_symbol +_atom_site_fract_x +_atom_site_fract_y +_atom_site_fract_z +_atom_site_occupancy +_atom_site_attached_hydrogens +_atom_site_calc_flag +Ti1 Ti4+ 4 a 0. 0. 0. 1. 0 d +O1 O2- 8 e 0. 0. 0.2 1. 0 d +loop_ +_atom_type_symbol +_atom_type_oxidation_number +Ti4+ 4.000 +O2- -2.000 diff --git a/python/examples/powder_demo.py b/python/examples/powder_demo.py new file mode 100644 index 00000000..063ebc76 --- /dev/null +++ b/python/examples/powder_demo.py @@ -0,0 +1,78 @@ +""" +Powder patterns of anatase +========================== + +Read a CIF file, let DISCUS build a supercell, calculate X-ray and neutron +powder patterns with the Debye equation, and plot them with matplotlib. + +The structure is anatase (TiO\\ :sub:`2`), COD entry 1010942 +(``python/examples/anatase.cif``). + +To run it yourself, from the repository root:: + + DIFFUSE_PYTHON_PATH=build/python PYTHONPATH=python python3 python/examples/powder_demo.py +""" + +from pathlib import Path + +import matplotlib.pyplot as plt + +import diffuse as dc + +# sphinx_gallery_start_ignore +try: + HERE = Path(__file__).resolve().parent +except NameError: # the docs gallery runs examples from their folder + HERE = Path.cwd() +# sphinx_gallery_end_ignore +CIF = HERE / "anatase.cif" + +# %% +# Read the structure +# ------------------ +# A CIF file holds the asymmetric unit. DISCUS applies the space group +# (I4\ :sub:`1`/amd) and builds 10 x 10 x 4 unit cells. + +crystal = dc.read_structure(CIF, supercell=(10, 10, 4)) +print(crystal) + +# %% +# Calculate powder patterns +# ------------------------- +# The results are NumPy arrays (``q`` and ``intensity``), so any plotting or +# analysis library can use them. + +xray = dc.powder(crystal, qmin=0.5, qmax=10, dq=0.005, radiation="xray") +neutron = dc.powder(crystal, qmin=0.5, qmax=10, dq=0.005, radiation="neutron") +print(f"{len(xray.q)} points from Q = {xray.q[0]} to {xray.q[-1]} Å⁻¹") + +# %% +# A much smaller crystal of the same structure shows how the crystal size +# broadens the peaks. + +small = dc.read_structure(CIF, supercell=(3, 3, 1)) +xray_small = dc.powder(small, qmin=0.5, qmax=10, dq=0.005, radiation="xray") + +# %% +# Plot +# ---- +# X-rays see mostly titanium; neutrons see oxygen much more strongly, so the +# relative peak heights change. + +fig, (top, bottom) = plt.subplots(2, 1, figsize=(9, 7), sharex=True, + constrained_layout=True) +top.plot(xray.q, xray.intensity / xray.intensity.max(), lw=1, label="X-ray") +top.plot(neutron.q, neutron.intensity / neutron.intensity.max(), lw=1, label="neutron") +top.set_title(f"Anatase, 10×10×4 unit cells ({crystal.natoms} atoms)") +top.set_ylabel("Intensity (normalised)") +top.legend() + +for p, label in ((xray, f"{crystal.natoms} atoms"), (xray_small, f"{small.natoms} atoms")): + bottom.plot(p.q, p.intensity / p.intensity.max(), lw=1, label=label) +bottom.set_title("X-ray: crystal size broadens the peaks") +bottom.set_xlabel(r"$Q$ (Å$^{-1}$)") +bottom.set_ylabel("Intensity (normalised)") +bottom.set_xlim(xray.q[0], xray.q[-1]) +bottom.legend() + +plt.show() diff --git a/python/suite_python.f90 b/python/suite_python.f90 index 3135aa52..7b71e3a9 100644 --- a/python/suite_python.f90 +++ b/python/suite_python.f90 @@ -34,6 +34,7 @@ MODULE suite PUBLIC get_data_length ! Returns length of KUPLOT data set ik PUBLIC get_data_sets ! Returns number of loaded KUPLOT data sets public python_error +PUBLIC flush_output ! Flush the Fortran output units (for Python output capture) ! CONTAINS !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! @@ -318,4 +319,25 @@ SUBROUTINE python_error(num) ! END SUBROUTINE python_error ! +! +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +! +SUBROUTINE flush_output() +! +! Write out anything the Fortran runtime still holds for the output and +! error units. Python redirects these file descriptors to capture the +! text; buffered output would otherwise appear later, outside the capture. +! +USE prompt_mod +USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY: OUTPUT_UNIT, ERROR_UNIT +! +IMPLICIT NONE +! +FLUSH(OUTPUT_UNIT) +FLUSH(ERROR_UNIT) +IF(output_io /= OUTPUT_UNIT .AND. output_io /= ERROR_UNIT) FLUSH(output_io) +IF(error_io /= OUTPUT_UNIT .AND. error_io /= ERROR_UNIT) FLUSH(error_io) +! +END SUBROUTINE flush_output +! END MODULE suite diff --git a/tests/README.md b/tests/README.md index 2a85cb43..49ded9f3 100644 --- a/tests/README.md +++ b/tests/README.md @@ -37,6 +37,8 @@ Useful options: | `--id '04.*'` | only tests whose id matches (repeatable) | | `--junit FILE`, `--json FILE` | machine-readable reports | | `--workdir DIR`, `--keep` | where copies and logs go; keep passing tests' copies too | +| `--seed N`, `--no-seed` | tests tagged `mc` run with `seed N` (default 1234; a test's own `seed` in the manifest wins) on one OpenMP thread, so they repeat exactly; `--no-seed` runs them unseeded with their own thread settings | +| `--retry-mc N` | re-run a failed test tagged `mc` up to N times; a pass on retry is reported as `flaky` (MMC ignores `seed`, WP0 0.5a) | | `--list` | show what would run | | `--check-test-all` | check that `manifest.toml` and `test_all.mac` list the same macros | @@ -75,6 +77,41 @@ DISCUS_SUITE=/path/to/discus_suite pytest tests/python -m "not slow" Without `DISCUS_SUITE` only the manifest checks run. +## 3. Python: `tests/python/test_suite_python.py`, `test_diffuse_api.py` + +Run DISCUS in-process through the f2py module `suite_python` and check the +results as NumPy arrays, against the legacy `RESULTS/` files and against +golden data in `tests/golden//`. `test_diffuse_api.py` tests the +`diffuse` package (`python/diffuse/`, see `python/README.md`) and the demo +script `python/examples/powder_demo.py` (needs matplotlib). Build with `-DDIFFUSE_PYTHON=ON`, then: + +```bash +DIFFUSE_PYTHON_PATH=/path/to/build/python pytest tests/python +``` + +| Variable | Meaning | +|---|---| +| `DIFFUSE_PYTHON_PATH` | folder that holds `suite_python*.so` (`/python`) | +| `DIFFUSE_REQUIRE_PYTHON=1` | fail instead of skip if the module cannot be imported (used in CI) | +| `DIFFUSE_UPDATE_GOLDEN=1` | write the golden files instead of comparing; review the diff before committing | + +To add a test, use the `suite` fixture (the session from `diffuse.session()`) or +the `diffuse` functions directly. `suite.run(commands, folder)` runs +macro text with `folder` as working directory and raises `MacroError` if a +command fails; `suite.value("n[1]")` evaluates an expression; +`suite.dataset(1)` / `suite.dataset_2d(1)` return KUPLOT data set 1. Load +results into KUPLOT (`kuplot`, `rese`, `load ...`) to read them back. +`compare.check_golden(id, name, r_max=..., axis..., result)` handles golden +data. The Fortran state is global and shared by all tests in one pytest run, +so start each calculation with the relevant `reset`. + +## CI + +`.github/workflows/tests.yml` builds with the Python module and runs the +pytest tests, then the legacy tests tagged `fast` and `mc`, on every push to +`claude-python-app` (and `claude/**` branches) and on pull requests into +`claude-python-app`. + ## Adding a test 1. Write the macro so that it sets `LTEST_MAC = TRUE` when its result is diff --git a/tests/golden/02.1d/fourier_1d.npz b/tests/golden/02.1d/fourier_1d.npz new file mode 100644 index 00000000..94f0268c Binary files /dev/null and b/tests/golden/02.1d/fourier_1d.npz differ diff --git a/tests/golden/02.1d/meta.json b/tests/golden/02.1d/meta.json new file mode 100644 index 00000000..deb7e537 --- /dev/null +++ b/tests/golden/02.1d/meta.json @@ -0,0 +1,10 @@ +{ + "fourier_1d": { + "date": "2026-11-16T16:05:43+00:00", + "git_commit": "2e9a50e24ca1b5ec09811a2298577a44e123e10d", + "machine": "x86_64", + "numpy": "2.5.3", + "platform": "Linux-6.18.44-fc-v470-x86_64-with-glibc2.39", + "r_max": 1e-05 + } +} diff --git a/tests/golden/02.2d/fourier_2d.npz b/tests/golden/02.2d/fourier_2d.npz new file mode 100644 index 00000000..5255c681 Binary files /dev/null and b/tests/golden/02.2d/fourier_2d.npz differ diff --git a/tests/golden/02.2d/meta.json b/tests/golden/02.2d/meta.json new file mode 100644 index 00000000..bba55e2c --- /dev/null +++ b/tests/golden/02.2d/meta.json @@ -0,0 +1,10 @@ +{ + "fourier_2d": { + "date": "2026-11-16T16:05:43+00:00", + "git_commit": "2e9a50e24ca1b5ec09811a2298577a44e123e10d", + "machine": "x86_64", + "numpy": "2.5.3", + "platform": "Linux-6.18.44-fc-v470-x86_64-with-glibc2.39", + "r_max": 1e-05 + } +} diff --git a/tests/golden/02.powder/meta.json b/tests/golden/02.powder/meta.json new file mode 100644 index 00000000..b405025a --- /dev/null +++ b/tests/golden/02.powder/meta.json @@ -0,0 +1,10 @@ +{ + "powder_debye": { + "date": "2026-11-16T16:05:44+00:00", + "git_commit": "2e9a50e24ca1b5ec09811a2298577a44e123e10d", + "machine": "x86_64", + "numpy": "2.5.3", + "platform": "Linux-6.18.44-fc-v470-x86_64-with-glibc2.39", + "r_max": 1e-05 + } +} diff --git a/tests/golden/02.powder/powder_debye.npz b/tests/golden/02.powder/powder_debye.npz new file mode 100644 index 00000000..a18fa5c4 Binary files /dev/null and b/tests/golden/02.powder/powder_debye.npz differ diff --git a/tests/golden/api.powder_anatase/meta.json b/tests/golden/api.powder_anatase/meta.json new file mode 100644 index 00000000..aab0e785 --- /dev/null +++ b/tests/golden/api.powder_anatase/meta.json @@ -0,0 +1,18 @@ +{ + "neutron_debye": { + "date": "2026-11-16T16:22:21+00:00", + "git_commit": "3dc76f37aa560abc94b0f41f89a93e9279105507", + "machine": "x86_64", + "numpy": "2.5.3", + "platform": "Linux-6.18.44-fc-v470-x86_64-with-glibc2.39", + "r_max": 1e-05 + }, + "xray_debye": { + "date": "2026-11-16T16:22:21+00:00", + "git_commit": "3dc76f37aa560abc94b0f41f89a93e9279105507", + "machine": "x86_64", + "numpy": "2.5.3", + "platform": "Linux-6.18.44-fc-v470-x86_64-with-glibc2.39", + "r_max": 1e-05 + } +} diff --git a/tests/golden/api.powder_anatase/neutron_debye.npz b/tests/golden/api.powder_anatase/neutron_debye.npz new file mode 100644 index 00000000..6ab60052 Binary files /dev/null and b/tests/golden/api.powder_anatase/neutron_debye.npz differ diff --git a/tests/golden/api.powder_anatase/xray_debye.npz b/tests/golden/api.powder_anatase/xray_debye.npz new file mode 100644 index 00000000..7ccee59f Binary files /dev/null and b/tests/golden/api.powder_anatase/xray_debye.npz differ diff --git a/tests/python/compare.py b/tests/python/compare.py new file mode 100644 index 00000000..8888d543 --- /dev/null +++ b/tests/python/compare.py @@ -0,0 +1,87 @@ +"""Numeric comparisons and golden reference data for the Python tests. + +Golden data live in ``tests/golden//``: one ``.npz`` per +result plus ``meta.json`` (git commit, date, platform, NumPy version). + +To (re)create them, run the tests with ``DIFFUSE_UPDATE_GOLDEN=1``. Those +tests then write their result and are skipped instead of compared. Review +the diff before committing new golden files. +""" + +from __future__ import annotations + +import datetime as _dt +import json +import os +import platform +import subprocess +from pathlib import Path + +import numpy as np +import pytest + +REPO = Path(__file__).resolve().parents[2] +GOLDEN = REPO / "tests" / "golden" + + +def rvalue(obs, calc) -> float: + """Unweighted R-value sqrt(sum (o - c)^2 / sum o^2), as KUPLOT ``rval ..., one``.""" + obs = np.asarray(obs, dtype=np.float64) + calc = np.asarray(calc, dtype=np.float64) + if obs.shape != calc.shape: + raise ValueError(f"shape mismatch: {obs.shape} vs {calc.shape}") + return float(np.sqrt(np.sum((obs - calc) ** 2) / np.sum(obs ** 2))) + + +def load_columns(path: Path, ncol: int = 2) -> np.ndarray: + """Read a whitespace-separated text file, skipping ``#`` header lines.""" + return np.loadtxt(path, comments="#", usecols=range(ncol), ndmin=2) + + +def _meta() -> dict: + try: + commit = subprocess.run(["git", "-C", str(REPO), "rev-parse", "HEAD"], + capture_output=True, text=True, check=True).stdout.strip() + except (OSError, subprocess.CalledProcessError): + commit = "unknown" + return { + "git_commit": commit, + "date": _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="seconds"), + "platform": platform.platform(), + "machine": platform.machine(), + "numpy": np.__version__, + } + + +def updating() -> bool: + return os.environ.get("DIFFUSE_UPDATE_GOLDEN", "") not in ("", "0") + + +def check_golden(test_id: str, name: str, *, r_max: float, **arrays) -> None: + """Compare ``arrays`` with ``golden//.npz``. + + Axis arrays (any key except the last) must match to float32 rounding; + the last array is the result and must have an R-value below ``r_max``. + With DIFFUSE_UPDATE_GOLDEN=1 the file is (re)written and the test skipped. + """ + folder = GOLDEN / test_id + path = folder / f"{name}.npz" + if updating(): + folder.mkdir(parents=True, exist_ok=True) + np.savez_compressed(path, **arrays) + meta_path = folder / "meta.json" + meta = json.loads(meta_path.read_text()) if meta_path.exists() else {} + meta[name] = _meta() | {"r_max": r_max} + meta_path.write_text(json.dumps(meta, indent=2, sort_keys=True) + "\n") + pytest.skip(f"golden data written to {path.relative_to(REPO)}") + if not path.exists(): + pytest.fail(f"no golden data {path.relative_to(REPO)}; " + "run once with DIFFUSE_UPDATE_GOLDEN=1") + ref = np.load(path) + assert sorted(ref.files) == sorted(arrays), f"golden keys {ref.files} != {list(arrays)}" + *axes, result = arrays + for key in axes: + np.testing.assert_allclose(arrays[key], ref[key], rtol=1e-6, atol=1e-6, + err_msg=f"axis '{key}' differs from golden") + r = rvalue(ref[result], arrays[result]) + assert r < r_max, f"R-value of '{result}' against golden is {r:.3g} (limit {r_max})" diff --git a/tests/python/conftest.py b/tests/python/conftest.py index ac0c33bc..5597a56d 100644 --- a/tests/python/conftest.py +++ b/tests/python/conftest.py @@ -14,3 +14,33 @@ def pytest_configure(config): for tag, text in TAGS.items(): config.addinivalue_line("markers", f"{tag}: {text}") + + +# ------------------------------------------------------- diffuse / suite_python +import os +import sys +from pathlib import Path + +import pytest + +HERE = Path(__file__).resolve().parent +sys.path.insert(0, str(HERE)) # compare.py +sys.path.insert(0, str(HERE.parents[1] / "python")) # the diffuse package + + +@pytest.fixture(scope="session") +def suite(): + """The in-process DISCUS suite (``diffuse.session()``). + + Skips the test if the f2py module suite_python cannot be imported. Build + it with -DDIFFUSE_PYTHON=ON and set DIFFUSE_PYTHON_PATH=/python + (DIFFUSE_REQUIRE_PYTHON=1 turns the skip into an error, as in CI). + The Fortran state is global, so there is one session per pytest run. + """ + import diffuse + try: + return diffuse.session() + except ImportError as exc: + if os.environ.get("DIFFUSE_REQUIRE_PYTHON"): + raise + pytest.skip(str(exc).splitlines()[0]) diff --git a/tests/python/test_diffuse_api.py b/tests/python/test_diffuse_api.py new file mode 100644 index 00000000..1628b947 --- /dev/null +++ b/tests/python/test_diffuse_api.py @@ -0,0 +1,146 @@ +"""Tests for the demo Python API: diffuse.read_structure, diffuse.powder, plotting. + + DIFFUSE_PYTHON_PATH=/python pytest tests/python/test_diffuse_api.py +""" + +from __future__ import annotations + +import os +import subprocess +import sys +from pathlib import Path + +import numpy as np +import pytest + +from compare import check_golden + +REPO = Path(__file__).resolve().parents[2] +EXAMPLES = REPO / "python" / "examples" +ANATASE = EXAMPLES / "anatase.cif" +SCATTERING = REPO / "tests" / "02.Calculation_Scattering" + + +@pytest.fixture +def dc(suite): + """The diffuse package, with the DISCUS session up.""" + import diffuse + return diffuse + + +# ------------------------------------------------------------- structures +def test_read_cif_unit_cell(dc): + cr = dc.read_structure(ANATASE) + assert cr.natoms == 12 # Ti4 O8 in the I41/amd cell + assert cr.lattice == pytest.approx((3.73, 3.73, 9.37, 90, 90, 90)) + assert cr.volume == pytest.approx(3.73 * 3.73 * 9.37, rel=1e-6) + names, xyz = cr.atoms() + assert sorted(set(names)) == ["O2-", "TI4+"] + assert (names == "TI4+").sum() == 4 + assert xyz.shape == (12, 3) + assert np.all((xyz >= -0.5) & (xyz <= 1.0)) + + +@pytest.mark.parametrize("supercell, natoms", [((2, 3, 1), 72), (2, 96)]) +def test_read_cif_supercell(dc, supercell, natoms): + cr = dc.read_structure(ANATASE, supercell=supercell) + assert cr.natoms == natoms + assert len(cr.positions()) == natoms + + +def test_read_stru_as_is(dc): + cr = dc.read_structure(SCATTERING / "example3.stru") + assert cr.natoms == 2500 + assert cr.supercell is None + + +def test_read_errors(dc, tmp_path): + with pytest.raises(FileNotFoundError): + dc.read_structure(tmp_path / "missing.cif") + bad = tmp_path / "x.xyz" + bad.write_text("1\n\nC 0 0 0\n") + with pytest.raises(dc.DiffuseError): + dc.read_structure(bad) + with pytest.raises(ValueError): + dc.read_structure(ANATASE, supercell=(0, 1, 1)) + + +def test_macro_error_message(dc): + with pytest.raises(dc.MacroError) as info: + dc.run_macro("discus\n no_such_command 1\nexit") + assert "Unknown command" in str(info.value) + assert "***" in info.value.output + + +# ----------------------------------------------------------------- powder +def anatase_pattern(dc, **kw): + cr = dc.read_structure(ANATASE, supercell=(10, 10, 4)) + return dc.powder(cr, qmin=0.5, qmax=6.0, dq=0.005, **kw) + + +def test_powder_grid_and_peaks(dc): + p = anatase_pattern(dc) + assert p.q[0] == pytest.approx(0.5) and p.q[-1] == pytest.approx(6.0) + assert np.allclose(np.diff(p.q), 0.005) + assert np.all(p.intensity >= 0) + # strongest X-ray line of anatase is (101): Q = 2 pi sqrt(1/a^2 + 1/c^2) + a, c = 3.73, 9.37 + q101 = 2 * np.pi * np.sqrt(1 / a**2 + 1 / c**2) + assert p.q[np.argmax(p.intensity)] == pytest.approx(q101, abs=0.01) + assert p.two_theta()[0] == pytest.approx(np.degrees(2 * np.arcsin(0.5 * 0.2 / (4 * np.pi)))) + check_golden("api.powder_anatase", "xray_debye", r_max=1e-5, q=p.q, intensity=p.intensity) + + +def test_powder_neutron_differs(dc): + x = anatase_pattern(dc, radiation="xray") + n = anatase_pattern(dc, radiation="neutron") + np.testing.assert_allclose(x.q, n.q) + assert not np.allclose(x.intensity / x.intensity.max(), n.intensity / n.intensity.max(), + atol=0.05) + check_golden("api.powder_anatase", "neutron_debye", r_max=1e-5, q=n.q, intensity=n.intensity) + + +def test_powder_reloads_older_crystal(dc): + """DISCUS holds one structure; powder() on an older Crystal reads it again.""" + big = dc.read_structure(ANATASE, supercell=(6, 6, 3)) + first = dc.powder(big, qmax=5.0) + small = dc.read_structure(ANATASE, supercell=(2, 2, 1)) + assert dc.session().current_crystal is small + again = dc.powder(big, qmax=5.0) + assert dc.session().current_crystal is big + np.testing.assert_allclose(again.intensity, first.intensity, rtol=1e-10) + + +def test_powder_bad_options(dc): + cr = dc.read_structure(ANATASE) + with pytest.raises(ValueError): + dc.powder(cr, radiation="gamma") + with pytest.raises(ValueError): + dc.powder(cr, qmin=5, qmax=1) + + +# --------------------------------------------------------------- plotting +def test_plot(dc): + mpl = pytest.importorskip("matplotlib") + mpl.use("Agg") + import matplotlib.pyplot as plt + + p = anatase_pattern(dc) + ax = p.plot() + line = ax.get_lines()[0] + np.testing.assert_allclose(line.get_xdata(), p.q) + ax2 = p.plot(x="tth") + assert ax2.get_xlim()[0] == pytest.approx(p.two_theta()[0]) + plt.close("all") + + +@pytest.mark.parametrize("script", sorted(p.name for p in EXAMPLES.glob("*.py"))) +def test_example_script(script, tmp_path): + """Each script in python/examples/ runs on its own (own process, no display).""" + pytest.importorskip("matplotlib") + if not os.environ.get("DIFFUSE_PYTHON_PATH"): + pytest.skip("DIFFUSE_PYTHON_PATH not set") + env = os.environ | {"PYTHONPATH": str(REPO / "python"), "MPLBACKEND": "Agg"} + r = subprocess.run([sys.executable, str(EXAMPLES / script)], cwd=tmp_path, + env=env, capture_output=True, text=True, timeout=300) + assert r.returncode == 0, r.stdout + r.stderr diff --git a/tests/python/test_legacy_macros.py b/tests/python/test_legacy_macros.py index 63e942ac..c49d9ba0 100644 --- a/tests/python/test_legacy_macros.py +++ b/tests/python/test_legacy_macros.py @@ -65,7 +65,7 @@ def workdir(): def test_macro(test, workdir): opts = argparse.Namespace( xvfb=not os.environ.get("DISPLAY") and runner.shutil.which("xvfb-run") is not None, - omp_threads=None, timeout_scale=1.0, keep=False) + omp_threads=None, timeout_scale=1.0, keep=False, seed=runner.DEFAULT_SEED) displays = runner.queue.Queue() displays.put(100 + (os.getpid() % 100) * 8) r = runner.run_one(test, EXE, workdir, displays, opts) diff --git a/tests/python/test_suite_python.py b/tests/python/test_suite_python.py new file mode 100644 index 00000000..d7af6337 --- /dev/null +++ b/tests/python/test_suite_python.py @@ -0,0 +1,220 @@ +"""Tests for the in-process Python interface (f2py module suite_python). + +These run DISCUS inside the Python process and read results back as NumPy +arrays. Each calculation is checked two ways: + +* against the legacy reference file in ``tests//RESULTS/`` (the same + file the macro test compares with), which shows that the Python path gives + the same answer as ``discus_suite``; +* against golden data in ``tests/golden//`` (see compare.py), which is + what the Python API work (WP3–WP5) will be tested against. + + DIFFUSE_PYTHON_PATH=/python pytest tests/python/test_suite_python.py + +Without the module these tests are skipped (set DIFFUSE_REQUIRE_PYTHON=1 to +make that an error instead, as CI does). +""" + +from __future__ import annotations + +import shutil +from pathlib import Path + +import numpy as np +import pytest + +from compare import check_golden, load_columns, rvalue +from diffuse import MacroError + +TESTS = Path(__file__).resolve().parents[1] +SCATTERING = TESTS / "02.Calculation_Scattering" + + +@pytest.fixture +def scattering_dir(tmp_path): + """Fresh folder with the inputs from 02.Calculation_Scattering.""" + for name in ("silicon.cell", "primitive.cell", "example3.stru"): + shutil.copy(SCATTERING / name, tmp_path) + shutil.copytree(SCATTERING / "RESULTS", tmp_path / "RESULTS") + return tmp_path + + +# ------------------------------------------------------------------ basics +def test_expression(suite, tmp_path): + assert suite.value("2*3+1") == 7.0 + suite.run("r[1] = 2.5\nr[2] = r[1]**2", tmp_path) + assert suite.value("r[2]") == pytest.approx(6.25) + + +def test_macro_error_raises(suite, tmp_path): + with pytest.raises(MacroError): + suite.run("discus\n no_such_command 1,2\nexit", tmp_path) + # the session is still usable afterwards + suite.run("r[3] = 4", tmp_path) + assert suite.value("r[3]") == 4.0 + + +def test_missing_dataset_raises(suite, tmp_path): + suite.run("kuplot\n rese\nexit", tmp_path) + with pytest.raises(IndexError): + suite.dataset(1) + + +# --------------------------------------------------------------- structure +def test_build_crystal(suite, scattering_dir): + suite.run(""" +discus + read + cell silicon.cell, 3, 2, 1 + r[10] = n[1] + r[11] = lat[1] + r[12] = lat[6] +exit +""", scattering_dir) + assert suite.value("r[10]") == 6 # one atom per cell, 3*2*1 cells + assert suite.value("r[11]") == pytest.approx(5.0) + assert suite.value("r[12]") == pytest.approx(90.0) + + +# ----------------------------------------------------------------- Fourier +FOURIER_1D = """ +discus + read + cell silicon.cell, 7, 1, 1 + fourier + reset + neutron + ll -2.5, 0.00, 0.00 + lr 2.5, 0.00, 0.00 + ul -2.5, 0.00, 0.00 + na 1001 + no 1 + abs h + ord k + temp ign + disp off + set aver, 0.0 + lots off + run + exit + output + outf py_1d.inte + value inte + form stan + run + exit +exit +kuplot + rese + load xy, py_1d.inte +exit +""" + + +def test_fourier_1d(suite, scattering_dir): + """Same calculation as tests/02.Calculation_Scattering/1d.mac 7.""" + suite.run(FOURIER_1D, scattering_dir) + h, inte = suite.dataset(1) + assert h.shape == (1001,) + assert h[0] == pytest.approx(-2.5) and h[-1] == pytest.approx(2.5) + # a row of atoms along a: the strongest intensity is at an integer h + assert h[np.argmax(inte)] == pytest.approx(round(h[np.argmax(inte)]), abs=1e-4) + + legacy = load_columns(scattering_dir / "RESULTS" / "1d.inte") + np.testing.assert_allclose(h, legacy[:, 0], atol=1e-5) + assert rvalue(legacy[:, 1], inte) < 1e-3 + + check_golden("02.1d", "fourier_1d", r_max=1e-5, h=h, intensity=inte) + + +def test_fourier_2d(suite, scattering_dir): + """2-D (hk0) section of example3.stru, coarser than 2d.mac (121 x 121).""" + suite.run(""" +discus + read + stru example3.stru + fourier + reset + xray + ll 0.0, 0.0, 0.0 + lr 4.0, 0.0, 0.0 + ul 0.0, 4.0, 0.0 + na 121 + no 121 + temp use + disp off + wvle 1.00 + abs h + ord k + set aver, 0 + run + exit + output + outf py_2d.inte + value inte + form stan + run + exit +exit +kuplot + rese + load ni, py_2d.inte +exit +""", scattering_dir) + h, k, inte = suite.dataset_2d(1) + assert h.shape == (121,) and k.shape == (121,) and inte.shape == (121, 121) + assert h[-1] == pytest.approx(4.0) and k[-1] == pytest.approx(4.0) + # strongest intensity at the origin and at the Bragg points (integer h,k) + i, j = np.unravel_index(np.argmax(inte), inte.shape) + assert h[i] == pytest.approx(round(h[i]), abs=1e-4) + assert k[j] == pytest.approx(round(k[j]), abs=1e-4) + + check_golden("02.2d", "fourier_2d", r_max=1e-5, h=h, k=k, intensity=inte) + + +# ------------------------------------------------------------------ powder +def test_powder_debye(suite, scattering_dir): + """Same calculation as tests/02.Calculation_Scattering/powder.mac 10.""" + suite.run(""" +set parallel, useomp:serial +discus + read + cell primitive.cell, 10, 10, 10 + powder + reset + xray + set axis, q + set calc, debye + set disp, off + set delta, 0.0 + set qmin, 0.500 + set qmax, 7.100 + set dq, 0.005 + set profile, off + set temp, use + set wvle, 0.20000 + set four, four + set lpcor, bragg, 26.58 + run + exit + output + outf py_powder.inte + value inte + form powder, tth, 1.0, 180, 0.01 + run + exit +exit +kuplot + rese + load xy, py_powder.inte +exit +""", scattering_dir) + tth, inte = suite.dataset(1) + assert np.all(np.diff(tth) > 0) + assert np.all(inte >= 0) + + legacy = load_columns(scattering_dir / "RESULTS" / "powder.inte") + np.testing.assert_allclose(tth, legacy[:, 0], atol=1e-4) + assert rvalue(legacy[:, 1], inte) < 1e-3 + + check_golden("02.powder", "powder_debye", r_max=1e-5, tth=tth, intensity=inte) diff --git a/tools/publish_docs.sh b/tools/publish_docs.sh new file mode 100755 index 00000000..434d59b9 --- /dev/null +++ b/tools/publish_docs.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash +# Put the built Sphinx HTML into a gh-pages checkout, under python-docs/ only. +# +# tools/publish_docs.sh +# +# The gh-pages branch holds the DISCUS homepage. This script replaces the +# python-docs/ folder and makes sure an empty .nojekyll exists at the root +# (GitHub Pages' Jekyll would otherwise drop Sphinx's _static/, _images/, ...; +# the homepage is plain HTML and is not affected). It then checks that +# nothing else in the checkout changed, and stages the change. Committing and +# pushing are left to the caller (CI). +# +# Exit codes: 0 = staged (or nothing to do), 1 = usage error, +# 2 = something outside python-docs/ and .nojekyll would change. +set -euo pipefail + +DEST=python-docs + +if [ $# -ne 2 ] || [ ! -f "$1/index.html" ] || ! git -C "$2" rev-parse --is-inside-work-tree >/dev/null 2>&1; then + echo "usage: $0 " >&2 + exit 1 +fi +html=$(cd "$1" && pwd) +site=$(cd "$2" && pwd) + +cd "$site" +rm -rf -- "$DEST" +mkdir -p -- "$DEST" +cp -a -- "$html"/. "$DEST"/ +rm -f -- "$DEST/.buildinfo" # Sphinx build cache, not needed online +[ -e .nojekyll ] || : > .nojekyll + +git add -A -- "$DEST" .nojekyll + +# Guard: only python-docs/ and .nojekyll may differ from the last commit. +outside=$(git status --porcelain | awk '{print $NF}' \ + | grep -v -e "^$DEST/" -e "^$DEST\$" -e '^\.nojekyll$' || true) +if [ -n "$outside" ]; then + echo "refusing to publish: these paths outside $DEST/ would change:" >&2 + echo "$outside" >&2 + exit 2 +fi + +if git diff --cached --quiet; then + echo "docs unchanged; nothing to publish" +else + git diff --cached --stat | tail -1 +fi diff --git a/tools/run_legacy_tests.py b/tools/run_legacy_tests.py index 5b933c87..444f5cf8 100755 --- a/tools/run_legacy_tests.py +++ b/tools/run_legacy_tests.py @@ -16,6 +16,12 @@ RAN check = "none": the macro finished, but nothing was verified SKIPPED enabled = false in the manifest, or filtered out by --tags +Randomness: tests tagged "mc" are seeded (--seed, default 1234, or the +test's own "seed" in the manifest): the driver runs "seed " before the +macro, and the run is limited to one OpenMP thread (OMP_THREAD_LIMIT=1), +because threaded MMC is not reproducible even with a seed. --no-seed gives +the old behaviour: unseeded, with the macro's own thread settings. + Exit code: 0 if no test is FAIL, ABORTED or TIMEOUT, else 1. 2 = usage error. Only the Python standard library is used (Python >= 3.11 for tomllib). @@ -61,6 +67,7 @@ ERROR_LINE = re.compile(r"\*\*\*[A-Z ]{3,5}\*\*\*") XVFB_FAILED = "Xvfb failed to start" XVFB_ATTEMPTS = 3 +DEFAULT_SEED = 1234 # --------------------------------------------------------------------- manifest @@ -77,6 +84,7 @@ class Test: in_test_all: bool = True enabled: bool = True skip_reason: str = "" + seed: int | None = None # overrides --seed for this test (tag mc only) def load_manifest(path: Path) -> list[Test]: @@ -181,7 +189,16 @@ def macro_string(s: str) -> str: return s -def write_driver(t: Test, run_dir: Path, result_file: Path, root: Path) -> Path: +def test_seed(t: Test, opts) -> int | None: + """Seed for a test tagged mc, or None (unseeded run).""" + seed = getattr(opts, "seed", None) + if "mc" not in t.tags or seed is None: + return None + return t.seed if t.seed is not None else seed + + +def write_driver(t: Test, run_dir: Path, result_file: Path, root: Path, + seed: int | None = None) -> Path: args = f" {t.args}" if t.args else "" lines = [ "# generated by tools/run_legacy_tests.py", @@ -194,8 +211,10 @@ def write_driver(t: Test, run_dir: Path, result_file: Path, root: Path) -> Path: "LTEST_BATCH = TRUE", f'LTEST_FILE = "%c", "{macro_string(str(result_file))}"', "set wait, off", - f"@{t.macro}{args}", ] + if seed is not None: + lines.append(f"seed {seed}") + lines.append(f"@{t.macro}{args}") if t.check == "macro": lines.append(f"@{macro_string(str(root / 'check.mac'))} {t.macro}") lines += [ @@ -252,7 +271,8 @@ def run_one(t: Test, exe: Path, work: Path, displays: queue.Queue, opts) -> Resu copy_test_tree(t, root) run_dir = root / t.dir result_file = root / "zz_results.txt" - driver = write_driver(t, run_dir, result_file, root) + seed = test_seed(t, opts) + driver = write_driver(t, run_dir, result_file, root, seed) log_path = work / f"{t.id}.log" cmd = [str(exe), "-macro", driver.name] @@ -264,6 +284,11 @@ def run_one(t: Test, exe: Path, work: Path, displays: queue.Queue, opts) -> Resu env["PGPLOT_DIR"] = "/usr/lib/pgplot5" if opts.omp_threads: env["OMP_NUM_THREADS"] = str(opts.omp_threads) + if seed is not None: + # Threaded MMC is not reproducible (per-thread random states, update + # order); OMP_THREAD_LIMIT also caps "set parallel, nthreads:all". + env["OMP_NUM_THREADS"] = "1" + env["OMP_THREAD_LIMIT"] = "1" # Temporary files of discus_suite and xvfb-run stay inside the work dir. env["TMPDIR"] = str(root / "tmp") (root / "tmp").mkdir() @@ -403,6 +428,13 @@ def main(argv: list[str] | None = None) -> int: help="first X display number used with xvfb " "(default: 100 + a number derived from the process ID)") p.add_argument("--timeout-scale", type=float, default=1.0) + p.add_argument("--seed", type=int, default=DEFAULT_SEED, + help="seed for tests tagged 'mc', run on one thread (default %(default)s)") + p.add_argument("--no-seed", dest="seed", action="store_const", const=None, + help="run 'mc' tests unseeded, with their own thread settings") + p.add_argument("--retry-mc", type=int, default=0, metavar="N", + help="re-run a failed test tagged 'mc' up to N times; a pass on " + "retry counts as PASS but is reported as flaky") p.add_argument("--list", action="store_true", help="list the selected tests and exit") p.add_argument("--check-test-all", action="store_true", help="compare the manifest with test_all.mac and exit") @@ -443,7 +475,9 @@ def main(argv: list[str] | None = None) -> int: work = work.resolve() work.mkdir(parents=True, exist_ok=True) print(f"discus_suite : {exe}\nwork dir : {work}\n" - f"tests : {len(to_run)} to run, {len(skipped)} skipped\n", flush=True) + f"tests : {len(to_run)} to run, {len(skipped)} skipped\n" + f"mc tests : {'unseeded' if opts.seed is None else f'seed {opts.seed}, one thread'}\n", + flush=True) by_id = {t.id: t for t in tests} results: dict[str, Result] = {} @@ -454,8 +488,9 @@ def main(argv: list[str] | None = None) -> int: # Tests tagged "exclusive" set their own OpenMP thread count (for example # "set parallel, useomp:use, nthreads:all") and slow everything down badly # when they share the CPUs. They run one at a time after the others. - shared = [t for t in to_run if "exclusive" not in t.tags] - alone = [t for t in to_run if "exclusive" in t.tags] + # Seeded tests are limited to one thread, so they can share. + alone = [t for t in to_run if "exclusive" in t.tags and test_seed(t, opts) is None] + shared = [t for t in to_run if t not in alone] for batch, width in ((shared, jobs), (alone, 1)): with cf.ThreadPoolExecutor(max_workers=width) as pool: futures = [pool.submit(run_one, t, exe, work, displays, opts) for t in batch] @@ -464,6 +499,23 @@ def main(argv: list[str] | None = None) -> int: results[r.id] = r print(f" {r.status:<8} {r.id} ({r.seconds} s)", flush=True) + # Monte-Carlo tests are not reproducible yet (seed does not fix MMC runs, + # WP0 task 0.5a) and are checked against statistical limits, so they can + # fail by chance. Re-run those, one at a time; a real regression fails + # every time. + for t in to_run: + r = results[t.id] + if r.status not in BAD or "mc" not in t.tags: + continue + first = f"{r.status}: {r.message}" if r.message else r.status + for attempt in range(1, opts.retry_mc + 1): + r = run_one(t, exe, work, displays, opts) + print(f" {r.status:<8} {r.id} (retry {attempt}, {r.seconds} s)", flush=True) + if r.status not in BAD: + r.message = f"flaky: passed on retry {attempt}; first run {first}" + break + results[t.id] = r + ordered = [results[t.id] for t in to_run] + skipped print() print_summary(ordered)