.. _core-shell-parallelepiped:

core_shell_parallelepiped
=======================================================

Rectangular solid with a core-shell structure.

=========== ============================================== ============ =============
Parameter   Description                                    Units        Default value
=========== ============================================== ============ =============
scale       Source intensity                               None                     1
background  Source background                              |cm^-1|              0.001
sld_core    Parallelepiped core scattering length density  |1e-6Ang^-2|             1
sld_a       Parallelepiped A rim scattering length density |1e-6Ang^-2|             2
sld_b       Parallelepiped B rim scattering length density |1e-6Ang^-2|             4
sld_c       Parallelepiped C rim scattering length density |1e-6Ang^-2|             2
sld_solvent Solvent scattering length density              |1e-6Ang^-2|             6
length_a    Shorter side of the parallelepiped             |Ang|                   35
length_b    Second side of the parallelepiped              |Ang|                   75
length_c    Larger side of the parallelepiped              |Ang|                  400
thick_rim_a Thickness of A rim                             |Ang|                   10
thick_rim_b Thickness of B rim                             |Ang|                   10
thick_rim_c Thickness of C rim                             |Ang|                   10
theta       c axis to beam angle                           degree                   0
phi         rotation about beam                            degree                   0
psi         rotation about c axis                          degree                   0
=========== ============================================== ============ =============

The returned value is scaled to units of |cm^-1| |sr^-1|, absolute scale.


**Definition**

Calculates the form factor for a rectangular solid with a core-shell structure.
The thickness and the scattering length density of the shell or
"rim" can be different on each (pair) of faces.

The form factor is normalized by the particle volume $V$ such that

.. math::

    I(q) = \text{scale}\frac{\langle f^2 \rangle}{V} + \text{background}

where $\langle \ldots \rangle$ is an average over all possible orientations
of the rectangular solid.

The function calculated is the form factor of the rectangular solid below.
The core of the solid is defined by the dimensions $A$, $B$, $C$ such that
$A < B < C$.

.. image:: img/core_shell_parallelepiped_geometry.jpg

There are rectangular "slabs" of thickness $t_A$ that add to the $A$ dimension
(on the $BC$ faces). There are similar slabs on the $AC$ $(=t_B)$ and $AB$
$(=t_C)$ faces. The projection in the $AB$ plane is then

.. image:: img/core_shell_parallelepiped_projection.jpg

The volume of the solid is

.. math::

    V = ABC + 2t_ABC + 2t_BAC + 2t_CAB

**meaning that there are "gaps" at the corners of the solid.**

The intensity calculated follows the :ref:`parallelepiped` model, with the
core-shell intensity being calculated as the square of the sum of the
amplitudes of the core and the slabs on the edges.

the scattering amplitude is computed for a particular orientation of the
core-shell parallelepiped with respect to the scattering vector and then
averaged over all possible orientations, where $\alpha$ is the angle between
the $z$ axis and the $C$ axis of the parallelepiped, $\beta$ is
the angle between projection of the particle in the $xy$ detector plane
and the $y$ axis.

.. math::

    F(Q)
    &= (\rho_\text{core}-\rho_\text{solvent})
       S(Q_A, A) S(Q_B, B) S(Q_C, C) \\
    &+ (\rho_\text{A}-\rho_\text{solvent})
        \left[S(Q_A, A+2t_A) - S(Q_A, Q)\right] S(Q_B, B) S(Q_C, C) \\
    &+ (\rho_\text{B}-\rho_\text{solvent})
        S(Q_A, A) \left[S(Q_B, B+2t_B) - S(Q_B, B)\right] S(Q_C, C) \\
    &+ (\rho_\text{C}-\rho_\text{solvent})
        S(Q_A, A) S(Q_B, B) \left[S(Q_C, C+2t_C) - S(Q_C, C)\right]

with

.. math::

    S(Q, L) = L \frac{\sin \tfrac{1}{2} Q L}{\tfrac{1}{2} Q L}

and

.. math::

    Q_A &= \sin\alpha \sin\beta \\
    Q_B &= \sin\alpha \cos\beta \\
    Q_C &= \cos\alpha


where $\rho_\text{core}$, $\rho_\text{A}$, $\rho_\text{B}$ and $\rho_\text{C}$
are the scattering length of the parallelepiped core, and the rectangular
slabs of thickness $t_A$, $t_B$ and $t_C$, respectively. $\rho_\text{solvent}$
is the scattering length of the solvent.

**FITTING NOTES**

If the scale is set equal to the particle volume fraction, $\phi$, the returned
value is the scattered intensity per unit volume, $I(q) = \phi P(q)$. However,
**no interparticle interference effects are included in this calculation.**

There are many parameters in this model. Hold as many fixed as possible with
known values, or you will certainly end up at a solution that is unphysical.

The returned value is in units of |cm^-1|, on absolute scale.

NB: The 2nd virial coefficient of the core_shell_parallelepiped is calculated
based on the the averaged effective radius $(=\sqrt{(A+2t_A)(B+2t_B)/\pi})$
and length $(C+2t_C)$ values, after appropriately sorting the three dimensions
to give an oblate or prolate particle, to give an effective radius,
for $S(Q)$ when $P(Q) * S(Q)$ is applied.

For 2d data the orientation of the particle is required, described using
angles $\theta$, $\phi$ and $\Psi$ as in the diagrams below, for further
details of the calculation and angular dispersions see :ref:`orientation`.
The angle $\Psi$ is the rotational angle around the *long_c* axis. For example,
$\Psi = 0$ when the *short_b* axis is parallel to the *x*-axis of the detector.

For 2d, constraints must be applied during fitting to ensure that the
inequality $A < B < C$ is not violated, and hence the correct definition
of angles is preserved. The calculation will not report an error,
but the results may be not correct.

.. figure:: img/parallelepiped_angle_definition.png

    Definition of the angles for oriented core-shell parallelepipeds.
    Note that rotation $\theta$, initially in the $xz$ plane, is carried
    out first, then rotation $\phi$ about the $z$ axis, finally rotation
    $\Psi$ is now around the axis of the cylinder. The neutron or X-ray
    beam is along the $z$ axis.

.. figure:: img/parallelepiped_angle_projection.png

    Examples of the angles for oriented core-shell parallelepipeds against the
    detector plane.


.. figure:: img/core_shell_parallelepiped_autogenfig.png

    1D and 2D plots corresponding to the default parameters of the model.

**References**

.. [#] P Mittelbach and G Porod, *Acta Physica Austriaca*, 14 (1961) 185-211
    Equations (1), (13-14). (in German)
.. [#] D Singh (2009). *Small angle scattering studies of self assembly in
   lipid mixtures*, Johns Hopkins University Thesis (2009) 223-225. `Available
   from Proquest <http://search.proquest.com/docview/304915826?accountid
   =26379>`_

**Authorship and Verification**

* **Author:** NIST IGOR/DANSE **Date:** pre 2010
* **Converted to sasmodels by:** Miguel Gonzales **Date:** February 26, 2016
* **Last Modified by:** Paul Kienzle **Date:** October 17, 2017
* Cross-checked against hollow rectangular prism and rectangular prism for
  equal thickness overlapping sides, and by Monte Carlo sampling of points
  within the shape for non-uniform, non-overlapping sides.

