.. _parallelepiped:

parallelepiped
=======================================================

Rectangular parallelepiped with uniform scattering length density.

=========== ======================================== ============ =============
Parameter   Description                              Units        Default value
=========== ======================================== ============ =============
scale       Source intensity                         None                     1
background  Source background                        |cm^-1|              0.001
sld         Parallelepiped scattering length density |1e-6Ang^-2|             4
sld_solvent Solvent scattering length density        |1e-6Ang^-2|             1
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
theta       c axis to beam angle                     degree                  60
phi         rotation about beam                      degree                  60
psi         rotation about c axis                    degree                  60
=========== ======================================== ============ =============

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


The form factor is normalized by the particle volume.
For information about polarised and magnetic scattering, see
the :ref:`magnetism` documentation.

**Definition**

 This model calculates the scattering from a rectangular parallelepiped
 (\:numref:`parallelepiped-image`\).
 If you need to apply polydispersity, see also :ref:`rectangular-prism`.

.. _parallelepiped-image:


.. figure:: img/parallelepiped_geometry.jpg

   Parallelepiped with the corresponding definition of sides.

The three dimensions of the parallelepiped (strictly here a cuboid) may be
given in *any* size order. To avoid multiple fit solutions, especially
with Monte-Carlo fit methods, it may be advisable to restrict their ranges.
There may be a number of closely similar "best fits", so some trial and
error, or fixing of some dimensions at expected values, may help.

The 1D scattering intensity $I(q)$ is calculated as:

.. Comment by Miguel Gonzalez:
   I am modifying the original text because I find the notation a little bit
   confusing. I think that in most textbooks/papers, the notation P(Q) is
   used for the form factor (adim, P(Q=0)=1), although F(q) seems also to
   be used. But here (as for many other models), P(q) is used to represent
   the scattering intensity (in cm-1 normally). It would be good to agree on
   a common notation.

.. math::

    I(q) = \frac{\text{scale}}{V} (\Delta\rho \cdot V)^2
           \left< P(q, \alpha) \right> + \text{background}

where the volume $V = A B C$, the contrast is defined as
$\Delta\rho = \rho_\text{p} - \rho_\text{solvent}$,
$P(q, \alpha)$ is the form factor corresponding to a parallelepiped oriented
at an angle $\alpha$ (angle between the long axis C and $\vec q$),
and the averaging $\left<\ldots\right>$ is applied over all orientations.

Assuming $a = A/B < 1$, $b = B /B = 1$, and $c = C/B > 1$, the
form factor is given by (Mittelbach and Porod, 1961)

.. math::

    P(q, \alpha) = \int_0^1 \phi_Q\left(\mu \sqrt{1-\sigma^2},a\right)
        \left[S(\mu c \sigma/2)\right]^2 d\sigma

with

.. math::

    \phi_Q(\mu,a) &= \int_0^1
        \left\{S\left[\frac{\mu}{2}\cos\left(\frac{\pi}{2}u\right)\right]
               S\left[\frac{\mu a}{2}\sin\left(\frac{\pi}{2}u\right)\right]
               \right\}^2 du \\
    S(x) &= \frac{\sin x}{x} \\
    \mu &= qB

The scattering intensity per unit volume is returned in units of |cm^-1|.

NB: The 2nd virial coefficient of the parallelepiped is calculated based on
the averaged effective radius, after appropriately sorting the three
dimensions, to give an oblate or prolate particle, $(=\sqrt{AB/\pi})$ and
length $(= C)$ values, and used as the effective radius for
$S(q)$ when $P(q) \cdot S(q)$ is applied.

To provide easy access to the orientation of the parallelepiped, we define
three angles $\theta$, $\phi$ and $\Psi$. The definition of $\theta$ and
$\phi$ is the same as for the cylinder model (see also figures below).

.. Comment by Miguel Gonzalez:
   The following text has been commented because I think there are two
   mistakes. Psi is the rotational angle around C (but I cannot understand
   what it means against the q plane) and psi=0 corresponds to a||x and b||y.

   The angle $\Psi$ is the rotational angle around the $C$ axis against
   the $q$ plane. For example, $\Psi = 0$ when the $B$ axis is parallel
   to the $x$-axis of the detector.

