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

core_shell_microgelscostrafo411magnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since adc753d was adc753d, checked in by butler, 7 years ago

bicelle model documentation standardized, ref to original derivation and
equations added to rst documentation. re #696 and #646

  • Property mode set to 100644
File size: 7.1 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} \cdot
43        F(Q,\alpha)^2 + \text{background}
44where
45
46.. math::
47
48    \begin{align}   
49    F(Q,\alpha) = &\frac{1}{V_t} \bigg[
50    (\rho_c - \rho_f) V_c \frac{J_1(QRsin \alpha)}{QRsin\alpha}\frac{2 \cdot QLcos\alpha}{QLcos\alpha} \\
51    &+(\rho_f - \rho_r) V_{c+f} \frac{J_1(QRsin\alpha)}{QRsin\alpha}\frac{2 \cdot Q(L+t_f)cos\alpha}{Q(L+t_f)cos\alpha} \\
52    &+(\rho_r - \rho_s) V_t \frac{J_1(Q(R+t_r)sin\alpha)}{Q(R+t_r)sin\alpha}\frac{2 \cdot Q(L+t_f)cos\alpha}{Q(L+t_f)cos\alpha}
53    \bigg]
54    \end{align}
55
56where $V_t$ is the total volume of the bicelle, $V_c$ the volume of the core,
57$V_{c+f}$ the volume of the core plus the volume of the faces, $R$ is the radius
58of the core, $L$ the length of the core, $t_f$ the thickness of the face, $t_r$
59the thickness of the rim and $J_1$ the usual first order bessel function.
60
61The output of the 1D scattering intensity function for randomly oriented
62cylinders is then given by integrating over all possible $\theta$ and $\phi$.
63
64The *theta* and *phi* parameters are not used for the 1D output.
65Our implementation of the scattering kernel and the 1D scattering intensity
66use the c-library from NIST.
67
68.. figure:: img/cylinder_angle_definition.jpg
69
70    Definition of the angles for the oriented core shell bicelle tmodel.
71
72.. figure:: img/cylinder_angle_projection.jpg
73    :width: 600px
74
75    Examples of the angles for oriented pp against the detector plane.
76
77References
78----------
79
80.. [#] D Singh (2009). *Small angle scattering studies of self assembly in
81   lipid mixtures*, John's Hopkins University Thesis (2009) 223-225. `Available
82   from Proquest <http://search.proquest.com/docview/304915826?accountid
83   =26379>`_
84
85Authorship and Verification
86----------------------------
87
88* **Author:** NIST IGOR/DANSE **Date:** pre 2010
89* **Last Modified by:** Paul Butler **Date:** September 30, 2016
90* **Last Reviewed by:** Richard Heenan **Date:** October 5, 2016
91"""
92
93from numpy import inf, sin, cos
94
95name = "core_shell_bicelle"
96title = "Circular cylinder with a core-shell scattering length density profile.."
97description = """
98    P(q,alpha)= (scale/Vs)*f(q)^(2) + bkg,  where:
99    f(q)= Vt(sld_rim - sld_solvent)* sin[qLt.cos(alpha)/2]
100    /[qLt.cos(alpha)/2]*J1(qRout.sin(alpha))
101    /[qRout.sin(alpha)]+
102    (sld_core-sld_face)*Vc*sin[qLcos(alpha)/2][[qL
103    *cos(alpha)/2]*J1(qRc.sin(alpha))
104    /qRc.sin(alpha)]+
105    (sld_face-sld_rim)*(Vc+Vf)*sin[q(L+2.thick_face).
106    cos(alpha)/2][[q(L+2.thick_face)*cos(alpha)/2]*
107    J1(qRc.sin(alpha))/qRc.sin(alpha)]
108
109    alpha:is the angle between the axis of
110    the cylinder and the q-vector
111    Vt = pi.(Rc + thick_rim)^2.Lt : total volume
112    Vc = pi.Rc^2.L :the volume of the core
113    Vf = 2.pi.Rc^2.thick_face
114    Rc = radius: is the core radius
115    L: the length of the core
116    Lt = L + 2.thick_face: total length
117    Rout = radius + thick_rim
118    sld_core, sld_rim, sld_face:scattering length
119    densities within the particle
120    sld_solvent: the scattering length density
121    of the solvent
122    bkg: the background
123    J1: the first order Bessel function
124    theta: axis_theta of the cylinder
125    phi: the axis_phi of the cylinder...
126        """
127category = "shape:cylinder"
128
129# pylint: disable=bad-whitespace, line-too-long
130#             ["name", "units", default, [lower, upper], "type", "description"],
131parameters = [
132    ["radius",         "Ang",       20, [0, inf],    "volume",      "Cylinder core radius"],
133    ["thick_rim",  "Ang",       10, [0, inf],    "volume",      "Rim shell thickness"],
134    ["thick_face", "Ang",       10, [0, inf],    "volume",      "Cylinder face thickness"],
135    ["length",         "Ang",      400, [0, inf],    "volume",      "Cylinder length"],
136    ["sld_core",       "1e-6/Ang^2", 1, [-inf, inf], "sld",         "Cylinder core scattering length density"],
137    ["sld_face",       "1e-6/Ang^2", 4, [-inf, inf], "sld",         "Cylinder face scattering length density"],
138    ["sld_rim",        "1e-6/Ang^2", 4, [-inf, inf], "sld",         "Cylinder rim scattering length density"],
139    ["sld_solvent",    "1e-6/Ang^2", 1, [-inf, inf], "sld",         "Solvent scattering length density"],
140    ["theta",          "degrees",   90, [-inf, inf], "orientation", "In plane angle"],
141    ["phi",            "degrees",    0, [-inf, inf], "orientation", "Out of plane angle"],
142    ]
143
144# pylint: enable=bad-whitespace, line-too-long
145
146source = ["lib/Si.c", "lib/polevl.c", "lib/sas_J1.c", "lib/gauss76.c",
147          "core_shell_bicelle.c"]
148
149demo = dict(scale=1, background=0,
150            radius=20.0,
151            thick_rim=10.0,
152            thick_face=10.0,
153            length=400.0,
154            sld_core=1.0,
155            sld_face=4.0,
156            sld_rim=4.0,
157            sld_solvent=1.0,
158            theta=90,
159            phi=0)
160
161qx, qy = 0.4 * cos(90), 0.5 * sin(0)
162tests = [
163    # Accuracy tests based on content in test/utest_other_models.py
164    [{'radius': 20.0,
165      'thick_rim': 10.0,
166      'thick_face': 10.0,
167      'length': 400.0,
168      'sld_core': 1.0,
169      'sld_face': 4.0,
170      'sld_rim': 4.0,
171      'sld_solvent': 1.0,
172      'background': 0.0,
173     }, 0.001, 353.550],
174
175    [{'radius': 20.0,
176      'thick_rim': 10.0,
177      'thick_face': 10.0,
178      'length': 400.0,
179      'sld_core': 1.0,
180      'sld_face': 4.0,
181      'sld_rim': 4.0,
182      'sld_solvent': 1.0,
183      'theta': 90.0,
184      'phi': 0.0,
185      'background': 0.00,
186     }, (qx, qy), 24.9167],
187
188    # Additional tests with larger range of parameters
189    [{'radius': 3.0,
190      'thick_rim': 100.0,
191      'thick_face': 100.0,
192      'length': 1200.0,
193      'sld_core': 5.0,
194      'sld_face': 41.0,
195      'sld_rim': 42.0,
196      'sld_solvent': 21.0,
197     }, 0.05, 1670.1828],
198    ]
Note: See TracBrowser for help on using the repository browser.