source: sasmodels/sasmodels/models/spherical_sld.py @ 627b68b

ticket-1257-vesicle-productticket_1156ticket_822_more_unit_tests
Last change on this file since 627b68b was 627b68b, checked in by smk78, 5 months ago

Fix doc build warning

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