Ignore:
File:
1 edited

Legend:

Unmodified
Added
Removed

  • sasmodels/models/core_shell_parallelepiped.py

    r97be877 rf89ec96  
    44 
    55Calculates the form factor for a rectangular solid with a core-shell structure. 
    6 The thickness and the scattering length density of the shell or 
    7 "rim" can be different on each (pair) of faces. 
     6The thickness and the scattering length density of the shell or "rim" can be 
     7different on each (pair) of faces. The three dimensions of the core of the 
     8parallelepiped (strictly here a cuboid) may be given in *any* size order as 
     9long as the particles are randomly oriented (i.e. take on all possible 
     10orientations see notes on 2D below). To avoid multiple fit solutions, 
     11especially with Monte-Carlo fit methods, it may be advisable to restrict their 
     12ranges. There may be a number of closely similar "best fits", so some trial and 
     13error, or fixing of some dimensions at expected values, may help. 
    814 
    915The form factor is normalized by the particle volume $V$ such that 
    … …  
    1117.. math:: 
    1218 
    13     I(q) = \text{scale}\frac{\langle f^2 \rangle}{V} + \text{background} 
     19    I(q) = \frac{\text{scale}}{V} \langle P(q,\alpha,\beta) \rangle 
     20    + \text{background} 
    1421 
    1522where $\langle \ldots \rangle$ is an average over all possible orientations 
    16 of the rectangular solid. 
    17  
    18 The function calculated is the form factor of the rectangular solid below. 
    19 The core of the solid is defined by the dimensions $A$, $B$, $C$ such that 
    20 $A < B < C$. 
    21  
    22 .. image:: img/core_shell_parallelepiped_geometry.jpg 
     23of the rectangular solid, and the usual $\Delta \rho^2 \ V^2$ term cannot be 
     24pulled out of the form factor term due to the multiple slds in the model. 
     25 
     26The core of the solid is defined by the dimensions $A$, $B$, $C$ here shown 
     27such that $A < B < C$. 
     28 
     29.. figure:: img/parallelepiped_geometry.jpg 
     30 
     31   Core of the core shell parallelepiped with the corresponding definition 
     32   of sides. 
     33 
    2334 
    2435There are rectangular "slabs" of thickness $t_A$ that add to the $A$ dimension 
    2536(on the $BC$ faces). There are similar slabs on the $AC$ $(=t_B)$ and $AB$ 
    26 $(=t_C)$ faces. The projection in the $AB$ plane is then 
    27  
    28 .. image:: img/core_shell_parallelepiped_projection.jpg 
    29  
    30 The volume of the solid is 
     37$(=t_C)$ faces. The projection in the $AB$ plane is 
     38 
     39.. figure:: img/core_shell_parallelepiped_projection.jpg 
     40 
     41   AB cut through the core-shell parallelipiped showing the cross secion of 
     42   four of the six shell slabs. As can be seen, this model leaves **"gaps"** 
     43   at the corners of the solid. 
     44 
     45 
     46The total volume of the solid is thus given as 
    3147 
    3248.. math:: 
    3349 
    3450    V = ABC + 2t_ABC + 2t_BAC + 2t_CAB 
    35  
    36 **meaning that there are "gaps" at the corners of the solid.** 
    3751 
    3852The intensity calculated follows the :ref:`parallelepiped` model, with the 
    3953core-shell intensity being calculated as the square of the sum of the 
    40 amplitudes of the core and the slabs on the edges. 
    41  
    42 the scattering amplitude is computed for a particular orientation of the 
    43 core-shell parallelepiped with respect to the scattering vector and then 
    44 averaged over all possible orientations, where $\alpha$ is the angle between 
    45 the $z$ axis and the $C$ axis of the parallelepiped, $\beta$ is 
    46 the angle between projection of the particle in the $xy$ detector plane 
    47 and the $y$ axis. 
    48  
    49 .. math:: 
    50  
    51     F(Q) 
     54amplitudes of the core and the slabs on the edges. The scattering amplitude is 
     55computed for a particular orientation of the core-shell parallelepiped with 
     56respect to the scattering vector and then averaged over all possible 
     57orientations, where $\alpha$ is the angle between the $z$ axis and the $C$ axis 
     58of the parallelepiped, and $\beta$ is the angle between the projection of the 
     59particle in the $xy$ detector plane and the $y$ axis. 
     60 
     61.. math:: 
     62 
     63    P(q)=\frac {\int_{0}^{\pi/2}\int_{0}^{\pi/2}F^2(q,\alpha,\beta) \ sin\alpha 
     64    \ d\alpha \ d\beta} {\int_{0}^{\pi/2} \ sin\alpha \ d\alpha \ d\beta} 
     65 
     66and 
     67 
     68.. math:: 
     69 
     70    F(q,\alpha,\beta) 
    5271    &= (\rho_\text{core}-\rho_\text{solvent}) 
    5372       S(Q_A, A) S(Q_B, B) S(Q_C, C) \\ 
    5473    &+ (\rho_\text{A}-\rho_\text{solvent}) 
    55         \left[S(Q_A, A+2t_A) - S(Q_A, Q)\right] S(Q_B, B) S(Q_C, C) \\ 
     74        \left[S(Q_A, A+2t_A) - S(Q_A, A)\right] S(Q_B, B) S(Q_C, C) \\ 
    5675    &+ (\rho_\text{B}-\rho_\text{solvent}) 
    5776        S(Q_A, A) \left[S(Q_B, B+2t_B) - S(Q_B, B)\right] S(Q_C, C) \\ 
    … …  
    6382.. math:: 
    6483 
    65     S(Q, L) = L \frac{\sin \tfrac{1}{2} Q L}{\tfrac{1}{2} Q L} 
     84    S(Q_X, L) = L \frac{\sin (\tfrac{1}{2} Q_X L)}{\tfrac{1}{2} Q_X L} 
    6685 
    6786and 
    … …  
    6988.. math:: 
    7089 
    71     Q_A &= \sin\alpha \sin\beta \\ 
    72     Q_B &= \sin\alpha \cos\beta \\ 
    73     Q_C &= \cos\alpha 
     90    Q_A &= q \sin\alpha \sin\beta \\ 
     91    Q_B &= q \sin\alpha \cos\beta \\ 
     92    Q_C &= q \cos\alpha 
    7493 
    7594 
    7695where $\rho_\text{core}$, $\rho_\text{A}$, $\rho_\text{B}$ and $\rho_\text{C}$ 
    77 are the scattering length of the parallelepiped core, and the rectangular 
     96are the scattering lengths of the parallelepiped core, and the rectangular 
    7897slabs of thickness $t_A$, $t_B$ and $t_C$, respectively. $\rho_\text{solvent}$ 
    7998is the scattering length of the solvent. 
    8099 
     100.. note::  
     101 
     102   the code actually implements two substitutions: $d(cos\alpha)$ is 
     103   substituted for -$sin\alpha \ d\alpha$ (note that in the 
     104   :ref:`parallelepiped` code this is explicitly implemented with 
     105   $\sigma = cos\alpha$), and $\beta$ is set to $\beta = u \pi/2$ so that 
     106   $du = \pi/2 \ d\beta$.  Thus both integrals go from 0 to 1 rather than 0 
     107   to $\pi/2$. 
     108 
    81109FITTING NOTES 
    82110~~~~~~~~~~~~~ 
    83111 
    84 If the scale is set equal to the particle volume fraction, $\phi$, the returned 
    85 value is the scattered intensity per unit volume, $I(q) = \phi P(q)$. However, 
    86 **no interparticle interference effects are included in this calculation.** 
    87  
    88 There are many parameters in this model. Hold as many fixed as possible with 
    89 known values, or you will certainly end up at a solution that is unphysical. 
    90  
    91 The returned value is in units of |cm^-1|, on absolute scale. 
    92  
    93 NB: The 2nd virial coefficient of the core_shell_parallelepiped is calculated 
    94 based on the the averaged effective radius $(=\sqrt{(A+2t_A)(B+2t_B)/\pi})$ 
    95 and length $(C+2t_C)$ values, after appropriately sorting the three dimensions 
    96 to give an oblate or prolate particle, to give an effective radius, 
    97 for $S(Q)$ when $P(Q) * S(Q)$ is applied. 
    98  
    99 For 2d data the orientation of the particle is required, described using 
    100 angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, for further 
    101 details of the calculation and angular dispersions see :ref:`orientation`. 
    102 The angle $\Psi$ is the rotational angle around the *long_c* axis. For example, 
    103 $\Psi = 0$ when the *short_b* axis is parallel to the *x*-axis of the detector. 
    104  
    105 For 2d, constraints must be applied during fitting to ensure that the 
    106 inequality $A < B < C$ is not violated, and hence the correct definition 
    107 of angles is preserved. The calculation will not report an error, 
    108 but the results may be not correct. 
     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. 
     137 
     138.. note:: For 2d, constraints must be applied during fitting to ensure that the 
     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. 
    109143 
    110144.. figure:: img/parallelepiped_angle_definition.png 
    111145 
    112146    Definition of the angles for oriented core-shell parallelepipeds. 
    113     Note that rotation $\theta$, initially in the $xz$ plane, is carried 
     147    Note that rotation $\theta$, initially in the $x-z$ plane, is carried 
    114148    out first, then rotation $\phi$ about the $z$ axis, finally rotation 
    115     $\Psi$ is now around the axis of the cylinder. The neutron or X-ray 
    116     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. 
    117151 
    118152.. figure:: img/parallelepiped_angle_projection.png 
    … …  
    120154    Examples of the angles for oriented core-shell parallelepipeds against the 
    121155    detector plane. 
     156 
     157 
     158Validation 
     159---------- 
     160 
     161Cross-checked against hollow rectangular prism and rectangular prism for equal 
     162thickness overlapping sides, and by Monte Carlo sampling of points within the 
     163shape for non-uniform, non-overlapping sides. 
     164 
    122165 
    123166References 
    … …  
    135178 
    136179* **Author:** NIST IGOR/DANSE **Date:** pre 2010 
    137 * **Converted to sasmodels by:** Miguel Gonzales **Date:** February 26, 2016 
     180* **Converted to sasmodels by:** Miguel Gonzalez **Date:** February 26, 2016 
    138181* **Last Modified by:** Paul Kienzle **Date:** October 17, 2017 
    139 * Cross-checked against hollow rectangular prism and rectangular prism for 
    140   equal thickness overlapping sides, and by Monte Carlo sampling of points 
    141   within the shape for non-uniform, non-overlapping sides. 
     182* **Last Reviewed by:** Paul Butler **Date:** May 24, 2018 - documentation 
     183  updated 
    142184""" 
    143185 
Note: See TracChangeset for help on using the changeset viewer.