From 4c31acd4c6c186dbe6c16bd95fd484f3f50042d3 Mon Sep 17 00:00:00 2001
From: Deepti <kannandeepti@yahoo.com>
Date: Mon, 9 Jan 2023 14:56:42 -0500
Subject: [PATCH] DOC: clarify purpose of class/functions

---
 polychrom/param_units.py | 28 +++++++++++++++++++---------
 1 file changed, 19 insertions(+), 9 deletions(-)

diff --git a/polychrom/param_units.py b/polychrom/param_units.py
index 27b76c0..b9c44df 100644
--- a/polychrom/param_units.py
+++ b/polychrom/param_units.py
@@ -76,12 +76,21 @@
 
 class SimulationParams(object):
     """
-    This class provides guidance on how to choose polychrom parameters based
-    on principles of the Rouse polymer model. The parameters in the constructor
-    are usually set for computational convenience and do not have any physical
-    meaning, except the nubmer of monomers, N. The methods in this class provide
-    ways of calculating physically meaningful quantities in the Rouse model from
-    polychrom parameter values and vice versa.
+    The methods in this class provide ways of calculating physically meaningful
+    quantities in the Rouse model fromn polychrom parameter values and vice versa.
+    The parameters in the constructor are usually set for computational convenience
+    and do not have any physical meaning, except the nubmer of monomers, N.
+
+    Notes
+    -----
+    This is only one way to guess initial polychrom simulation parameters and is
+    exclusively based on the Rouse model, which may or may not apply to chromatin.
+
+    To do
+    -----
+    - add more functions to guess parameters based on desired dimensionless ratios
+    or experimental measurements.
+    - create additional classes based on other polymer models (not the Rouse model)
     """
 
     def __init__(
@@ -135,9 +144,10 @@ def get_D_from_measured_Dapp(
         Dapp=0.01 * unit.micrometer**2 / unit.second**0.5,
         b=40 * unit.nanometer,
     ):
-        """Measurements of the subdiffusive motion of chromosomal loci indicate that
-        MSD = D_app t^{1/2}, where Dapp is approximately 0.01 um^2 / s^{1/2}. Here, we
-        convert D_app to a monomer diffusion coefficient using a given Kuhn length b."""
+        """Extract the monomer diffusion coefficient from a given Kuhn length, b, and a measurement of the anomolus diffusion
+        coefficient D_app, where MSD = D_app t^{1/2}. Some measurements of the subdiffusive motion of chromosomal loci indicate that
+        Dapp is approximately 0.01 um^2 / s^{1/2}. Note, this assumes MSDs scale as :math:`t^{1/2}`. A different polymer model is
+        needed if a different scaling with time is observed."""
 
         if not isinstance(Dapp, unit.Quantity):
             raise ValueError("Dapp should be a simtk.Quantity object")