Index: sasmodels/models/hardsphere.py
===================================================================
--- sasmodels/models/hardsphere.py	(revision 0507e09b26f5789862db8a175d64657cf4f3b829)
+++ sasmodels/models/hardsphere.py	(revision 5f3c53407f846f392cb5b6037b030e309de351eb)
@@ -1,22 +1,33 @@
 # Note: model title and parameter table are inserted automatically
-r"""Calculate the interparticle structure factor for monodisperse
+r"""
+Calculates the interparticle structure factor for monodisperse
 spherical particles interacting through hard sphere (excluded volume)
-interactions.
-May be a reasonable approximation for other shapes of particles that
-freely rotate, and for moderately polydisperse systems. Though strictly
-the maths needs to be modified (no \Beta(Q) correction yet in sasview).
+interactions. This $S(q)$ may also be a reasonable approximation for 
+other particle shapes that freely rotate (but see the note below), 
+and for moderately polydisperse systems.
+
+.. note::
+
+   This routine is intended for uncharged particles! For charged 
+   particles try using the :ref:`hayter-msa` $S(q)$ instead.
+   
+.. note::
+
+   Earlier versions of SasView did not incorporate the so-called 
+   $\beta(q)$ ("beta") correction [1] for polydispersity and non-sphericity. 
+   This is only available in SasView versions 4.2.2 and higher.
 
 radius_effective is the effective hard sphere radius.
 volfraction is the volume fraction occupied by the spheres.
 
-In sasview the effective radius may be calculated from the parameters
+In SasView the effective radius may be calculated from the parameters
 used in the form factor $P(q)$ that this $S(q)$ is combined with.
 
 For numerical stability the computation uses a Taylor series expansion
-at very small $qR$, there may be a very minor glitch at the transition point
-in some circumstances.
+at very small $qR$, but there may be a very minor glitch at the 
+transition point in some circumstances.
 
-The S(Q) uses the Percus-Yevick closure where the interparticle
-potential is
+This S(q) uses the Percus-Yevick closure relationship [2] where the 
+interparticle potential $U(r)$ is
 
 .. math::
@@ -27,5 +38,5 @@
     \end{cases}
 
-where $r$ is the distance from the center of the sphere of a radius $R$.
+where $r$ is the distance from the center of a sphere of a radius $R$.
 
 For a 2D plot, the wave transfer is defined as
@@ -38,4 +49,6 @@
 References
 ----------
