docs: note that GPU pytest runs must be serialised

Captures the operational gotcha discovered while preparing v0.2.0:
the default 24-worker pytest-xdist parallelism opens 24 CUDA
contexts on the single visible GPU and triggers spurious
CUBLAS_STATUS_ALLOC_FAILED / OutOfMemoryError failures even on
96 GB cards. The same suite passes cleanly under -n 0.

Updated:

- README.md (Contributing block)
- CLAUDE.md (Build and Test Commands)
- AGENTS.md (testing block)
- .cursor/rules/tests.mdc (testing rule)

Author: FridrichMethod

.cursor/rules/tests.mdc

@@ -31,3 +31,6 @@ Users run:
 - `pytest -m "not gpu"` -- CPU-only environments
 - `pytest -m "not benchmark"` -- fast CI (correctness only)
 - `pytest -m "benchmark and not slow"` -- fast perf checks
+- `pytest -m "gpu and not slow" -n 0` -- GPU agreement (serial)
+
+**GPU runs must use `-n 0`** (single worker). The 24-worker pytest-xdist default opens 24 CUDA contexts on the single visible GPU and triggers spurious `CUBLAS_STATUS_ALLOC_FAILED` / `OutOfMemoryError` failures. The same suite passes cleanly when serialised.

AGENTS.md

@@ -46,8 +46,15 @@ pytest -m "benchmark and not slow"      # fast benchmarks only
 pytest -m "not gpu"                     # CPU-only run
 pytest -m "benchmark and gpu"           # all GPU-exercising benchmarks
 pytest -m "not (slow or benchmark)"     # minimum fast CI subset
+pytest -m "gpu and not slow" -n 0       # GPU agreement (serial -- see note)
 ```
 
+> **Always pass `-n 0` to GPU-marked runs.** The default 24-worker
+> pytest-xdist parallelism opens 24 simultaneous CUDA contexts on the
+> single visible GPU and triggers spurious `CUBLAS_STATUS_ALLOC_FAILED`
+> / `OutOfMemoryError` failures even on 96 GB cards. The same suite
+> passes cleanly under `-n 0` (or `-n 1`).
+
 Register any new markers in `pyproject.toml` `[tool.pytest.ini_options].markers`.
 
 After modifying any production code under `src/mdpp/`, you MUST complete the following loop before considering the task done. Repeat until no CRITICAL issues remain:

CLAUDE.md

@@ -108,6 +108,13 @@ pytest -m benchmark
 # Skip slow + benchmark tests
 pytest -m "not (slow or benchmark)"
 
+# GPU backend agreement (cupy / torch / jax vs mdtraj / numba).
+# Always pass `-n 0` -- the default 24-worker pytest-xdist parallelism
+# opens 24 CUDA contexts on a single GPU and produces spurious
+# CUBLAS_STATUS_ALLOC_FAILED / OutOfMemoryError failures even on
+# 96 GB cards.  Serial runs are clean.
+pytest -m "gpu and not slow" -n 0
+
 # Lint and format
 ruff check src/ tests/ --fix
 ruff format src/ tests/

README.md

@@ -242,13 +242,20 @@ pytest                               # full suite
 pytest -m "not benchmark"            # skip perf benchmarks
 pytest -m "not gpu"                  # skip GPU backend tests (CPU-only)
 pytest -m "benchmark and not slow"   # fast performance checks
+pytest -m "gpu and not slow" -n 0    # GPU backend agreement (serial, see note)
 
 # Full pre-commit suite
 pre-commit run --all-files
 ```
 
 Custom pytest markers: `benchmark` (timing), `slow` (>10s), `gpu` (cupy/torch/jax).
 
+> **GPU test note:** Always run GPU-marked tests with `-n 0` (one worker).
+> The default 24-worker pytest-xdist parallelism opens 24 simultaneous CUDA
+> contexts on the single visible GPU and triggers spurious
+> `CUBLAS_STATUS_ALLOC_FAILED` / `OutOfMemoryError` failures even on a
+> 96 GB card. Serial runs are clean.
+
 ## License
 
 [MIT](LICENSE) — Zhaoyang Li