The angle $\Psi$ is the rotational angle around the $C$ axis.
For $\theta = 0$ and $\phi = 0$, $\Psi = 0$ corresponds to the $B$ axis
oriented parallel to the y-axis of the detector with $A$ along the z-axis.
For other $\theta$, $\phi$ values, the parallelepiped has to be first rotated
$\theta$ degrees around $z$ and $\phi$ degrees around $y$,
before doing a final rotation of $\Psi$ degrees around the resulting $C$ to
obtain the final orientation of the parallelepiped.
For example, for $\theta = 0$ and $\phi = 90$, we have that $\Psi = 0$
corresponds to $A$ along $x$ and $B$ along $y$,
while for $\theta = 90$ and $\phi = 0$, $\Psi = 0$ corresponds to
$A$ along $z$ and $B$ along $x$.

.. _parallelepiped-orientation:

.. figure:: img/parallelepiped_angle_definition.png

    Definition of the angles for oriented parallelepiped, shown with $A<B<C$.

.. figure:: img/parallelepiped_angle_projection.png

    Examples of the angles for an oriented parallelepiped against the
    detector plane.

On introducing "Orientational Distribution" in the angles, "distribution of theta" and "distribution of phi" parameters will
appear. These are actually rotations about axes $\delta_1$ and $\delta_2$ of the parallelepiped, perpendicular to the $a$ x $c$ and $b$ x $c$ faces.
(When $\theta = \phi = 0$ these are parallel to the $Y$ and $X$ axes of the instrument.) The third orientation distribution, in $\psi$, is
about the $c$ axis of the particle, perpendicular to the $a$ x $b$ face. Some experimentation may be required to
understand the 2d patterns fully. (Earlier implementations had numerical integration issues in some circumstances when orientation
distributions passed through 90 degrees, such situations, with very broad distributions, should still be approached with care.)


For a given orientation of the parallelepiped, the 2D form factor is
calculated as

.. math::

    P(q_x, q_y) = \left[\frac{\sin(\tfrac{1}{2}qA\cos\alpha)}{(\tfrac{1}{2}qA\cos\alpha)}\right]^2
                  \left[\frac{\sin(\tfrac{1}{2}qB\cos\beta)}{(\tfrac{1}{2}qB\cos\beta)}\right]^2
                  \left[\frac{\sin(\tfrac{1}{2}qC\cos\gamma)}{(\tfrac{1}{2}qC\cos\gamma)}\right]^2

with

.. math::

    \cos\alpha &= \hat A \cdot \hat q, \\
    \cos\beta  &= \hat B \cdot \hat q, \\
    \cos\gamma &= \hat C \cdot \hat q

and the scattering intensity as:

.. math::

    I(q_x, q_y) = \frac{\text{scale}}{V} V^2 \Delta\rho^2 P(q_x, q_y)
            + \text{background}

.. Comment by Miguel Gonzalez:
   This reflects the logic of the code, as in parallelepiped.c the call
   to _pkernel returns $P(q_x, q_y)$ and then this is multiplied by
   $V^2 * (\Delta \rho)^2$. And finally outside parallelepiped.c it will be
   multiplied by scale, normalized by $V$ and the background added. But
   mathematically it makes more sense to write
   $I(q_x, q_y) = \text{scale} V \Delta\rho^2 P(q_x, q_y) + \text{background}$,
   with scale being the volume fraction.


**Validation**

Validation of the code was done by comparing the output of the 1D calculation
to the angular average of the output of a 2D calculation over all possible
angles.



.. figure:: img/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

R Nayuk and K Huber, *Z. Phys. Chem.*, 226 (2012) 837-854

**Authorship and Verification**

* **Author:** This model is based on form factor calculations implemented
    in a c-library provided by the NIST Center for Neutron Research (Kline, 2006).
* **Last Modified by:**  Paul Kienzle **Date:** April 05, 2017
* **Last Reviewed by:**  Richard Heenan **Date:** April 06, 2017


