readcon-core 0.14.0

An oxidized single and multiple CON file reader and writer with FFI bindings for ergonomic C/C++ usage.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

#!/usr/bin/env python3
"""Render docs/source/_generated/cachegrind_results.rst from JSON."""
from __future__ import annotations

import json
import sys
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
JSON = ROOT / "docs/source/_generated/cachegrind_results.json"
RST = ROOT / "docs/source/_generated/cachegrind_results.rst"

NOTES = {
    "parse_multi_2x4": "2-frame multi CON (50×)",
    "forward_multi_2x4": "forward() skip (50×)",
    "convel_multi": "coords + velocities (50×)",
    "parse_100_frames": "100× tiny_cuh2 (10×)",
    "forward_100_frames": "skip 100 frames (10×)",
    "parse_cuh2_218": "218-atom frame (20×)",
    "float_fast_float2": "5-col fast-float2 (10k)",
    "float_std_parse": "5-col str::parse (10k)",
    "write_100_frames": "buffer writer (10×)",
    "chemfiles_xyz_path": "XYZ path → ConFrame (50×)",
    "chemfiles_xyz_memory": "XYZ memory → ConFrame (50×)",
    "chemfiles_select_name_O": "selection ``name O`` (50×)",
}


def main() -> int:
    if not JSON.is_file():
        print(f"missing {JSON}", file=sys.stderr)
        return 1
    data = json.loads(JSON.read_text())
    scenarios = data.get("scenarios", {})
    lines = [
        ".. cachegrind-results — generated by scripts/run_cachegrind_bench.sh; do not edit by hand.",
        "",
        ".. list-table:: Cachegrind instruction counts (CI-refreshable)",
        "   :header-rows: 1",
        "   :widths: 42 22 36",
        "",
        "   * - Scenario",
        "     - I refs",
        "     - Notes",
    ]
    for name, irefs in scenarios.items():
        note = NOTES.get(name, "")
        lines.append(f"   * - ``{name}``")
        lines.append(f"     - {irefs:,}" if isinstance(irefs, int) else f"     - {irefs}")
        lines.append(f"     - {note}")
    feat = data.get("features", "")
    lines += [
        "",
        f"Generated **{data.get('generated_at', '?')}** from commit ``{data.get('git_sha', '?')}``",
        f"(Cargo features: ``{feat or 'default'}``). Metric: Valgrind Cachegrind **I refs**.",
        "Lower is better for the same scenario. Comparable across commits on the same CI image/Valgrind.",
        "",
        "Wall-clock Criterion tables elsewhere on this page are **illustrative** unless re-run for a release.",
        "PR workflow **Benchmark PR** still uses Criterion + ``critcmp`` for latency deltas.",
        "",
    ]
    RST.parent.mkdir(parents=True, exist_ok=True)
    RST.write_text("\n".join(lines) + "\n", encoding="utf-8")
    print(f"wrote {RST}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())