Index: sasmodels/models/core_shell_ellipsoid_xt.py
===================================================================
--- sasmodels/models/core_shell_ellipsoid_xt.py	(revision 29172aa52f4fdcefe534e792b14ec43221514fe1)
+++ sasmodels/models/core_shell_ellipsoid_xt.py	(revision 3556ad79872d55bd8cff8b5ca27db3a80f326f98)
@@ -89,7 +89,7 @@
 parameters = [
     ["equat_core",    "Ang",       20,   [0, inf],    "volume",      "Equatorial radius of core"],
-    ["x_core",        "None",       3,   [0, inf],    "volume",      "Polar radius of core"],
-    ["t_shell",       "Ang",       30,   [0, inf],    "volume",      "Equatorial radius of shell"],
-    ["x_polar_shell", "",           1,   [0, inf],    "volume",      "Polar radius of shell"],
+    ["x_core",        "None",       3,   [0, inf],    "volume",      "axial ratio of core, X = r_polar/r_equatorial"],
+    ["t_shell",       "Ang",       30,   [0, inf],    "volume",      "thickness of shell at equator"],
+    ["x_polar_shell", "",           1,   [0, inf],    "volume",      "ratio of thickness of shell at pole to that at equator"],
     ["sld_core",      "1e-6/Ang^2", 2,   [-inf, inf], "",            "Core scattering length density"],
     ["sld_shell",     "1e-6/Ang^2", 1,   [-inf, inf], "",            "Shell scattering length density"],
Index: sasmodels/models/core_shell_sphere.py
===================================================================
--- sasmodels/models/core_shell_sphere.py	(revision aa2edb2b2fb550caed0506dcf63bc7eac7e1779a)
+++ sasmodels/models/core_shell_sphere.py	(revision 3556ad79872d55bd8cff8b5ca27db3a80f326f98)
@@ -19,6 +19,6 @@
     V_s(\rho_s-\rho_{solv})\frac{\sin(qr_s)-qr_s\cos(qr_s)}{(qr_s)^3}\right]
 
-where $V_s$ is the volume of the outer shell, $V_c$ is
-the volume of the core, $r_s$ is the radius of the shell, $r_c$ is the radius of the
+where $V_s$ is the volume of the whole particle, $V_c$ is
+the volume of the core, $r_s$ = $radius$ + $thickness$ is the radius of the particle, $r_c$ is the radius of the
 core, $\rho_c$ is the scattering length density of the core, $\rho_s$ is the scattering length
 density of the shell, $\rho_{solv}$ is the scattering length density of the solvent.
@@ -30,6 +30,6 @@
 effective radius for $S(Q)$ when $P(Q) \cdot S(Q)$ is applied.
 
-Reference
----------
+References
+----------
 
 A Guinier and G Fournet, *Small-Angle Scattering of X-Rays*, John Wiley and Sons, New York, (1955)
