source: sasmodels/sasmodels/models/core_shell_ellipsoid.py @ db1c84b

core_shell_microgelsmagnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since db1c84b was 0507e09, checked in by smk78, 5 years ago

Added link to source code to each model. Closes #883

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