Index: sasmodels/models/core_shell_ellipsoid.py
===================================================================
--- sasmodels/models/core_shell_ellipsoid.py	(revision 22221346d45e39a667fe231ce7ca5ecfc79b0ac5)
+++ sasmodels/models/core_shell_ellipsoid.py	(revision 5031ca39a761c97db704b9b8e3a0f211847bb0db)
@@ -1,132 +1,121 @@
 r"""
-This model provides the form factor, $P(q)$, for a core shell ellipsoid (below)
-where the form factor is normalized by the volume of the outer [CHECK].
+An alternative version of $P(q)$ for the core_shell_ellipsoid
+having as parameters the core axial ratio X and a shell thickness,
+which are more often what we would like to determine.
 
-.. math::
-
-    P(q) = \text{scale} * \left<f^2\right>/V + \text{background}
-
-where the volume $V = (4/3)\pi(r_\text{major outer} r_\text{minor outer}^2)$
-and the averaging $< >$ is applied over all orientations for 1D.
-
-.. figure:: img/core_shell_ellipsoid_geometry.png
-
-    The returned value is in units of |cm^-1|, on absolute scale.
+This model is also better behaved when polydispersity is applied than the four
+independent radii in core_shell_ellipsoid model.
 
 Definition
 ----------
 
-The form factor calculated is
+.. figure:: img/core_shell_ellipsoid_geometry.png
 
-.. math::
+The geometric parameters of this model are
 
-    P(q) &= \frac{\text{scale}}{V}\int_0^1
-        \left|F(q,r_\text{minor core},r_\text{major core},\alpha)
-        + F(q,r_\text{minor outer},r_\text{major outer},\alpha)\right|^2
-        d\alpha
-        + \text{background}
+*radius_equat_core =* equatorial core radius *= R_minor_core*
 
-    \left|F(q,r_\text{minor},r_\text{major},\alpha)\right|
-        &=(4\pi/3)r_\text{major}r_\text{minor}^2 \Delta \rho \cdot (3j_1(u)/u)
+*X_core = polar_core / radius_equat_core = Rmajor_core / Rminor_core*
 
-    u &= q\left[ r_\text{major}^2\alpha ^2
-                  + r_\text{minor}^2(1-\alpha ^2)\right]^{1/2}
+*Thick_shell = equat_outer - radius_equat_core = Rminor_outer - Rminor_core*
 
-where
+*XpolarShell = Tpolar_shell / Thick_shell = (Rmajor_outer - Rmajor_core)/
+(Rminor_outer - Rminor_core)*
 
-.. math::
+In terms of the original radii
 
-    j_1(u)=(\sin x - x \cos x)/x^2
+*polar_core = radius_equat_core * X_core*
 
-To provide easy access to the orientation of the core-shell ellipsoid,
-we define the axis of the solid ellipsoid using two angles $\theta$ and $\phi$.
-These angles are defined as for
-:ref:`cylinder orientation <cylinder-angle-definition>`.
-The contrast is defined as SLD(core) - SLD(shell) and SLD(shell) - SLD(solvent).
+*equat_shell = radius_equat_core + Thick_shell*
 
-Note: It is the users' responsibility to ensure that shell radii are larger than
-the core radii, especially if both are polydisperse, in which case the
-core_shell_ellipsoid_xt model may be much better.
+*polar_shell = radius_equat_core * X_core + Thick_shell * XpolarShell*
 
+(where we note that "shell" perhaps confusingly, relates to the outer radius)
+When *X_core < 1* the core is oblate; when *X_core > 1* it is prolate.
+*X_core = 1* is a spherical core.
 
-.. note::
-    The 2nd virial coefficient of the solid ellipsoid is calculated based on
-    the *radius_a* (= *radius_polar_shell)* and *radius_b (= radius_equat_shell)* values,
-    and used as the effective radius for *S(Q)* when $P(Q) * S(Q)$ is applied.
+For a fixed shell thickness *XpolarShell = 1*, to scale the shell thickness
+pro-rata with the radius *XpolarShell = X_core*.
 
-.. figure:: img/core_shell_ellipsoid_angle_projection.jpg
+When including an $S(q)$, the radius in $S(q)$ is calculated to be that of
+a sphere with the same 2nd virial coefficient of the outer surface of the
+ellipsoid. This may have some undesirable effects if the aspect ratio of the
+ellipsoid is large (ie, if $X << 1$ or $X >> 1$ ), when the $S(q)$
+- which assumes spheres - will not in any case be valid.
 
-    The angles for oriented core_shell_ellipsoid.
-
-Our model uses the form factor calculations implemented in a c-library provided
-by the NIST Center for Neutron Research (Kline, 2006).
+If SAS data are in absolute units, and the SLDs are correct, then scale should
+be the total volume fraction of the "outer particle". When $S(q)$ is introduced
+this moves to the $S(q)$ volume fraction, and scale should then be 1.0,
+or contain some other units conversion factor (for example, if you have SAXS data).
 
 References
 ----------
 
-M Kotlarchyk, S H Chen, *J. Chem. Phys.*, 79 (1983) 2461
+R K Heenan, 2015, reparametrised the core_shell_ellipsoid model
 
-S J Berr, *Phys. Chem.*, 91 (1987) 4760
 """
 
 from numpy import inf, sin, cos, pi
 
