Changeset fc7bcd5 in sasmodels


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

Location:
sasmodels/models
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • sasmodels/models/core_shell_parallelepiped.py

    r96153e4 rfc7bcd5  
    88parallelepiped (strictly here a cuboid) may be given in *any* size order as 
    99long as the particles are randomly oriented (i.e. take on all possible 
    10 orientations see notes on 2D below). To avoid multiple fit solutions, e 
    11 specially with Monte-Carlo fit methods, it may be advisable to restrict their 
     10orientations see notes on 2D below). To avoid multiple fit solutions, 
     11especially with Monte-Carlo fit methods, it may be advisable to restrict their 
    1212ranges. There may be a number of closely similar "best fits", so some trial and 
    1313error, or fixing of some dimensions at expected values, may help. 
    … …  
    1717.. math:: 
    1818 
    19     I(q) = \frac{\text{scale}}{V} \langle P(q,\alpha,\beta) \rangle  
     19    I(q) = \frac{\text{scale}}{V} \langle P(q,\alpha,\beta) \rangle 
    2020    + \text{background} 
    2121 
    … …  
    110110~~~~~~~~~~~~~ 
    111111 
    112 There are many parameters in this model. Hold as many fixed as possible with 
    113 known values, or you will certainly end up at a solution that is unphysical. 
    114  
    115  
    116 NB: The 2nd virial coefficient of the core_shell_parallelepiped is calculated 
    117 based on the the averaged effective radius $(=\sqrt{(A+2t_A)(B+2t_B)/\pi})$ 
    118 and length $(C+2t_C)$ values, after appropriately sorting the three dimensions 
    119 to give an oblate or prolate particle, to give an effective radius 
    120 for $S(q)$ when $P(q) * S(q)$ is applied. 
    121  
    122 For 2d data the orientation of the particle is required, described using 
    123 angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, for further details 
    124 of the calculation and angular dispersions see :ref:`orientation` . 
    125  
    126 The angle $\Psi$ is the rotational angle around the $C$ axis. 
    127 For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the $B$ axis 
    128 oriented parallel to the y-axis of the detector with $A$ along the x-axis. 
    129 For other $\theta$, $\phi$ values, the parallelepiped has to be first rotated 
    130 $\theta$ degrees in the $z-x$ plane and then $\phi$ degrees around the $z$ axis, 
    131 before doing a final rotation of $\Psi$ degrees around the resulting $C$ axis 
    132 of the particle to obtain the final orientation of the parallelepiped. 
     112#. There are many parameters in this model. Hold as many fixed as possible with 
     113   known values, or you will certainly end up at a solution that is unphysical. 
     114 
     115#. The 2nd virial coefficient of the core_shell_parallelepiped is calculated 
     116   based on the the averaged effective radius $(=\sqrt{(A+2t_A)(B+2t_B)/\pi})$ 
     117   and length $(C+2t_C)$ values, after appropriately sorting the three 
     118   dimensions to give an oblate or prolate particle, to give an effective radius 
     119   for $S(q)$ when $P(q) * S(q)$ is applied. 
     120 
     121#. For 2d data the orientation of the particle is required, described using 
     122   angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, where $\theta$ 
     123   and $\phi$ define the orientation of the director in the laboratry reference 
     124   frame of the beam direction ($z$) and detector plane ($x-y$ plane), while 
     125   the angle $\Psi$ is effectively the rotational angle around the particle 
     126   $C$ axis. For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the 
     127   $B$ axis oriented parallel to the y-axis of the detector with $A$ along 
     128   the x-axis. For other $\theta$, $\phi$ values, the order of rotations 
     129   matters. In particular, the parallelepiped must first be rotated $\theta$ 
     130   degrees in the $x-z$ plane before rotating $\phi$ degrees around the $z$ 
     131   axis (in the $x-y$ plane). Applying orientational distribution to the 
     132   particle orientation (i.e  `jitter` to one or more of these angles) can get 
     133   more confusing as `jitter` is defined **NOT** with respect to the laboratory 
     134   frame but the particle reference frame. It is thus highly recmmended to 
     135   read :ref:`orientation` for further details of the calculation and angular 
     136   dispersions. 
    133137 
    134138.. note:: For 2d, constraints must be applied during fitting to ensure that the 
    135    inequality $A < B < C$ is not violated, and hence the correct definition 
    136    of angles is preserved. The calculation will not report an error, 
    137    but the results may be not correct. 
     139   order of sides chosen is not altered, and hence that the correct definition 
     140   of angles is preserved. For the default choice shown here, that means 
     141   ensuring that the inequality $A < B < C$ is not violated,  The calculation 
     142   will not report an error, but the results may be not correct. 
    138143 
    139144.. figure:: img/parallelepiped_angle_definition.png 
    140145 
    141146    Definition of the angles for oriented core-shell parallelepipeds. 
    142     Note that rotation $\theta$, initially in the $xz$ plane, is carried 
     147    Note that rotation $\theta$, initially in the $x-z$ plane, is carried 
    143148    out first, then rotation $\phi$ about the $z$ axis, finally rotation 
    144     $\Psi$ is now around the axis of the particle. The neutron or X-ray 
    145     beam is along the $z$ axis. 
     149    $\Psi$ is now around the $C$ axis of the particle. The neutron or X-ray 
     150    beam is along the $z$ axis and the detecotr defines the $x-y$ plane. 
    146151 
    147152.. figure:: img/parallelepiped_angle_projection.png 

  • 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.