# source:sasmodels/sasmodels/models/multilayer_vesicle.py@b297ba9

core_shell_microgelsmagnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since b297ba9 was b297ba9, checked in by Paul Kienzle <pkienzle@…>, 6 months ago

lint

• Property mode set to 100644
File size: 7.3 KB
Line
1r"""
2Definition
3----------
4
5This model is a trivial extension of the core_shell_sphere function where the
6core is filled with solvent and is surrounded by $N$ shells of material
7(such as lipids) interleaved with $N - 1$ layers of solvent. For $N = 1$, this
8returns the same as the vesicle model, except for the normalisation, which here
9is to outermost volume. The shell thicknesses and SLD are constant for all
10shells as expected for a multilayer vesicle.
11
12.. figure:: img/multi_shell_geometry.jpg
13
14    Geometry of the multilayer_vesicle model.
15
16See the :ref:core-shell-sphere model for more documentation.
17
18The 1D scattering intensity is calculated in the following way (Guinier, 1955)
19
20.. math::
21    P(q) = \text{scale} \cdot \frac{\phi}{V(R_N)} F^2(q) + \text{background}
22
23where
24
25.. math::
26     F(q) = (\rho_\text{shell}-\rho_\text{solv}) \sum_{i=1}^{N} \left[
27     3V(r_i)\frac{\sin(qr_i) - qr_i\cos(qr_i)}{(qr_i)^3}
28     - 3V(R_i)\frac{\sin(qR_i) - qR_i\cos(qR_i)}{(qR_i)^3}
29     \right]
30
31for
32
33.. math::
34
35     r_i &= r_c + (i-1)(t_s + t_w) \text{ solvent radius before shell } i \\
36     R_i &= r_i + t_s \text{ shell radius for shell } i
37
38$\phi$ is the volume fraction of particles, $V(r)$ is the volume of a sphere
39of radius $r$, $r_c$ is the radius of the core, $t_s$ is the thickness of
40the shell, $t_w$ is the thickness of the solvent layer between the shells,
41$\rho_\text{shell}$ is the scattering length density of a shell, and
42$\rho_\text{solv}$ is the scattering length density of the solvent.
43
44USAGE NOTES
45
46* The outer-most shell radius $R_N$ is used as the effective radius
47  for $P(Q)$ when $P(Q) * S(Q)$ is applied.
48  calculations rather slow.
49* The number of shells is always rounded to an integer value as a non interger
50  number of layers is not physical.
51* Thus Polydispersity should only be applied to number of shells **VERY
52  CAREFULLY**.  A possible legitimate use would be for mixed systems in which
53  some vesicles have 1 shell, some have 2, etc. A polydispersity on $N$ can be
54  used to model the data by using the "array distriubtion" feature. First
55  create a file such as *shell_dist.txt* containing the relative portion
56  of each vesicle size::
57
58    1 20
59    2  4
60    3  1
61
62  Turn on polydispersity and select an array distribution for the *n_shells*
63  parameter.  Choose the above *shell_dist.txt* file, and the model will be
64  computed with 80% 1-shell vesicles, 16% 2-shell vesicles and 4%
65  3-shell vesicles.
66* This is a highly non-linear, highly oscillatory (especially around the
67  q-values that correspond to the repeat distance of the layers), model
68  function complicated by the fact that the number of water/shell pairs must
69  physically be an integer value, although the optimization treats it as a
70  floating point value. Thus it may be that the resolution interpolation is not
71  sufficiently fine grained in certain cases. Please report any such occurences
72  to the SasView team. Generally, for the best possible experience:
73
74 - Start with the best possible guess
75 - Using a priori knowledge, hold as many parameters fixed as possible
76 - if N=1, tw (water thickness) must by definition be zero. Both N and tw should
77   be fixed during fitting.
78 - If N>1, use constraints to keep N > 1
79 - Because N only really moves in integer steps, it may get "stuck" if the
80   optimizer step size is too small so care should be taken
81   If you experience problems with this please contact the SasView team and let
82   them know the issue preferably with example data and model which fail to
83   converge.
84
85The 2D scattering intensity is the same as 1D, regardless of the orientation
86of the q vector which is defined as:
87
88.. math::
89
90    q = \sqrt{q_x^2 + q_y^2}
91
92For information about polarised and magnetic scattering, see
93the :ref:magnetism documentation.
94
95References
96----------
97
98.. [#] B Cabane, *Small Angle Scattering Methods*, in *Surfactant Solutions:
99   New Methods of Investigation*, Ch.2, Surfactant Science Series Vol. 22, Ed.
100   R Zana and M Dekker, New York, (1987).
101
102Authorship and Verification
103----------------------------
104
105* **Author:** NIST IGOR/DANSE **Date:** pre 2010
106* **Converted to sasmodels by:** Piotr Rozyczko **Date:** Feb 24, 2016
107* **Last Modified by:** Paul Kienzle **Date:** Feb 7, 2017
108* **Last Reviewed by:** Paul Butler **Date:** March 12, 2017
109"""
110
111import numpy as np
112from numpy import inf
113
114name = "multilayer_vesicle"
115title = "P(Q) for a Multi-lamellar vesicle"
116description = """
117    multilayer_vesicle model parameters;
118    scale : scale factor for abs intensity if needed else 1.0
119    volfraction: volume fraction
120    radius : Core radius of the multishell
121    thick_shell: shell thickness
122    thick_solvent: water thickness
123    sld_solvent: solvent scattering length density
124    sld: shell scattering length density
125    n_shells:number of "shell plus solvent" layer pairs
126    background: incoherent background
127        """
128category = "shape:sphere"
129
130# pylint: disable=bad-whitespace, line-too-long
131#   ["name", "units", default, [lower, upper], "type","description"],
132parameters = [
133    ["volfraction", "",  0.05, [0.0, 1],  "", "volume fraction of vesicles"],
134    ["radius", "Ang", 60.0, [0.0, inf],  "volume", "radius of solvent filled core"],
135    ["thick_shell", "Ang",        10.0, [0.0, inf],  "volume", "thickness of one shell"],
136    ["thick_solvent", "Ang",        10.0, [0.0, inf],  "volume", "solvent thickness between shells"],
137    ["sld_solvent",    "1e-6/Ang^2",  6.4, [-inf, inf], "sld", "solvent scattering length density"],
138    ["sld",   "1e-6/Ang^2",  0.4, [-inf, inf], "sld", "Shell scattering length density"],
139    ["n_shells",     "",            2.0, [1.0, inf],  "volume", "Number of shell plus solvent layer pairs"],
140    ]
141# pylint: enable=bad-whitespace, line-too-long
142
143# TODO: proposed syntax for specifying which parameters can be polydisperse
144#polydispersity = ["radius", "thick_shell"]
145
146source = ["lib/sas_3j1x_x.c", "multilayer_vesicle.c"]
147have_Fq = True
149
150def random():
151    """Return a random parameter set for the model."""
152    volfraction = 10**np.random.uniform(-3, -0.5)  # scale from 0.1% to 30%
153    radius = 10**np.random.uniform(0, 2.5) # core less than 300 A
154    total_thick = 10**np.random.uniform(2, 4) # up to 10000 A of shells
155    # random number of shells, with shell+solvent thickness > 10 A
156    n_shells = int(10**np.random.uniform(0, np.log10(total_thick)-1)+0.5)
157    # split total shell thickness with preference for shell over solvent;
158    # make sure that shell thickness is at least 1 A
159    one_thick = total_thick/n_shells
160    thick_solvent = 10**np.random.uniform(-2, 0)*(one_thick - 1)
161    thick_shell = one_thick - thick_solvent
162    pars = dict(
163        scale=1,
164        volfraction=volfraction,
166        thick_shell=thick_shell,
167        thick_solvent=thick_solvent,
168        n_shells=n_shells,
169    )
170    return pars
171
172tests = [
173    # Accuracy tests based on content in test/utest_other_models.py
175      'thick_shell': 10.0,
176      'thick_solvent': 10.0,
177      'sld_solvent': 6.4,
178      'sld': 0.4,
179      'n_shells': 2.0,
180      'scale': 1.0,
181      'background': 0.001,
182     }, 0.001, 122.1405],
183
184    [{'volfraction': 1.0,