+
+.. [#] M Kotlarchyk & S-H Chen, *J. Chem. Phys.*, 79 (1983) 2461-2469
 
 .. [#] J K Percus, J Yevick, *J. Phys. Rev.*, 110, (1958) 1
@@ -63,8 +76,8 @@
     [Hard sphere structure factor, with Percus-Yevick closure]
         Interparticle S(Q) for random, non-interacting spheres.
-    May be a reasonable approximation for other shapes of
-    particles that freely rotate, and for moderately polydisperse
-        systems. Though strictly the maths needs to be modified -
-    which sasview does not do yet.
+    May be a reasonable approximation for other particle shapes
+    that freely rotate, and for moderately polydisperse systems
+    . The "beta(q)" correction is available in versions 4.2.2
+    and higher.
     radius_effective is the hard sphere radius
     volfraction is the volume fraction occupied by the spheres.
Index: sasmodels/models/hayter_msa.py
===================================================================
--- sasmodels/models/hayter_msa.py	(revision 0507e09b26f5789862db8a175d64657cf4f3b829)
+++ sasmodels/models/hayter_msa.py	(revision 5f3c53407f846f392cb5b6037b030e309de351eb)
@@ -1,23 +1,40 @@
 # Note: model title and parameter table are inserted automatically
 r"""
-This calculates the structure factor (the Fourier transform of the pair
-correlation function $g(r)$) for a system of charged, spheroidal objects
-in a dielectric medium. When combined with an appropriate form factor
-(such as sphere, core+shell, ellipsoid, etc), this allows for inclusion
-of the interparticle interference effects due to screened coulomb repulsion
-between charged particles.
+Calculates the interparticle structure factor for a system of charged, 
+spheroidal, objects in a dielectric medium [1,2]. When combined with an 
+appropriate form factor $P(q)$, this allows for inclusion of the 
+interparticle interference effects due to screened Coulombic 
+repulsion between the charged particles.
 
-**This routine only works for charged particles**. If the charge is set to
-zero the routine may self-destruct! For non-charged particles use a hard
-sphere potential.
+.. note::
+
+   This routine only works for charged particles! If the charge is set 
+   to zero the routine may self-destruct! For uncharged particles use 
+   the :ref:`hardsphere` $S(q)$ instead.
+   
+.. note::
+
+   Earlier versions of SasView did not incorporate the so-called 
+   $\beta(q)$ ("beta") correction [3] for polydispersity and non-sphericity. 
+   This is only available in SasView versions 4.2.2 and higher.
 
 The salt concentration is used to compute the ionic strength of the solution
-which in turn is used to compute the Debye screening length. At present
-there is no provision for entering the ionic strength directly nor for use
-of any multivalent salts, though it should be possible to simulate the effect
-of this by increasing the salt concentration. The counterions are also
-assumed to be monovalent.
+which in turn is used to compute the Debye screening length. There is no 
+provision for entering the ionic strength directly. **At present the 
+counterions are assumed to be monovalent**, though it should be possible 
+to simulate the effect of multivalent counterions by increasing the salt 
+concentration.
 
-In sasview the effective radius may be calculated from the parameters
+Over the range 0 - 100 C the dielectric constant $\kappa$ of water may be 
+approximated with a maximum deviation of 0.01 units by the empirical 
+formula [4]
+
+.. math::
+
+    \kappa = 87.740 - 0.40008 T + 9.398x10^{-4} T^2 - 1.410x10^{-6} T^3
+    
+where $T$ is the temperature in celsius.
+
+In SasView the effective radius may be calculated from the parameters
 used in the form factor $P(q)$ that this $S(q)$ is combined with.
 
@@ -38,5 +55,10 @@
 
 .. [#] J B Hayter and J Penfold, *Molecular Physics*, 42 (1981) 109-118
+
 .. [#] J P Hansen and J B Hayter, *Molecular Physics*, 46 (1982) 651-656
+
+.. [#] M Kotlarchyk and S-H Chen, *J. Chem. Phys.*, 79 (1983) 2461-2469
+
+.. [#] C G Malmberg and A A Maryott, *J. Res. Nat. Bureau Standards*, 56 (1956) 2641
 
 Source
@@ -52,5 +74,5 @@
 * **Author:** 
 * **Last Modified by:** 
-* **Last Reviewed by:** 
+* **Last Reviewed by:** Steve King **Date:** March 27, 2019
 * **Source added by :** Steve King **Date:** March 25, 2019
 """
@@ -74,12 +96,11 @@
 
 name = "hayter_msa"
-title = "Hayter-Penfold rescaled MSA, charged sphere, interparticle S(Q) structure factor"
+title = "Hayter-Penfold Rescaled Mean Spherical Approximation (RMSA) structure factor for charged spheres"
 description = """\
     [Hayter-Penfold RMSA charged sphere interparticle S(Q) structure factor]
-        Interparticle structure factor S(Q)for a charged hard spheres.
-        Routine takes absolute value of charge, use HardSphere if charge
-        goes to zero.
-        In sasview the effective radius and volume fraction may be calculated
-        from the parameters used in P(Q).
+        Interparticle structure factor S(Q) for charged hard spheres.
+    This routine only works for charged particles! For uncharged particles 
+    use the hardsphere S(q) instead. The "beta(q)" correction is available 
+    in versions 4.2.2 and higher.
 """
 
@@ -93,5 +114,5 @@
     ["temperature",   "K",  318.16,   [0, 450],    "", "temperature, in Kelvin, for Debye length calculation"],
     ["concentration_salt",      "M",    0.0,    [0, inf], "", "conc of salt, moles/litre, 1:1 electolyte, for Debye length"],
-    ["dielectconst",  "None",    71.08,   [-inf, inf], "", "dielectric constant (relative permittivity) of solvent, default water, for Debye length"]
+    ["dielectconst",  "None",    71.08,   [-inf, inf], "", "dielectric constant (relative permittivity) of solvent, kappa, default water, for Debye length"]
     ]
 # pylint: enable=bad-whitespace, line-too-long
Index: sasmodels/models/squarewell.py
===================================================================
--- sasmodels/models/squarewell.py	(revision 0507e09b26f5789862db8a175d64657cf4f3b829)
+++ sasmodels/models/squarewell.py	(revision 5f3c53407f846f392cb5b6037b030e309de351eb)
@@ -1,16 +1,24 @@
 # Note: model title and parameter table are inserted automatically
 r"""
-This calculates the interparticle structure factor for a square well fluid
-spherical particles. The mean spherical approximation (MSA) closure was
-used for this calculation, and is not the most appropriate closure for
-an attractive interparticle potential. This solution has been compared
-to Monte Carlo simulations for a square well fluid, showing this calculation
-to be limited in applicability to well depths $\epsilon < 1.5$ kT and
-volume fractions $\phi < 0.08$.
+Calculates the interparticle structure factor for a hard sphere fluid 
+with a narrow, attractive, square well potential. **The Mean Spherical 
+Approximation (MSA) closure relationship is used, but it is not the most 
+appropriate closure for an attractive interparticle potential.** However, 
+the solution has been compared to Monte Carlo simulations for a square 
+well fluid and these show the MSA calculation to be limited to well 
+depths $\epsilon < 1.5$ kT and volume fractions $\phi < 0.08$.
 
 Positive well depths correspond to an attractive potential well. Negative
 well depths correspond to a potential "shoulder", which may or may not be
-physically reasonable. The stickyhardsphere model may be a better choice in
-some circumstances. Computed values may behave badly at extremely small $qR$.
+physically reasonable. The :ref:`stickyhardsphere` model may be a better 
+choice in some circumstances.
+
+Computed values may behave badly at extremely small $qR$.
+
+.. note::
+
+   Earlier versions of SasView did not incorporate the so-called 
+   $\beta(q)$ ("beta") correction [2] for polydispersity and non-sphericity. 
+   This is only available in SasView versions 4.2.2 and higher.
 
 The well width $(\lambda)$ is defined as multiples of the particle diameter
@@ -18,6 +26,4 @@
 
 The interaction potential is:
-
-  .. image:: img/squarewell.png
 
 .. math::
@@ -29,7 +35,7 @@
     \end{cases}
 
-where $r$ is the distance from the center of the sphere of a radius $R$.
+where $r$ is the distance from the center of a sphere of a radius $R$.
 
-In sasview the effective radius may be calculated from the parameters
+In SasView the effective radius may be calculated from the parameters
 used in the form factor $P(q)$ that this $S(q)$ is combined with.
 
@@ -46,4 +52,6 @@
 .. [#] R V Sharma, K C Sharma, *Physica*, 89A (1977) 213
 
+.. [#] M Kotlarchyk and S-H Chen, *J. Chem. Phys.*, 79 (1983) 2461-2469
+
 Source
 ------
@@ -56,5 +64,5 @@
 * **Author:** 
 * **Last Modified by:** 
-* **Last Reviewed by:** 
+* **Last Reviewed by:** Steve King **Date:** March 27, 2019
 * **Source added by :** Steve King **Date:** March 25, 2019
 """
@@ -64,12 +72,12 @@
 
 name = "squarewell"
-title = "Square well structure factor, with MSA closure"
+title = "Square well structure factor with Mean Spherical Approximation closure"
 description = """\
     [Square well structure factor, with MSA closure]
-        Interparticle structure factor S(Q)for a hard sphere fluid with
-        a narrow attractive well. Fits are prone to deliver non-physical
-        parameters, use with care and read the references in the full manual.
-        In sasview the effective radius will be calculated from the
-        parameters used in P(Q).
+        Interparticle structure factor S(Q) for a hard sphere fluid 
+    with a narrow attractive well. Fits are prone to deliver non-
+    physical parameters; use with care and read the references in 
+    the model documentation.The "beta(q)" correction is available 
+    in versions 4.2.2 and higher.
 """
 category = "structure-factor"
Index: sasmodels/models/stickyhardsphere.py
===================================================================
--- sasmodels/models/stickyhardsphere.py	(revision 0507e09b26f5789862db8a175d64657cf4f3b829)
+++ sasmodels/models/stickyhardsphere.py	(revision 5f3c53407f846f392cb5b6037b030e309de351eb)
@@ -1,23 +1,23 @@
 # Note: model title and parameter table are inserted automatically
 r"""
-This calculates the interparticle structure factor for a hard sphere fluid
-with a narrow attractive well. A perturbative solution of the Percus-Yevick
-closure is used. The strength of the attractive well is described in terms
-of "stickiness" as defined below.
-
-The perturb (perturbation parameter), $\epsilon$, should be held between 0.01
-and 0.1. It is best to hold the perturbation parameter fixed and let
-the "stickiness" vary to adjust the interaction strength. The stickiness,
-$\tau$, is defined in the equation below and is a function of both the
-perturbation parameter and the interaction strength. $\tau$ and $\epsilon$
-are defined in terms of the hard sphere diameter $(\sigma = 2 R)$, the
-width of the square well, $\Delta$ (same units as $R$\ ), and the depth of
-the well, $U_o$, in units of $kT$. From the definition, it is clear that
-smaller $\tau$ means stronger attraction.
+Calculates the interparticle structure factor for a hard sphere fluid 
+with a narrow, attractive, potential well. Unlike the :ref:`squarewell` 
+model, here a perturbative solution of the Percus-Yevick closure 
+relationship is used. The strength of the attractive well is described 
+in terms of "stickiness" as defined below.
+
+The perturbation parameter (perturb), $\tau$, should be fixed between 0.01
+and 0.1 and the "stickiness", $\epsilon$, allowed to vary to adjust the 
+interaction strength. The "stickiness" is defined in the equation below and is 
+a function of both the perturbation parameter and the interaction strength. 
+$\epsilon$ and $\tau$ are defined in terms of the hard sphere diameter $(\sigma = 2 R)$, 
+the width of the square well, $\Delta$ (having the same units as $R$\ ), 
+and the depth of the well, $U_o$, in units of $kT$. From the definition, it 
+is clear that smaller $\epsilon$ means a stronger attraction.
 
 .. math::
 
-    \tau     &= \frac{1}{12\epsilon} \exp(u_o / kT) \\
-    \epsilon &= \Delta / (\sigma + \Delta)
+    \epsilon     &= \frac{1}{12\tau} \exp(u_o / kT) \\
+    \tau &= \Delta / (\sigma + \Delta)
 
 where the interaction potential is
@@ -31,23 +31,32 @@
         \end{cases}
 
-The Percus-Yevick (PY) closure was used for this calculation, and is an
-adequate closure for an attractive interparticle potential. This solution
+The Percus-Yevick (PY) closure is used for this calculation, and is an
+adequate closure for an attractive interparticle potential. The solution
 has been compared to Monte Carlo simulations for a square well fluid, with
 good agreement.
 
-The true particle volume fraction, $\phi$, is not equal to $h$, which appears
-in most of the reference. The two are related in equation (24) of the
-reference. The reference also describes the relationship between this
-perturbation solution and the original sticky hard sphere (or adhesive
-sphere) model by Baxter.
-
-**NB**: The calculation can go haywire for certain combinations of the input
-parameters, producing unphysical solutions - in this case errors are
-reported to the command window and the $S(q)$ is set to -1 (so it will
-disappear on a log-log plot). Use tight bounds to keep the parameters to
-values that you know are physical (test them) and keep nudging them until
-the optimization does not hit the constraints.
-
-In sasview the effective radius may be calculated from the parameters
+The true particle volume fraction, $\phi$, is not equal to $h$ which appears
+in most of reference [1]. The two are related in equation (24). Reference 
+[1] also describes the relationship between this perturbative solution and 
+the original sticky hard sphere (or "adhesive sphere") model of Baxter [2].
+
+.. note::
+
+   The calculation can go haywire for certain combinations of the input
+   parameters, producing unphysical solutions. In this case errors are
+   reported to the command window and $S(q)$ is set to -1 (so it will
+   disappear on a log-log plot!).
+   
+   Use tight bounds to keep the parameters to values that you know are 
+   physical (test them), and keep nudging them until the optimization 
+   does not hit the constraints.
+
+.. note::
+
+   Earlier versions of SasView did not incorporate the so-called 
+   $\beta(q)$ ("beta") correction [3] for polydispersity and non-sphericity. 
+   This is only available in SasView versions 4.2.2 and higher.
+   
+In SasView the effective radius may be calculated from the parameters
 used in the form factor $P(q)$ that this $S(q)$ is combined with.
 
@@ -65,4 +74,8 @@
 .. [#] S V G Menon, C Manohar, and K S Rao, *J. Chem. Phys.*, 95(12) (1991) 9186-9190
 
+.. [#] R J Baxter, *J. Chem. Phys.*, 49 (1968), 2770-2774
+
+.. [#] M Kotlarchyk and S-H Chen, *J. Chem. Phys.*, 79 (1983) 2461-2469
+
 Source
 ------
@@ -75,5 +88,5 @@
 * **Author:** 
 * **Last Modified by:** 
-* **Last Reviewed by:** 
+* **Last Reviewed by:** Steve King **Date:** March 27, 2019
 * **Source added by :** Steve King **Date:** March 25, 2019
 """
@@ -85,12 +98,12 @@
 
 name = "stickyhardsphere"
-title = "Sticky hard sphere structure factor, with Percus-Yevick closure"
+title = "'Sticky' hard sphere structure factor with Percus-Yevick closure"
 description = """\
     [Sticky hard sphere structure factor, with Percus-Yevick closure]
-        Interparticle structure factor S(Q)for a hard sphere fluid with
-        a narrow attractive well. Fits are prone to deliver non-physical
-        parameters, use with care and read the references in the full manual.
-        In sasview the effective radius will be calculated from the
-        parameters used in P(Q).
+        Interparticle structure factor S(Q) for a hard sphere fluid 
+    with a narrow attractive well. Fits are prone to deliver non-
+    physical parameters; use with care and read the references in 
+    the model documentation.The "beta(q)" correction is available 
+    in versions 4.2.2 and higher.
 """
 category = "structure-factor"
@@ -107,7 +120,7 @@
      "volume fraction of hard spheres"],
     ["perturb", "", 0.05, [0.01, 0.1], "",
-     "perturbation parameter, epsilon"],
+     "perturbation parameter, tau"],
     ["stickiness", "", 0.20, [-inf, inf], "",
-     "stickiness, tau"],
+     "stickiness, epsilon"],
     ]
 
