-                      reda8b30
+                      re964ab1
 -------------------------------------
+For 2d data from oriented anisotropic particles, the mean particle orientation is defined by angles $\theta$, $\phi$ and $\Psi$, which
+are not in general the same as similarly named angles in many form factors. The wikipedia page on Euler angles
+(https://en.wikipedia.org/wiki/Euler_angles) lists the different conventions available. To quote: "Different authors may use different
+sets of rotation axes to define Euler angles, or different names for the same angles. Therefore, any discussion employing Euler angles
+For 2d data from oriented anisotropic particles, the mean particle
+orientation is defined by angles $\theta$, $\phi$ and $\Psi$, which are not
+in general the same as similarly named angles in many form factors. The
+wikipedia page on Euler angles (https://en.wikipedia.org/wiki/Euler_angles)
+lists the different conventions available. To quote: "Different authors may
+use different sets of rotation axes to define Euler angles, or different
+names for the same angles. Therefore, any discussion employing Euler angles
 should always be preceded by their definition."
+We are using the z-y-z convention with extrinsic rotations $\Psi-\theta-\phi$ for the particle orientation and $x-y-z$ convention with
+extrinsic rotations $\psi-\theta-\phi$ for jitter, with jitter applied before particle orientation.
+For numerical integration within form factors etc. sasmodels is mostly using Gaussian quadrature with 20, 76 or 150 points depending on
+the model.  It also makes use of symmetries such as calculating only over one quadrant rather than the whole sphere.  There is often a
+U-substitution replacing $\theta$ with $cos(\theta)$ which changes the limits of integration from 0 to $\pi/2$ to 0 to 1 and also conveniently
+absorbs the $sin(\theta)$ scale factor in the integration.  This can cause confusion if checking equations to say include in a paper or thesis!
+Most models use the same core kernel code expressed in terms of the rotated view (qa, qb, qc) for both the 1D and the 2D models, but there
+are also historical quirks such as the parallelepiped model, which has a useless transformation representing j0(a qa) as j0(b qa a/b).
+We are using the z-y-z convention with extrinsic rotations $\Psi-\theta-\phi$
+for the particle orientation and $x-y-z$ convention with extrinsic rotations
+$\psi-\theta-\phi$ for jitter, with jitter applied before particle
+orientation.
+For numerical integration within form factors etc. sasmodels is mostly using
+Gaussian quadrature with 20, 76 or 150 points depending on the model. It also
+makes use of symmetries such as calculating only over one quadrant rather
+than the whole sphere. There is often a U-substitution replacing $\theta$
+with $cos(\theta)$ which changes the limits of integration from 0 to $\pi/2$
+to 0 to 1 and also conveniently absorbs the $sin(\theta)$ scale factor in the
+integration. This can cause confusion if checking equations to say include in
+a paper or thesis! Most models use the same core kernel code expressed in
+terms of the rotated view (qa, qb, qc) for both the 1D and the 2D models, but
+there are also historical quirks such as the parallelepiped model, which has
+a useless transformation representing j0(a qa) as j0(b qa a/b).
 Useful testing routines include -
+:mod:`asymint` a direct implementation of the surface integral for certain models to get a more trusted value for the 1D integral using a reimplementation of the 2D kernel in python and mpmath
+(which computes math functions to arbitrary precision). It uses $\theta$ ranging from 0 to $\pi$ and $\phi$ ranging from 0 to $2\pi$.  It perhaps would benefit
+from including the U-substitution for theta.
+:mod:`check1d` uses sasmodels 1D integration and compares that with a rectangle distribution in $\theta$ and $\phi$, with $\theta$ limits set to
+$\pm90/\sqrt(3)$ and $\phi$ limits set to $\pm180/\sqrt(3)$
+[The rectangle weight function uses the fact that the distribution width column is labelled sigma to decide
+that the 1-sigma width of a rectangular distribution needs to be multiplied by $\sqrt(3)$ to get the corresponding gaussian equivalent,
+or similar reasoning.]  This should rotate the sample through the entire $\theta-\phi$
+surface according to the pattern that you see in jitter.py when you modify it to use 'rectangle' rather than 'gaussian' for its distribution
+without changing the viewing angle. When computing the dispersity integral, weights are scaled by abs(cos(dtheta)) to account for the points in
+phi getting closer together as dtheta increases.  This integrated dispersion is computed at a set of $(qx, qy)$ points $(q cos(\alpha), q sin(\alpha))$
+at some angle $\alpha$ (currently angle=0) for each q used in the 1-D integration.  The individual q points should be equivalent to asymint rect-n
+when the viewing angle is set to (theta,phi,psi) = (90, 0, 0). Such tests can help to validate that 2d intensity is consistent with 1d models.
+:mod:`sascomp -sphere=n` uses the identical rectangular distribution to compute the pattern of the qx-qy grid.  You can see from triaxial_ellipsoid
+that there may be something wrong conceptually since the pattern is no longer circular when the view (theta,phi,psi) is not (90, phi, 0).
+check1d shows that it is different from the sasmodels 1D integral even when at theta=0, psi=0. Cross checking the values with asymint,
+the sasmodels 1D integral is better at low q, though for very large structures there are not enough points in the integration for sasmodels 1D
+to compute the high q 1D integral correctly. [Some of that may now be fixed?]
+The :mod:`sascomp` utility can be used for 2d as well as 1d calculations to compare results for two sets of parameters or processor types, for example
+:mod:`asymint` a direct implementation of the surface integral for certain
+models to get a more trusted value for the 1D integral using a
+reimplementation of the 2D kernel in python and mpmath (which computes math
+functions to arbitrary precision). It uses $\theta$ ranging from 0 to $\pi$
+and $\phi$ ranging from 0 to $2\pi$. It perhaps would benefit from including
+the U-substitution for theta.
+:mod:`check1d` uses sasmodels 1D integration and compares that with a
+rectangle distribution in $\theta$ and $\phi$, with $\theta$ limits set to
+$\pm90/\sqrt(3)$ and $\phi$ limits set to $\pm180/\sqrt(3)$ [The rectangle
+weight function uses the fact that the distribution width column is labelled
+sigma to decide that the 1-sigma width of a rectangular distribution needs to
+be multiplied by $\sqrt(3)$ to get the corresponding gaussian equivalent, or
+similar reasoning.] This should rotate the sample through the entire
+$\theta-\phi$ surface according to the pattern that you see in jitter.py when
+you modify it to use 'rectangle' rather than 'gaussian' for its distribution
+without changing the viewing angle. When computing the dispersity integral,
+weights are scaled by abs(cos(dtheta)) to account for the points in phi
+getting closer together as dtheta increases. This integrated dispersion is
+computed at a set of $(qx, qy)$ points $(q cos(\alpha), q sin(\alpha))$ at
+some angle $\alpha$ (currently angle=0) for each q used in the 1-D
+integration. The individual q points should be equivalent to asymint rect-n
+when the viewing angle is set to (theta,phi,psi) = (90, 0, 0). Such tests can
+help to validate that 2d intensity is consistent with 1d models.
+:mod:`sascomp -sphere=n` uses the identical rectangular distribution to
+compute the pattern of the qx-qy grid. You can see from triaxial_ellipsoid
+that there may be something wrong conceptually since the pattern is no longer
+circular when the view (theta,phi,psi) is not (90, phi, 0). check1d shows
+that it is different from the sasmodels 1D integral even when at theta=0,
+psi=0. Cross checking the values with asymint, the sasmodels 1D integral is
+better at low q, though for very large structures there are not enough points
+in the integration for sasmodels 1D to compute the high q 1D integral
+correctly. [Some of that may now be fixed?]
+The :mod:`sascomp` utility can be used for 2d as well as 1d calculations to
+compare results for two sets of parameters or processor types, for example
 these two oriented cylinders here should be equivalent.

doc/guide/orientation/orientation.rst

-                      reda8b30
+                      re964ab1
 ==================
+With two dimensional small angle diffraction data SasView will calculate scattering from
+oriented particles, applicable for example to shear flow or orientation in a magnetic field.
+With two dimensional small angle diffraction data SasView will calculate
+scattering from oriented particles, applicable for example to shear flow
+or orientation in a magnetic field.
+In general we first need to define the mean, or a reference orientation of the particles with respect
+to the incoming neutron or X-ray beam. This is done using three angles: $\theta$ and $\phi$ define the
+orientation of the axis of the particle, angle $\Psi$ is defined as the orientation of the major
+axis of the particle cross section with respect to its starting position along the beam direction.
+The figures below are for an elliptical cross section cylinder,
+but may be applied analogously to other shapes of particle.
+In general we first need to define the mean, or a reference orientation
+of the particles with respect to the incoming neutron or X-ray beam. This
+is done using three angles: $\theta$ and $\phi$ define the orientation of
+the axis of the particle, angle $\Psi$ is defined as the orientation of
+the major axis of the particle cross section with respect to its starting
+position along the beam direction. The figures below are for an elliptical
+cross section cylinder, but may be applied analogously to other shapes of
+particle.
 .. note::
+    It is very important to note that these angles, in particular $\theta$ and $\phi$, are NOT in general
+    the same as the $\theta$ and $\phi$ appearing in equations for the scattering form factor which gives
+    the scattered intensity or indeed in the equation for scattering vector $Q$.
+    The $\theta$ rotation must be applied before the $\phi$ rotation, else there is an ambiguity.
+    It is very important to note that these angles, in particular $\theta$
+    and $\phi$, are NOT in general the same as the $\theta$ and $\phi$
+    appearing in equations for the scattering form factor which gives the
+    scattered intensity or indeed in the equation for scattering vector $Q$.
+    The $\theta$ rotation must be applied before the $\phi$ rotation, else
+    there is an ambiguity.
 .. figure::
     orient_img/elliptical_cylinder_angle_definition.png
+    Definition of angles for oriented elliptical cylinder, where axis_ratio b/a is shown >1,
+    Note that rotation $\theta$, initially in the $xz$ plane, is carried out first, then
+    rotation $\phi$ about the $z$ axis, finally rotation $\Psi$ is around the axis of the cylinder.
+    The neutron or X-ray beam is along the $z$ axis.
+    Definition of angles for oriented elliptical cylinder, where axis_ratio
+    b/a is shown >1, Note that rotation $\theta$, initially in the $xz$
+    plane, is carried out first, then rotation $\phi$ about the $z$ axis,
+    finally rotation $\Psi$ is around the axis of the cylinder. The neutron
+    or X-ray beam is along the $z$ axis.
 .. figure::
     orient_img/elliptical_cylinder_angle_projection.png
+    Some examples of the orientation angles for an elliptical cylinder, with $\Psi$ = 0.
+    Some examples of the orientation angles for an elliptical cylinder,
+    with $\Psi$ = 0.
+Having established the mean direction of the particle we can then apply angular orientation distributions.
+This is done by a numerical integration over a range of angles in a similar way to polydispersity for particle size.
+In the current version of sasview the orientational dispersity is defined with respect to the axes of the particle.
+Having established the mean direction of the particle we can then apply
+angular orientation distributions. This is done by a numerical integration
+over a range of angles in a similar way to polydispersity for particle size.
+In the current version of sasview the orientational dispersity is defined
+with respect to the axes of the particle.
+The $\theta$ and $\phi$ parameters to orient the cylinder only appear in the model when fitting 2d data.
+On introducing "Orientational Distribution" in the angles, "distribution of theta" and "distribution of phi" parameters will
+appear. These are actually rotations about the axes $\delta_1$ and $\delta_2$ of the cylinder, the $b$ and $a$ axes of the
+cylinder cross section. (When $\theta = \phi = 0$ these are parallel to the $Y$ and $X$ axes of the instrument.)
+The third orientation distribution, in $\psi$, is about the $c$ axis of the particle. Some experimentation may be required to
+understand the 2d patterns fully. A number of different shapes of distribution are available, as described for
+polydispersity, see :ref:`polydispersityhelp` .
+The $\theta$ and $\phi$ parameters to orient the cylinder only appear in the
+model when fitting 2d data. On introducing "Orientational Distribution" in
+the angles, "distribution of theta" and "distribution of phi" parameters will
+appear. These are actually rotations about the axes $\delta_1$ and $\delta_2$
+of the cylinder, the $b$ and $a$ axes of the cylinder cross section. (When
+$\theta = \phi = 0$ these are parallel to the $Y$ and $X$ axes of the
+instrument.) The third orientation distribution, in $\psi$, is about the $c$
+axis of the particle. Some experimentation may be required to understand the
+d patterns fully. A number of different shapes of distribution are
+available, as described for polydispersity, see :ref:`polydispersityhelp` .
+Earlier versions of SasView had numerical integration issues in some circumstances when
+distributions passed through 90 degrees. The distributions in particle coordinates are more robust, but should still be approached
+with care for large ranges of angle.
+Earlier versions of SasView had numerical integration issues in some
+circumstances when distributions passed through 90 degrees. The distributions
+in particle coordinates are more robust, but should still be approached with
+care for large ranges of angle.
+Note that the form factors for asymmetric particles are also performing numerical integrations over one or more variables, so
+care should be taken, especially with very large particles or more extreme aspect ratios. Users can experiment with the
+values of Npts and Nsigs, the number of steps used in the integration and the range spanned in number of standard deviations.
+The standard deviation is entered in units of degrees. For a rectangular (uniform) distribution the full width
+should be $\pm\sqrt(3)$ ~ 1.73 standard deviations (this may be changed soon).
+Note that the form factors for asymmetric particles are also performing
+numerical integrations over one or more variables, so care should be taken,
+especially with very large particles or more extreme aspect ratios. Users can
+experiment with the values of Npts and Nsigs, the number of steps used in the
+integration and the range spanned in number of standard deviations. The
+standard deviation is entered in units of degrees. For a rectangular
+(uniform) distribution the full width should be $\pm\sqrt(3)$ ~ 1.73 standard
+deviations (this may be changed soon).
+Where appropriate, for best numerical results, keep $a < b < c$ and the $\theta$ distribution narrower than the $\phi$ distribution.
+Where appropriate, for best numerical results, keep $a < b < c$ and the
+$\theta$ distribution narrower than the $\phi$ distribution.
+Some more detailed technical notes are provided in the developer section of this manual :ref:`orientation_developer` .
+Some more detailed technical notes are provided in the developer section of
+this manual :ref:`orientation_developer` .
 *Document History*
 | 2017-10-27 Richard Heenan
+| 2017-10-27 Richard Heenan

Note: See TracChangeset for help on using the changeset viewer.

SasView

Changeset e964ab1 in sasmodels for doc

Legend:

doc/developer/overview.rst

doc/guide/orientation/orientation.rst

Download in other formats: