Changeset 7e6bc45e in sasmodels


Ignore:
Timestamp:
Dec 20, 2017 2:33:39 PM (3 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:
06ee63c
Parents:
93fbc34
Message:

update orientation docs

Location:
doc/guide
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • doc/guide/orientation/orientation.rst

    r82592da r7e6bc45e  
    44================== 
    55 
    6 With two dimensional small angle diffraction data SasView will calculate 
     6With two dimensional small angle diffraction data sasmodels will calculate 
    77scattering from oriented particles, applicable for example to shear flow 
    88or orientation in a magnetic field. 
    99 
    1010In general we first need to define the reference orientation 
    11 of the particles with respect to the incoming neutron or X-ray beam. This 
    12 is done using three angles: $\theta$ and $\phi$ define the orientation of 
    13 the axis of the particle, angle $\Psi$ is defined as the orientation of 
    14 the major axis of the particle cross section with respect to its starting 
    15 position along the beam direction. The figures below are for an elliptical 
    16 cross section cylinder, but may be applied analogously to other shapes of 
    17 particle. 
     11of the particle's $a$-$b$-$c$ axes with respect to the incoming 
     12neutron or X-ray beam. This is done using three angles: $\theta$ and $\phi$ 
     13define the orientation of the $c$-axis of the particle, and angle $\Psi$ is 
     14defined as the orientation of the major axis of the particle cross section 
     15with respect to its starting position along the beam direction (or 
     16equivalently, as rotation about the $c$ axis). There is an unavoidable 
     17ambiguity when $c$ is aligned with $z$ in that $\phi$ and $\Psi$ both 
     18serve to rotate the particle about $c$, but this symmetry is destroyed 
     19when $\theta$ is not a multiple of 180. 
     20 
     21The figures below are for an elliptical cross section cylinder, but may 
     22be applied analogously to other shapes of particle. 
    1823 
    1924.. note:: 
     
    2934 
    3035    Definition of angles for oriented elliptical cylinder, where axis_ratio 
    31     b/a is shown >1, Note that rotation $\theta$, initially in the $x$-$z$ 
     36    b/a is shown >1. Note that rotation $\theta$, initially in the $x$-$z$ 
    3237    plane, is carried out first, then rotation $\phi$ about the $z$-axis, 
    3338    finally rotation $\Psi$ is around the axis of the cylinder. The neutron 
    34     or X-ray beam is along the $z$ axis. 
     39    or X-ray beam is along the $-z$ axis. 
    3540 
    3641.. figure:: 
     
    4045    with $\Psi$ = 0. 
    4146 
    42 Having established the mean direction of the particle we can then apply 
    43 angular orientation distributions. This is done by a numerical integration 
    44 over a range of angles in a similar way to particle size dispersity. 
    45 In the current version of sasview the orientational dispersity is defined 
    46 with respect to the axes of the particle. 
     47Having established the mean direction of the particle (the view) we can then 
     48apply angular orientation distributions (jitter). This is done by a numerical 
     49integration over a range of angles in a similar way to particle size 
     50dispersity. The orientation dispersity is defined with respect to the 
     51$a$-$b$-$c$ axes of the particle, with roll angle $\Psi$ about the $c$-axis, 
     52yaw angle $\theta$ about the $b$-axis and pitch angle $\phi$ about the 
     53$a$-axis. 
     54 
     55More formally, starting with axes $a$-$b$-$c$ of the particle aligned 
     56with axes $x$-$y$-$z$ of the laboratory frame, the orientation dispersity 
     57is applied first, using the 
     58`Tait-Bryan <https://en.wikipedia.org/wiki/Euler_angles#Conventions_2>`_ 
     59$x$-$y'$-$z''$ convention with angles $\Delta\phi$-$\Delta\theta$-$\Delta\Psi$. 
     60The reference orientation then follows, using the 
     61`Euler angles <https://en.wikipedia.org/wiki/Euler_angles#Conventions>`_ 
     62$z$-$y'$-$z''$ with angles $\phi$-$\theta$-$\Psi$.  This is implemented 
     63using rotation matrices as 
     64 
     65.. math:: 
     66 
     67    R = R_z(\phi)\, R_y(\theta)\, R_z(\Psi)\, 
     68        R_x(\Delta\phi)\, R_y(\Delta\theta)\, R_z(\Delta\Psi) 
     69 
     70To transform detector $(q_x, q_y)$ values into $(q_a, q_b, q_c)$ for the 
     71shape in its canonical orientation, use 
     72 
     73.. math:: 
     74 
     75    [q_a, q_b, q_c]^T = R^{-1} \, [q_x, q_y, 0]^T 
     76 
     77 
     78The inverse rotation is easily calculated by rotating the opposite directions 
     79in the reverse order, so 
     80 
     81.. math:: 
     82 
     83    R^{-1} = R_z(-\Delta\Psi)\, R_y(-\Delta\theta)\, R_x(-\Delta\phi)\, 
     84             R_z(-\Psi)\, R_y(-\theta)\, R_z(-\phi) 
     85 
    4786 
    4887The $\theta$ and $\phi$ orientation parameters for the cylinder only appear 
    49 when fitting 2d data. On introducing "Orientational Distribution" in 
    50 the angles, "distribution of theta" and "distribution of phi" parameters will 
     88when fitting 2d data. On introducing "Orientation Distribution" in the 
     89angles, "distribution of theta" and "distribution of phi" parameters will 
    5190appear. These are actually rotations about the axes $\delta_1$ and $\delta_2$ 
    52 of the cylinder, the $b$ and $a$ axes of the cylinder cross section. (When 
    53 $\theta = \phi = 0$ these are parallel to the $Y$ and $X$ axes of the 
    54 instrument.) The third orientation distribution, in $\Psi$, is about the $c$ 
    55 axis of the particle. Some experimentation may be required to understand the 
    56 2d patterns fully. A number of different shapes of distribution are 
    57 available, as described for polydispersity, see :ref:`polydispersityhelp` . 
     91of the cylinder, which correspond to the $b$ and $a$ axes of the cylinder 
     92cross section. (When $\theta = \phi = 0$ these are parallel to the $Y$ and 
     93$X$ axes of the instrument.) The third orientation distribution, in $\Psi$, 
     94is about the $c$ axis of the particle. Some experimentation may be required 
     95to understand the 2d patterns fully. A number of different shapes of 
     96distribution are available, as described for size dispersity, see 
     97:ref:`polydispersityhelp`. 
    5898 
    59 Earlier versions of SasView had numerical integration issues in some 
    60 circumstances when distributions passed through 90 degrees. The distributions 
    61 in particle coordinates are more robust, but should still be approached with 
    62 care for large ranges of angle. 
     99Given that the angular dispersion distribution is defined in cartesian space, 
     100over a cube defined by 
     101 
     102.. math:: 
     103 
     104    [-\Delta \theta, \Delta \theta] \times 
     105    [-\Delta \phi, \Delta \phi] \times 
     106    [-\Delta \Psi, \Delta \Psi] 
     107 
     108but the orientation is defined over a sphere, we are left with a 
     109`map projection <https://en.wikipedia.org/wiki/List_of_map_projections>`_ 
     110problem, with different tradeoffs depending on how values in $\Delta\theta$ 
     111and $\Delta\phi$ are translated into latitude/longitude on the sphere. 
     112 
     113Sasmodels is using the *equirectangular* projection. In this projection, 
     114square patches in angular dispersity become wedge-shaped patches on the 
     115sphere. To correct for the changing point density, there is a scale factor of 
     116$\sin(\Delta\theta)$ that applies to each point in the integral. This is not 
     117enough, though. Consider a shape which is tumbling freely around the $b$ 
     118axis, with $\Delta\theta$ uniform in $[-180, 180]$. At $\pm 90$, all points 
     119in $\Delta\phi$ map to the pole, so the jitter will have a 
     120distinct angular preference. If the spin axis is normal to the beam 
     121(which will be the case for $\theta=90$ and $\Psi=90$), the scattering 
     122pattern should be circularly symmetric, but it will go to zero at $\pm 90$ due 
     123to the $\sin(\Delta\theta)$ correction. This problem does not appear for a shape 
     124that is tumbling freely around the $a$ axis, with $\Delta\phi$ uniform in 
     125$[-180, 180]$, so swap the $a$ and $b$ axes so $\Delta\theta < \Delta\phi$ 
     126and adjust $\Psi$ by 90. This works with the existing sasmodels shapes 
     127due to symmetry. 
     128 
     129There are alternative projections. The *sinusoidal* projection works by 
     130scaling $\Delta\phi$ as $\Delta\theta$ increases, and dropping those points 
     131outside $[-180, 180]$. The distortions are a little less for middle ranges of 
     132$\Delta\theta$, but they are still severe for large $\Delta\theta$ and the 
     133model is much harder to explain. The *Guyou* projection has an excellent 
     134balance with reasonable distortion in both $\Delta\theta$ and $\Delta\phi$, 
     135as well as preserving small patches. However, it is considerably more 
     136expensive to implement, and we have not yet computed the distortion 
     137correction, measuring the degree of stretch at the 
     138point $(\Delta\theta, \Delta\phi)$ in the correction. 
    63139 
    64140.. note:: 
    65     Note that the form factors for oriented particles are also performing 
    66     numerical integrations over one or more variables, so care should be taken, 
    67     especially with very large particles or more extreme aspect ratios. In such  
    68     cases results may not be accurate, particularly at very high Q, unless the model 
    69     has been specifically coded to use limiting forms of the scattering equations. 
    70      
    71     For best numerical results keep the $\theta$ distribution narrower than the $\phi$  
    72     distribution. Thus for asymmetric particles, such as elliptical_cylinder, you may  
    73     need to reorder the sizes of the three axes to acheive the desired result.  
    74     This is due to the issues of mapping a rectangular distribution onto the  
    75     surface of a sphere. 
     141    Note that the form factors for oriented particles are performing 
     142    numerical integrations over one or more variables, so care should be 
     143    taken, especially with very large particles or more extreme aspect 
     144    ratios. In such cases results may not be accurate, particularly at very 
     145    high Q, unless the model has been specifically coded to use limiting 
     146    forms of the scattering equations. 
    76147 
    77 Users can experiment with the values of *Npts* and *Nsigs*, the number of steps  
    78 used in the integration and the range spanned in number of standard deviations.  
    79 The standard deviation is entered in units of degrees. For a "rectangular"  
    80 distribution the full width should be $\pm \sqrt(3)$ ~ 1.73 standard deviations.  
    81 The new "uniform" distribution avoids this by letting you directly specify the  
     148    For best numerical results keep the $\theta$ distribution narrower than 
     149    the $\phi$ distribution. Thus for asymmetric particles, such as 
     150    elliptical_cylinder, you may need to reorder the sizes of the three axes 
     151    to acheive the desired result. This is due to the issues of mapping a 
     152    rectanglar distribution onto the surface of a sphere. 
     153 
     154Users can experiment with the values of *Npts* and *Nsigs*, the number of steps 
     155used in the integration and the range spanned in number of standard deviations. 
     156The standard deviation is entered in units of degrees. For a "rectangular" 
     157distribution the full width should be $\pm \sqrt(3)$ ~ 1.73 standard deviations. 
     158The new "uniform" distribution avoids this by letting you directly specify the 
    82159half width. 
    83160 
    84 The angular distributions will be truncated outside of the range -180 to +180  
    85 degrees, so beware of using saying a broad Gaussian distribution with large value 
    86 of *Nsigs*, as the array of *Npts* may be truncated to many fewer points than would  
    87 give a good integration,as well as becoming rather meaningless. (At some point  
    88 in the future the actual polydispersity arrays may be made available to the user  
    89 for inspection.) 
     161The angular distributions may be truncated outside of the range -180 to +180 
     162degrees, so beware of using saying a broad Gaussian distribution with large 
     163value of *Nsigs*, as the array of *Npts* may be truncated to many fewer 
     164points than would give a good integration,as well as becoming rather 
     165meaningless. (At some point in the future the actual dispersion arrays may be 
     166made available to the user for inspection.) 
    90167 
    91168Some more detailed technical notes are provided in the developer section of 
    92169this manual :ref:`orientation_developer` . 
    93170 
     171This definition of orientation is new to SasView 4.2.  In earlier versions, 
     172the orientation distribution appeared as a distribution of view angles. 
     173This led to strange effects when $c$ was aligned with $z$, where changes 
     174to the $\phi$ angle served only to rotate the shape about $c$, rather than 
     175having a consistent interpretation as the pitch of the shape relative to 
     176the flow field defining the reference orientation.  Prior to SasView 4.1, 
     177the reference orientation was defined using a Tait-Bryan convention, making 
     178it difficult to control.  Now, rotation in $\theta$ modifies the spacings 
     179in the refraction pattern, and rotation in $\phi$ rotates it in the detector 
     180plane. 
     181 
     182 
    94183*Document History* 
    95184 
    96185| 2017-11-06 Richard Heenan 
     186| 2017-12-20 Paul Kienzle 
  • doc/guide/plugin.rst

    rc654160 r7e6bc45e  
    538538If the scattering is dependent on the orientation of the shape, then you 
    539539will need to include *orientation* parameters *theta*, *phi* and *psi* 
    540 at the end of the parameter table.  Shape orientation uses *a*, *b* and *c* 
    541 axes, corresponding to the *x*, *y* and *z* axes in the laboratory coordinate 
    542 system, with *z* along the beam and *x*-*y* in the detector plane, with *x* 
    543 horizontal and *y* vertical.  The *psi* parameter rotates the shape 
    544 about its *c* axis, the *theta* parameter then rotates the *c* axis toward 
    545 the *x* axis of the detector, then *phi* rotates the shape in the detector 
    546 plane.  (Prior to these rotations, orientation dispersity will be applied 
    547 as roll-pitch-yaw, rotating *c*, then *b* then *a* in the shape coordinate 
    548 system.)  A particular *qx*, *qy* point on the detector, then corresponds 
    549 to *qa*, *qb*, *qc* with respect to the shape. 
    550  
    551 The oriented C model is called as *Iqabc(qa, qb, qc, par1, par2, ...)* where 
     540at the end of the parameter table.  As described in the section 
     541:ref:`orientation`, the individual $(q_x, q_y)$ points on the detector will 
     542be rotated into $(q_a, q_b, q_c)$ points relative to the sample in its 
     543canonical orientation with $a$-$b$-$c$ aligned with $x$-$y$-$z$ in the 
     544laboratory frame and beam travelling along $-z$. 
     545 
     546The oriented C model is called using *Iqabc(qa, qb, qc, par1, par2, ...)* where 
    552547*par1*, etc. are the parameters to the model.  If the shape is rotationally 
    553548symmetric about *c* then *psi* is not needed, and the model is called 
Note: See TracChangeset for help on using the changeset viewer.