Three-layer displaced core-shell ellipsoid - core_shell_extra_inner_shell.py

    r"""
Three-layer displaced core-shell ellipsoid with polydispersity.

**Description**

This model extends ``core_shell_displ_core`` by adding an **extra inner
shell** between the core and the outer shell.  The particle has three
concentric ellipsoidal regions (from outside in):

.. list-table::
   :header-rows: 1

   * - Layer
     - Radial extent
     - Normalised contrast
   * - Outer shell
     - R < r < R + d_shell
     - 1 (reference)
   * - Inner shell
     - R − d_in < r < R
     - ``contrast_inner_shell``
   * - Core
     - r < R − d_in
     - ``contrast_core``

where d_shell = |thickness_shell| + 2 |sigma_outer|  and
d_in = |thickness_inner_shell|.

The entire inner structure (inner shell + core) can be displaced rigidly
by ``displacement`` perpendicular to the symmetry axis, while the outer
shell remains centred.

**Form Factor Decomposition**

At a given orientation angle *\theta* (between *q* and symmetry axis) the
scattering amplitude is

.. math::

    F(q,\theta) = F_\text{shell}(q,\theta)
                 + F_\text{inner}(q,\theta)\,\cos(q\,\delta\,\sin\theta)

where *δ* = ``displacement`` and

.. math::

    F_\text{shell} &= V_\text{RO}\,\phi(q\,r_\text{RO})\,
                       e^{-\frac{1}{2}(q\sigma_\text{out})^2} \\
    F_\text{inner} &= \Bigl[
        -V_R\,(1-c_\text{in})\,\phi(q\,r_R)
        -V_\text{RI}\,(c_\text{in}-c_\text{core})\,\phi(q\,r_\text{RI})
      \Bigr]\,e^{-\frac{1}{2}(q\sigma_\text{core})^2}

with :math:`\phi(x) = 3j_1(x)/x` and c\ :sub:`in` =
``contrast_inner_shell``, c\ :sub:`core` = ``contrast_core``.

The intensity uses the same decoupling approximation as
``core_shell_displ_core``:

.. math::

    I(q) = \bigl[P(q) + \langle F\rangle^2(S(q)-1)\bigr]B(q)
           + I_\text{poly}(q)

The global ``scale`` and ``background`` are applied by SASView.

**Parameter Definitions**

``radius`` (*R*, Ang)
    Mean equatorial semi-axis of the outer boundary of the inner shell
    (also the inner boundary of the outer shell).

``aspect_ratio`` (*eps* = c/a)
    Core polar/equatorial semi-axis ratio; >1 prolate, <1 oblate, =1 sphere.

``volfraction_hs``, ``radius_hs``
    Volume fraction and interaction radius for the Percus-Yevick hard-sphere
    S(q).  Set ``volfraction_hs`` = 0 to disable.

``thickness_shell`` (*d*, Ang)
    Equatorial thickness of the **outer** shell.  The effective geometric
    extent used is d_shell = |d| + 2 |sigma_outer|.

``contrast_core``
    SLD contrast of the innermost core normalised to the outer-shell contrast
    = 1.  Value 0 : core invisible; 1 : core matches outer shell.

``thickness_inner_shell`` (*d_in*, Ang)
    Equatorial thickness of the **inner** shell.  The core equatorial
    radius is R − d_in.

``contrast_inner_shell``
    SLD contrast of the inner shell normalised to the outer-shell contrast
    = 1.  When equal to ``contrast_core``, the inner and core regions merge
    (model degenerates to a two-layer particle).

``sigma_rel``
    Relative Gaussian polydispersity sigma_R/R of the core radius *R*.

``power_law``, ``exponent_2``
    Amplitude A\ :sub:`10` and exponent parameter A\ :sub:`11` of the
    empirical low-*q* correction B(q) = 1 + A\ :sub:`10` * (0.001/q)\ :sup:`m`
    where m = |A\ :sub:`11`| + 2.  Set ``power_law`` = 0 to disable.

``sigma_outer`` (Ang)
    Debye–Waller roughness of the outer shell surface.

``sigma_core`` (Ang)
    Debye–Waller roughness shared by the inner shell surfaces (both the
    inner-shell/outer-shell interface at *R* and the core/inner-shell
    interface at R − d_in).

``rg_polymer`` (Ang), ``scale_polymer``
    Radius of gyration and amplitude of the Debye polymer background
    I\ :sub:`poly`(q) = scale_polymer × P\ :sub:`Debye`(q).

``displacement`` (*delta*, Ang)
    Perpendicular displacement of the inner structure.  Clamped to
    [0, d_shell]; 0 = concentric particle.

**References**

- Spinozzi et al., *Biophys. J.* (2002)
- Orthaber et al., *J. Appl. Cryst.* 33, 218–225 (2000)
"""

