source:sasmodels/sasmodels/models/spherical_sld.py@4e0968b

core_shell_microgelscostrafo411magnetic_modelrelease_v0.94release_v0.95ticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since 4e0968b was 4e0968b, checked in by Paul Kienzle <pkienzle@…>, 6 years ago

spherical sld: doc cleanup (with syntax errors fixed)

• Property mode set to 100644
File size: 9.8 KB
Line
1r"""
2Similarly to the onion, this model provides the form factor, $P(q)$, for
3a multi-shell sphere, where the interface between the each neighboring
4shells can be described by the error function, power-law, or exponential
5functions.  The scattering intensity is computed by building a continuous
6custom SLD profile along the radius of the particle. The SLD profile is
7composed of a number of uniform shells with interfacial shells between them.
8
9.. figure:: img/spherical_sld_profile.png
10
11    Example SLD profile
12
13Unlike the <onion> model (using an analytical integration), the interfacial
14shells here are sub-divided and numerically integrated assuming each
15sub-shell is described by a line function, with *n_steps* sub-shells per
16interface. The form factor is normalized by the total volume of the sphere.
17
18Definition
19----------
20
21The form factor $P(q)$ in 1D is calculated by:
22
23.. math::
24
25    P(q) = \frac{f^2}{V_\text{particle}} \text{ where }
26    f = f_\text{core} + \sum_{\text{inter}_i=0}^N f_{\text{inter}_i} +
27    \sum_{\text{flat}_i=0}^N f_{\text{flat}_i} +f_\text{solvent}
28
29For a spherically symmetric particle with a particle density $\rho_x(r)$
30the sld function can be defined as:
31
32.. math::
33
34    f_x = 4 \pi \int_{0}^{\infty} \rho_x(r)  \frac{\sin(qr)} {qr^2} r^2 dr
35
36
37so that individual terms can be calculated as follows:
38
39.. math::
40    f_\text{core} = 4 \pi \int_{0}^{r_\text{core}} \rho_\text{core}
41    \frac{\sin(qr)} {qr} r^2 dr =
42    3 \rho_\text{core} V(r_\text{core})
43    \Big[ \frac{\sin(qr_\text{core}) - qr_\text{core} \cos(qr_\text{core})}
44    {qr_\text{core}^3} \Big]
45
46    f_{\text{inter}_i} = 4 \pi \int_{\Delta t_{ \text{inter}_i } }
47    \rho_{ \text{inter}_i } \frac{\sin(qr)} {qr} r^2 dr
48
49    f_{\text{shell}_i} = 4 \pi \int_{\Delta t_{ \text{inter}_i } }
50    \rho_{ \text{flat}_i } \frac{\sin(qr)} {qr} r^2 dr =
51    3 \rho_{ \text{flat}_i } V ( r_{ \text{inter}_i } +
52    \Delta t_{ \text{inter}_i } )
53    \Big[ \frac{\sin(qr_{\text{inter}_i} + \Delta t_{ \text{inter}_i } )
54    - q (r_{\text{inter}_i} + \Delta t_{ \text{inter}_i })
55    \cos(q( r_{\text{inter}_i} + \Delta t_{ \text{inter}_i } ) ) }
56    {q ( r_{\text{inter}_i} + \Delta t_{ \text{inter}_i } )^3 }  \Big]
57    -3 \rho_{ \text{flat}_i } V(r_{ \text{inter}_i })
58    \Big[ \frac{\sin(qr_{\text{inter}_i}) - qr_{\text{flat}_i}
59    \cos(qr_{\text{inter}_i}) } {qr_{\text{inter}_i}^3} \Big]
60
61    f_\text{solvent} = 4 \pi \int_{r_N}^{\infty} \rho_\text{solvent}
62    \frac{\sin(qr)} {qr} r^2 dr =
63    3 \rho_\text{solvent} V(r_N)
64    \Big[ \frac{\sin(qr_N) - qr_N \cos(qr_N)} {qr_N^3} \Big]
65
66
67Here we assumed that the SLDs of the core and solvent are constant in $r$.
68The SLD at the interface between shells, $\rho_{\text {inter}_i}$
69is calculated with a function chosen by an user, where the functions are
70
71Exp:
72
73.. math::
74    \rho_{{inter}_i} (r) = \begin{cases}
75    B \exp\Big( \frac {\pm A(r - r_{\text{flat}_i})}
76    {\Delta t_{ \text{inter}_i }} \Big) +C  & \text{for} A \neq 0 \\
77    B \Big( \frac {(r - r_{\text{flat}_i})}
78    {\Delta t_{ \text{inter}_i }} \Big) +C  & \text{for} A = 0 \\
79    \end{cases}
80
81Power-Law
82
83.. math::
84    \rho_{{inter}_i} (r) = \begin{cases}
85    \pm B \Big( \frac {(r - r_{\text{flat}_i} )} {\Delta t_{ \text{inter}_i }}
86    \Big) ^A  +C  & \text{for} A \neq 0 \\
87    \rho_{\text{flat}_{i+1}}  & \text{for} A = 0 \\
88    \end{cases}
89
90Erf:
91
92.. math::
93    \rho_{{inter}_i} (r) = \begin{cases}
94    B \text{erf} \Big( \frac { A(r - r_{\text{flat}_i})}
95    {\sqrt{2} \Delta t_{ \text{inter}_i }} \Big) +C  & \text{for} A \neq 0 \\
96    B \Big( \frac {(r - r_{\text{flat}_i} )} {\Delta t_{ \text{inter}_i }}
97    \Big)  +C  & \text{for} A = 0 \\
98    \end{cases}
99
100The functions are normalized so that they vary between 0 and 1, and they are
101constrained such that the SLD is continuous at the boundaries of the interface
102as well as each sub-shell. Thus B and C are determined.
103
104Once $\rho_{\text{inter}_i}$ is found at the boundary of the sub-shell of the
105interface, we can find its contribution to the form factor $P(q)$
106
107.. math::
108    f_{\text{inter}_i} = 4 \pi \int_{\Delta t_{ \text{inter}_i } }
109    \rho_{ \text{inter}_i } \frac{\sin(qr)} {qr} r^2 dr =
110    4 \pi \sum_{j=0}^{npts_{\text{inter}_i} -1 }
111    \int_{r_j}^{r_{j+1}} \rho_{ \text{inter}_i } (r_j)
112    \frac{\sin(qr)} {qr} r^2 dr \approx
113
114    4 \pi \sum_{j=0}^{npts_{\text{inter}_i} -1 } \Big[
115    3 ( \rho_{ \text{inter}_i } ( r_{j+1} ) - \rho_{ \text{inter}_i }
116    ( r_{j} ) V ( r_{ \text{subshell}_j } )
117    \Big[ \frac {r_j^2 \beta_\text{out}^2 \sin(\beta_\text{out})
118    - (\beta_\text{out}^2-2) \cos(\beta_\text{out}) }
119    {\beta_\text{out}^4 } \Big]
120
121    - 3 ( \rho_{ \text{inter}_i } ( r_{j+1} ) - \rho_{ \text{inter}_i }
122    ( r_{j} ) V ( r_{ \text{subshell}_j-1 } )
123    \Big[ \frac {r_{j-1}^2 \sin(\beta_\text{in})
124    - (\beta_\text{in}^2-2) \cos(\beta_\text{in}) }
125    {\beta_\text{in}^4 } \Big]
126
127    + 3 \rho_{ \text{inter}_i } ( r_{j+1} )  V ( r_j )
128    \Big[ \frac {\sin(\beta_\text{out}) - \cos(\beta_\text{out}) }
129    {\beta_\text{out}^4 } \Big]
130
131    - 3 \rho_{ \text{inter}_i } ( r_{j} )  V ( r_j )
132    \Big[ \frac {\sin(\beta_\text{in}) - \cos(\beta_\text{in}) }
133    {\beta_\text{in}^4 } \Big]
134    \Big]
135
136where
137
138.. math::
139    V(a) = \frac {4\pi}{3}a^3
140
141    a_\text{in} ~ \frac{r_j}{r_{j+1} -r_j} \text{, } a_\text{out}
142    ~ \frac{r_{j+1}}{r_{j+1} -r_j}
143
144    \beta_\text{in} = qr_j \text{, } \beta_\text{out} = qr_{j+1}
145
146
147We assume $\rho_{\text{inter}_j} (r)$ is approximately linear
148within the sub-shell $j$.
149
150Finally the form factor can be calculated by
151
152.. math::
153
154    P(q) = \frac{[f]^2} {V_\text{particle}} \text{where} V_\text{particle}
155    = V(r_{\text{shell}_N})
156
157For 2D data the scattering intensity is calculated in the same way as 1D,
158where the $q$ vector is defined as
159
160.. math::
161
162    q = \sqrt{q_x^2 + q_y^2}
163
164.. note::
165
166    The outer most radius is used as the effective radius for S(Q)
167    when $P(Q) * S(Q)$ is applied.
168
169References
170----------
171L A Feigin and D I Svergun, Structure Analysis by Small-Angle X-Ray
172and Neutron Scattering, Plenum Press, New York, (1987)
173
174"""
175
176import numpy as np
177from numpy import inf, expm1, sqrt
178from scipy.special import erf
179
180name = "spherical_sld"
181title = "Sperical SLD intensity calculation"
182description = """
183            I(q) =
184               background = Incoherent background [1/cm]
185        """
186category = "shape:sphere"
187
188SHAPES = ["erf(|nu|*z)", "Rpow(z^|nu|)", "Lpow(z^|nu|)",
189          "Rexp(-|nu|z)", "Lexp(-|nu|z)"],
190
192#            ["name", "units", default, [lower, upper], "type", "description"],
193parameters = [["n_shells",             "",           1,      [1, 10],        "volume", "number of shells"],
194              ["sld_solvent",          "1e-6/Ang^2", 1.0,    [-inf, inf],    "sld", "solvent sld"],
195              ["sld[n_shells]",        "1e-6/Ang^2", 4.06,   [-inf, inf],    "sld", "sld of the shell"],
196              ["thickness[n_shells]",  "Ang",        100.0,  [0, inf],       "volume", "thickness shell"],
197              ["interface[n_shells]",  "Ang",        50.0,   [0, inf],       "volume", "thickness of the interface"],
198              ["shape[n_shells]",      "",           0,      SHAPES,         "", "interface shape"],
199              ["nu[n_shells]",         "",           2.5,    [0, inf],       "", "interface shape exponent"],
200              ["n_steps",              "",           35,     [0, inf],       "", "number of steps in each interface (must be an odd integer)"],
201              ]
203source = ["lib/polevl.c", "lib/sas_erf.c", "lib/sph_j1c.c", "spherical_sld.c"]
204single = False  # TODO: fix low q behaviour
205
206profile_axes = ['Radius (A)', 'SLD (1e-6/A^2)']
207
208SHAPE_FUNCTIONS = [
209    lambda z, nu: erf(nu/sqrt(2)*(2*z-1))/(2*erf(nu/sqrt(2))) + 0.5,  # erf
210    lambda z, nu: z**nu,                    # Rpow
211    lambda z, nu: 1 - (1-z)**nu,            # Lpow
212    lambda z, nu: expm1(-nu*z)/expm1(-nu),  # Rexp
213    lambda z, nu: expm1(nu*z)/expm1(nu),    # Lexp
214]
215
216def profile(n_shells, sld_solvent, sld, thickness,
217            interface, shape, nu, n_steps):
218    """
219    Returns shape profile with x=radius, y=SLD.
220    """
221
222    z = []
223    rho = []
224    z0 = 0
225    # two sld points for core
226    z.append(0)
227    rho.append(sld[0])
228
229    for i in range(0, int(n_shells)):
230        z0 += thickness[i]
231        z.append(z0)
232        rho.append(sld[i])
233        dz = interface[i]/n_steps
234        sld_l = sld[i]
235        sld_r = sld[i+1] if i < n_shells-1 else sld_solvent
236        interface = SHAPE_FUNCTIONS[int(np.clip(shape[i], 0, len(SHAPES)-1))]
237        for step in range(1, n_steps+1):
238            portion = interface(float(step)/n_steps, max(abs(nu[i]), 1e-14))
239            z0 += dz
240            z.append(z0)
241            rho.append((sld_r - sld_l)*portion + sld_l)
242    z.append(z0*1.2)
243    rho.append(sld_solvent)
244    # return sld profile (r, beta)
245    return np.asarray(z), np.asarray(rho)
246
247
248def ER(n_shells, thickness, interface):
249    n_shells = int(n_shells)
250    total = (np.sum(thickness[:n_shells], axis=1)
251             + np.sum(interface[:n_shells], axis=1))
252    return total
253
254
255demo = {
256    "n_shells": 5,
257    "n_steps": 35.0,
258    "sld_solvent": 1.0,
259    "sld":[2.07,4.0,3.5,4.0,3.5],
260    "thickness":[50.0,100.0,100.0,100.0,100.0],
261    "interface":[50.0,50.0,50.0,50.0],
262    "shape": [0,0,0,0,0],
263    "nu":[2.5,2.5,2.5,2.5,2.5],
264    }
265
266#TODO: Not working yet
267"""
268tests = [
269    # Accuracy tests based on content in test/utest_extra_models.py
270    [{"n_shells": 5,
271        "n_steps": 35,
272        "sld_solvent": 1.0,
273        "sld": [2.07, 4.0, 3.5, 4.0, 3.5],
274        "thickness": [50.0, 100.0, 100.0, 100.0, 100.0],
275        "interface": [50]*5,
276        "shape": [0]*5,
277        "nu": [2.5]*5,
278    }, 0.001, 0.001],
279]
280"""
Note: See TracBrowser for help on using the repository browser.