source: sasmodels/sasmodels/models/be_polyelectrolyte.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 years ago

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

  • Property mode set to 100644
File size: 9.2 KB
Line 
1r"""
2.. note:: Please read the Validation section below.
3
4Definition
5----------
6This model calculates the structure factor of a polyelectrolyte solution with
7the RPA expression derived by Borue and Erukhimovich\ [#Borue]_.  Note however
8that the fitting procedure here does not follow the notation in that reference
9as 's' and 't' are **not** decoupled. Instead the scattering intensity $I(q)$
10is calculated as
11
12.. math::
13
14    I(q) = K\frac{q^2+k^2}{4\pi L_b\alpha ^2}
15    \frac{1}{1+r_{0}^4(q^2+k^2)(q^2-12hC_a/b^2)} + background
16
17    k^2 = 4\pi L_b(2C_s + \alpha C_a)
18
19    r_{0}^2 = \frac{b}{\alpha \sqrt{C_a 48\pi L_b}}
20
21where
22
23$K$ is the contrast factor for the polymer which is defined differently than in
24other models and is given in barns where 1 $barn = 10^{-24}$ $cm^2$.  $K$ is
25defined as:
26
27.. math::
28
29    K = a^2
30
31    a = b_p - (v_p/v_s) b_s
32
33where:
34
35- $b_p$ and $b_s$ are **sum of the scattering lengths of the atoms**
36  constituting the polymer monomer and the solvent molecules, respectively.
37
38- $v_p$ and $v_s$ are the partial molar volume of the polymer and the
39  solvent, respectively.
40
41- $L_b$ is the Bjerrum length (|Ang|) - **Note:** This parameter needs to be
42  kept constant for a given solvent and temperature!
43
44- $h$ is the virial parameter (|Ang^3|) - **Note:** See [#Borue]_ for the
45  correct interpretation of this parameter.  It incorporates second and third
46  virial coefficients and can be *negative*.
47
48- $b$ is the monomer length (|Ang|).
49
50- $C_s$ is the concentration of monovalent salt(1/|Ang^3| - internally converted from mol/L).
51
52- $\alpha$ is the degree of ionization (the ratio of charged monomers to the total
53  number of monomers)
54
55- $C_a$ is the polymer molar concentration (1/|Ang^3| - internally converted from mol/L)
56
57- $background$ is the incoherent background.
58
59For 2D data the scattering intensity is calculated in the same way as 1D,
60where the $\vec q$ vector is defined as
61
62.. math::
63
64    q = \sqrt{q_x^2 + q_y^2}
65
66Validation
67----------
68
69As of the last revision, this code is believed to be correct.  However it
70needs further validation and should be used with caution at this time.  The
71history of this code goes back to a 1998 implementation. It was recently noted
72that in that implementation, while both the polymer concentration and salt
73concentration were converted from experimental units of mol/L to more
74dimensionally useful units of 1/|Ang^3|, only the converted version of the
75polymer concentration was actually being used in the calculation while the
76unconverted salt concentration (still in apparent units of mol/L) was being
77used.  This was carried through to Sasmodels as used for SasView 4.1 (though
78the line of code converting the salt concentration to the new units was removed
79somewhere along the line). Simple dimensional analysis of the calculation shows
80that the converted salt concentration should be used, which the original code
81suggests was the intention, so this has now been corrected (for SasView 4.2).
82Once better validation has been performed this note will be removed.
83
84References
85----------
86
87.. [#Borue] V Y Borue, I Y Erukhimovich, *Macromolecules*, 21 (1988) 3240
88.. [#] J F Joanny, L Leibler, *Journal de Physique*, 51 (1990) 545
89.. [#] A Moussaid, F Schosseler, J P Munch, S Candau, *J. Journal de Physique
90   II France*, 3 (1993) 573
91.. [#] E Raphael, J F Joanny, *Europhysics Letters*, 11 (1990) 179
92
93Source
94------
95
96`be_polyelectrolyte.py <https://github.com/SasView/sasmodels/blob/master/sasmodels/models/be_polyelectrolyte.py>`_
97
98Authorship and Verification
99----------------------------
100
101* **Author:** NIST IGOR/DANSE **Date:** pre 2010
102* **Last Modified by:** Paul Butler **Date:** September 25, 2018
103* **Last Reviewed by:** Paul Butler **Date:** September 25, 2018
104* **Source added by :** Steve King **Date:** March 25, 2019
105"""
106
107import numpy as np
108from numpy import inf, pi, sqrt
109
110name = "be_polyelectrolyte"
111title = "Polyelectrolyte with the RPA expression derived by Borue and Erukhimovich"
112description = """
113            Evaluate
114            F(x) = K 1/(4 pi Lb (alpha)^(2)) (q^(2)+k2)/(1+(r02)^(2))
115                 (q^(2)+k2) (q^(2)-(12 h C/b^(2)))
116
117            has 3 internal parameters :
118                   The inverse Debye Length: K2 = 4 pi Lb (2 Cs+alpha C)
119                   r02 =1/alpha/Ca^(0.5) (B/(48 pi Lb)^(0.5))
120                   Ca = 6.022136e-4 C
121            """
122category = "shape-independent"
123
124# pylint: disable=bad-whitespace, line-too-long
125#   ["name", "units", default, [lower, upper], "type", "description"],
126parameters = [
127    ["contrast_factor",       "barns",   10.0,  [-inf, inf], "", "Contrast factor of the polymer"],
128    ["bjerrum_length",        "Ang",      7.1,  [0, inf],    "", "Bjerrum length"],
129    ["virial_param",          "Ang^3", 12.0,  [-inf, inf], "", "Virial parameter"],
130    ["monomer_length",        "Ang",     10.0,  [0, inf],    "", "Monomer length"],
131    ["salt_concentration",    "mol/L",    0.0,  [-inf, inf], "", "Concentration of monovalent salt"],
132    ["ionization_degree",     "",         0.05, [0, inf],    "", "Degree of ionization"],
133    ["polymer_concentration", "mol/L",    0.7,  [0, inf],    "", "Polymer molar concentration"],
134    ]
135# pylint: enable=bad-whitespace, line-too-long
136
137
138def Iq(q,
139       contrast_factor,
140       bjerrum_length,
141       virial_param,
142       monomer_length,
143       salt_concentration,
144       ionization_degree,
145       polymer_concentration):
146    """
147    :params: see parameter table
148    :return: 1-D form factor for polyelectrolytes in low salt
149
150    parameter names, units, default values, and behavior (volume, sld etc) are
151    defined in the parameter table.  The concentrations are converted from
152    experimental mol/L to dimensionaly useful 1/A3 in first two lines
153    """
154
155    concentration_pol = polymer_concentration * 6.022136e-4
156    concentration_salt = salt_concentration * 6.022136e-4
157
158    k_square = 4.0 * pi * bjerrum_length * (2*concentration_salt +
159                                            ionization_degree * concentration_pol)
160
161    r0_square = 1.0/ionization_degree/sqrt(concentration_pol) * \
162                (monomer_length/sqrt((48.0*pi*bjerrum_length)))
163
164    term1 = contrast_factor/(4.0 * pi * bjerrum_length *
165                             ionization_degree**2) * (q**2 + k_square)
166
167    term2 = 1.0 + r0_square**2 * (q**2 + k_square) * \
168        (q**2 - (12.0 * virial_param * concentration_pol/(monomer_length**2)))
169
170    return term1/term2
171
172Iq.vectorized = True  # Iq accepts an array of q values
173
174def random():
175    """Return a random parameter set for the model."""
176    # TODO: review random be_polyelectrolyte model generation
177    pars = dict(
178        scale=10000, #background=0,
179        #polymer_concentration=0.7,
180        polymer_concentration=np.random.beta(5, 3), # around 70%
181        #salt_concentration=0.0,
182        # keep salt concentration extremely low
183        # and use explicit molar to match polymer concentration
184        salt_concentration=np.random.beta(1, 100)*6.022136e-4,
185        #contrast_factor=10.0,
186        contrast_fact=np.random.uniform(1, 100),
187        #bjerrum_length=7.1,
188        bjerrum_length=np.random.uniform(1, 10),
189        #virial_param=12.0,
190        virial_param=np.random.uniform(-1000, 30),
191        #monomer_length=10.0,
192        monomer_length=10.0**(4*np.random.beta(1.5, 3)),
193        #ionization_degree=0.05,
194        ionization_degree=np.random.beta(1.5, 4),
195    )
196    return pars
197
198demo = dict(scale=1, background=0.1,
199            contrast_factor=10.0,
200            bjerrum_length=7.1,
201            virial_param=12.0,
202            monomer_length=10.0,
203            salt_concentration=0.0,
204            ionization_degree=0.05,
205            polymer_concentration=0.7)
206
207tests = [
208
209    # Accuracy tests based on content in test/utest_other_models.py
210    # Note that these should some day be validated beyond this self validation
211    # (circular reasoning). -- i.e. the "good value," at least for those with
212    # non zero salt concentrations, were obtained by running the current
213    # model in SasView and copying the appropriate result here.
214    #    PDB -- Sep 26, 2018
215    [{'contrast_factor':       10.0,
216      'bjerrum_length':         7.1,
217      'virial_param':          12.0,
218      'monomer_length':        10.0,
219      'salt_concentration':     0.0,
220      'ionization_degree':      0.05,
221      'polymer_concentration':  0.7,
222      'background':             0.001,
223     }, 0.001, 0.0948379],
224
225    [{'contrast_factor':       10.0,
226      'bjerrum_length':       100.0,
227      'virial_param':           3.0,
228      'monomer_length':         5.0,
229      'salt_concentration':     1.0,
230      'ionization_degree':      0.1,
231      'polymer_concentration':  1.0,
232      'background':             0.0,
233     }, 0.1, 0.253469484],
234
235    [{'contrast_factor':       10.0,
236      'bjerrum_length':       100.0,
237      'virial_param':           3.0,
238      'monomer_length':         5.0,
239      'salt_concentration':     1.0,
240      'ionization_degree':      0.1,
241      'polymer_concentration':  1.0,
242      'background':             1.0,
243     }, 0.05, 1.738358122],
244
245    [{'contrast_factor':     100.0,
246      'bjerrum_length':       10.0,
247      'virial_param':         12.0,
248      'monomer_length':       10.0,
249      'salt_concentration':    0.1,
250      'ionization_degree':     0.5,
251      'polymer_concentration': 0.1,
252      'background':           0.01,
253     }, 0.5, 0.012881893],
254    ]
Note: See TracBrowser for help on using the repository browser.