from numpy import inf

name  = "core_shell_extra_inner_shell"
title = "Three-Layer Displaced Core-Shell Ellipsoid with Polydispersity"
category = "shape:ellipsoid"
description = """
    Scattering from a three-layer polydisperse ellipsoid: outer shell,
    inner shell, and core. Contrasts are normalised to the outer shell = 1.
    Includes Percus-Yevick S(q), Debye polymer background, and optional
    displacement of the inner structure relative to the outer shell.
"""

# Parameter order must match Iq() in the C kernel exactly.
# "volume"-tagged parameters (radius, aspect_ratio, thickness_shell) are
# the only ones passed to form_volume() and radius_effective().
parameters = [
    ["radius",               "Ang",    37.45,  [0,   inf], "volume",
     "Mean equatorial semi-axis of the inner/outer shell boundary"],
    ["aspect_ratio",         "",        1.326,  [0,   inf], "volume",
     "Polar/equatorial semi-axis ratio eps=c/a (>1 prolate, <1 oblate, =1 sphere)"],
    ["volfraction_hs",       "",        0.0,   [0,  0.74], "",
     "Hard-sphere volume fraction for Percus-Yevick S(q); 0 = no interactions"],
    ["radius_hs",            "Ang",   100.0,   [0,   inf], "",
     "Hard-sphere interaction radius; active only when volfraction_hs > 0"],
    ["thickness_shell",      "Ang",    15.37,  [0,   inf], "volume",
     "Equatorial outer-shell thickness d; effective extent = d + 2*sigma_outer"],
    ["contrast_core",        "",       -0.255, [-inf, inf], "",
     "Innermost core contrast normalised to outer shell = 1; 0=invisible, 1=matches shell"],
    ["sigma_rel",            "",        0.02,  [0,   inf], "",
     "Relative polydispersity sigma_R/R of size distribution; 0 = monodisperse"],
    ["power_law",            "",        3.664, [-inf, inf], "",
     "Amplitude A10 of low-q correction B(q)=1+A10*(0.001/q)^m; 0 = disabled"],
    ["exponent_2",           "",        0.40,  [-inf, inf], "",
     "Exponent parameter A11; actual power-law exponent m = |A11| + 2"],
    ["sigma_outer",          "Ang",     0.0,   [0,   inf], "",
     "Debye-Waller roughness of the outer shell surface; 0 = sharp"],
    ["rg_polymer",           "Ang",    13.0,   [0,   inf], "",
     "Radius of gyration of free polymer chains (Debye background)"],
    ["scale_polymer",        "",        4.348e-3,[-inf,inf], "",
     "Zero-q intensity of Debye polymer contribution; 0 = disabled"],
    ["displacement",         "Ang",     0.0,   [-inf, inf], "",
     "Perpendicular displacement of inner structure; 0 = concentric"],
    ["sigma_core",           "Ang",     0.0,   [0,   inf], "",
     "Debye-Waller roughness shared by both inner shell surfaces; 0 = sharp"],
    ["thickness_inner_shell","Ang",     8.547, [0,   inf], "",
     "Equatorial inner-shell thickness d_in; core radius = R - d_in"],
    ["contrast_inner_shell", "",       -1.204, [-inf, inf], "",
     "Inner shell contrast normalised to outer shell = 1"],
]

