Changeset 3d40839 in sasmodels for doc

Timestamp:

Oct 28, 2017 9:28:22 PM (7 years ago)

Author:

Paul Kienzle <pkienzle@…>

Branches:

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

Children:

0db85af

Parents:

e964ab1

Message:

update orientation docs

Location:

doc

Files:

• _extensions/dollarmath.py (modified) (1 diff)
• developer/overview.rst (modified) (3 diffs)
• guide/orientation/orientation.rst (modified) (4 diffs)

doc/_extensions/dollarmath.py

@@ -12 +12 @@
 import re
 
-_dollar = re.compile(r"(?:^|(?<=\s|[(]))[$]([^\n]*?)(?<![\\])[$](?:$|(?=\s|[.,;)\\]))")
+_dollar = re.compile(r"(?:^|(?<=\s|[-(]))[$]([^\n]*?)(?<![\\])[$](?:$|(?=\s|[-.,;)\\]))")
 _notdollar = re.compile(r"\\[$]")
 

doc/developer/overview.rst

@@ -180 +180 @@
 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.
+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
@@ -191 +191 @@
 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 -
+integration. This can cause confusion if checking equations to include in a
+paper or thesis! Most models use the same core kernel code expressed in terms
+of the rotated view ($q_a$, $q_b$, $q_c$) 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 $j_0(a q_a)$ as $j_0(b q_a a/b)$.
+
+Useful testing routines include:
 
 :mod:`asymint` a direct implementation of the surface integral for certain
@@ -204 +204 @@
 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.
+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
+$\pm 90/\sqrt(3)$ and $\phi$ limits set to $\pm 180/\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
+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
+$\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?]
+without changing the viewing angle. In order to match the 1-D pattern for
+an arbitrary viewing angle on triaxial shapes, we need to integrate
+over $\theta$, $\phi$ and $\Psi$.
+
+When computing the dispersity integral, weights are scaled by
+$|\cos(\delta \theta)|$ to account for the points in $\phi$ getting closer
+together as $\delta \theta$ increases.
+[This will probably change so that instead of adjusting the weights, we will
+adjust $\delta\theta$-$\delta\phi$ mesh so that the point density in
+$\delta\phi$ is lower at larger $\delta\theta$. The flag USE_SCALED_PHI in
+*kernel_iq.c* selects an alternative algorithm.]
+
+The 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
+models are consistent with 1d models.
+
+:mod:`sascomp -sphere=n` uses the same rectangular distribution as check1d to
+compute the pattern of the $q_x$-$q_y$ grid.
 
 The :mod:`sascomp` utility can be used for 2d as well as 1d calculations to

doc/guide/orientation/orientation.rst

@@ -8 +8 @@
 or orientation in a magnetic field.
 
-In general we first need to define the mean, or a reference orientation
+In general we first need to define the 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
@@ -29 +29 @@
 
     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,
+    b/a is shown >1, Note that rotation $\theta$, initially in the $x$-$z$
+    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.
@@ -42 +42 @@
 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.
+over a range of angles in a similar way to particle size dispersity.
 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 $\theta$ and $\phi$ orientation parameters for the cylinder only appear
+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$
+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
@@ -65 +65 @@
 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
+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
+(uniform) distribution the full width should be $\pm \sqrt(3)$ ~ 1.73 standard
 deviations (this may be changed soon).