From f312b6d43d54a85b5454fa64bc0ca1060ed908b2 Mon Sep 17 00:00:00 2001
From: jac16 <jennifer.clark@nist.gov>
Date: Wed, 13 Nov 2024 10:15:59 -0500
Subject: [PATCH] Update docstrings for units.py for the case of entropy values

---
 src/alchemlyb/estimators/mbar_.py     |  2 --
 src/alchemlyb/parsing/__init__.py     |  5 +++++
 src/alchemlyb/postprocessors/units.py | 13 ++++++++++++-
 3 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/src/alchemlyb/estimators/mbar_.py b/src/alchemlyb/estimators/mbar_.py
index 8edd8568..5b964057 100644
--- a/src/alchemlyb/estimators/mbar_.py
+++ b/src/alchemlyb/estimators/mbar_.py
@@ -232,8 +232,6 @@ def fit(self, u_nk, compute_entropy_enthalpy=False):
             self._d_delta_h_.attrs = u_nk.attrs
             self._delta_s_.attrs = u_nk.attrs
             self._d_delta_s_.attrs = u_nk.attrs
-            self._delta_s_.attrs["energy_unit"] = "k"
-            self._d_delta_s_.attrs["energy_unit"] = "k"
 
         return self
 
diff --git a/src/alchemlyb/parsing/__init__.py b/src/alchemlyb/parsing/__init__.py
index dc048732..c4bd8981 100644
--- a/src/alchemlyb/parsing/__init__.py
+++ b/src/alchemlyb/parsing/__init__.py
@@ -31,8 +31,13 @@ def wrapper(outfile, T, *args, **kwargs):
         dict_with_df = func(outfile, T, *args, **kwargs)
         for k in dict_with_df.keys():
             if dict_with_df[k] is not None:
+
+                if T < 273:
+                    raise ValueError("Temperature must be in Kelvin.")
+
                 dict_with_df[k].attrs["temperature"] = T
                 dict_with_df[k].attrs["energy_unit"] = "kT"
+
         return dict_with_df
 
     return wrapper
diff --git a/src/alchemlyb/postprocessors/units.py b/src/alchemlyb/postprocessors/units.py
index 510b4465..9b547055 100644
--- a/src/alchemlyb/postprocessors/units.py
+++ b/src/alchemlyb/postprocessors/units.py
@@ -16,6 +16,9 @@
 def to_kT(df, T=None):
     """Convert the unit of a DataFrame to `kT`.
 
+    Note that if entropy values are passed it is assumed that they are
+    multiplied by the temperature, S * T.
+    
     If temperature `T` is not provided, the DataFrame need to have attribute
     `temperature` and `energy_unit`. Otherwise, the temperature of the output
     dateframe will be set accordingly.
@@ -25,7 +28,7 @@ def to_kT(df, T=None):
     df : DataFrame
         DataFrame to convert unit.
     T : float
-        Temperature (default: None).
+        Temperature (default: None) in Kelvin.
 
     Returns
     -------
@@ -34,6 +37,8 @@ def to_kT(df, T=None):
     """
     new_df = df.copy()
     if T is not None:
+        if T < 273:
+            raise ValueError("Temperature must be in Kelvin.")
         new_df.attrs["temperature"] = T
     elif "temperature" not in df.attrs:
         raise TypeError("Attribute temperature not found in the input " "Dataframe.")
@@ -61,6 +66,9 @@ def to_kT(df, T=None):
 def to_kcalmol(df, T=None):
     """Convert the unit of a DataFrame to kcal/mol.
 
+    Note that if entropy values are passed, the result is S * T in units
+    of kcal/mol.
+    
     If temperature `T` is not provided, the DataFrame need to have attribute
     `temperature` and `energy_unit`. Otherwise, the temperature of the output
     dateframe will be set accordingly.
@@ -86,6 +94,9 @@ def to_kcalmol(df, T=None):
 def to_kJmol(df, T=None):
     """Convert the unit of a DataFrame to kJ/mol.
 
+    Note that if entropy values are passed, the result is S * T in units
+    of kJ/mol.
+    
     If temperature `T` is not provided, the DataFrame need to have attribute
     `temperature` and `energy_unit`. Otherwise, the temperature of the output
     dateframe will be set accordingly.