source: sasmodels/sasmodels/models/bcc_paracrystal.py @ da7b26b

core_shell_microgelsmagnetic_modelticket-1257-vesicle-productticket_1156ticket_1265_superballticket_822_more_unit_tests
Last change on this file since da7b26b was da7b26b, checked in by smk78, 13 months ago

Added warning to bcc, fcc and sc model doc strings

  • Property mode set to 100644
File size: 6.7 KB
Line 
1r"""
2.. warning:: This model and this model description are under review following
3             concerns raised by SasView users. If you need to use this model,
4             please email help@sasview.org for the latest situation. *The
5             SasView Developers. September 2018.*
6
7Definition
8----------
9
10Calculates the scattering from a **body-centered cubic lattice** with
11paracrystalline distortion. Thermal vibrations are considered to be negligible,
12and the size of the paracrystal is infinitely large. Paracrystalline distortion
13is assumed to be isotropic and characterized by a Gaussian distribution.
14
15The scattering intensity $I(q)$ is calculated as
16
17.. math::
18
19    I(q) = \frac{\text{scale}}{V_p} V_\text{lattice} P(q) Z(q)
20
21where *scale* is the volume fraction of spheres, $V_p$ is the volume of the
22primary particle, $V_\text{lattice}$ is a volume correction for the crystal
23structure, $P(q)$ is the form factor of the sphere (normalized), and $Z(q)$
24is the paracrystalline structure factor for a body-centered cubic structure.
25
26Equation (1) of the 1990 reference\ [#CIT1990]_ is used to calculate $Z(q)$,
27using equations (29)-(31) from the 1987 paper\ [#CIT1987]_ for $Z1$, $Z2$, and
28$Z3$.
29
30The lattice correction (the occupied volume of the lattice) for a
31body-centered cubic structure of particles of radius $R$ and nearest neighbor
32separation $D$ is
33
34.. math::
35
36    V_\text{lattice} = \frac{16\pi}{3} \frac{R^3}{\left(D\sqrt{2}\right)^3}
37
38
39The distortion factor (one standard deviation) of the paracrystal is included
40in the calculation of $Z(q)$
41
42.. math::
43
44    \Delta a = g D
45
46where $g$ is a fractional distortion based on the nearest neighbor distance.
47
48
49.. figure:: img/bcc_geometry.jpg
50
51    Body-centered cubic lattice.
52
53For a crystal, diffraction peaks appear at reduced q-values given by
54
55.. math::
56
57    \frac{qD}{2\pi} = \sqrt{h^2 + k^2 + l^2}
58
59where for a body-centered cubic lattice, only reflections where
60$(h + k + l) = \text{even}$ are allowed and reflections where
61$(h + k + l) = \text{odd}$ are forbidden. Thus the peak positions
62correspond to (just the first 5)
63
64.. math::
65
66    \begin{array}{lccccc}
67    q/q_o          &   1   & \sqrt{2} & \sqrt{3} & \sqrt{4} & \sqrt{5} \\
68    \text{Indices} & (110) &    (200) & (211)    & (220)    & (310)    \\
69    \end{array}
70
71.. note::
72
73  The calculation of $Z(q)$ is a double numerical integral that
74  must be carried out with a high density of points to properly capture
75  the sharp peaks of the paracrystalline scattering.
76  So be warned that the calculation is slow. Fitting of any experimental data
77  must be resolution smeared for any meaningful fit. This makes a triple integral
78  which may be very slow.
79
80This example dataset is produced using 200 data points,
81*qmin* = 0.001 |Ang^-1|, *qmax* = 0.1 |Ang^-1| and the above default values.
82
83The 2D (Anisotropic model) is based on the reference below where $I(q)$ is
84approximated for 1d scattering. Thus the scattering pattern for 2D may not
85be accurate, particularly at low $q$. For general details of the calculation and angular
86dispersions for oriented particles see :ref:`orientation` .
87Note that we are not responsible for any incorrectness of the 2D model computation.
88
89.. figure:: img/parallelepiped_angle_definition.png
90
91    Orientation of the crystal with respect to the scattering plane, when
92    $\theta = \phi = 0$ the $c$ axis is along the beam direction (the $z$ axis).
93
94References
95----------
96
97.. [#CIT1987] Hideki Matsuoka et. al. *Physical Review B*, 36 (1987) 1754-1765
98   (Original Paper)
99.. [#CIT1990] Hideki Matsuoka et. al. *Physical Review B*, 41 (1990) 3854 -3856
100   (Corrections to FCC and BCC lattice structure calculation)
101
102Authorship and Verification
103---------------------------
104
105* **Author:** NIST IGOR/DANSE **Date:** pre 2010
106* **Last Modified by:** Paul Butler **Date:** September 29, 2016
107* **Last Reviewed by:** Richard Heenan **Date:** March 21, 2016
108"""
109
110import numpy as np
111from numpy import inf, pi
112
113name = "bcc_paracrystal"
114title = "Body-centred cubic lattic with paracrystalline distortion"
115description = """
116    Calculates the scattering from a **body-centered cubic lattice** with
117    paracrystalline distortion. Thermal vibrations are considered to be
118    negligible, and the size of the paracrystal is infinitely large.
119    Paracrystalline distortion is assumed to be isotropic and characterized
120    by a Gaussian distribution.
121    """
122category = "shape:paracrystal"
123
124#note - calculation requires double precision
125single = False
126
127# pylint: disable=bad-whitespace, line-too-long
128#             ["name", "units", default, [lower, upper], "type","description" ],
129parameters = [["dnn",         "Ang",       220,    [-inf, inf], "",            "Nearest neighbour distance"],
130              ["d_factor",    "",            0.06, [-inf, inf], "",            "Paracrystal distortion factor"],
131              ["radius",      "Ang",        40,    [0, inf],    "volume",      "Particle radius"],
132              ["sld",         "1e-6/Ang^2",  4,    [-inf, inf], "sld",         "Particle scattering length density"],
133              ["sld_solvent", "1e-6/Ang^2",  1,    [-inf, inf], "sld",         "Solvent scattering length density"],
134              ["theta",       "degrees",    60,    [-360, 360], "orientation", "c axis to beam angle"],
135              ["phi",         "degrees",    60,    [-360, 360], "orientation", "rotation about beam"],
136              ["psi",         "degrees",    60,    [-360, 360], "orientation", "rotation about c axis"]
137             ]
138# pylint: enable=bad-whitespace, line-too-long
139
140source = ["lib/sas_3j1x_x.c", "lib/gauss150.c", "lib/sphere_form.c", "bcc_paracrystal.c"]
141
142def random():
143    # Define lattice spacing as a multiple of the particle radius
144    # using the formulat a = 4 r/sqrt(3).  Systems which are ordered
145    # are probably mostly filled, so use a distribution which goes from
146    # zero to one, but leaving 90% of them within 80% of the
147    # maximum bcc packing.  Lattice distortion values are empirically
148    # useful between 0.01 and 0.7.  Use an exponential distribution
149    # in this range 'cuz its easy.
150    radius = 10**np.random.uniform(1.3, 4)
151    d_factor = 10**np.random.uniform(-2, -0.7)  # sigma_d in 0.01-0.7
152    dnn_fraction = np.random.beta(a=10, b=1)
153    dnn = radius*4/np.sqrt(3)/dnn_fraction
154    pars = dict(
155        #sld=1, sld_solvent=0, scale=1, background=1e-32,
156        dnn=dnn,
157        d_factor=d_factor,
158        radius=radius,
159    )
160    return pars
161
162# april 6 2017, rkh add unit tests, NOT compared with any other calc method, assume correct!
163# add 2d test later
164# TODO: fix the 2d tests
165q = 4.*pi/220.
166tests = [
167    [{}, [0.001, q, 0.215268], [1.46601394721, 2.85851284174, 0.00866710287078]],
168    #[{'theta': 20.0, 'phi': 30, 'psi': 40.0}, (-0.017, 0.035), 2082.20264399],
169    #[{'theta': 20.0, 'phi': 30, 'psi': 40.0}, (-0.081, 0.011), 0.436323144781],
170    ]
Note: See TracBrowser for help on using the repository browser.