source: sasmodels/sasmodels/models/flexible_cylinder.py @ 0507e09

core_shell_microgelsmagnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since 0507e09 was 0507e09, checked in by smk78, 5 months ago

Added link to source code to each model. Closes #883

  • Property mode set to 100644
File size: 6.1 KB
Line 
1r"""
2This model provides the form factor, $P(q)$, for a flexible cylinder
3where the form factor is normalized by the volume of the cylinder.
4**Inter-cylinder interactions are NOT provided for.**
5
6.. math::
7
8    P(q) = \text{scale} \left<F^2\right>/V + \text{background}
9
10where the averaging $\left<\ldots\right>$ is applied only for the 1D
11calculation
12
13The 2D scattering intensity is the same as 1D, regardless of the orientation of
14the q vector which is defined as
15
16.. math::
17
18    q = \sqrt{q_x^2 + q_y^2}
19
20Definitions
21-----------
22
23.. figure:: img/flexible_cylinder_geometry.jpg
24
25
26The chain of contour length, $L$, (the total length) can be described as a
27chain of some number of locally stiff segments of length $l_p$, the persistence
28length (the length along the cylinder over which the flexible cylinder can be
29considered a rigid rod).
30The Kuhn length $(b = 2*l_p)$ is also used to describe the stiffness of a chain.
31
32The returned value is in units of $cm^{-1}$, on absolute scale.
33
34In the parameters, the sld and sld\_solvent represent the SLD of the cylinder
35and solvent respectively.
36
37Our model uses the form factor calculations implemented in a c-library provided
38by the NIST Center for Neutron Research (Kline, 2006).
39
40
41From the reference:
42
43    'Method 3 With Excluded Volume' is used.
44    The model is a parametrization of simulations of a discrete representation
45    of the worm-like chain model of Kratky and Porod applied in the
46    pseudocontinuous limit.
47    See equations (13,26-27) in the original reference for the details.
48
49References
50----------
51
52.. [#] J S Pedersen and P Schurtenberger. *Scattering functions of semiflexible polymers with and without excluded volume effects.* Macromolecules, 29 (1996) 7602-7612
53
54Correction of the formula can be found in
55
56.. [#] 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
57
58Source
59------
60
61`flexible_cylinder.py <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/flexible_cylinder.py>`_
62
63`flexible_cylinder.c <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/flexible_cylinder.c>`_
64
65Authorship and Verification
66----------------------------
67
68* **Author:**
69* **Last Modified by:**
70* **Last Reviewed by:**
71* **Source added by :** Steve King **Date:** March 25, 2019
72"""
73
74import numpy as np
75from numpy import inf
76
77name = "flexible_cylinder"
78title = "Flexible cylinder where the form factor is normalized by the volume" \
79        "of the cylinder."
80description = """Note : scale and contrast = (sld - sld_solvent) are both
81                multiplicative factors in the model and are perfectly
82                correlated. One or both of these parameters must be held fixed
83                during model fitting.
84              """
85
86category = "shape:cylinder"
87single = False  # double precision only!
88
89# pylint: disable=bad-whitespace, line-too-long
90#             ["name", "units", default, [lower, upper], "type", "description"],
91parameters = [
92    ["length",      "Ang",       1000.0, [0, inf],    "volume", "Length of the flexible cylinder"],
93    ["kuhn_length", "Ang",        100.0, [0, inf],    "volume", "Kuhn length of the flexible cylinder"],
94    ["radius",      "Ang",         20.0, [0, inf],    "volume", "Radius of the flexible cylinder"],
95    ["sld",         "1e-6/Ang^2",   1.0, [-inf, inf], "sld",    "Cylinder scattering length density"],
96    ["sld_solvent", "1e-6/Ang^2",   6.3, [-inf, inf], "sld",    "Solvent scattering length density"],
97    ]
98# pylint: enable=bad-whitespace, line-too-long
99source = ["lib/polevl.c", "lib/sas_J1.c", "lib/wrc_cyl.c", "flexible_cylinder.c"]
100
101def random():
102    """Return a random parameter set for the model."""
103    length = 10**np.random.uniform(2, 6)
104    radius = 10**np.random.uniform(1, 3)
105    kuhn_length = 10**np.random.uniform(-2, 0)*length
106    pars = dict(
107        length=length,
108        radius=radius,
109        kuhn_length=kuhn_length,
110    )
111    return pars
112
113tests = [
114    # Accuracy tests based on content in test/utest_other_models.py
115    [{'length':     1000.0,  # test T1
116      'kuhn_length': 100.0,
117      'radius':       20.0,
118      'sld':           1.0,
119      'sld_solvent':   6.3,
120      'background':    0.0001,
121     }, 0.001, 3509.2187],
122
123    # Additional tests with larger range of parameters
124    [{'length':    1000.0,  # test T2
125      'kuhn_length': 100.0,
126      'radius':       20.0,
127      'sld':           1.0,
128      'sld_solvent':   6.3,
129      'background':    0.0001,
130     }, 1.0, 0.000595345],
131    [{'length':        10.0,  # test T3
132      'kuhn_length': 800.0,
133      'radius':        2.0,
134      'sld':           6.0,
135      'sld_solvent':  12.3,
136      'background':    0.001,
137     }, 0.1, 1.55228],
138    [{'length':        100.0,  # test T4
139      'kuhn_length': 800.0,
140      'radius':       50.0,
141      'sld':           0.1,
142      'sld_solvent':   5.1,
143      'background':    0.0,
144     }, 1.0, 0.000938456]
145    ]
146
147# There are a few branches in the code that ought to have test values:
148#
149# For length > 4 * kuhn_length
150#        if length > 10 * kuhn_length then C is scaled by 3.06 (L/b)^(-0.44)
151#        q*kuhn_length <= 3.1  => Sexv_new
152#           dS/dQ < 0 has different behaviour from dS/dQ >= 0
153#  T2    q*kuhn_length > 3.1   => a_long
154#
155# For length <= 4 * kuhn_length
156#        q*kuhn_length <= max(1.9/Rg_short, 3.0)  => Sdebye((q*Rg)^2)
157#           q*Rg < 0.5 uses Pade approx, q*Rg > 1.0 uses math lib
158#  T3,T4 q*kuhn_length > max(1.9/Rg_short, 3.0)   => a_short
159#
160# Note that the transitions between branches may be abrupt.  You can see a
161# several percent change around length=10*kuhn_length and length=4*kuhn_length
162# using the following:
163#
164#    sascomp flexible_cylinder -calc=double -sets=10 length=10*kuhn_length,10.000001*kuhn_length
165#    sascomp flexible_cylinder -calc=double -sets=10 length=4*kuhn_length,4.000001*kuhn_length
166#
167# The transition between low q and high q around q*kuhn_length = 3 seems
168# to be good to 4 digits or better.  This was tested by computing the value
169# on each branches near the transition point and reporting the relative error
170# for kuhn lengths of 10, 100 and 1000 and a variety of length:kuhn_length
171# ratios.
Note: See TracBrowser for help on using the repository browser.