Changeset da5536f in sasmodels for doc/developer


Ignore:
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:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/developer/overview.rst

    r870a2f4 rda5536f  
    166166:ref:`Calculator_Interface` 
    167167 
     168Orientation and Numerical Integration 
     169------------------------------------- 
     170 
     171For 2d data from oriented anisotropic particles, the mean particle orientation is defined by angles $\theta$, $\phi$ and $\Psi$, which 
     172are not in general the same as similarly named angles in many form factors. The wikipedia page on Euler angles  
     173(https://en.wikipedia.org/wiki/Euler_angles) lists the different conventions available. To quote: "Different authors may use different  
     174sets of rotation axes to define Euler angles, or different names for the same angles. Therefore, any discussion employing Euler angles 
     175should always be preceded by their definition." 
     176 
     177We are using the z-y-z convention with extrinsic rotations $\Psi-\theta-\phi$ for the particle orientation and $x-y-z$ convention with  
     178extrinsic rotations $\psi-\theta-\phi$ for jitter, with jitter applied before particle orientation. 
     179 
     180For numerical integration within form factors etc. sasmodels is mostly using Gaussian quadrature with 20, 76 or 150 points depending on  
     181the model.  It also makes use of symmetries such as calculating only over one quadrant rather than the whole sphere.  There is often a  
     182U-substitution replacing $\theta$ with $cos(\theta)$ which changes the limits of integration from 0 to $\pi/2$ to 0 to 1 and also conveniently  
     183absorbs the $sin(\theta)$ scale factor in the integration.  This can cause confusion if checking equations to say include in a paper or thesis! 
     184Most 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  
     185are also historical quirks such as the parallelepiped model, which has a useless transformation representing j0(a qa) as j0(b qa a/b). 
     186 
     187Useful testing routines include - 
     188 
     189: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  
     190(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 
     191from including the U-substitution for theta. 
     192 
     193:mod:`check1d` uses sasmodels 1D integration and compares that with a rectangle distribution in $\theta$ and $\phi$, with $\theta$ limits set to 
     194$\pm90/\sqrt(3)$ and $\phi$ limits set to $\pm180/\sqrt(3)$   
     195[The rectangle weight function uses the fact that the distribution width column is labelled sigma to decide  
     196that the 1-sigma width of a rectangular distribution needs to be multiplied by $\sqrt(3)$ to get the corresponding gaussian equivalent,  
     197or similar reasoning.]  This should rotate the sample through the entire $\theta-\phi$  
     198surface according to the pattern that you see in jitter.py when you modify it to use 'rectangle' rather than 'gaussian' for its distribution  
     199without changing the viewing angle. When computing the dispersity integral, weights are scaled by abs(cos(dtheta)) to account for the points in  
     200phi getting closer together as dtheta increases.  This integrated dispersion is computed at a set of $(qx, qy)$ points $(q cos(\alpha), q sin(\alpha))$  
     201at 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  
     202when 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. 
     203  
     204:mod:`sascomp -sphere=n` uses the identical rectangular distribution to compute the pattern of the qx-qy grid.  You can see from triaxial_ellipsoid 
     205that there may be something wrong conceptually since the pattern is no longer circular when the view (theta,phi,psi) is not (90, phi, 0).   
     206check1d shows that it is different from the sasmodels 1D integral even when at theta=0, psi=0. Cross checking the values with asymint,  
     207the sasmodels 1D integral is better at low q, though for very large structures there are not enough points in the integration for sasmodels 1D  
     208to compute the high q 1D integral correctly. [Some of that may now be fixed?] 
     209 
     210The :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 
     211these two oriented cylinders here should be equivalent. 
     212 
     213: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` 
     214 
    168215 
    169216Testing 
Note: See TracChangeset for help on using the changeset viewer.