Add: concise __repr__ to data model classes and Thermodynamics

The frozen dataclasses in models.py (PoseResult, BindingModeResult,
DockingResult) relied on auto-generated __repr__ which dumped all
fields including the full remarks dict and Path objects, making them
unreadable in interactive Python sessions. Added concise __repr__
methods showing only key identifiers and scores.

Also added __repr__ to Thermodynamics in thermodynamics.py for
consistency with the existing repr style in docking.py classes.

https://claude.ai/code/session_01LFSRF3YrvmxjcGBBJbvgLv

Author: claude

python/flexaidds/models.py

@@ -22,7 +22,7 @@
 from typing import Any, Dict, List, Optional, Union
 
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, repr=False)
 class PoseResult:
     """A single docked pose read from one FlexAID∆S output PDB file.
 
@@ -62,8 +62,17 @@ class PoseResult:
     temperature: Optional[float] = None
     remarks: Dict[str, Any] = field(default_factory=dict)
 
+    def __repr__(self) -> str:
+        parts = [f"mode={self.mode_id}", f"rank={self.pose_rank}"]
+        if self.cf is not None:
+            parts.append(f"cf={self.cf:.3f}")
+        if self.free_energy is not None:
+            parts.append(f"F={self.free_energy:.3f}")
+        parts.append(f"path='{self.path.name}'")
+        return f"<PoseResult {' '.join(parts)}>"
 
-@dataclass(frozen=True)
+
+@dataclass(frozen=True, repr=False)
 class BindingModeResult:
     """A cluster of docked poses that share a common binding geometry.
 
@@ -129,8 +138,17 @@ def best_pose(self) -> Optional[PoseResult]:
             return min(scored, key=lambda p: p.cf_app)
         return self.poses[0] if self.poses else None
 
+    def __repr__(self) -> str:
+        parts = [f"id={self.mode_id}", f"rank={self.rank}",
+                 f"n_poses={self.n_poses}"]
+        if self.free_energy is not None:
+            parts.append(f"F={self.free_energy:.3f}")
+        if self.best_cf is not None:
+            parts.append(f"best_cf={self.best_cf:.3f}")
+        return f"<BindingModeResult {' '.join(parts)}>"
+
 
-@dataclass(frozen=True)
+@dataclass(frozen=True, repr=False)
 class DockingResult:
     """Top-level container for a complete FlexAID∆S docking run.
 
@@ -174,6 +192,13 @@ def top_mode(self) -> Optional[BindingModeResult]:
             return min(free_modes, key=lambda m: m.free_energy)
         return min(self.binding_modes, key=lambda m: m.rank)
 
+    def __repr__(self) -> str:
+        parts = [f"n_modes={self.n_modes}"]
+        if self.temperature is not None:
+            parts.append(f"T={self.temperature:.1f}K")
+        parts.append(f"source='{self.source_dir.name}'")
+        return f"<DockingResult {' '.join(parts)}>"
+
     def to_records(self) -> List[Dict[str, Any]]:
         """Serialise all binding modes to a list of flat dictionaries.
 

python/flexaidds/thermodynamics.py

@@ -59,6 +59,13 @@ def entropy_term(self) -> float:
         """Entropic contribution to free energy: TΔS (kcal/mol)."""
         return self.temperature * self.entropy
 
+    def __repr__(self) -> str:
+        return (
+            f"<Thermodynamics T={self.temperature:.1f}K "
+            f"F={self.free_energy:.3f} H={self.mean_energy:.3f} "
+            f"S={self.entropy:.6f} Cv={self.heat_capacity:.6f}>"
+        )
+
     def to_dict(self) -> dict:
         """Convert to dictionary for serialization."""
         return {

python/tests/test_results_loader_models.py

@@ -1,5 +1,6 @@
 from pathlib import Path
 
+from flexaidds.models import BindingModeResult, DockingResult, PoseResult
 from flexaidds.results import load_results
 
 
@@ -89,3 +90,72 @@ def test_load_results_promotes_frequency_metadata_to_mode_level(tmp_path: Path)
     assert mode.n_poses == 2
     assert mode.frequency == 7
     assert mode.metadata["frequency"] == 7
+
+
+# ── __repr__ tests ───────────────────────────────────────────────────────────
+
+
+class TestPoseResultRepr:
+    def test_repr_with_all_scores(self):
+        pose = PoseResult(
+            path=Path("/tmp/mode1_pose1.pdb"),
+            mode_id=1, pose_rank=2, cf=-42.5, free_energy=-41.0,
+        )
+        r = repr(pose)
+        assert r.startswith("<PoseResult")
+        assert "mode=1" in r
+        assert "rank=2" in r
+        assert "cf=-42.500" in r
+        assert "F=-41.000" in r
+        assert "mode1_pose1.pdb" in r
+
+    def test_repr_without_optional_scores(self):
+        pose = PoseResult(path=Path("/tmp/test.pdb"), mode_id=3, pose_rank=1)
+        r = repr(pose)
+        assert "mode=3" in r
+        assert "cf=" not in r
+        assert "F=" not in r
+        assert "test.pdb" in r
+
+
+class TestBindingModeResultRepr:
+    def test_repr_with_free_energy(self):
+        pose = PoseResult(path=Path("/tmp/p.pdb"), mode_id=1, pose_rank=1)
+        mode = BindingModeResult(
+            mode_id=1, rank=2, poses=[pose],
+            free_energy=-41.0, best_cf=-42.5,
+        )
+        r = repr(mode)
+        assert "id=1" in r
+        assert "rank=2" in r
+        assert "n_poses=1" in r
+        assert "F=-41.000" in r
+        assert "best_cf=-42.500" in r
+
+    def test_repr_without_optional_fields(self):
+        mode = BindingModeResult(mode_id=5, rank=1, poses=[])
+        r = repr(mode)
+        assert "id=5" in r
+        assert "n_poses=0" in r
+        assert "F=" not in r
+
+
+class TestDockingResultRepr:
+    def test_repr_with_temperature(self):
+        result = DockingResult(
+            source_dir=Path("/tmp/docking_run"),
+            binding_modes=[], temperature=300.0,
+        )
+        r = repr(result)
+        assert "n_modes=0" in r
+        assert "T=300.0K" in r
+        assert "docking_run" in r
+
+    def test_repr_without_temperature(self):
+        result = DockingResult(
+            source_dir=Path("/data/results"), binding_modes=[],
+        )
+        r = repr(result)
+        assert "n_modes=0" in r
+        assert "T=" not in r
+        assert "results" in r

python/tests/test_thermodynamics.py

@@ -133,6 +133,24 @@ def test_thermodynamics_dataclass_legacy():
     assert d["entropy_kcal_mol_K"] == 0.001667
 
 
+def test_thermodynamics_repr():
+    """Thermodynamics __repr__ includes key thermodynamic quantities."""
+    from flexaidds.thermodynamics import Thermodynamics
+
+    thermo = Thermodynamics(
+        temperature=300.0, log_Z=10.0, free_energy=-5.0,
+        mean_energy=-4.5, mean_energy_sq=20.5,
+        heat_capacity=0.1, entropy=0.001667, std_energy=0.3,
+    )
+    r = repr(thermo)
+    assert r.startswith("<Thermodynamics")
+    assert "T=300.0K" in r
+    assert "F=-5.000" in r
+    assert "H=-4.500" in r
+    assert "S=0.001667" in r
+    assert "Cv=0.100000" in r
+
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Tests that require the compiled C++ extension
 # ─────────────────────────────────────────────────────────────────────────────