@@ -49,6 +49,6 @@
 title = "Form factor for a monodisperse spherical particle with particle with a core-shell structure."
 description = """
-    F^2(q) = 3/V_s [V_c (core_sld-shell_sld) (sin(q*radius)-q*radius*cos(q*radius))/(q*radius)^3 
-                   + V_s (shell_sld-solvent_sld) (sin(q*r_s)-q*r_s*cos(q*r_s))/(q*r_s)^3]
+    F^2(q) = 3/V_s [V_c (sld_core-sld_shell) (sin(q*radius)-q*radius*cos(q*radius))/(q*radius)^3 
+                   + V_s (sld_shell-sld_solvent) (sin(q*r_s)-q*r_s*cos(q*r_s))/(q*r_s)^3]
 
             V_s: Volume of the sphere shell
@@ -62,7 +62,7 @@
 parameters = [["radius",      "Ang",        60.0, [0, inf],    "volume", "Sphere core radius"],
               ["thickness",   "Ang",        10.0, [0, inf],    "volume", "Sphere shell thickness"],
-              ["core_sld",    "1e-6/Ang^2", 1.0,  [-inf, inf], "",       "Sphere core scattering length density"],
-              ["shell_sld",   "1e-6/Ang^2", 2.0,  [-inf, inf], "",       "Sphere shell scattering length density"],
-              ["solvent_sld", "1e-6/Ang^2", 3.0,  [-inf, inf],  "",      "Solvent scattering length density"]]
+              ["sld_core",    "1e-6/Ang^2", 1.0,  [-inf, inf], "",       "core scattering length density"],
+              ["sld_shell",   "1e-6/Ang^2", 2.0,  [-inf, inf], "",       "shell scattering length density"],
+              ["sld_solvent", "1e-6/Ang^2", 3.0,  [-inf, inf],  "",      "Solvent scattering length density"]]
 # pylint: enable=bad-whitespace, line-too-long
 
@@ -70,8 +70,10 @@
 
 demo = dict(scale=1, background=0, radius=60, thickness=10,
-            core_sld=1.0, shell_sld=2.0, solvent_sld=0.0)
+            sld_core=1.0, sld_shell=2.0, sld_solvent=0.0)
 
 oldname = 'CoreShellModel'
-oldpars = {}
+oldpars = dict( sld_core='core_sld',
+               sld_shell='shell_sld',
+               sld_solvent='solvent_sld')
 
 def ER(radius, thickness):
@@ -99,7 +101,7 @@
          [{'radius': 60.0,
            'thickness': 10.0,
-           'core_sld': 1.0,
-           'shell_sld':2.0,
-           'solvent_sld':3.0,
+           'sld_core': 1.0,
+           'sld_shell':2.0,
+           'sld_solvent':3.0,
            'background':0.0
           }, 0.4, 0.000698838]]
Index: sasmodels/models/ellipsoid.py
===================================================================
--- sasmodels/models/ellipsoid.py	(revision 43b7eea5794b4eb3362114ebde67ff2fb1c38fdc)
+++ sasmodels/models/ellipsoid.py	(revision 3556ad79872d55bd8cff8b5ca27db3a80f326f98)
@@ -2,5 +2,5 @@
 # Note: model title and parameter table are inserted automatically
 r"""
-The form factor is normalized by the particle volume.
+The form factor is normalized by the particle volume 
 
 Definition
@@ -31,5 +31,5 @@
 
 $\alpha$ is the angle between the axis of the ellipsoid and $\vec q$,
-$V$ is the volume of the ellipsoid, $R_p$ is the polar radius along the
+$V = (4/3)\pi R_pR_e^2$ is the volume of the ellipsoid , $R_p$ is the polar radius along the
 rotational axis of the ellipsoid, $R_e$ is the equatorial radius perpendicular
 to the rotational axis of the ellipsoid and $\Delta \rho$ (contrast) is the
@@ -41,5 +41,5 @@
 :ref:`cylinder orientation figure <cylinder-angle-definition>`.
 For the ellipsoid, $\theta$ is the angle between the rotational axis
-and the $z$-axis.
+and the $z$ -axis.
 
 NB: The 2nd virial coefficient of the solid ellipsoid is calculated based
@@ -54,5 +54,5 @@
 .. figure:: img/ellipsoid_angle_projection.jpg
 
-    The angles for oriented ellipsoid.
+    The angles for oriented ellipsoid, shown here as oblate, $a$ = $R_p$ and $b$ = $R_e$
 
 Validation
@@ -74,5 +74,5 @@
     calculated from our 2D model and the intensity from the NIST SANS
     analysis software. The parameters used were: *scale* = 1.0,
-    *rpolar* = 20 |Ang|, *requatorial* = 400 |Ang|,
+    *r_polar* = 20 |Ang|, *r_equatorial* = 400 |Ang|,
     *contrast* = 3e-6 |Ang^-2|, and *background* = 0.0 |cm^-1|.
 
