source: sasmodels/sasmodels/models/flexible_cylinder_elliptical.py @ db1d9d5

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

merge with master

  • Property mode set to 100644
File size: 6.8 KB
Line 
1r"""
2This model calculates the form factor for a flexible cylinder with an
3elliptical cross section and a uniform scattering length density.
4The non-negligible diameter of the cylinder is included by accounting
5for excluded volume interactions within the walk of a single cylinder.
6**Inter-cylinder interactions are NOT provided for.**
7
8The form factor is normalized by the particle volume such that
9
10.. math::
11
12    P(q) = \text{scale} \left<F^2\right>/V + \text{background}
13
14where the averaging $\left<\ldots\right>$ is over all possible orientations
15of the flexible cylinder.
16
17The 2D scattering intensity is the same as 1D, regardless of the orientation
18of the q vector which is defined as
19
20.. math::
21
22    q = \sqrt{q_x^2 + q_y^2}
23
24
25Definitions
26-----------
27
28The function is calculated in a similar way to that for the
29:ref:`flexible-cylinder` model in reference [1] below using the author's
30"Method 3 With Excluded Volume".
31
32The model is a parameterization of simulations of a discrete representation of
33the worm-like chain model of Kratky and Porod applied in the pseudo-continuous
34limit. See equations (13, 26-27) in the original reference for the details.
35
36.. note::
37
38    There are several typos in the original reference that have been corrected
39    by WRC [2]. Details of the corrections are in the reference below. Most notably
40
41    - Equation (13): the term $(1 - w(QR))$ should swap position with $w(QR)$
42
43    - Equations (23) and (24) are incorrect; WRC has entered these into
44      Mathematica and solved analytically. The results were then converted to
45      code.
46
47    - Equation (27) should be $q0 = max(a3/(Rg^2)^{1/2},3)$ instead of
48      $max(a3*b(Rg^2)^{1/2},3)$
49
50    - The scattering function is negative for a range of parameter values and
51      q-values that are experimentally accessible. A correction function has been
52      added to give the proper behavior.
53
54.. figure:: img/flexible_cylinder_ex_geometry.jpg
55
56
57The chain of contour length, $L$, (the total length) can be described as a chain
58of some number of locally stiff segments of length $l_p$, the persistence length
59(the length along the cylinder over which the flexible cylinder can be considered
60a rigid rod).
61The Kuhn length $(b = 2*l_p)$ is also used to describe the stiffness of a chain.
62
63The cross section of the cylinder is elliptical, with minor radius $a$ .
64The major radius is larger, so of course, **the axis_ratio must be
65greater than one.** Simple constraints should be applied during curve fitting to
66maintain this inequality.
67
68In the parameters, the $sld$ and $sld\_solvent$ represent the SLD of the
69chain/cylinder and solvent respectively. The *scale*, and the contrast are both
70multiplicative factors in the model and are perfectly correlated. One or both of
71these parameters must be held fixed during model fitting.
72
73**This is a model with complex behaviour depending on the ratio of** $L/b$ **and the
74reader is strongly encouraged to read reference [1] before use.**
75
76References
77----------
78
79.. [#] J S Pedersen and P Schurtenberger. *Scattering functions of semiflexible polymers with and without excluded volume effects.* Macromolecules, 29 (1996) 7602-7612
80
81Correction of the formula can be found in
82
83.. [#] W R Chen, P D Butler and L J Magid, *Incorporating Intermicellar Interactions in the Fitting of SANS Data from Cationic Wormlike Micelles.* Langmuir, 22(15) 2006 6539-6548
84
85Source
86------
87
88`flexible_cylinder_elliptical.py <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/flexible_cylinder_elliptical.py>`_
89
90`flexible_cylinder_elliptical.c <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/flexible_cylinder_elliptical.c>`_
91
92`wrc_cyl.c <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/lib/wrc_cyl.c>`_
93
94Authorship and Verification
95----------------------------
96
97* **Author:**
98* **Last Modified by:** Richard Heenan **Date:** December, 2016
99* **Last Reviewed by:** Steve King **Date:** March 26, 2019
100* **Source added by :** Steve King **Date:** March 25, 2019
101"""
102
103import numpy as np
104from numpy import inf
105
106name = "flexible_cylinder_elliptical"
107title = "Flexible cylinder wth an elliptical cross section and a uniform " \
108        "scattering length density."
109description = """Note : scale and contrast=sldCyl-sldSolv are both multiplicative
110        factors in the
111        model and are perfectly correlated. One or
112        both of these parameters must be held fixed
113        during model fitting.
114        """
115single = False
116
117category = "shape:cylinder"
118# pylint: disable=bad-whitespace, line-too-long
119#             ["name", "units", default, [lower, upper], "type", "description"],
120parameters = [
121    ["length",      "Ang",       1000.0, [0, inf],    "volume", "Length of the flexible cylinder"],
122    ["kuhn_length", "Ang",        100.0, [0, inf],    "volume", "Kuhn length of the flexible cylinder"],
123    ["radius",      "Ang",         20.0, [1, inf],    "volume", "Radius of the flexible cylinder"],
124    ["axis_ratio",  "",             1.5, [0, inf],    "",       "Axis_ratio (major_radius/minor_radius"],
125    ["sld",         "1e-6/Ang^2",   1.0, [-inf, inf], "sld",    "Cylinder scattering length density"],
126    ["sld_solvent", "1e-6/Ang^2",   6.3, [-inf, inf], "sld",    "Solvent scattering length density"],
127    ]
128# pylint: enable=bad-whitespace, line-too-long
129
130source = ["lib/polevl.c", "lib/sas_J1.c", "lib/gauss76.c", "lib/wrc_cyl.c",
131          "flexible_cylinder_elliptical.c"]
132
133def random():
134    """Return a random parameter set for the model."""
135    length = 10**np.random.uniform(2, 6)
136    radius = 10**np.random.uniform(1, 3)
137    axis_ratio = 10**np.random.uniform(-1, 1)
138    kuhn_length = 10**np.random.uniform(-2, -0.7)*length  # at least 10 segments
139    pars = dict(
140        length=length,
141        radius=radius,
142        axis_ratio=axis_ratio,
143        kuhn_length=kuhn_length,
144    )
145    return pars
146
147tests = [
148    # Accuracy tests based on content in test/utest_other_models.py
149    # Currently fails in OCL
150    # [{'length':     1000.0,
151    #  'kuhn_length': 100.0,
152    #  'radius':       20.0,
153    #  'axis_ratio':    1.5,
154    #  'sld':           1.0,
155    #  'sld_solvent':   6.3,
156    #  'background':    0.0001,
157    # }, 0.001, 3509.2187],
158
159    # Additional tests with larger range of parameters
160    [{'length':     1000.0,
161      'kuhn_length': 100.0,
162      'radius':       20.0,
163      'axis_ratio':    1.5,
164      'sld':           1.0,
165      'sld_solvent':   6.3,
166      'background':    0.0001,
167     }, 1.0, 0.00223819],
168    [{'length':        10.0,
169      'kuhn_length': 800.0,
170      'radius':        2.0,
171      'axis_ratio':    0.5,
172      'sld':           6.0,
173      'sld_solvent':  12.3,
174      'background':    0.001,
175     }, 0.1, 0.390281],
176    [{'length':        100.0,
177      'kuhn_length': 800.0,
178      'radius':       50.0,
179      'axis_ratio':    4.5,
180      'sld':           0.1,
181      'sld_solvent':   5.1,
182      'background':    0.0,
183     }, 1.0, 0.0016338264790]
184    ]
Note: See TracBrowser for help on using the repository browser.