source = ["lib/sas_3j1x_x.c", "core_shell_extra_inner_shell.c"]

effective_radius_type = [
    "outer equatorial radius",
    "core equatorial radius",
]


def form_volume(radius, aspect_ratio, thickness_shell):
    import numpy as np
    r_outer   = radius + thickness_shell
    eps_outer = (radius*aspect_ratio + thickness_shell) / r_outer
    return 4.0*np.pi/3.0 * r_outer**3 * eps_outer


def radius_effective(mode, radius, aspect_ratio, thickness_shell):
    if mode == 1:
        return radius + thickness_shell
    else:
        return radius


def random():
    import numpy as np
    radius               = 10**np.random.uniform(1, 3)
    aspect_ratio         = np.random.uniform(0.5, 2.0)
    thickness_shell      = np.random.uniform(0.05, 0.4)*radius
    thickness_inner_shell= np.random.uniform(0.05, 0.4)*radius
    volfraction_hs       = np.random.uniform(0, 0.35)
    radius_hs            = np.random.uniform(0.8, 2.0)*radius
    contrast_core        = np.random.uniform(-2, 2)
    contrast_inner_shell = np.random.uniform(-2, 2)
    sigma_rel            = 10**np.random.uniform(-2, -0.3)
    power_law            = np.random.uniform(0, 10)
    exponent_2           = np.random.uniform(0, 1)
    sigma_outer          = np.random.uniform(0, 2)
    sigma_core           = np.random.uniform(0, 2)
    rg_polymer           = 10**np.random.uniform(0, 2)
    scale_polymer        = 10**np.random.uniform(-4, -1)
    displacement         = np.random.uniform(0, 0.8*thickness_shell)
    return dict(
        radius=radius, aspect_ratio=aspect_ratio,
        volfraction_hs=volfraction_hs, radius_hs=radius_hs,
        thickness_shell=thickness_shell, contrast_core=contrast_core,
        sigma_rel=sigma_rel, power_law=power_law, exponent_2=exponent_2,
        sigma_outer=sigma_outer, rg_polymer=rg_polymer,
        scale_polymer=scale_polymer, displacement=displacement,
        sigma_core=sigma_core,
        thickness_inner_shell=thickness_inner_shell,
        contrast_inner_shell=contrast_inner_shell,
    )


# Reference values with scale=1, background=0.
# Defaults: radius=37.446, aspect_ratio=1.3256, volfraction_hs=0,
#   radius_hs=100, thickness_shell=15.374, contrast_core=-0.2553,
#   sigma_rel=0.02, power_law=3.664, exponent_2=0.40, sigma_outer=0,
#   rg_polymer=13, scale_polymer=4.348e-3, displacement=0, sigma_core=0,
#   thickness_inner_shell=8.547, contrast_inner_shell=-1.2037.
_default = {
    'scale': 1.0, 'background': 0.0,
    'radius': 37.446, 'aspect_ratio': 1.3256,
    'volfraction_hs': 0.0, 'radius_hs': 100.0,
    'thickness_shell': 15.374, 'contrast_core': -0.2553,
    'sigma_rel': 0.02, 'power_law': 3.664, 'exponent_2': 0.40,
    'sigma_outer': 0.0, 'rg_polymer': 13.0, 'scale_polymer': 4.348e-3,
    'displacement': 0.0, 'sigma_core': 0.0,
    'thickness_inner_shell': 8.547, 'contrast_inner_shell': -1.2037,
}

tests = [
    [_default, 0.01,  9.034152e-01],
    [_default, 0.05,  7.331966e-03],
    [_default, 0.10,  8.073183e-02],
    [_default, 0.20,  1.246710e-02],
    [dict(_default, volfraction_hs=0.2, radius_hs=50.0), 0.05, 7.333570e-03],
    [dict(_default, volfraction_hs=0.2, radius_hs=50.0), 0.10, 7.617066e-02],
]
Back to Model Download