Changeset da5536f in sasmodels for doc/developer

Timestamp:

Oct 27, 2017 12:11:24 PM (7 years ago)

Author:

richardh

Branches:

master, core_shell_microgels, magnetic_model, ticket-1257-vesicle-product, ticket_1156, ticket_1265_superball, ticket_822_more_unit_tests

Children:

eda8b30

Parents:

767dca8

Message:

new chapters in main user and developed docs for Orientation

File:

• doc/developer/overview.rst (modified) (1 diff)

doc/developer/overview.rst

@@ -166 +166 @@
 :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