Index: doc/developer/overview.rst
===================================================================
--- doc/developer/overview.rst	(revision 870a2f45e993d96ff75196552953ec259f2ba197)
+++ doc/developer/overview.rst	(revision da5536f0d03ab140552048df710e20a4d61bef14)
@@ -166,4 +166,51 @@
 :ref:`Calculator_Interface`
 
+Orientation and Numerical Integration
+-------------------------------------
+
+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).
+
+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
+these two oriented cylinders here should be equivalent.
+
+:mod:`\./sascomp -2d cylinder theta=0 phi=0,90 theta_pd_type=rectangle phi_pd_type=rectangle phi_pd=10,1 theta_pd=1,10 length=500 radius=10`
+
 
 Testing
Index: doc/guide/index.rst
===================================================================
--- doc/guide/index.rst	(revision c0d7ab32b1b507381b7c5005d1a655606a8753a9)
+++ doc/guide/index.rst	(revision da5536f0d03ab140552048df710e20a4d61bef14)
@@ -13,4 +13,5 @@
    resolution.rst
    magnetism/magnetism.rst
+   orientation/orientation.rst
    sesans/sans_to_sesans.rst
    sesans/sesans_fitting.rst
Index: doc/guide/orientation/orientation.rst
===================================================================
--- doc/guide/orientation/orientation.rst	(revision da5536f0d03ab140552048df710e20a4d61bef14)
+++ doc/guide/orientation/orientation.rst	(revision da5536f0d03ab140552048df710e20a4d61bef14)
@@ -0,0 +1,62 @@
+.. _orientation:
+
+Oriented particles
+==================
+
+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.
+
+.. 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.
+
+.. 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.
+
+.. figure::
+    orient_img/elliptical_cylinder_angle_projection.png
+
+    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.
+
+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.
+
+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.
+
+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.
+    
+*Document History*
+
+| 2017-10-27 Richard Heenan 
