⚡ Bolt: Optimize Pandas DataFrame iteration

.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.
+
+## 2026-08-08 - Optimize Pandas DataFrame iteration
+**Learning:** Iterating over Pandas DataFrames with `iterrows()` is a performance bottleneck and generates `FutureWarning`s related to integer-based lookups on Pandas `Series` objects.
+**Action:** Replace `iterrows()` with `itertuples(index=False, name=None)` for significantly faster execution and standard tuple return. If dictionary access is required, especially with dynamic or non-standard column names, iterate over `df.to_dict('records')`. Remember to remove index variable unpacking in the loop declaration.

ml_peg/calcs/bulk_crystal/elasticity/calc_elasticity.py

@@ -301,7 +301,8 @@ def run_elasticity_benchmark(
         else {}
     )
     atoms_list = []
-    for _, row in results.iterrows():
+    # ⚡ Bolt: Use to_dict('records') over iterrows for faster iteration.
+    for row in results.to_dict("records"):
         struct = row.get("final_structure")
         if not isinstance(struct, Structure):
             struct = mock_ref_map.get(row[benchmark.index_name])

ml_peg/calcs/conformers/MPCONF196/calc_MPCONF196.py

@@ -86,9 +86,10 @@ 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
+    # ⚡ Bolt: Use itertuples() over iterrows() for faster iteration.
+    for row in df.itertuples(index=False, name=None):
+        label = row[0]
+        ref_energies[label] = float(row[2]) * KCAL_TO_EV
 
     return ref_energies
 

ml_peg/calcs/conformers/solvMPCONF196/calc_solvMPCONF196.py

@@ -84,9 +84,10 @@ 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
+    # ⚡ Bolt: Use itertuples() over iterrows() for faster iteration.
+    for row in df.itertuples(index=False, name=None):
+        label = row[0]
+        e_ref = float(row[1]) * units.Hartree
         ref_energies[label] = e_ref
 
     return ref_energies

ml_peg/calcs/utils/gscdb138.py

@@ -106,7 +106,8 @@ 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]):
+        # ⚡ Bolt: Use to_dict('records') over iterrows for faster iteration.
+        for row in tqdm(df_refs.to_dict("records"), dataset, total=df_refs.shape[0]):
             atoms_list = []
             identifier = row["Reaction"]
             reactions = row["Stoichiometry"].split(",")  # Parse stoichiometry string.