.. _cylinder:

cylinder
=======================================================

Right circular cylinder with uniform scattering length density.

=========== ================================== ============ =============
Parameter   Description                        Units        Default value
=========== ================================== ============ =============
scale       Source intensity                   None                     1
background  Source background                  |cm^-1|              0.001
sld         Cylinder scattering length density |1e-6Ang^-2|             4
sld_solvent Solvent scattering length density  |1e-6Ang^-2|             1
radius      Cylinder radius                    |Ang|                   20
length      Cylinder length                    |Ang|                  400
theta       cylinder axis to beam angle        degree                  60
phi         rotation about beam                degree                  60
=========== ================================== ============ =============

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



For information about polarised and magnetic scattering, see
the :ref:`magnetism` documentation.

**Definition**

The output of the 2D scattering intensity function for oriented cylinders is
given by (Guinier, 1955)

.. math::

    P(q,\alpha) = \frac{\text{scale}}{V} F^2(q,\alpha).sin(\alpha) + \text{background}

where

.. math::

    F(q,\alpha) = 2 (\Delta \rho) V
           \frac{\sin \left(\tfrac12 qL\cos\alpha \right)}
                {\tfrac12 qL \cos \alpha}
           \frac{J_1 \left(q R \sin \alpha\right)}{q R \sin \alpha}

and $\alpha$ is the angle between the axis of the cylinder and $\vec q$, $V =\pi R^2L$
is the volume of the cylinder, $L$ is the length of the cylinder, $R$ is the
radius of the cylinder, and $\Delta\rho$ (contrast) is the scattering length
density difference between the scatterer and the solvent. $J_1$ is the
first order Bessel function.

For randomly oriented particles:

.. math::

    F^2(q)=\int_{0}^{\pi/2}{F^2(q,\alpha)\sin(\alpha)d\alpha}=\int_{0}^{1}{F^2(q,u)du}


Numerical integration is simplified by a change of variable to $u = cos(\alpha)$ with
$sin(\alpha)=\sqrt{1-u^2}$.

The output of the 1D scattering intensity function for randomly oriented
cylinders is thus given by

.. math::

    P(q) = \frac{\text{scale}}{V}
        \int_0^{\pi/2} F^2(q,\alpha) \sin \alpha\ d\alpha + \text{background}


NB: The 2nd virial coefficient of the cylinder is calculated based on the
radius and length values, and used as the effective radius for $S(q)$
when $P(q) \cdot S(q)$ is applied.

For oriented cylinders, we define the direction of the
axis of the cylinder using two angles $\theta$ (note this is not the
same as the scattering angle used in q) and $\phi$. Those angles
are defined in :numref:`cylinder-angle-definition` .

.. _cylinder-angle-definition:

.. figure:: img/cylinder_angle_definition.png

    Definition of the $\theta$ and $\phi$ orientation angles for a cylinder relative
    to the beam line coordinates, plus an indication of their orientation distributions
    which are described as rotations about each of the perpendicular axes $\delta_1$ and $\delta_2$
    in the frame of the cylinder itself, which when $\theta = \phi = 0$ are parallel to the $Y$ and $X$ axes.

.. figure:: img/cylinder_angle_projection.png

    Examples for oriented cylinders.

The $\theta$ and $\phi$ parameters to orient the cylinder only appear in the model when fitting 2d data.
On introducing "Orientational Distribution" in the angles, "distribution of theta" and "distribution of phi" parameters will
appear. These are actually rotations about the axes $\delta_1$ and $\delta_2$ of the cylinder, which when $\theta = \phi = 0$ are parallel
to the $Y$ and $X$ axes of the instrument respectively. 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.)

**Validation**

Validation of the code was done by comparing the output of the 1D model
to the output of the software provided by the NIST (Kline, 2006).
The implementation of the intensity for fully oriented cylinders was done
by averaging over a uniform distribution of orientations using

.. math::

    P(q) = \int_0^{\pi/2} d\phi
        \int_0^\pi p(\theta) P_0(q,\theta) \sin \theta\ d\theta


where $p(\theta,\phi) = 1$ is the probability distribution for the orientation
and $P_0(q,\theta)$ is the scattering intensity for the fully oriented
system, and then comparing to the 1D result.


.. figure:: img/cylinder_autogenfig.png

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

**References**

J. S. Pedersen, Adv. Colloid Interface Sci. 70, 171-210 (1997).
G. Fournet, Bull. Soc. Fr. Mineral. Cristallogr. 74, 39-113 (1951).

