# source:sasmodels/sasmodels/models/core_shell_ellipsoid.py@830cf6b

ticket-1257-vesicle-productticket_1156ticket_822_more_unit_tests
Last change on this file since 830cf6b was 830cf6b, checked in by Paul Kienzle <pkienzle@…>, 8 months ago

Merge branch 'master' into ticket_822_v5_unit_tests

• Property mode set to 100644
File size: 8.7 KB
Line
1r"""
2Definition
3----------
4
5Parameters for this model are the core axial ratio $X_{core}$ and a shell
6thickness $t_{shell}$, which are more often what we would like to determine
7and make the model better behaved, particularly when polydispersity is
8applied, than the four independent radii used in the original parameterization
9of this model.
10
11
12.. figure:: img/core_shell_ellipsoid_geometry.png
13
14The geometric parameters of this model are shown in the diagram above, which
15shows (a) a cut through at the circular equator and (b) a cross section through
16the poles, of a prolate ellipsoid.
17
18When $X_{core}$ < 1 the core is oblate; when $X_{core}$ > 1 it is prolate.
19$X_{core}$ = 1 is a spherical core.
20
21For a fixed shell thickness $X_{polar shell}$ = 1, to scale $t_{shell}$
22pro-rata with the radius set or constrain $X_{polar shell}$ = $X_{core}$.
23
24.. note::
25
26   When including an $S(q)$, the radius in $S(q)$ is calculated to be that of
27   a sphere with the same 2nd virial coefficient of the outer surface of the
28   ellipsoid. This may have some undesirable effects if the aspect ratio of the
29   ellipsoid is large (ie, if $X << 1$ or $X >> 1$), when the $S(q)$
30   - which assumes spheres - will not in any case be valid.  Generating a
31   custom product model will enable separate effective volume fraction and
32   effective radius in the $S(q)$.
33
34If SAS data are in absolute units, and the SLDs are correct, then scale should
35be the total volume fraction of the "outer particle". When $S(q)$ is introduced
36this moves to the $S(q)$ volume fraction, and scale should then be 1.0, or
37contain some other units conversion factor (for example, if you have SAXS data).
38
39The calculation of intensity follows that for the solid ellipsoid, but
40with separate terms for the core-shell and shell-solvent boundaries.
41
42.. math::
43
44    P(q,\alpha) = \frac{\text{scale}}{V} F^2(q,\alpha) + \text{background}
45
46where
47
48.. In following equation SK changed radius\_equat\_core to R_e
49.. math::
50    :nowrap:
51
52    \begin{align*}
53    F(q,\alpha) = &f(q,R_e,R_e.x_{core},\alpha) \\
54    &+ f(q,R_e + t_{shell},
55         R_e.x_{core} + t_{shell}.x_{polar shell},\alpha)
56    \end{align*}
57
58where
59
60.. math::
61
62    f(q,R_e,R_p,\alpha) = \frac{3 \Delta \rho V (\sin[qr(R_p,R_e,\alpha)]
63                - \cos[qr(R_p,R_e,\alpha)])}
64                {[qr(R_p,R_e,\alpha)]^3}
65
66and
67
68.. math::
69
70    r(R_e,R_p,\alpha) = \left[ R_e^2 \sin^2 \alpha
71        + R_p^2 \cos^2 \alpha \right]^{1/2}
72
73
74$\alpha$ is the angle between the axis of the ellipsoid and $\vec q$,
75$V = (4/3)\pi R_pR_e^2$ is the volume of the ellipsoid , $R_p$ is the
76polar radius along the rotational axis of the ellipsoid, $R_e$ is the
77equatorial radius perpendicular to the rotational axis of the ellipsoid,
78$t_{shell}$ is the thickness of the shell at the equator,
79and $\Delta \rho$ (the contrast) is the scattering length density difference,
80either $(\rho_{core} - \rho_{shell})$ or $(\rho_{shell} - \rho_{solvent})$.
81
82For randomly oriented particles:
83
84.. math::
85
86   F^2(q)=\int_{0}^{\pi/2}{F^2(q,\alpha)\sin(\alpha)d\alpha}
87
88For oriented ellipsoids the *theta*, *phi* and *psi* orientation parameters
89will appear when fitting 2D data, see the :ref:elliptical-cylinder model
90for further information.
91
92References
93----------
94see for example:
95
96.. [#] Kotlarchyk, M.; Chen, S.-H. *J. Chem. Phys.*, 1983, 79, 2461
97.. [#] Berr, S. *J. Phys. Chem.*, 1987, 91, 4760
98
99Source
100------
101
102core_shell_ellipsoid.py <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/core_shell_ellipsoid.py>_
103
104core_shell_ellipsoid.c <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/core_shell_ellipsoid.c>_
105
106Authorship and Verification
107----------------------------
108
109* **Author:** NIST IGOR/DANSE **Date:** pre 2010
111* **Last Reviewed by:** Steve King **Date:** March 27, 2019
112* **Source added by :** Steve King **Date:** March 25, 2019
113"""
114
115import numpy as np
116from numpy import inf, sin, cos, pi
117
118name = "core_shell_ellipsoid"
119title = "Form factor for an spheroid ellipsoid particle with a core shell structure."
120description = """
121        [core_shell_ellipsoid] Calculates the form factor for an spheroid
122        ellipsoid particle with a core_shell structure.
123        The form factor is averaged over all possible
124        orientations of the ellipsoid such that P(q)
125        = scale*<f^2>/Vol + bkg, where f is the
126        single particle scattering amplitude.
127        [Parameters]:
129        x_core = ratio of core polar/equatorial radii,
130        thick_shell = equatorial radius of outer surface,
131        x_polar_shell = ratio of polar shell thickness to equatorial shell thickness,
132        sld_core = SLD_core
133        sld_shell = SLD_shell
134        sld_solvent = SLD_solvent
135        background = Incoherent bkg
136        scale =scale
137        Note:It is the users' responsibility to ensure
140        prolate :  polar radius > equatorial radius - this new model will make this easier
141        and polydispersity integrals more logical (as previously the shell could disappear).
142    """
143category = "shape:ellipsoid"
144
146#             ["name", "units", default, [lower, upper], "type", "description"],
147parameters = [
149    ["x_core",        "None",       3,   [0, inf],    "volume",      "axial ratio of core, X = r_polar/r_equatorial"],
150    ["thick_shell",   "Ang",       30,   [0, inf],    "volume",      "thickness of shell at equator"],
151    ["x_polar_shell", "",           1,   [0, inf],    "volume",      "ratio of thickness of shell at pole to that at equator"],
152    ["sld_core",      "1e-6/Ang^2", 2,   [-inf, inf], "sld",         "Core scattering length density"],
153    ["sld_shell",     "1e-6/Ang^2", 1,   [-inf, inf], "sld",         "Shell scattering length density"],
154    ["sld_solvent",   "1e-6/Ang^2", 6.3, [-inf, inf], "sld",         "Solvent scattering length density"],
155    ["theta",         "degrees",    0,   [-360, 360], "orientation", "elipsoid axis to beam angle"],
156    ["phi",           "degrees",    0,   [-360, 360], "orientation", "rotation about beam"],
157    ]
159
160source = ["lib/sas_3j1x_x.c", "lib/gauss76.c", "core_shell_ellipsoid.c"]
161have_Fq = True
163    "average outer curvature", "equivalent volume sphere",
165    ]
166
167def random():
168    """Return a random parameter set for the model."""
169    volume = 10**np.random.uniform(5, 12)
170    outer_polar = 10**np.random.uniform(1.3, 4)
171    outer_equatorial = np.sqrt(volume/outer_polar) # ignore 4/3 pi
172    # Use a distribution with a preference for thin shell or thin core
173    # Avoid core,shell radii < 1
174    thickness_polar = np.random.beta(0.5, 0.5)*(outer_polar-2) + 1
175    thickness_equatorial = np.random.beta(0.5, 0.5)*(outer_equatorial-2) + 1
176    radius_polar = outer_polar - thickness_polar
177    radius_equatorial = outer_equatorial - thickness_equatorial
179    x_polar_shell = thickness_polar/thickness_equatorial
180    pars = dict(
181        #background=0, sld=0, sld_solvent=1,
183        x_core=x_core,
184        thick_shell=thickness_equatorial,
185        x_polar_shell=x_polar_shell,
186    )
187    return pars
188
189q = 0.1
190# tests had in old coords theta=0, phi=0; new coords theta=90, phi=0
191qx = q*cos(pi/6.0)
192qy = q*sin(pi/6.0)
193# 11Jan2017 RKH sorted tests after redefinition of angles
194tests = [
195    # Accuracy tests based on content in test/utest_coreshellellipsoidXTmodel.py
197      'x_core': 0.1,
198      'thick_shell': 50.0,
199      'x_polar_shell': 0.2,
200      'sld_core': 2.0,
201      'sld_shell': 1.0,
202      'sld_solvent': 6.3,
203      'background': 0.001,
204      'scale': 1.0,
205     }, 1.0, 0.00189402],
206
207    # Additional tests with larger range of parameters
208    [{'background': 0.01}, 0.1, 11.6915],
209
211      'x_core': 200.0,
212      'thick_shell': 54.0,
213      'x_polar_shell': 3.0,
214      'sld_core': 20.0,
215      'sld_shell': 10.0,
216      'sld_solvent': 6.0,
217      'background': 0.0,
218      'scale': 1.0,
219     }, 0.01, 8688.53],
220
221    # 2D tests
222    [{'background': 0.001,
223      'theta': 90.0,
224      'phi': 0.0,
225     }, (0.4, 0.5), 0.00690673],
226