Migrate PySCF reference checks to 2.15

.github/workflows/ci.yml

@@ -128,6 +128,27 @@ jobs:
         if: matrix.os == 'windows-latest' && matrix.python-version == '3.12'
         run: uv run --locked --python ${{ matrix.python-version }} pytest tools/reference/test_persistence_interop.py -k reads_rust
 
+  pyscf-native:
+    name: PySCF reference suite (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-15-intel, macos-latest, windows-latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up uv
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3
+        with:
+          python-version: '3.12'
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable
+      - name: Cache Rust builds
+        uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3
+      - name: Run PySCF comparisons
+        run: uv run --locked pytest tools/reference
+
   nix:
     name: Nix flake (${{ matrix.system }})
     runs-on: ${{ matrix.os }}

docs/src/development/manual-setup.md

@@ -10,8 +10,7 @@
   dependencies through `Cargo.lock`, but does not pin the entire host environment.
 - **Platforms:** native Cargo supports the platforms in the
   [compatibility table](platforms.md), including Windows and Intel macOS.
-  Python development tools run natively on Windows; PySCF comparisons currently
-  require Linux, macOS, or WSL2.
+  Python development tools run natively on Windows; PySCF comparisons also run on Windows x86-64.
 - **HPC use:** this route can use the site's existing compiler environment
   without Docker or Nix. Build and run according to cluster policy, using the
   scheduler's assigned resources. A locally built binary still needs a
@@ -52,21 +51,17 @@ uv run --locked pytest tools/test_book_links.py tools/test_release_smoke.py tool
 
 The project supports Python 3.12 through 3.14. The default groups install
 JupyterLab, ipykernel, Matplotlib, SciPy, NumPy, pytest, and Ruff. The lock
-also includes PySCF 2.14.0 on Linux and macOS, but that pinned release has no
-Windows wheel, so uv excludes it on native Windows. Binary wheels are required;
+also includes PySCF 2.15.0 on Linux, macOS, and Windows x86-64.
+Windows ARM64 remains excluded. Binary wheels are required;
 source builds remain disabled. Run the reference suite with:
 
 ```sh
 uv run --locked pytest tools/reference
 ```
 
-On native Windows, only the PySCF calculation tests in
-`tools/reference/test_compare_pyscf.py` and `tools/reference/test_integrals.py`
-are skipped. Helper tests in
-`test_compare_pyscf_helpers.py`, report validation, and NumPy persistence tests,
-including Rust-generated persistence artifacts, remain available. Use WSL2
-for PySCF comparisons and the scientific report
-generator (`tools/reference/report.py`). These Python tools support
+On Windows x86-64, the same command runs PySCF calculations, AO integral
+comparisons, helper tests, and persistence interoperability tests. Use WSL2
+for PySCF on Windows ARM64. These Python tools support
 development and validation; building the RustiQ executable still requires the
 Rust toolchain and the Cargo commands above.
 

docs/src/development/platforms.md

@@ -42,9 +42,9 @@ Windows troubleshooting, and the configured VS Code extensions.
 
 The optional scientific Python tools have their own platform requirements.
 The project configures `uv` for Linux, macOS, and native Windows. The locked
-PySCF release is excluded on native Windows; the remaining Python tools and
-tests run there. The Nix environment provides PySCF on every declared Nix
-system. For PySCF comparisons on Windows, use WSL2 or the Linux Dev Container.
+PySCF 2.15.0 release includes native Windows x86-64 wheels; Windows ARM64
+remains excluded. The Nix environment provides PySCF on every declared Nix
+system. For PySCF comparisons on Windows ARM64, use WSL2 or the Linux Dev Container.
 
 ## How compatibility is checked
 
@@ -61,7 +61,9 @@ provides ongoing evidence for this support:
   and PySCF comparisons. Separate Windows and macOS host integrations are not
   exercised by these checks.
 - The standalone `uv` environment is checked on Linux and Windows x86_64 with
-  Python 3.12 and 3.14. Windows skips the PySCF comparison modules and also checks
+  Python 3.12 and 3.14. A native PySCF job runs the reference suite on Linux
+  x86-64 and ARM64, macOS Intel and Apple Silicon, and Windows x86-64.
+  Windows also checks
   Rust/NumPy persistence interoperability with Python 3.12.
 
 The [scheduled full Nix workflow](https://github.com/mveril/RustiQ/actions/workflows/nix-full.yml)

docs/src/user-guide/hartree-fock.md

@@ -165,7 +165,7 @@ The electronic HF energy includes electronic kinetic, electron–nuclear, and
 electron–electron terms. Total HF energy adds nuclear repulsion. Energies are
 in Hartree; input Angstrom coordinates are converted to Bohr internally.
 Terminal energies are rounded for display. The H₂/STO-3G example is checked
-against a PySCF 2.14.0 reference in the project comparison suite with an
+against a PySCF 2.15.0 reference in the project comparison suite with an
 absolute energy tolerance of \\(2\times10^{-10}\\) Hartree; the CLI test checks
 the rounded value. See [reference comparison coverage](../scientific-scope.md#reference-comparisons)
 and the [output guide](../getting-started/output.md).

docs/src/user-guide/json-output.md

@@ -107,6 +107,6 @@ for readability. Do not compare a rounded terminal value against a tight
 numerical tolerance. Existing JSON CLI tests validate both schemas and
 full-precision H₂ output in
 [`tests/json_output_cli.rs`](https://github.com/mveril/RustiQ/blob/main/tests/json_output_cli.rs).
-The checked-in reference tests compare JSON values against PySCF 2.14.0 for
+The checked-in reference tests compare JSON values against PySCF 2.15.0 for
 selected systems; see [scientific scope](../scientific-scope.md#reference-comparisons).
 For terminology used in result fields, see the [glossary](../glossary.md).

docs/src/user-guide/mp2.md

@@ -159,7 +159,7 @@ budget resolution follows the shared [resource policy](https://github.com/mveril
 
 The H₂/STO-3G RHF-MP2 comparison checks the HF energy within \\(2\times10^{-10}\\)
 Hartree and MP2 correlation energy within \\(10^{-10}\\) Hartree against PySCF
-2.14.0. The OH/STO-3G UHF-MP2 case checks HF energy within \\(5\times10^{-8}\\),
+2.15.0. The OH/STO-3G UHF-MP2 case checks HF energy within \\(5\times10^{-8}\\),
 correlation energy within \\(5\times10^{-9}\\) Hartree, and spin expectation
 within \\(2\times10^{-5}\\). These are agreement tolerances for those inputs,
 not a measure of general chemical accuracy. See the

pyproject.toml

@@ -3,13 +3,19 @@ name = "rustiq-reference-tools"
 version = "0.0.0"
 description = "Python tooling used to validate RustiQ against reference implementations"
 requires-python = ">=3.12,<3.15"
-# PySCF 2.14.0 predates upstream Windows-wheel publishing; PR #3424 adds Windows wheels to PyPI releases.
-# Recheck this marker when upgrading PySCF: https://github.com/pyscf/pyscf/pull/3424
-dependencies = ["pyscf==2.14.0; sys_platform != 'win32'"]
+# PySCF publishes native Windows wheels for x86-64; Windows ARM64 still requires WSL2.
+dependencies = ["pyscf==2.15.0; sys_platform != 'win32' or platform_machine == 'AMD64' or platform_machine == 'x86_64'"]
 
 [dependency-groups]
 test = ["numpy", "pytest"]
-dev = ["ipykernel", "jupyterlab", "matplotlib", "scipy"]
+# 26.1.0 has no macOS Intel wheel; remove this constraint when one is published.
+dev = [
+    "ipykernel",
+    "jupyterlab",
+    "matplotlib",
+    "scipy",
+    "argon2-cffi-bindings==25.1.0; sys_platform == 'darwin' and platform_machine == 'x86_64'",
+]
 linting = ["ruff"]
 
 [tool.uv]

tools/reference/README.md

@@ -50,10 +50,10 @@ uv run --locked pytest tools/reference
 
 This uses the cross-platform lock for Python 3.12 through 3.14 and requires
 compatible binary wheels; it does not build Python packages from source. PySCF
-supports Linux, macOS, and WSL2, but the pinned release has no native Windows
-wheel. The lock excludes PySCF on native Windows. Windows uv jobs still run the
-PySCF-independent report and helper tests; the PySCF comparison and AO
-integral suites run in the Nix PySCF environment or WSL2. Cargo must remain on
+2.15.0 provides binary wheels for Linux, macOS, and native Windows x86-64.
+Windows ARM64 remains excluded; use WSL2 there. The native PySCF CI job runs
+the full reference suite, including energy and AO integral comparisons, on
+supported Linux, macOS, and Windows x86-64 runners. Cargo must remain on
 `PATH` when using the default `cargo run` invocation.
 Set `RUSTIQ_BIN` to an absolute executable path to compare a specific build
 instead; `nix run .#pyscf-check` supplies its Nix-built executable this way.
@@ -265,7 +265,7 @@ reference, not a correlated MP2 spin expectation.
 
 ### Absolute tolerances
 
-Measured errors with pinned PySCF 2.14.0 and single-thread BLAS/OpenMP are below.
+Measured errors with PySCF 2.14.0 and single-thread BLAS/OpenMP are below.
 The tolerances leave a numerical margin over the observed errors for independent
 SCF termination and platform-dependent floating-point reductions; they do not
 represent physical error bars. No existing tolerance is increased.

tools/reference/integrals.py

@@ -193,7 +193,7 @@ def validate():
                 env=env,
             )
         except RuntimeError as error:
-            if not list(output.glob("*.json")):
+            if any(not (output / f"{name}.json").exists() for name, *_ in CASES):
                 raise
             cargo_error = str(error)
         rust = [json.loads((output / f"{name}.json").read_text()) for name, *_ in CASES]

tools/reference/test_integrals.py

@@ -6,7 +6,7 @@
 import numpy as np
 import pytest
 
-# PySCF is intentionally unavailable on Windows for the pinned reference suite.
+# PySCF wheels are unavailable on some architectures, including Windows ARM64.
 # This module contains only tests that execute PySCF.
 pytest.importorskip("pyscf", reason="AO integral references require PySCF")
 
@@ -24,8 +24,13 @@ def test_ao_integrals():
 def test_checked_in_pyscf_references():
     metadata, generated = generate_fixture()
     stored = json.loads(FIXTURE.read_text())
+    # The checked-in arrays retain the PySCF version that generated them.
+    # Compare their values with the currently pinned PySCF independently.
+    metadata.pop("pyscf_version")
     assert metadata == {
-        key: value for key, value in stored.items() if key != "array_sha256"
+        key: value
+        for key, value in stored.items()
+        if key not in {"array_sha256", "pyscf_version"}
     }
     assert set(stored["array_sha256"]) == set(generated)
     for name, values in generated.items():