Changeset eda8b30 in sasmodels


Ignore:
Timestamp:
Oct 28, 2017 4:42:15 AM (6 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:
5f8b72b
Parents:
da5536f
Message:

further changes to model docs for orientation calcs

Files:
12 edited

Legend:

Unmodified
Added
Removed

  • doc/developer/overview.rst

    rda5536f reda8b30  
    165165Further details are provided in the next section, 
    166166:ref:`Calculator_Interface` 
     167 
     168.. _orientation_developer: 
    167169 
    168170Orientation and Numerical Integration 

  • doc/guide/orientation/orientation.rst

    rda5536f reda8b30  
    4242cylinder cross section. (When $\theta = \phi = 0$ these are parallel to the $Y$ and $X$ axes of the instrument.) 
    4343The third orientation distribution, in $\psi$, is about the $c$ axis of the particle. Some experimentation may be required to 
    44 understand the 2d patterns fully. A number of different shapes of distribution are available, as described for polydispersity. 
     44understand the 2d patterns fully. A number of different shapes of distribution are available, as described for  
     45polydispersity, see :ref:`polydispersityhelp` . 
    4546 
    4647Earlier versions of SasView had numerical integration issues in some circumstances when  
    … …  
    5253values of Npts and Nsigs, the number of steps used in the integration and the range spanned in number of standard deviations. 
    5354The standard deviation is entered in units of degrees. For a rectangular (uniform) distribution the full width  
    54 should be $\pm\sqrt(3)$ ~ 1.73 standard deviations. 
     55should be $\pm\sqrt(3)$ ~ 1.73 standard deviations (this may be changed soon). 
    5556 
    5657Where appropriate, for best numerical results, keep $a < b < c$ and the $\theta$ distribution narrower than the $\phi$ distribution. 
    5758 
    58 Some more detailed technical notes are provided in the Developer section of this manual. 
     59Some more detailed technical notes are provided in the developer section of this manual :ref:`orientation_developer` . 
    5960     
    6061*Document History* 

  • doc/guide/pd/polydispersity.rst

    r1f058ea reda8b30  
    66.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ 
    77 
     8.. _polydispersityhelp: 
     9 
    810Polydispersity Distributions 
    911---------------------------- 
    1012 
    11 With some models in sasmodels we can calculate the average form factor for a 
     13With some models in sasmodels we can calculate the average intensity for a 
    1214population of particles that exhibit size and/or orientational 
    13 polydispersity. The resultant form factor is normalized by the average 
     15polydispersity. The resultant intensity is normalized by the average 
    1416particle volume such that 
    1517 

  • sasmodels/models/bcc_paracrystal.py

    r8f04da4 reda8b30  
    6565    \end{array} 
    6666 
    67 **NB**: The calculation of $Z(q)$ is a double numerical integral that must 
    68 be carried out with a high density of points to properly capture the sharp 
    69 peaks of the paracrystalline scattering. So be warned that the calculation 
    70 is SLOW. Go get some coffee. Fitting of any experimental data must be 
    71 resolution smeared for any meaningful fit. This makes a triple integral. 
    72 Very, very slow. Go get lunch! 
     67.. note:: 
    7368 
     69  The calculation of $Z(q)$ is a double numerical integral that 
     70  must be carried out with a high density of points to properly capture 
     71  the sharp peaks of the paracrystalline scattering.      
     72  So be warned that the calculation is slow. Fitting of any experimental data  
     73  must be resolution smeared for any meaningful fit. This makes a triple integral 
     74  which may be very slow. 
     75   
    7476This example dataset is produced using 200 data points, 
    7577*qmin* = 0.001 |Ang^-1|, *qmax* = 0.1 |Ang^-1| and the above default values. 
    … …  
    7779The 2D (Anisotropic model) is based on the reference below where $I(q)$ is 
    7880approximated for 1d scattering. Thus the scattering pattern for 2D may not 
    79 be accurate. 
     81be accurate, particularly at low $q$. For general details of the calculation and angular  
     82dispersions for oriented particles see :ref:`orientation` . 
     83Note that we are not responsible for any incorrectness of the 2D model computation. 
    8084 
    8185.. figure:: img/parallelepiped_angle_definition.png 

  • sasmodels/models/core_shell_parallelepiped.py

    r8f04da4 reda8b30  
    8585effective radius, for $S(Q)$ when $P(Q) * S(Q)$ is applied. 
    8686 
    87 To provide easy access to the orientation of the parallelepiped, we define the 
    88 axis of the cylinder using three angles $\theta$, $\phi$ and $\Psi$. 
    89 (see :ref:`cylinder orientation <cylinder-angle-definition>`). 
    90 The angle $\Psi$ is the rotational angle around the *long_c* axis against the 
    91 $q$ plane. For example, $\Psi = 0$ when the *short_b* axis is parallel to the 
    92 *x*-axis of the detector. 
     87For 2d data the orientation of the particle is required, described using  
     88angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, for further details  
     89of the calculation and angular dispersions see :ref:`orientation` . 
     90The angle $\Psi$ is the rotational angle around the *long_c* axis. For example,  
     91$\Psi = 0$ when the *short_b* axis is parallel to the *x*-axis of the detector. 
    9392 
    9493.. figure:: img/parallelepiped_angle_definition.png 
    9594 
    9695    Definition of the angles for oriented core-shell parallelepipeds. 
     96    Note that rotation $\theta$, initially in the $xz$ plane, is carried out first, then 
     97    rotation $\phi$ about the $z$ axis, finally rotation $\Psi$ is now around the axis of the cylinder. 
     98    The neutron or X-ray beam is along the $z$ axis. 
    9799 
    98100.. figure:: img/parallelepiped_angle_projection.png 

  • sasmodels/models/cylinder.py

    r31df0c9 reda8b30  
    5454when $P(q) \cdot S(q)$ is applied. 
    5555 
    56 For oriented cylinders, we define the direction of the 
     56For 2d scattering from oriented cylinders, we define the direction of the 
    5757axis of the cylinder using two angles $\theta$ (note this is not the 
    5858same as the scattering angle used in q) and $\phi$. Those angles 
    59 are defined in :numref:`cylinder-angle-definition` . 
     59are defined in :numref:`cylinder-angle-definition` , for further details see :ref:`orientation` . 
    6060 
    6161.. _cylinder-angle-definition: 
    … …  
    6363.. figure:: img/cylinder_angle_definition.png 
    6464 
    65     Definition of the $\theta$ and $\phi$ orientation angles for a cylinder relative 
    66     to the beam line coordinates, plus an indication of their orientation distributions 
    67     which are described as rotations about each of the perpendicular axes $\delta_1$ and $\delta_2$ 
     65    Angles $\theta$ and $\phi$ orient the cylinder relative 
     66    to the beam line coordinates, where the beam is along the $z$ axis. Rotation $\theta$, initially  
     67    in the $xz$ plane, is carried out first, then rotation $\phi$ about the $z$ axis. Orientation distributions 
     68    are described as rotations about two perpendicular axes $\delta_1$ and $\delta_2$ 
    6869    in the frame of the cylinder itself, which when $\theta = \phi = 0$ are parallel to the $Y$ and $X$ axes. 
    6970 
    … …  
    7374 
    7475The $\theta$ and $\phi$ parameters to orient the cylinder only appear in the model when fitting 2d data. 
    75 On introducing "Orientational Distribution" in the angles, "distribution of theta" and "distribution of phi" parameters will 
    76 appear. These are actually rotations about the axes $\delta_1$ and $\delta_2$ of the cylinder, which when $\theta = \phi = 0$ are parallel 
    77 to the $Y$ and $X$ axes of the instrument respectively. Some experimentation may be required to understand the 2d patterns fully. 
    78 (Earlier implementations had numerical integration issues in some circumstances when orientation distributions passed through 90 degrees, such 
    79 situations, with very broad distributions, should still be approached with care.) 
    8076 
    8177Validation 

  • sasmodels/models/ellipsoid.py

    r92708d8 reda8b30  
    5353    r = R_e \left[ 1 + u^2\left(R_p^2/R_e^2 - 1\right)\right]^{1/2} 
    5454 
    55 To provide easy access to the orientation of the ellipsoid, we define 
    56 the rotation axis of the ellipsoid using two angles $\theta$ and $\phi$. 
    57 These angles are defined in the 
     55For 2d data from oriented ellipsoids the direction of the rotation axis of  
     56the ellipsoid is defined using two angles $\theta$ and $\phi$ as for the  
    5857:ref:`cylinder orientation figure <cylinder-angle-definition>`. 
    5958For the ellipsoid, $\theta$ is the angle between the rotational axis 
    6059and the $z$ -axis in the $xz$ plane followed by a rotation by $\phi$ 
    61 in the $xy$ plane. 
     60in the $xy$ plane, for further details of the calculation and angular  
     61dispersions see :ref:`orientation` . 
    6262 
    6363NB: The 2nd virial coefficient of the solid ellipsoid is calculated based 

  • sasmodels/models/elliptical_cylinder.py

    rd9ec8f9 reda8b30  
    11# pylint: disable=line-too-long 
    22r""" 
    3 Definition for 2D (orientated system) 
    4 ------------------------------------- 
    5  
    6 The angles $\theta$ and $\phi$ define the orientation of the axis of the 
    7 cylinder. The angle $\Psi$ is defined as the orientation of the major 
    8 axis of the ellipse with respect to the vector $Q$. A gaussian polydispersity 
    9 can be added to any of the orientation angles, and also for the minor 
    10 radius and the ratio of the ellipse radii. 
    113 
    124.. figure:: img/elliptical_cylinder_geometry.png 
    … …  
    4436 
    4537 
    46 Definition for 1D (no preferred orientation) 
    47 -------------------------------------------- 
    48  
    49 The form factor is averaged over all possible orientation before normalized 
     38For 1D scattering, with no preferred orientation, the form factor is averaged over all possible orientations and normalized 
    5039by the particle volume 
    5140 
    … …  
    5443    P(q) = \text{scale}  <F^2> / V 
    5544 
    56 To provide easy access to the orientation of the elliptical cylinder, we 
    57 define the axis of the cylinder using two angles $\theta$, $\phi$ and $\Psi$ 
    58 (see :ref:`cylinder orientation <cylinder-angle-definition>`). The angle 
    59 $\Psi$ is the rotational angle around its own long_c axis. 
     45For 2d data the orientation of the particle is required, described using a different set  
     46of angles as in the diagrams below, for further details of the calculation and angular  
     47dispersions  see :ref:`orientation` . 
    6048 
    61 All angle parameters are valid and given only for 2D calculation; ie, an 
    62 oriented system. 
    6349 
    6450.. figure:: img/elliptical_cylinder_angle_definition.png 
    6551 
    66     Definition of angles for oriented elliptical cylinder, where axis_ratio is drawn >1, 
    67     and angle $\Psi$ is now a rotation around the axis of the cylinder. 
     52    Note that the angles here are not the same as in the equations for the scattering function. 
     53    Rotation $\theta$, initially in the $xz$ plane, is carried out first, then 
     54    rotation $\phi$ about the $z$ axis, finally rotation $\Psi$ is now around the axis of the cylinder. 
     55    The neutron or X-ray beam is along the $z$ axis. 
    6856 
    6957.. figure:: img/elliptical_cylinder_angle_projection.png 
    … …  
    7361 
    7462The $\theta$ and $\phi$ parameters to orient the cylinder only appear in the model when fitting 2d data. 
    75 On introducing "Orientational Distribution" in the angles, "distribution of theta" and "distribution of phi" parameters will 
    76 appear. These are actually rotations about the axes $\delta_1$ and $\delta_2$ of the cylinder, the $b$ and $a$ axes of the 
    77 cylinder cross section. (When $\theta = \phi = 0$ these are parallel to the $Y$ and $X$ axes of the instrument.) 
    78 The third orientation distribution, in $\psi$, is about the $c$ axis of the particle. Some experimentation may be required to 
    79 understand the 2d patterns fully. (Earlier implementations had numerical integration issues in some circumstances when orientation 
    80 distributions passed through 90 degrees, such situations, with very broad distributions, should still be approached with care.) 
     63 
    8164 
    8265NB: The 2nd virial coefficient of the cylinder is calculated based on the 

  • sasmodels/models/fcc_paracrystal.py

    r8f04da4 reda8b30  
    6464    \end{array} 
    6565 
    66 **NB**: The calculation of $Z(q)$ is a double numerical integral that 
    67 must be carried out with a high density of points to properly capture 
    68 the sharp peaks of the paracrystalline scattering. So be warned that the 
    69 calculation is SLOW. Go get some coffee. Fitting of any experimental data 
    70 must be resolution smeared for any meaningful fit. This makes a triple 
    71 integral. Very, very slow. Go get lunch! 
     66.. note:: 
     67 
     68  The calculation of $Z(q)$ is a double numerical integral that 
     69  must be carried out with a high density of points to properly capture 
     70  the sharp peaks of the paracrystalline scattering.      
     71  So be warned that the calculation is slow. Fitting of any experimental data  
     72  must be resolution smeared for any meaningful fit. This makes a triple integral 
     73  which may be very slow. 
    7274 
    7375The 2D (Anisotropic model) is based on the reference below where $I(q)$ is 
    7476approximated for 1d scattering. Thus the scattering pattern for 2D may not 
    75 be accurate. Note that we are not responsible for any incorrectness of the 
     77be accurate particularly at low $q$. For general details of the calculation  
     78and angular dispersions for oriented particles see :ref:`orientation` . 
     79Note that we are not responsible for any incorrectness of the 
    76802D model computation. 
    7781 

  • sasmodels/models/parallelepiped.py

    rca04add reda8b30  
    7474$S(q)$ when $P(q) \cdot S(q)$ is applied. 
    7575 
    76 To provide easy access to the orientation of the parallelepiped, we define 
    77 three angles $\theta$, $\phi$ and $\Psi$. The definition of $\theta$ and 
    78 $\phi$ is the same as for the cylinder model (see also figures below). 
     76For 2d data the orientation of the particle is required, described using  
     77angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, for further details  
     78of the calculation and angular dispersions see :ref:`orientation` . 
    7979 
    8080.. Comment by Miguel Gonzalez: 
    … …  
    8989The angle $\Psi$ is the rotational angle around the $C$ axis. 
    9090For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the $B$ axis 
    91 oriented parallel to the y-axis of the detector with $A$ along the z-axis. 
     91oriented parallel to the y-axis of the detector with $A$ along the x-axis. 
    9292For other $\theta$, $\phi$ values, the parallelepiped has to be first rotated 
    93 $\theta$ degrees around $z$ and $\phi$ degrees around $y$, 
    94 before doing a final rotation of $\Psi$ degrees around the resulting $C$ to 
    95 obtain the final orientation of the parallelepiped. 
    96 For example, for $\theta = 0$ and $\phi = 90$, we have that $\Psi = 0$ 
    97 corresponds to $A$ along $x$ and $B$ along $y$, 
    98 while for $\theta = 90$ and $\phi = 0$, $\Psi = 0$ corresponds to 
    99 $A$ along $z$ and $B$ along $x$. 
     93$\theta$ degrees in the $z-x$ plane and then $\phi$ degrees around the $z$ axis, 
     94before doing a final rotation of $\Psi$ degrees around the resulting $C$ axis 
     95of the particle to obtain the final orientation of the parallelepiped. 
    10096 
    10197.. _parallelepiped-orientation: 
    … …  
    114110(When $\theta = \phi = 0$ these are parallel to the $Y$ and $X$ axes of the instrument.) The third orientation distribution, in $\psi$, is 
    115111about the $c$ axis of the particle, perpendicular to the $a$ x $b$ face. Some experimentation may be required to 
    116 understand the 2d patterns fully. (Earlier implementations had numerical integration issues in some circumstances when orientation 
    117 distributions passed through 90 degrees, such situations, with very broad distributions, should still be approached with care.) 
    118  
     112understand the 2d patterns fully as discussed in :ref:`orientation` .  
    119113 
    120114For a given orientation of the parallelepiped, the 2D form factor is 

  • sasmodels/models/sc_paracrystal.py

    r9bc4882 reda8b30  
    7373    carried out with a high density of points to properly capture the sharp 
    7474    peaks of the paracrystalline scattering. 
    75     So be warned that the calculation is SLOW. Go get some coffee. 
    76     Fitting of any experimental data must be resolution smeared for any 
    77     meaningful fit. This makes a triple integral. Very, very slow. 
    78     Go get lunch! 
     75    So be warned that the calculation is slow. Fitting of any experimental data  
     76    must be resolution smeared for any meaningful fit. This makes a triple integral 
     77    which may be very slow. 
    7978 
    8079The 2D (Anisotropic model) is based on the reference below where *I(q)* is 
    8180approximated for 1d scattering. Thus the scattering pattern for 2D may not 
    82 be accurate. Note that we are not responsible for any incorrectness of the 2D 
    83 model computation. 
     81be accurate particularly at low $q$. For general details of the calculation  
     82and angular dispersions for oriented particles see :ref:`orientation` . 
     83Note that we are not responsible for any incorrectness of the 
     842D model computation. 
    8485 
    8586.. figure:: img/parallelepiped_angle_definition.png 

  • sasmodels/models/stacked_disks.py

    r8f04da4 reda8b30  
    7474    the layers. 
    7575 
    76 To provide easy access to the orientation of the stacked disks, we define 
    77 the axis of the cylinder using two angles $\theta$ and $\varphi$. 
     762d scattering from oriented stacks is calculated in the same way as for cylinders, 
     77for further details of the calculation and angular dispersions see :ref:`orientation` .  
    7878 
    7979.. figure:: img/cylinder_angle_definition.png 
    8080 
    81     Examples of the angles against the detector plane. 
     81    Angles $\theta$ and $\phi$ orient the stack of discs relative 
     82    to the beam line coordinates, where the beam is along the $z$ axis. Rotation $\theta$, initially  
     83    in the $xz$ plane, is carried out first, then rotation $\phi$ about the $z$ axis. Orientation distributions 
     84    are described as rotations about two perpendicular axes $\delta_1$ and $\delta_2$ 
     85    in the frame of the cylinder itself, which when $\theta = \phi = 0$ are parallel to the $Y$ and $X$ axes. 
    8286 
    8387 
Note: See TracChangeset for help on using the changeset viewer.