Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 142 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -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
41 changes: 41 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 4 additions & 0 deletions docs/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
_build/
_generated/
gallery/
sg_execution_times.rst
42 changes: 42 additions & 0 deletions docs/api.md
Original file line number Diff line number Diff line change
@@ -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
```
100 changes: 100 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -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 = []
38 changes: 38 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -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
```
Loading
Loading