-name = "core_shell_ellipsoid"
+name = "core_shell_ellipsoid_xt"
 title = "Form factor for an spheroid ellipsoid particle with a core shell structure."
 description = """
-    [SpheroidCoreShellModel] Calculates the form factor for an spheroid
-    ellipsoid particle with a core_shell structure.
-    The form factor is averaged over all possible
-    orientations of the ellipsoid such that P(q)
-    = scale*<f^2>/Vol + bkg, where f is the
-    single particle scattering amplitude.
-    [Parameters]:
-    radius_equat_core = equatorial radius of core, Rminor_core,
-    radius_polar_core = polar radius of core, Rmajor_core,
-    radius_equat_shell = equatorial radius of shell, Rminor_outer,
-    radius_polar_shell = polar radius of shell, Rmajor_outer,
-    sld_core = scattering length density of core,
-    sld_shell = scattering length density of shell,
-    sld_solvent = scattering length density of solvent,
-    background = Incoherent bkg
-    scale =scale
-    Note:It is the users' responsibility to ensure
-    that shell radii are larger than core radii,
-    especially if both are polydisperse.
-    oblate: polar radius < equatorial radius
-    prolate :  polar radius > equatorial radius
+        [core_shell_ellipsoid_xt] Calculates the form factor for an spheroid
+        ellipsoid particle with a core_shell structure.
+        The form factor is averaged over all possible
+        orientations of the ellipsoid such that P(q)
+        = scale*<f^2>/Vol + bkg, where f is the
+        single particle scattering amplitude.
+        [Parameters]:
+        radius_equat_core = equatorial radius of core,
+        x_core = ratio of core polar/equatorial radii,
+        thick_shell = equatorial radius of outer surface,
+        x_polar_shell = ratio of polar shell thickness to equatorial shell thickness,
+        sld_core = SLD_core
+        sld_shell = SLD_shell
+        sld_solvent = SLD_solvent
+        background = Incoherent bkg
+        scale =scale
+        Note:It is the users' responsibility to ensure
+        that shell radii are larger than core radii.
+        oblate: polar radius < equatorial radius
+        prolate :  polar radius > equatorial radius - this new model will make this easier
+        and polydispersity integrals more logical (as previously the shell could disappear).
     """
 category = "shape:ellipsoid"
 
 # pylint: disable=bad-whitespace, line-too-long
