test: document gdxcc vs gams_transfer read/write speed across fixtures

Adds tests/test_backend_timing.py: times read+write for both backends over
every in-tree fixture (sub-3 KB up to ~1.9 MB) and records the results. A
pytest_terminal_summary hook in conftest renders a size-sorted table plus a
clear-winner / switchover note at the end of the run.

These are not pass/fail performance gates (timings are machine-dependent and
measured as a single min-of-3 burst); the only assertion is that both backends
ran. The robust finding: gdxcc wins on small files (transfer's Container
overhead is not amortized) while gams.transfer wins on large ones (~2x read,
~4x write at 1.9 MB), with the write switchover around 100-300 KB.

Runs by default; skipped only when gams.transfer is unavailable.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: elainethale

tests/conftest.py

@@ -21,6 +21,63 @@ def clean_up(request):
     return not request.config.getoption("--no-clean-up")
 
 
+# Rows appended by tests/test_backend_timing.py; rendered once after the run by
+# pytest_terminal_summary below. Each row: dict(fixture, size_kb, op, gdxcc,
+# gams_transfer, ratio) where ratio = gdxcc / gams_transfer (>1 = transfer faster).
+_BACKEND_TIMINGS = []
+
+
+@pytest.fixture(scope="session")
+def backend_timings():
+    return _BACKEND_TIMINGS
+
+
+def _crossover_note(rows, op):
+    """Describe the gdxcc<->gams_transfer winner across sizes for one op.
+
+    Rows are sorted by size; returns "clear winner" text if one backend wins at
+    every size, else the size band where gams_transfer overtakes gdxcc.
+    """
+    op_rows = sorted((r for r in rows if r["op"] == op), key=lambda r: r["size_kb"])
+    if not op_rows:
+        return ""
+    wins = [r["ratio"] >= 1.0 for r in op_rows]  # True = transfer faster
+    if all(wins):
+        return f"{op}: gams_transfer faster at every size tested."
+    if not any(wins):
+        return f"{op}: gdxcc faster at every size tested (transfer overhead never amortized)."
+    first = next(i for i, w in enumerate(wins) if w)
+    below = op_rows[first - 1]
+    above = op_rows[first]
+    return (
+        f"{op}: switchover between {below['size_kb']:.1f} KB ({below['fixture']}, gdxcc faster) "
+        f"and {above['size_kb']:.1f} KB ({above['fixture']}, transfer faster)."
+    )
+
+
+def pytest_terminal_summary(terminalreporter, exitstatus, config):
+    rows = _BACKEND_TIMINGS
+    if not rows:
+        return
+    tr = terminalreporter
+    tr.write_sep("=", "backend timing (gdxcc vs gams_transfer)")
+    tr.write_line(
+        "min seconds over repeated runs; ratio = gdxcc / gams_transfer (>1 = transfer faster)"
+    )
+    header = f"{'fixture':32s} {'size_KB':>9s} {'op':>5s} {'gdxcc':>9s} {'xfer':>9s} {'ratio':>7s}"
+    tr.write_line(header)
+    tr.write_line("-" * len(header))
+    for r in sorted(rows, key=lambda r: (r["size_kb"], r["op"])):
+        tr.write_line(
+            f"{r['fixture'][:32]:32s} {r['size_kb']:9.1f} {r['op']:>5s} "
+            f"{r['gdxcc']:9.4f} {r['gams_transfer']:9.4f} {r['ratio']:7.2f}"
+        )
+    for op in ("read", "write"):
+        note = _crossover_note(rows, op)
+        if note:
+            tr.write_line(note)
+
+
 @pytest.fixture(scope="session")
 def base_dir():
     return os.path.dirname(__file__)

tests/test_backend_timing.py

@@ -0,0 +1,78 @@
+"""Document the read/write speed difference between the gdxcc and gams_transfer
+backends across the in-tree fixtures (sub-3 KB up to ~1.9 MB).
+
+These are not pass/fail performance gates -- timings are machine-dependent. Each
+test records its measurements; conftest's ``pytest_terminal_summary`` renders a
+size-sorted table plus a clear-winner / switchover note at the end of the run.
+The only assertion is that both backends actually ran (a backend that errors on a
+fixture fails here rather than silently dropping out of the comparison).
+
+Skipped when gams.transfer is unavailable.
+"""
+
+import glob
+import os
+import time
+
+import pytest
+
+import gdxpds
+from gdxpds import to_dataframes, to_gdx
+
+pytestmark = pytest.mark.skipif(not gdxpds.HAVE_GAMS_TRANSFER, reason="gams.transfer not available")
+
+FIXTURES = sorted(
+    os.path.basename(p) for p in glob.glob(os.path.join(os.path.dirname(__file__), "data", "*.gdx"))
+)
+
+# Repeats per measurement; the minimum is reported (least perturbed by noise).
+# Small because this runs in the default suite and the largest fixture is ~1.9 MB.
+_REPEATS = 3
+
+
+def _min_time(fn, repeats=_REPEATS):
+    best = float("inf")
+    for _ in range(repeats):
+        t = time.perf_counter()
+        fn()
+        best = min(best, time.perf_counter() - t)
+    return best
+
+
+@pytest.mark.parametrize("fixture", FIXTURES)
+def test_backend_timing(data_dir, fixture, tmp_path, backend_timings):
+    path = os.path.join(data_dir, fixture)
+    size_kb = os.path.getsize(path) / 1024.0
+
+    # Read (eager / bulk path -- the same one to_dataframes uses).
+    read_g = _min_time(lambda: to_dataframes(path, backend="gdxcc"))
+    read_t = _min_time(lambda: to_dataframes(path, backend="gams_transfer"))
+
+    # Write: read once (untimed) to get DataFrames, then time each backend's write.
+    dfs = to_dataframes(path, backend="gdxcc")
+    write_g = _min_time(lambda: to_gdx(dfs, str(tmp_path / "g.gdx"), backend="gdxcc"))
+    write_t = _min_time(lambda: to_gdx(dfs, str(tmp_path / "t.gdx"), backend="gams_transfer"))
+
+    backend_timings.append(
+        {
+            "fixture": fixture,
+            "size_kb": size_kb,
+            "op": "read",
+            "gdxcc": read_g,
+            "gams_transfer": read_t,
+            "ratio": read_g / read_t,
+        }
+    )
+    backend_timings.append(
+        {
+            "fixture": fixture,
+            "size_kb": size_kb,
+            "op": "write",
+            "gdxcc": write_g,
+            "gams_transfer": write_t,
+            "ratio": write_g / write_t,
+        }
+    )
+
+    # Sanity only: both backends ran for both ops (no timing threshold).
+    assert min(read_g, read_t, write_g, write_t) > 0