@@ -102,5 +102,5 @@
 description = """\
 P(q.alpha)= scale*f(q)^2 + background, where f(q)= 3*(sld
-        - solvent_sld)*V*[sin(q*r(Rp,Re,alpha))
+        - sld_solvent)*V*[sin(q*r(Rp,Re,alpha))
         -q*r*cos(qr(Rp,Re,alpha))]
         /[qr(Rp,Re,alpha)]^3"
@@ -110,5 +110,5 @@
 
         sld: SLD of the ellipsoid
-        solvent_sld: SLD of the solvent
+        sld_solvent: SLD of the solvent
         V: volume of the ellipsoid
         Rp: polar radius of the ellipsoid
@@ -120,9 +120,9 @@
 parameters = [["sld", "1e-6/Ang^2", 4, [-inf, inf], "",
                "Ellipsoid scattering length density"],
-              ["solvent_sld", "1e-6/Ang^2", 1, [-inf, inf], "",
+              ["sld_solvent", "1e-6/Ang^2", 1, [-inf, inf], "",
                "Solvent scattering length density"],
-              ["rpolar", "Ang", 20, [0, inf], "volume",
+              ["r_polar", "Ang", 20, [0, inf], "volume",
                "Polar radius"],
-              ["requatorial", "Ang", 400, [0, inf], "volume",
+              ["r_equatorial", "Ang", 400, [0, inf], "volume",
                "Equatorial radius"],
               ["theta", "degrees", 60, [-inf, inf], "orientation",
@@ -134,15 +134,15 @@
 source = ["lib/sph_j1c.c", "lib/gauss76.c", "ellipsoid.c"]
 
-def ER(rpolar, requatorial):
+def ER(r_polar, r_equatorial):
     import numpy as np
 
-    ee = np.empty_like(rpolar)
-    idx = rpolar > requatorial
-    ee[idx] = (rpolar[idx] ** 2 - requatorial[idx] ** 2) / rpolar[idx] ** 2
-    idx = rpolar < requatorial
-    ee[idx] = (requatorial[idx] ** 2 - rpolar[idx] ** 2) / requatorial[idx] ** 2
-    idx = rpolar == requatorial
-    ee[idx] = 2 * rpolar[idx]
-    valid = (rpolar * requatorial != 0)
+    ee = np.empty_like(r_polar)
+    idx = r_polar > r_equatorial
+    ee[idx] = (r_polar[idx] ** 2 - r_equatorial[idx] ** 2) / r_polar[idx] ** 2
+    idx = r_polar < r_equatorial
+    ee[idx] = (r_equatorial[idx] ** 2 - r_polar[idx] ** 2) / r_equatorial[idx] ** 2
+    idx = r_polar == r_equatorial
+    ee[idx] = 2 * r_polar[idx]
+    valid = (r_polar * r_equatorial != 0)
     bd = 1.0 - ee[valid]
     e1 = np.sqrt(ee[valid])
@@ -152,19 +152,19 @@
     delta = 0.75 * b1 * b2
 
-    ddd = np.zeros_like(rpolar)
-    ddd[valid] = 2.0 * (delta + 1.0) * rpolar * requatorial ** 2
+    ddd = np.zeros_like(r_polar)
+    ddd[valid] = 2.0 * (delta + 1.0) * r_polar * r_equatorial ** 2
     return 0.5 * ddd ** (1.0 / 3.0)
 
 
 demo = dict(scale=1, background=0,
-            sld=6, solvent_sld=1,
-            rpolar=50, requatorial=30,
+            sld=6, sld_solvent=1,
+            r_polar=50, r_equatorial=30,
             theta=30, phi=15,
-            rpolar_pd=.2, rpolar_pd_n=15,
-            requatorial_pd=.2, requatorial_pd_n=15,
+            r_polar_pd=.2, r_polar_pd_n=15,
+            r_equatorial_pd=.2, r_equatorial_pd_n=15,
             theta_pd=15, theta_pd_n=45,
             phi_pd=15, phi_pd_n=1)
 oldname = 'EllipsoidModel'
 oldpars = dict(theta='axis_theta', phi='axis_phi',
-               sld='sldEll', solvent_sld='sldSolv',
-               rpolar='radius_a', requatorial='radius_b')
+               sld='sldEll', sld_solvent='sldSolv',
+               r_polar='radius_a', r_equatorial='radius_b')
