Changeset 7e6bc45e in sasmodels for doc/guide/orientation
- Timestamp:
- Dec 20, 2017 2:33:39 PM (7 years ago)
- Branches:
- master, core_shell_microgels, magnetic_model, ticket-1257-vesicle-product, ticket_1156, ticket_1265_superball, ticket_822_more_unit_tests
- Children:
- 06ee63c
- Parents:
- 93fbc34
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
doc/guide/orientation/orientation.rst
r82592da r7e6bc45e 4 4 ================== 5 5 6 With two dimensional small angle diffraction data SasViewwill calculate6 With two dimensional small angle diffraction data sasmodels will calculate 7 7 scattering from oriented particles, applicable for example to shear flow 8 8 or orientation in a magnetic field. 9 9 10 10 In general we first need to define the reference orientation 11 of the particles with respect to the incoming neutron or X-ray beam. This 12 is done using three angles: $\theta$ and $\phi$ define the orientation of 13 the axis of the particle, angle $\Psi$ is defined as the orientation of 14 the major axis of the particle cross section with respect to its starting 15 position along the beam direction. The figures below are for an elliptical 16 cross section cylinder, but may be applied analogously to other shapes of 17 particle. 11 of the particle's $a$-$b$-$c$ axes with respect to the incoming 12 neutron or X-ray beam. This is done using three angles: $\theta$ and $\phi$ 13 define the orientation of the $c$-axis of the particle, and angle $\Psi$ is 14 defined as the orientation of the major axis of the particle cross section 15 with respect to its starting position along the beam direction (or 16 equivalently, as rotation about the $c$ axis). There is an unavoidable 17 ambiguity when $c$ is aligned with $z$ in that $\phi$ and $\Psi$ both 18 serve to rotate the particle about $c$, but this symmetry is destroyed 19 when $\theta$ is not a multiple of 180. 20 21 The figures below are for an elliptical cross section cylinder, but may 22 be applied analogously to other shapes of particle. 18 23 19 24 .. note:: … … 29 34 30 35 Definition of angles for oriented elliptical cylinder, where axis_ratio 31 b/a is shown >1 ,Note that rotation $\theta$, initially in the $x$-$z$36 b/a is shown >1. Note that rotation $\theta$, initially in the $x$-$z$ 32 37 plane, is carried out first, then rotation $\phi$ about the $z$-axis, 33 38 finally rotation $\Psi$ is around the axis of the cylinder. The neutron 34 or X-ray beam is along the $ z$ axis.39 or X-ray beam is along the $-z$ axis. 35 40 36 41 .. figure:: … … 40 45 with $\Psi$ = 0. 41 46 42 Having established the mean direction of the particle we can then apply 43 angular orientation distributions. This is done by a numerical integration 44 over a range of angles in a similar way to particle size dispersity. 45 In the current version of sasview the orientational dispersity is defined 46 with respect to the axes of the particle. 47 Having established the mean direction of the particle (the view) we can then 48 apply angular orientation distributions (jitter). This is done by a numerical 49 integration over a range of angles in a similar way to particle size 50 dispersity. The orientation dispersity is defined with respect to the 51 $a$-$b$-$c$ axes of the particle, with roll angle $\Psi$ about the $c$-axis, 52 yaw angle $\theta$ about the $b$-axis and pitch angle $\phi$ about the 53 $a$-axis. 54 55 More formally, starting with axes $a$-$b$-$c$ of the particle aligned 56 with axes $x$-$y$-$z$ of the laboratory frame, the orientation dispersity 57 is applied first, using the 58 `Tait-Bryan <https://en.wikipedia.org/wiki/Euler_angles#Conventions_2>`_ 59 $x$-$y'$-$z''$ convention with angles $\Delta\phi$-$\Delta\theta$-$\Delta\Psi$. 60 The reference orientation then follows, using the 61 `Euler angles <https://en.wikipedia.org/wiki/Euler_angles#Conventions>`_ 62 $z$-$y'$-$z''$ with angles $\phi$-$\theta$-$\Psi$. This is implemented 63 using rotation matrices as 64 65 .. math:: 66 67 R = R_z(\phi)\, R_y(\theta)\, R_z(\Psi)\, 68 R_x(\Delta\phi)\, R_y(\Delta\theta)\, R_z(\Delta\Psi) 69 70 To transform detector $(q_x, q_y)$ values into $(q_a, q_b, q_c)$ for the 71 shape in its canonical orientation, use 72 73 .. math:: 74 75 [q_a, q_b, q_c]^T = R^{-1} \, [q_x, q_y, 0]^T 76 77 78 The inverse rotation is easily calculated by rotating the opposite directions 79 in the reverse order, so 80 81 .. math:: 82 83 R^{-1} = R_z(-\Delta\Psi)\, R_y(-\Delta\theta)\, R_x(-\Delta\phi)\, 84 R_z(-\Psi)\, R_y(-\theta)\, R_z(-\phi) 85 47 86 48 87 The $\theta$ and $\phi$ orientation parameters for the cylinder only appear 49 when fitting 2d data. On introducing "Orientation al Distribution" in50 theangles, "distribution of theta" and "distribution of phi" parameters will88 when fitting 2d data. On introducing "Orientation Distribution" in the 89 angles, "distribution of theta" and "distribution of phi" parameters will 51 90 appear. These are actually rotations about the axes $\delta_1$ and $\delta_2$ 52 of the cylinder, the $b$ and $a$ axes of the cylinder cross section. (When 53 $\theta = \phi = 0$ these are parallel to the $Y$ and $X$ axes of the 54 instrument.) The third orientation distribution, in $\Psi$, is about the $c$ 55 axis of the particle. Some experimentation may be required to understand the 56 2d patterns fully. A number of different shapes of distribution are 57 available, as described for polydispersity, see :ref:`polydispersityhelp` . 91 of the cylinder, which correspond to the $b$ and $a$ axes of the cylinder 92 cross section. (When $\theta = \phi = 0$ these are parallel to the $Y$ and 93 $X$ axes of the instrument.) The third orientation distribution, in $\Psi$, 94 is about the $c$ axis of the particle. Some experimentation may be required 95 to understand the 2d patterns fully. A number of different shapes of 96 distribution are available, as described for size dispersity, see 97 :ref:`polydispersityhelp`. 58 98 59 Earlier versions of SasView had numerical integration issues in some 60 circumstances when distributions passed through 90 degrees. The distributions 61 in particle coordinates are more robust, but should still be approached with 62 care for large ranges of angle. 99 Given that the angular dispersion distribution is defined in cartesian space, 100 over a cube defined by 101 102 .. math:: 103 104 [-\Delta \theta, \Delta \theta] \times 105 [-\Delta \phi, \Delta \phi] \times 106 [-\Delta \Psi, \Delta \Psi] 107 108 but the orientation is defined over a sphere, we are left with a 109 `map projection <https://en.wikipedia.org/wiki/List_of_map_projections>`_ 110 problem, with different tradeoffs depending on how values in $\Delta\theta$ 111 and $\Delta\phi$ are translated into latitude/longitude on the sphere. 112 113 Sasmodels is using the *equirectangular* projection. In this projection, 114 square patches in angular dispersity become wedge-shaped patches on the 115 sphere. To correct for the changing point density, there is a scale factor of 116 $\sin(\Delta\theta)$ that applies to each point in the integral. This is not 117 enough, though. Consider a shape which is tumbling freely around the $b$ 118 axis, with $\Delta\theta$ uniform in $[-180, 180]$. At $\pm 90$, all points 119 in $\Delta\phi$ map to the pole, so the jitter will have a 120 distinct angular preference. If the spin axis is normal to the beam 121 (which will be the case for $\theta=90$ and $\Psi=90$), the scattering 122 pattern should be circularly symmetric, but it will go to zero at $\pm 90$ due 123 to the $\sin(\Delta\theta)$ correction. This problem does not appear for a shape 124 that is tumbling freely around the $a$ axis, with $\Delta\phi$ uniform in 125 $[-180, 180]$, so swap the $a$ and $b$ axes so $\Delta\theta < \Delta\phi$ 126 and adjust $\Psi$ by 90. This works with the existing sasmodels shapes 127 due to symmetry. 128 129 There are alternative projections. The *sinusoidal* projection works by 130 scaling $\Delta\phi$ as $\Delta\theta$ increases, and dropping those points 131 outside $[-180, 180]$. The distortions are a little less for middle ranges of 132 $\Delta\theta$, but they are still severe for large $\Delta\theta$ and the 133 model is much harder to explain. The *Guyou* projection has an excellent 134 balance with reasonable distortion in both $\Delta\theta$ and $\Delta\phi$, 135 as well as preserving small patches. However, it is considerably more 136 expensive to implement, and we have not yet computed the distortion 137 correction, measuring the degree of stretch at the 138 point $(\Delta\theta, \Delta\phi)$ in the correction. 63 139 64 140 .. note:: 65 Note that the form factors for oriented particles are also performing 66 numerical integrations over one or more variables, so care should be taken, 67 especially with very large particles or more extreme aspect ratios. In such 68 cases results may not be accurate, particularly at very high Q, unless the model 69 has been specifically coded to use limiting forms of the scattering equations. 70 71 For best numerical results keep the $\theta$ distribution narrower than the $\phi$ 72 distribution. Thus for asymmetric particles, such as elliptical_cylinder, you may 73 need to reorder the sizes of the three axes to acheive the desired result. 74 This is due to the issues of mapping a rectangular distribution onto the 75 surface of a sphere. 141 Note that the form factors for oriented particles are performing 142 numerical integrations over one or more variables, so care should be 143 taken, especially with very large particles or more extreme aspect 144 ratios. In such cases results may not be accurate, particularly at very 145 high Q, unless the model has been specifically coded to use limiting 146 forms of the scattering equations. 76 147 77 Users can experiment with the values of *Npts* and *Nsigs*, the number of steps 78 used in the integration and the range spanned in number of standard deviations. 79 The standard deviation is entered in units of degrees. For a "rectangular" 80 distribution the full width should be $\pm \sqrt(3)$ ~ 1.73 standard deviations. 81 The new "uniform" distribution avoids this by letting you directly specify the 148 For best numerical results keep the $\theta$ distribution narrower than 149 the $\phi$ distribution. Thus for asymmetric particles, such as 150 elliptical_cylinder, you may need to reorder the sizes of the three axes 151 to acheive the desired result. This is due to the issues of mapping a 152 rectanglar distribution onto the surface of a sphere. 153 154 Users can experiment with the values of *Npts* and *Nsigs*, the number of steps 155 used in the integration and the range spanned in number of standard deviations. 156 The standard deviation is entered in units of degrees. For a "rectangular" 157 distribution the full width should be $\pm \sqrt(3)$ ~ 1.73 standard deviations. 158 The new "uniform" distribution avoids this by letting you directly specify the 82 159 half width. 83 160 84 The angular distributions will be truncated outside of the range -180 to +18085 degrees, so beware of using saying a broad Gaussian distribution with large value86 of *Nsigs*, as the array of *Npts* may be truncated to many fewer points than would 87 give a good integration,as well as becoming rather meaningless. (At some point 88 in the future the actual polydispersity arrays may be made available to the user 89 for inspection.)161 The angular distributions may be truncated outside of the range -180 to +180 162 degrees, so beware of using saying a broad Gaussian distribution with large 163 value of *Nsigs*, as the array of *Npts* may be truncated to many fewer 164 points than would give a good integration,as well as becoming rather 165 meaningless. (At some point in the future the actual dispersion arrays may be 166 made available to the user for inspection.) 90 167 91 168 Some more detailed technical notes are provided in the developer section of 92 169 this manual :ref:`orientation_developer` . 93 170 171 This definition of orientation is new to SasView 4.2. In earlier versions, 172 the orientation distribution appeared as a distribution of view angles. 173 This led to strange effects when $c$ was aligned with $z$, where changes 174 to the $\phi$ angle served only to rotate the shape about $c$, rather than 175 having a consistent interpretation as the pitch of the shape relative to 176 the flow field defining the reference orientation. Prior to SasView 4.1, 177 the reference orientation was defined using a Tait-Bryan convention, making 178 it difficult to control. Now, rotation in $\theta$ modifies the spacings 179 in the refraction pattern, and rotation in $\phi$ rotates it in the detector 180 plane. 181 182 94 183 *Document History* 95 184 96 185 | 2017-11-06 Richard Heenan 186 | 2017-12-20 Paul Kienzle
Note: See TracChangeset
for help on using the changeset viewer.