Changeset fc7bcd5 in sasmodels for sasmodels/models/parallelepiped.py


Ignore:
Timestamp:
May 26, 2018 3:29:07 PM (6 years ago)
Author:
butler
Branches:
master, core_shell_microgels, magnetic_model, ticket-1257-vesicle-product, ticket_1156, ticket_1265_superball, ticket_822_more_unit_tests
Children:
f89ec96
Parents:
96153e4
Message:

Final? edits to Parallelepiped (and core shell version) documentation

addresses #896

File:
1 edited

Legend:

Unmodified
Added
Removed

  • sasmodels/models/parallelepiped.py

    r96153e4 rfc7bcd5  
    55---------- 
    66 
    7 This model calculates the scattering from a rectangular parallelepiped 
     7This model calculates the scattering from a rectangular solid 
    88(:numref:`parallelepiped-image`). 
    99If you need to apply polydispersity, see also :ref:`rectangular-prism`. For 
    … …  
    7272applied. 
    7373 
    74 NB: The 2nd virial coefficient of the parallelepiped is calculated based on 
    75 the averaged effective radius, after appropriately sorting the three 
    76 dimensions, to give an oblate or prolate particle, $(=\sqrt{AB/\pi})$ and 
    77 length $(= C)$ values, and used as the effective radius for 
    78 $S(q)$ when $P(q) \cdot S(q)$ is applied. 
    79  
    80 For 2d data the orientation of the particle is required, described using 
    81 angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, for further details 
    82 of the calculation and angular dispersions see :ref:`orientation` . 
    83  
    84 The angle $\Psi$ is the rotational angle around the $C$ axis. 
    85 For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the $B$ axis 
    86 oriented parallel to the y-axis of the detector with $A$ along the x-axis. 
    87 For other $\theta$, $\phi$ values, the parallelepiped has to be first rotated 
    88 $\theta$ degrees in the $z-x$ plane and then $\phi$ degrees around the $z$ axis, 
    89 before doing a final rotation of $\Psi$ degrees around the resulting $C$ axis 
    90 of the particle to obtain the final orientation of the parallelepiped. 
    91  
    92 .. note:: For 2d, constraints must be applied during fitting to ensure that the 
    93    inequality $A < B < C$ is not violated, and hence the correct definition 
    94    of angles is preserved. The calculation will not report an error, 
    95    but the results may be not correct. 
    96     
    97 .. _parallelepiped-orientation: 
    98  
    99 .. figure:: img/parallelepiped_angle_definition.png 
    100  
    101     Definition of the angles for oriented parallelepiped, shown with $A<B<C$. 
    102  
    103 .. figure:: img/parallelepiped_angle_projection.png 
    104  
    105     Examples of the angles for an oriented parallelepiped against the 
    106     detector plane. 
    107  
    108 On introducing "Orientational Distribution" in the angles, "distribution of 
    109 theta" and "distribution of phi" parameters will appear. These are actually 
    110 rotations about axes $\delta_1$ and $\delta_2$ of the parallelepiped, 
    111 perpendicular to the $a$ x $c$ and $b$ x $c$ faces. (When $\theta = \phi = 0$ 
    112 these are parallel to the $Y$ and $X$ axes of the instrument.) The third 
    113 orientation distribution, in $\psi$, is about the $c$ axis of the particle, 
    114 perpendicular to the $a$ x $b$ face. Some experimentation may be required to 
    115 understand the 2d patterns fully as discussed in :ref:`orientation` . 
    116  
    117 For a given orientation of the parallelepiped, the 2D form factor is 
    118 calculated as 
    119  
    120 .. math:: 
    121  
    122     P(q_x, q_y) = \left[\frac{\sin(\tfrac{1}{2}qA\cos\alpha)}{(\tfrac{1} 
    123                    {2}qA\cos\alpha)}\right]^2 
    124                   \left[\frac{\sin(\tfrac{1}{2}qB\cos\beta)}{(\tfrac{1} 
    125                    {2}qB\cos\beta)}\right]^2 
    126                   \left[\frac{\sin(\tfrac{1}{2}qC\cos\gamma)}{(\tfrac{1} 
    127                    {2}qC\cos\gamma)}\right]^2 
    128  
    129 with 
    130  
    131 .. math:: 
    132  
    133     \cos\alpha &= \hat A \cdot \hat q, \\ 
    134     \cos\beta  &= \hat B \cdot \hat q, \\ 
    135     \cos\gamma &= \hat C \cdot \hat q 
    136  
    137 and the scattering intensity as: 
    138  
    139 .. math:: 
    140  
    141     I(q_x, q_y) = \frac{\text{scale}}{V} V^2 \Delta\rho^2 P(q_x, q_y) 
     74For **oriented** particles, the 2D scattering intensity, $I(q_x, q_y)$, is 
     75given as: 
     76 
     77.. math:: 
     78 
     79    I(q_x, q_y) = \frac{\text{scale}}{V} (\Delta\rho \cdot V)^2 P(q_x, q_y) 
    14280            + \text{background} 
    14381 
    … …  
    15189   with scale being the volume fraction. 
    15290 
     91Where $P(q_x, q_y)$ for a given orientation of the form factor is calculated as 
     92 
     93.. math:: 
     94 
     95    P(q_x, q_y) = \left[\frac{\sin(\tfrac{1}{2}qA\cos\alpha)}{(\tfrac{1} 
     96                   {2}qA\cos\alpha)}\right]^2 
     97                  \left[\frac{\sin(\tfrac{1}{2}qB\cos\beta)}{(\tfrac{1} 
     98                   {2}qB\cos\beta)}\right]^2 
     99                  \left[\frac{\sin(\tfrac{1}{2}qC\cos\gamma)}{(\tfrac{1} 
     100                   {2}qC\cos\gamma)}\right]^2 
     101 
     102with 
     103 
     104.. math:: 
     105 
     106    \cos\alpha &= \hat A \cdot \hat q, \\ 
     107    \cos\beta  &= \hat B \cdot \hat q, \\ 
     108    \cos\gamma &= \hat C \cdot \hat q 
     109 
     110 
     111FITTING NOTES 
     112~~~~~~~~~~~~~ 
     113 
     114#. The 2nd virial coefficient of the parallelepiped is calculated based on 
     115   the averaged effective radius, after appropriately sorting the three 
     116   dimensions, to give an oblate or prolate particle, $(=\sqrt{AB/\pi})$ and 
     117   length $(= C)$ values, and used as the effective radius for 
     118   $S(q)$ when $P(q) \cdot S(q)$ is applied. 
     119 
     120#. For 2d data the orientation of the particle is required, described using 
     121   angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, where $\theta$ 
     122   and $\phi$ define the orientation of the director in the laboratry reference 
     123   frame of the beam direction ($z$) and detector plane ($x-y$ plane), while 
     124   the angle $\Psi$ is effectively the rotational angle around the particle 
     125   $C$ axis. For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the 
     126   $B$ axis oriented parallel to the y-axis of the detector with $A$ along 
     127   the x-axis. For other $\theta$, $\phi$ values, the order of rotations 
     128   matters. In particular, the parallelepiped must first be rotated $\theta$ 
     129   degrees in the $x-z$ plane before rotating $\phi$ degrees around the $z$ 
     130   axis (in the $x-y$ plane). Applying orientational distribution to the 
     131   particle orientation (i.e  `jitter` to one or more of these angles) can get 
     132   more confusing as `jitter` is defined **NOT** with respect to the laboratory 
     133   frame but the particle reference frame. It is thus highly recmmended to 
     134   read :ref:`orientation` for further details of the calculation and angular 
     135   dispersions. 
     136 
     137.. note:: For 2d, constraints must be applied during fitting to ensure that the 
     138   order of sides chosen is not altered, and hence that the correct definition 
     139   of angles is preserved. For the default choice shown here, that means 
     140   ensuring that the inequality $A < B < C$ is not violated,  The calculation 
     141   will not report an error, but the results may be not correct. 
     142    
     143.. _parallelepiped-orientation: 
     144 
     145.. figure:: img/parallelepiped_angle_definition.png 
     146 
     147    Definition of the angles for oriented parallelepiped, shown with $A<B<C$. 
     148 
     149.. figure:: img/parallelepiped_angle_projection.png 
     150 
     151    Examples of the angles for an oriented parallelepiped against the 
     152    detector plane. 
     153 
     154.. Comment by Paul Butler 
     155   I am commenting this section out as we are trying to minimize the amount of 
     156   oritentational detail here and encourage the user to go to the full 
     157   orientation documentation so that changes can be made in just one place. 
     158   below is the commented paragrah: 
     159   On introducing "Orientational Distribution" in the angles, "distribution of 
     160   theta" and "distribution of phi" parameters will appear. These are actually 
     161   rotations about axes $\delta_1$ and $\delta_2$ of the parallelepiped, 
     162   perpendicular to the $a$ x $c$ and $b$ x $c$ faces. (When $\theta = \phi = 0$ 
     163   these are parallel to the $Y$ and $X$ axes of the instrument.) The third 
     164   orientation distribution, in $\psi$, is about the $c$ axis of the particle, 
     165   perpendicular to the $a$ x $b$ face. Some experimentation may be required to 
     166   understand the 2d patterns fully as discussed in :ref:`orientation` . 
     167 
    153168 
    154169Validation 
    … …  
    158173to the angular average of the output of a 2D calculation over all possible 
    159174angles. 
    160  
    161175 
    162176References 
Note: See TracChangeset for help on using the changeset viewer.