From 309542136d6a42ebf6144e6c169ded87d8752dfa Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Wed, 13 May 2026 06:38:31 +0000
Subject: [PATCH] perf: Replace pandas iterrows with itertuples/to_dict

Co-authored-by: alinelena <3306823+alinelena@users.noreply.github.com>
---
 .jules/bolt.md                                            | 4 ++++
 ml_peg/calcs/bulk_crystal/elasticity/calc_elasticity.py   | 2 +-
 ml_peg/calcs/conformers/MPCONF196/calc_MPCONF196.py       | 6 +++---
 .../calcs/conformers/solvMPCONF196/calc_solvMPCONF196.py  | 6 +++---
 ml_peg/calcs/utils/gscdb138.py                            | 8 ++++----
 5 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/.jules/bolt.md b/.jules/bolt.md
index b140c4a7c..b44e6faa3 100644
--- a/.jules/bolt.md
+++ b/.jules/bolt.md
@@ -5,3 +5,7 @@
 ## 2024-05-19 - Caching YAML Load for Framework Registry
 **Learning:** `yaml.safe_load` on `frameworks.yml` within `load_framework_registry()` was taking ~2-3 ms per call and it was repeatedly called for every framework entry via `get_framework_config()`. This was a micro-bottleneck, especially when dealing with lists or multiple frameworks.
 **Action:** Applied the `@lru_cache` and `deepcopy` pattern successfully again to `load_framework_registry()` and `get_framework_config()` to avoid caching a mutable dictionary directly and avoid repeated YAML I/O parsing.
+
+## 2024-05-19 - Pandas Iteration Performance
+**Learning:** Iterating over a Pandas DataFrame using `iterrows()` is incredibly slow because it wraps every row into a pandas Series object, leading to huge overhead. This can cause significant slowdowns when parsing results datasets or evaluation sets.
+**Action:** Always replace `iterrows()` with `itertuples()` for positional access or `to_dict('records')` when dictionary key-based access is strictly required (e.g. dynamic column names or existing `.get()` interfaces). This yields ~15-20x speedups.
diff --git a/ml_peg/calcs/bulk_crystal/elasticity/calc_elasticity.py b/ml_peg/calcs/bulk_crystal/elasticity/calc_elasticity.py
index 90628dad1..d5256c94b 100644
--- a/ml_peg/calcs/bulk_crystal/elasticity/calc_elasticity.py
+++ b/ml_peg/calcs/bulk_crystal/elasticity/calc_elasticity.py
@@ -235,7 +235,7 @@ def run_elasticity_benchmark(
 
     # Save relaxed structures to extxyz for visualisation
     atoms_list = []
-    for _, row in results.iterrows():
+    for row in results.to_dict("records"):
         struct = row.get("final_structure")
         if struct is not None:
             atoms = AseAtomsAdaptor.get_atoms(struct).copy()
diff --git a/ml_peg/calcs/conformers/MPCONF196/calc_MPCONF196.py b/ml_peg/calcs/conformers/MPCONF196/calc_MPCONF196.py
index 145bd924a..c67da6eee 100644
--- a/ml_peg/calcs/conformers/MPCONF196/calc_MPCONF196.py
+++ b/ml_peg/calcs/conformers/MPCONF196/calc_MPCONF196.py
@@ -85,9 +85,9 @@ def get_ref_energies(data_path: Path) -> dict[str, float]:
     )
     ref_energies = {}
 
-    for row in df.iterrows():
-        label = row[1][0]
-        ref_energies[label] = float(row[1][2]) * KCAL_TO_EV
+    for row in df.itertuples(index=False):
+        label = row[0]
+        ref_energies[label] = float(row[2]) * KCAL_TO_EV
 
     return ref_energies
 
diff --git a/ml_peg/calcs/conformers/solvMPCONF196/calc_solvMPCONF196.py b/ml_peg/calcs/conformers/solvMPCONF196/calc_solvMPCONF196.py
index c6cc078dd..ad6d3d811 100644
--- a/ml_peg/calcs/conformers/solvMPCONF196/calc_solvMPCONF196.py
+++ b/ml_peg/calcs/conformers/solvMPCONF196/calc_solvMPCONF196.py
@@ -83,9 +83,9 @@ def get_ref_energies(data_path: Path) -> dict[str, float]:
     )
     ref_energies = {}
 
-    for row in df.iterrows():
-        label = row[1][0]
-        e_ref = float(row[1][1]) * units.Hartree
+    for row in df.itertuples(index=False):
+        label = row[0]
+        e_ref = float(row[1]) * units.Hartree
         ref_energies[label] = e_ref
 
     return ref_energies
diff --git a/ml_peg/calcs/utils/gscdb138.py b/ml_peg/calcs/utils/gscdb138.py
index 4d0a019ca..095e14666 100644
--- a/ml_peg/calcs/utils/gscdb138.py
+++ b/ml_peg/calcs/utils/gscdb138.py
@@ -105,11 +105,11 @@ def run_gscdb138(
         df_refs["Reference"] *= units.Hartree
 
         # Calculate relative energy for each entry.
-        for _, row in tqdm(df_refs.iterrows(), dataset, total=df_refs.shape[0]):
+        for row in tqdm(df_refs.itertuples(), dataset, total=df_refs.shape[0]):
             atoms_list = []
-            identifier = row["Reaction"]
-            reactions = row["Stoichiometry"].split(",")  # Parse stoichiometry string.
-            e_rel_ref = row["Reference"]
+            identifier = row.Reaction
+            reactions = row.Stoichiometry.split(",")  # Parse stoichiometry string.
+            e_rel_ref = row.Reference
             num_species = len(reactions) // 2  # Each species has coefficient and name.
 
             e_rel_model = 0