-#   ["name", "units", default, [lower, upper], "type", "description"],
+#             ["name", "units", default, [lower, upper], "type", "description"],
 parameters = [
-    ["radius_equat_core",  "Ang",      200,   [0, inf],    "volume",      "Equatorial radius of core, r minor core"],
-    ["radius_polar_core",  "Ang",       10,   [0, inf],    "volume",      "Polar radius of core, r major core"],
-    ["radius_equat_shell", "Ang",      250,   [0, inf],    "volume",      "Equatorial radius of shell, r minor outer"],
-    ["radius_polar_shell", "Ang",       30,   [0, inf],    "volume",      "Polar radius of shell, r major outer"],
-    ["sld_core",    "1e-6/Ang^2", 2,   [-inf, inf], "sld",         "Core scattering length density"],
-    ["sld_shell",   "1e-6/Ang^2", 1,   [-inf, inf], "sld",         "Shell scattering length density"],
-    ["sld_solvent", "1e-6/Ang^2", 6.3, [-inf, inf], "sld",         "Solvent scattering length density"],
-    ["theta",       "degrees",    0,   [-inf, inf], "orientation", "Oblate orientation wrt incoming beam"],
-    ["phi",         "degrees",    0,   [-inf, inf], "orientation", "Oblate orientation in the plane of the detector"],
+    ["radius_equat_core","Ang",     20,   [0, inf],    "volume",      "Equatorial radius of core"],
+    ["x_core",        "None",       3,   [0, inf],    "volume",      "axial ratio of core, X = r_polar/r_equatorial"],
+    ["thick_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], "sld",         "Core scattering length density"],
+    ["sld_shell",     "1e-6/Ang^2", 1,   [-inf, inf], "sld",         "Shell scattering length density"],
+    ["sld_solvent",   "1e-6/Ang^2", 6.3, [-inf, inf], "sld",         "Solvent scattering length density"],
+    ["theta",         "degrees",    0,   [-inf, inf], "orientation", "Oblate orientation wrt incoming beam"],
+    ["phi",           "degrees",    0,   [-inf, inf], "orientation", "Oblate orientation in the plane of the detector"],
     ]
 # pylint: enable=bad-whitespace, line-too-long
 
-source = ["lib/sph_j1c.c", "lib/gfn.c", "lib/gauss76.c", "core_shell_ellipsoid.c"]
+source = ["lib/sph_j1c.c", "lib/gfn.c", "lib/gauss76.c",
+          "core_shell_ellipsoid_xt.c"]
 
-def ER(radius_equat_core, radius_polar_core, radius_equat_shell, radius_polar_shell):
+def ER(radius_equat_core, x_core, thick_shell, x_polar_shell):
     """
         Returns the effective radius used in the S*P calculation
     """
     from .ellipsoid import ER as ellipsoid_ER
-    return ellipsoid_ER(radius_polar_shell, radius_equat_shell)
+    polar_outer = radius_equat_core*x_core + thick_shell*x_polar_shell
+    equat_outer = radius_equat_core + thick_shell
+    return ellipsoid_ER(polar_outer, equat_outer)
 
 
-demo = dict(scale=1, background=0.001,
-            radius_equat_core=200.0,
-            radius_polar_core=10.0,
-            radius_equat_shell=250.0,
-            radius_polar_shell=30.0,
+demo = dict(scale=0.05, background=0.001,
+            radius_equat_core=20.0,
+            x_core=3.0,
+            thick_shell=30.0,
+            x_polar_shell=1.0,
             sld_core=2.0,
             sld_shell=1.0,
@@ -141,9 +130,9 @@
 
 tests = [
-    # Accuracy tests based on content in test/utest_other_models.py
+    # Accuracy tests based on content in test/utest_coreshellellipsoidXTmodel.py
     [{'radius_equat_core': 200.0,
-      'radius_polar_core': 20.0,
-      'radius_equat_shell': 250.0,
-      'radius_polar_shell': 30.0,
+      'x_core': 0.1,
+      'thick_shell': 50.0,
+      'x_polar_shell': 0.2,
       'sld_core': 2.0,
       'sld_shell': 1.0,
@@ -154,10 +143,10 @@
 
     # Additional tests with larger range of parameters
-    [{'background': 0.01}, 0.1, 8.86741],
+    [{'background': 0.01}, 0.1, 11.6915],
 
     [{'radius_equat_core': 20.0,
-      'radius_polar_core': 200.0,
-      'radius_equat_shell': 54.0,
-      'radius_polar_shell': 3.0,
+      'x_core': 200.0,
+      'thick_shell': 54.0,
+      'x_polar_shell': 3.0,
       'sld_core': 20.0,
       'sld_shell': 10.0,
@@ -165,12 +154,12 @@
       'background': 0.0,
       'scale': 1.0,
-     }, 0.01, 26150.4],
+     }, 0.01, 8688.53],
 
-    [{'background': 0.001}, (0.4, 0.5), 0.00170471],
+    [{'background': 0.001}, (0.4, 0.5), 0.00690673],
 
     [{'radius_equat_core': 20.0,
-      'radius_polar_core': 200.0,
-      'radius_equat_shell': 54.0,
-      'radius_polar_shell': 3.0,
+      'x_core': 200.0,
+      'thick_shell': 54.0,
+      'x_polar_shell': 3.0,
       'sld_core': 20.0,
       'sld_shell': 10.0,
@@ -178,4 +167,4 @@
       'background': 0.01,
       'scale': 0.01,
-     }, (qx, qy), 0.105764],
+     }, (qx, qy), 0.0100002],
     ]
