source: sasmodels/doc/guide/pd/polydispersity.rst @ a5a12ca

core_shell_microgelsmagnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since a5a12ca was a5a12ca, checked in by dirk, 6 years ago

implementation of Boltzmann distribution refs #1018

  • Property mode set to 100644
File size: 7.6 KB
RevLine 
[990d8df]1.. pd_help.rst
2
3.. This is a port of the original SasView html help file to ReSTructured text
4.. by S King, ISIS, during SasView CodeCamp-III in Feb 2015.
5
6.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
7
8Polydispersity Distributions
9----------------------------
10
11With some models in sasmodels we can calculate the average form factor for a
12population of particles that exhibit size and/or orientational
13polydispersity. The resultant form factor is normalized by the average
14particle volume such that
15
16.. math::
17
18  P(q) = \text{scale} \langle F^* F \rangle / V + \text{background}
19
20where $F$ is the scattering amplitude and $\langle\cdot\rangle$ denotes an
21average over the size distribution.
22
23Each distribution is characterized by its center $\bar x$, its width $\sigma$,
24the number of sigmas $N_\sigma$ to include from the tails, and the number of
25points used to compute the average. The center of the distribution is set by the
26value of the model parameter.  Volume parameters have polydispersity *PD*
27(not to be confused with a molecular weight distributions in polymer science)
28leading to a size distribution of width $\text{PD} = \sigma / \bar x$, but
29orientation parameters use an angular distributions of width $\sigma$.
30$N_\sigma$ determines how far into the tails to evaluate the distribution, with
31larger values of $N_\sigma$ required for heavier tailed distributions.
32The scattering in general falls rapidly with $qr$ so the usual assumption
33that $G(r - 3\sigma_r)$ is tiny and therefore $f(r - 3\sigma_r)G(r - 3\sigma_r)$
34will not contribute much to the average may not hold when particles are large.
35This, too, will require increasing $N_\sigma$.
36
37Users should note that the averaging computation is very intensive. Applying
38polydispersion to multiple parameters at the same time or increasing the
39number of points in the distribution will require patience! However, the
40calculations are generally more robust with more data points or more angles.
41
[a5a12ca]42The following six distribution functions are provided:
[990d8df]43
44*  *Rectangular Distribution*
45*  *Gaussian Distribution*
46*  *Lognormal Distribution*
47*  *Schulz Distribution*
48*  *Array Distribution*
[a5a12ca]49*  *Boltzmann Distribution*
[990d8df]50
51These are all implemented as *number-average* distributions.
52
53.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
54
55Rectangular Distribution
56^^^^^^^^^^^^^^^^^^^^^^^^
57
58The Rectangular Distribution is defined as
59
60.. math::
61
62    f(x) = \frac{1}{\text{Norm}}
63    \begin{cases}
64      1 & \text{for } |x - \bar x| \leq w \\
65      0 & \text{for } |x - \bar x| > w
66    \end{cases}
67
68where $\bar x$ is the mean of the distribution, $w$ is the half-width, and
69*Norm* is a normalization factor which is determined during the numerical
70calculation.
71
72Note that the standard deviation and the half width $w$ are different!
73
74The standard deviation is
75
76.. math:: \sigma = w / \sqrt{3}
77
78whilst the polydispersity is
79
80.. math:: \text{PD} = \sigma / \bar x
81
82.. figure:: pd_rectangular.jpg
83
84    Rectangular distribution.
85
86.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
87
88Gaussian Distribution
89^^^^^^^^^^^^^^^^^^^^^
90
91The Gaussian Distribution is defined as
92
93.. math::
94
95    f(x) = \frac{1}{\text{Norm}}
96           \exp\left(-\frac{(x - \bar x)^2}{2\sigma^2}\right)
97
[1f058ea]98where $\bar x$ is the mean of the distribution and *Norm* is a normalization
99factor which is determined during the numerical calculation.
[990d8df]100
101The polydispersity is
102
103.. math:: \text{PD} = \sigma / \bar x
104
105.. figure:: pd_gaussian.jpg
106
107    Normal distribution.
108
109.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
110
111Lognormal Distribution
112^^^^^^^^^^^^^^^^^^^^^^
113
114The Lognormal Distribution is defined as
115
116.. math::
117
118    f(x) = \frac{1}{\text{Norm}}
119           \frac{1}{xp}\exp\left(-\frac{(\ln(x) - \mu)^2}{2p^2}\right)
120
121where $\mu=\ln(x_\text{med})$ when $x_\text{med}$ is the median value of the
122distribution, and *Norm* is a normalization factor which will be determined
123during the numerical calculation.
124
[1f058ea]125The median value for the distribution will be the value given for the
126respective size parameter, for example, *radius=60*.
[990d8df]127
128The polydispersity is given by $\sigma$
129
130.. math:: \text{PD} = p
131
132For the angular distribution
133
134.. math:: p = \sigma / x_\text{med}
135
136The mean value is given by $\bar x = \exp(\mu+ p^2/2)$. The peak value
137is given by $\max x = \exp(\mu - p^2)$.
138
139.. figure:: pd_lognormal.jpg
140
141    Lognormal distribution.
142
143This distribution function spreads more, and the peak shifts to the left, as
144$p$ increases, so it requires higher values of $N_\sigma$ and more points
145in the distribution.
146
147.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
148
149Schulz Distribution
150^^^^^^^^^^^^^^^^^^^
151
152The Schulz distribution is defined as
153
154.. math::
155
156    f(x) = \frac{1}{\text{Norm}}
157           (z+1)^{z+1}(x/\bar x)^z\frac{\exp[-(z+1)x/\bar x]}{\bar x\Gamma(z+1)}
158
159where $\bar x$ is the mean of the distribution and *Norm* is a normalization
160factor which is determined during the numerical calculation, and $z$ is a
161measure of the width of the distribution such that
162
163.. math:: z = (1-p^2) / p^2
164
165The polydispersity is
166
167.. math:: p = \sigma / \bar x
168
169Note that larger values of PD might need larger number of points and $N_\sigma$.
170For example, at PD=0.7 and radius=60 |Ang|, Npts>=160 and Nsigmas>=15 at least.
171
172.. figure:: pd_schulz.jpg
173
174    Schulz distribution.
175
176For further information on the Schulz distribution see:
177M Kotlarchyk & S-H Chen, *J Chem Phys*, (1983), 79, 2461.
178
179.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
180
181Array Distribution
182^^^^^^^^^^^^^^^^^^
183
[a5a12ca]184This user-definable distribution should be given as a simple ASCII text
[990d8df]185file where the array is defined by two columns of numbers: $x$ and $f(x)$.
186The $f(x)$ will be normalized to 1 during the computation.
187
188Example of what an array distribution file should look like:
189
190====  =====
191 30    0.1
192 32    0.3
193 35    0.4
194 36    0.5
195 37    0.6
196 39    0.7
197 41    0.9
198====  =====
199
200Only these array values are used computation, therefore the parameter value
201given for the model will have no affect, and will be ignored when computing
202the average.  This means that any parameter with an array distribution will
[a5a12ca]203not be fitable.
204
205.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
206
207Boltzmann Distribution
208^^^^^^^^^^^^^^^^^^^^^^
209
210The Boltzmann Distribution is defined as
211
212.. math::
213
214    f(x) = \frac{1}{\text{Norm}}
215           \exp\left(-\frac{ | x - \bar x | }{\sigma}\right)
216
217where $\bar x$ is the mean of the distribution and *Norm* is a normalization
218factor which is determined during the numerical calculation.
219The width is defined as
220
221.. math:: \sigma=\frac{k T}{E}
222
223which is the inverse Boltzmann factor,
224where $k$ is the Boltzmann constant, $T$ the temperature in Kelvin and $E$ a
225characteristic energy per particle.
226
227.. figure:: pd_boltzmann.jpg
228
229    Boltzmann distribution.
[990d8df]230
231.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
232
233Note about DLS polydispersity
234^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
235
236Many commercial Dynamic Light Scattering (DLS) instruments produce a size
[1f058ea]237polydispersity parameter, sometimes even given the symbol $p$\ ! This
[990d8df]238parameter is defined as the relative standard deviation coefficient of
239variation of the size distribution and is NOT the same as the polydispersity
240parameters in the Lognormal and Schulz distributions above (though they all
241related) except when the DLS polydispersity parameter is <0.13.
242
243For more information see:
244S King, C Washington & R Heenan, *Phys Chem Chem Phys*, (2005), 7, 143
245
246.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
247
248*Document History*
249
250| 2015-05-01 Steve King
251| 2017-05-08 Paul Kienzle
Note: See TracBrowser for help on using the repository browser.