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

Last change on this file since c1e44e5 was c1e44e5, checked in by Paul Kienzle <pkienzle@…>, 5 years ago

Add local link to source files. Refs #1263.

  • Property mode set to 100644
File size: 8.4 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
50.. math::
51    :nowrap:
52
53    \begin{align*}
54    F(q,\alpha) = &f(q,R_e,R_e.x_{core},\alpha) \\
55    &+ f(q,R_e + t_{shell},
56         R_e.x_{core} + t_{shell}.x_{polar shell},\alpha)
57    \end{align*}
58
59where
60
61.. math::
62
63    f(q,R_e,R_p,\alpha) = \frac{3 \Delta \rho V (\sin[qr(R_p,R_e,\alpha)]
64                - \cos[qr(R_p,R_e,\alpha)])}
65                {[qr(R_p,R_e,\alpha)]^3}
66
67and
68
69.. math::
70
71    r(R_e,R_p,\alpha) = \left[ R_e^2 \sin^2 \alpha
72        + R_p^2 \cos^2 \alpha \right]^{1/2}
73
74
75$\alpha$ is the angle between the axis of the ellipsoid and $\vec q$,
76$V = (4/3)\pi R_pR_e^2$ is the volume of the ellipsoid , $R_p$ is the
77polar radius along the rotational axis of the ellipsoid, $R_e$ is the
78equatorial radius perpendicular to the rotational axis of the ellipsoid,
79$t_{shell}$ is the thickness of the shell at the equator,
80and $\Delta \rho$ (the contrast) is the scattering length density difference,
81either $(\rho_{core} - \rho_{shell})$ or $(\rho_{shell} - \rho_{solvent})$.
82
83For randomly oriented particles:
84
85.. math::
86
87   F^2(q)=\int_{0}^{\pi/2}{F^2(q,\alpha)\sin(\alpha)d\alpha}
88
89For oriented ellipsoids the *theta*, *phi* and *psi* orientation parameters
90will appear when fitting 2D data, see the :ref:`elliptical-cylinder` model
91for further information.
92
93References
94----------
95see for example:
96
97.. [#] Kotlarchyk, M.; Chen, S.-H. *J. Chem. Phys.*, 1983, 79, 2461
98.. [#] Berr, S. *J. Phys. Chem.*, 1987, 91, 4760
99
100Authorship and Verification
101----------------------------
102
103* **Author:** NIST IGOR/DANSE **Date:** pre 2010
104* **Last Modified by:** Richard Heenan (reparametrised model) **Date:** 2015
105* **Last Reviewed by:** Steve King **Date:** March 27, 2019
106"""
107
108import numpy as np
109from numpy import inf, sin, cos, pi
110
111name = "core_shell_ellipsoid"
112title = "Form factor for an spheroid ellipsoid particle with a core shell structure."
113description = """
114        [core_shell_ellipsoid] Calculates the form factor for an spheroid
115        ellipsoid particle with a core_shell structure.
116        The form factor is averaged over all possible
117        orientations of the ellipsoid such that P(q)
118        = scale*<f^2>/Vol + bkg, where f is the
119        single particle scattering amplitude.
120        [Parameters]:
121        radius_equat_core = equatorial radius of core,
122        x_core = ratio of core polar/equatorial radii,
123        thick_shell = equatorial radius of outer surface,
124        x_polar_shell = ratio of polar shell thickness to equatorial shell thickness,
125        sld_core = SLD_core
126        sld_shell = SLD_shell
127        sld_solvent = SLD_solvent
128        background = Incoherent bkg
129        scale =scale
130        Note:It is the users' responsibility to ensure
131        that shell radii are larger than core radii.
132        oblate: polar radius < equatorial radius
133        prolate :  polar radius > equatorial radius - this new model will make this easier
134        and polydispersity integrals more logical (as previously the shell could disappear).
135    """
136category = "shape:ellipsoid"
137
138# pylint: disable=bad-whitespace, line-too-long
139#             ["name", "units", default, [lower, upper], "type", "description"],
140parameters = [
141    ["radius_equat_core","Ang",     20,   [0, inf],   "volume",      "Equatorial radius of core"],
142    ["x_core",        "None",       3,   [0, inf],    "volume",      "axial ratio of core, X = r_polar/r_equatorial"],
143    ["thick_shell",   "Ang",       30,   [0, inf],    "volume",      "thickness of shell at equator"],
144    ["x_polar_shell", "",           1,   [0, inf],    "volume",      "ratio of thickness of shell at pole to that at equator"],
145    ["sld_core",      "1e-6/Ang^2", 2,   [-inf, inf], "sld",         "Core scattering length density"],
146    ["sld_shell",     "1e-6/Ang^2", 1,   [-inf, inf], "sld",         "Shell scattering length density"],
147    ["sld_solvent",   "1e-6/Ang^2", 6.3, [-inf, inf], "sld",         "Solvent scattering length density"],
148    ["theta",         "degrees",    0,   [-360, 360], "orientation", "elipsoid axis to beam angle"],
149    ["phi",           "degrees",    0,   [-360, 360], "orientation", "rotation about beam"],
150    ]
151# pylint: enable=bad-whitespace, line-too-long
152
153source = ["lib/sas_3j1x_x.c", "lib/gauss76.c", "core_shell_ellipsoid.c"]
154have_Fq = True
155effective_radius_type = [
156    "average outer curvature", "equivalent volume sphere",
157    "min outer radius", "max outer radius",
158    ]
159
160def random():
161    """Return a random parameter set for the model."""
162    volume = 10**np.random.uniform(5, 12)
163    outer_polar = 10**np.random.uniform(1.3, 4)
164    outer_equatorial = np.sqrt(volume/outer_polar) # ignore 4/3 pi
165    # Use a distribution with a preference for thin shell or thin core
166    # Avoid core,shell radii < 1
167    thickness_polar = np.random.beta(0.5, 0.5)*(outer_polar-2) + 1
168    thickness_equatorial = np.random.beta(0.5, 0.5)*(outer_equatorial-2) + 1
169    radius_polar = outer_polar - thickness_polar
170    radius_equatorial = outer_equatorial - thickness_equatorial
171    x_core = radius_polar/radius_equatorial
172    x_polar_shell = thickness_polar/thickness_equatorial
173    pars = dict(
174        #background=0, sld=0, sld_solvent=1,
175        radius_equat_core=radius_equatorial,
176        x_core=x_core,
177        thick_shell=thickness_equatorial,
178        x_polar_shell=x_polar_shell,
179    )
180    return pars
181
182q = 0.1
183# tests had in old coords theta=0, phi=0; new coords theta=90, phi=0
184qx = q*cos(pi/6.0)
185qy = q*sin(pi/6.0)
186# 11Jan2017 RKH sorted tests after redefinition of angles
187tests = [
188    # Accuracy tests based on content in test/utest_coreshellellipsoidXTmodel.py
189    [{'radius_equat_core': 200.0,
190      'x_core': 0.1,
191      'thick_shell': 50.0,
192      'x_polar_shell': 0.2,
193      'sld_core': 2.0,
194      'sld_shell': 1.0,
195      'sld_solvent': 6.3,
196      'background': 0.001,
197      'scale': 1.0,
198     }, 1.0, 0.00189402],
199
200    # Additional tests with larger range of parameters
201    [{'background': 0.01}, 0.1, 11.6915],
202
203    [{'radius_equat_core': 20.0,
204      'x_core': 200.0,
205      'thick_shell': 54.0,
206      'x_polar_shell': 3.0,
207      'sld_core': 20.0,
208      'sld_shell': 10.0,
209      'sld_solvent': 6.0,
210      'background': 0.0,
211      'scale': 1.0,
212     }, 0.01, 8688.53],
213
214    # 2D tests
215    [{'background': 0.001,
216      'theta': 90.0,
217      'phi': 0.0,
218     }, (0.4, 0.5), 0.00690673],
219
220    [{'radius_equat_core': 20.0,
221      'x_core': 200.0,
222      'thick_shell': 54.0,
223      'x_polar_shell': 3.0,
224      'sld_core': 20.0,
225      'sld_shell': 10.0,
226      'sld_solvent': 6.0,
227      'background': 0.01,
228      'scale': 0.01,
229      'theta': 90.0,
230      'phi': 0.0,
231     }, (qx, qy), 0.01000025],
232]
Note: See TracBrowser for help on using the repository browser.