source: sasmodels/sasmodels/models/core_shell_bicelle.py @ a34b811

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

use radius_effective/radius_effective_mode/radius_effective_modes consistently throughout the code

  • Property mode set to 100644
File size: 7.4 KB
Line 
1r"""
2Definition
3----------
4
5This model provides the form factor for a circular cylinder with a
6core-shell scattering length density profile. Thus this is a variation
7of a core-shell cylinder or disc where the shell on the walls and ends
8may be of different thicknesses and scattering length densities. The form
9factor is normalized by the particle volume.
10
11
12.. figure:: img/core_shell_bicelle_geometry.png
13
14    Schematic cross-section of bicelle. Note however that the model here
15    calculates for rectangular, not curved, rims as shown below.
16
17.. figure:: img/core_shell_bicelle_parameters.png
18
19   Cross section of cylindrical symmetry model used here. Users will have
20   to decide how to distribute "heads" and "tails" between the rim, face
21   and core regions in order to estimate appropriate starting parameters.
22
23Given the scattering length densities (sld) $\rho_c$, the core sld, $\rho_f$,
24the face sld, $\rho_r$, the rim sld and $\rho_s$ the solvent sld, the
25scattering length density variation along the cylinder axis is:
26
27.. math::
28
29    \rho(r) =
30      \begin{cases}
31      &\rho_c \text{ for } 0 \lt r \lt R; -L \lt z\lt L \\[1.5ex]
32      &\rho_f \text{ for } 0 \lt r \lt R; -(L+2t) \lt z\lt -L;
33      L \lt z\lt (L+2t) \\[1.5ex]
34      &\rho_r\text{ for } 0 \lt r \lt R; -(L+2t) \lt z\lt -L; L \lt z\lt (L+2t)
35      \end{cases}
36
37The form factor for the bicelle is calculated in cylindrical coordinates, where
38$\alpha$ is the angle between the $Q$ vector and the cylinder axis, to give:
39
40.. math::
41
42    I(Q,\alpha) = \frac{\text{scale}}{V_t} \cdot
43        F(Q,\alpha)^2 \cdot sin(\alpha) + \text{background}
44
45where
46
47.. math::
48    :nowrap:
49
50    \begin{align*}
51    F(Q,\alpha) = &\bigg[
52    (\rho_c - \rho_f) V_c
53     \frac{2J_1(QRsin \alpha)}{QRsin\alpha}
54     \frac{sin(QLcos\alpha/2)}{Q(L/2)cos\alpha} \\
55    &+(\rho_f - \rho_r) V_{c+f}
56     \frac{2J_1(QRsin\alpha)}{QRsin\alpha}
57     \frac{sin(Q(L/2+t_f)cos\alpha)}{Q(L/2+t_f)cos\alpha} \\
58    &+(\rho_r - \rho_s) V_t
59     \frac{2J_1(Q(R+t_r)sin\alpha)}{Q(R+t_r)sin\alpha}
60     \frac{sin(Q(L/2+t_f)cos\alpha)}{Q(L/2+t_f)cos\alpha}
61    \bigg]
62    \end{align*}
63
64where $V_t$ is the total volume of the bicelle, $V_c$ the volume of the core,
65$V_{c+f}$ the volume of the core plus the volume of the faces, $R$ is the radius
66of the core, $L$ the length of the core, $t_f$ the thickness of the face, $t_r$
67the thickness of the rim and $J_1$ the usual first order bessel function.
68
69The output of the 1D scattering intensity function for randomly oriented
70cylinders is then given by integrating over all possible $\theta$ and $\phi$.
71
72For oriented bicelles the *theta*, and *phi* orientation parameters will appear
73when fitting 2D data, see the :ref:`cylinder` model for further information.
74Our implementation of the scattering kernel and the 1D scattering intensity
75use the c-library from NIST.
76
77.. figure:: img/cylinder_angle_definition.png
78
79    Definition of the angles for the oriented core shell bicelle model,
80    note that the cylinder axis of the bicelle starts along the beam direction
81    when $\theta  = \phi = 0$.
82
83
84References
85----------
86
87.. [#] D Singh (2009). *Small angle scattering studies of self assembly in
88   lipid mixtures*, John's Hopkins University Thesis (2009) 223-225. `Available
89   from Proquest <http://search.proquest.com/docview/304915826?accountid
90   =26379>`_
91
92.. [#] L. Onsager, *Ann. New York Acad. Sci.*, 51 (1949) 627-659
93
94Source
95------
96
97`core_shell_bicelle.py <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/core_shell_bicelle.py>`_
98
99`core_shell_bicelle.c <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/core_shell_bicelle.c>`_
100
101Authorship and Verification
102----------------------------
103
104* **Author:** NIST IGOR/DANSE **Date:** pre 2010
105* **Last Modified by:** Paul Butler **Date:** September 30, 2016
106* **Last Reviewed by:** Richard Heenan **Date:** January 4, 2017
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_bicelle"
114title = "Circular cylinder with a core-shell scattering length density profile.."
115description = """
116    P(q,alpha)= (scale/Vs)*f(q)^(2) + bkg,  where:
117    f(q)= Vt(sld_rim - sld_solvent)* sin[qLt.cos(alpha)/2]
118    /[qLt.cos(alpha)/2]*J1(qRout.sin(alpha))
119    /[qRout.sin(alpha)]+
120    (sld_core-sld_face)*Vc*sin[qLcos(alpha)/2][[qL
121    *cos(alpha)/2]*J1(qRc.sin(alpha))
122    /qRc.sin(alpha)]+
123    (sld_face-sld_rim)*(Vc+Vf)*sin[q(L+2.thick_face).
124    cos(alpha)/2][[q(L+2.thick_face)*cos(alpha)/2]*
125    J1(qRc.sin(alpha))/qRc.sin(alpha)]
126
127    alpha:is the angle between the axis of
128    the cylinder and the q-vector
129    Vt = pi.(Rc + thick_rim)^2.Lt : total volume
130    Vc = pi.Rc^2.L :the volume of the core
131    Vf = 2.pi.Rc^2.thick_face
132    Rc = radius: is the core radius
133    L: the length of the core
134    Lt = L + 2.thick_face: total length
135    Rout = radius + thick_rim
136    sld_core, sld_rim, sld_face:scattering length
137    densities within the particle
138    sld_solvent: the scattering length density
139    of the solvent
140    bkg: the background
141    J1: the first order Bessel function
142    theta: axis_theta of the cylinder
143    phi: the axis_phi of the cylinder...
144        """
145category = "shape:cylinder"
146
147# pylint: disable=bad-whitespace, line-too-long
148#             ["name", "units", default, [lower, upper], "type", "description"],
149parameters = [
150    ["radius",         "Ang",       80, [0, inf],    "volume",      "Cylinder core radius"],
151    ["thick_rim",  "Ang",       10, [0, inf],    "volume",      "Rim shell thickness"],
152    ["thick_face", "Ang",       10, [0, inf],    "volume",      "Cylinder face thickness"],
153    ["length",         "Ang",      50, [0, inf],    "volume",      "Cylinder length"],
154    ["sld_core",       "1e-6/Ang^2", 1, [-inf, inf], "sld",         "Cylinder core scattering length density"],
155    ["sld_face",       "1e-6/Ang^2", 4, [-inf, inf], "sld",         "Cylinder face scattering length density"],
156    ["sld_rim",        "1e-6/Ang^2", 4, [-inf, inf], "sld",         "Cylinder rim scattering length density"],
157    ["sld_solvent",    "1e-6/Ang^2", 1, [-inf, inf], "sld",         "Solvent scattering length density"],
158    ["theta",          "degrees",   90, [-360, 360], "orientation", "cylinder axis to beam angle"],
159    ["phi",            "degrees",    0, [-360, 360], "orientation", "rotation about beam"]
160    ]
161
162# pylint: enable=bad-whitespace, line-too-long
163
164source = ["lib/sas_Si.c", "lib/polevl.c", "lib/sas_J1.c", "lib/gauss76.c",
165          "core_shell_bicelle.c"]
166have_Fq = True
167radius_effective_modes = [
168    "excluded volume", "equivalent volume sphere", "outer rim radius",
169    "half outer thickness", "half diagonal",
170    ]
171
172def random():
173    """Return a random parameter set for the model."""
174    pars = dict(
175        radius=10**np.random.uniform(1.3, 3),
176        length=10**np.random.uniform(1.3, 4),
177        thick_rim=10**np.random.uniform(0, 1.7),
178        thick_face=10**np.random.uniform(0, 1.7),
179    )
180    return pars
181
182demo = dict(scale=1, background=0,
183            radius=20.0,
184            thick_rim=10.0,
185            thick_face=10.0,
186            length=400.0,
187            sld_core=1.0,
188            sld_face=4.0,
189            sld_rim=4.0,
190            sld_solvent=1.0,
191            theta=90,
192            phi=0)
193q = 0.1
194# april 6 2017, rkh add unit tests, NOT compared with any other calc method, assume correct!
195qx = q*cos(pi/6.0)
196qy = q*sin(pi/6.0)
197tests = [
198    [{}, 0.05, 7.4883545957],
199    [{'theta':80., 'phi':10.}, (qx, qy), 2.81048892474]
200]
201del qx, qy  # not necessary to delete, but cleaner
Note: See TracBrowser for help on using the repository browser.