Displaced core-shell ellipsoid model - absolute scale version - ABS_core_shell_displ_core.py

    r"""
Displaced core-shell ellipsoid model - absolute scale version.

**Description**

This model is identical in geometry and physics to ``core_shell_displ_core``,
but works in **absolute scale** (cm\ :sup:`-1`).  Instead of a dimensionless
contrast ratio, the user supplies the scattering length densities (SLDs) of
the core, shell, and solvent directly, together with the particle volume
fraction.  The model then computes all contrasts internally and returns the
absolute intensity without any additional ``scale`` factor.

Because the absolute intensity is computed internally, the SASView global
``scale`` parameter should be left at **1** and ``background`` set to the
measured incoherent flat background.

**Model Geometry**

Same as ``core_shell_displ_core``:

- Core ellipsoid: equatorial semi-axis *R*, aspect ratio *eps* = c/a.
- Coaxial shell: equatorial outer radius *R* + *d_shell*, where
  *d_shell* = |thickness_shell| + 2 |sigma_outer|.
- Core centre displaced by ``displacement`` perpendicular to the symmetry
  axis.

**Form Factor Decomposition**

The scattering amplitude at a given size and orientation is

.. math::

    F(q) = \Delta\rho_\text{shell}\, V_\text{out}\,\phi(q r_\text{out})
           + (\Delta\rho_\text{core} - \Delta\rho_\text{shell})\,
             V_\text{core}\,\phi(q r_\text{core})\,e^{i q\delta\sin\theta}

where :math:`\Delta\rho_X = \text{sld}_X - \text{sld\_solvent}` and
:math:`\phi(x) = 3j_1(x)/x`.

**Absolute Intensity**

.. math::

    I(q) = 10^{-4}\,\frac{\varphi}{\langle V\rangle}
           \bigl[\langle F^2(q)\rangle + \langle F(q)\rangle^2
           (S(q)-1)\bigr]\,B(q) + I_\text{poly}(q)

where the factor :math:`10^{-4}` converts
:math:`(10^{-6}\,\text{Ang}^{-2})^2 \cdot \text{Ang}^3 \cdot \text{Ang}^{-3}`
= :math:`10^{-12}\,\text{Ang}^{-1}` to cm\ :sup:`-1`
(:math:`1\,\text{Ang}^{-1} = 10^8\,\text{cm}^{-1}`).

:math:`\langle\cdot\rangle` denotes an average over the Gaussian size
distribution and all particle orientations (each 50-point Gauss quadrature).
:math:`\langle V\rangle` is the Gaussian-weighted mean particle volume used
as the number-density denominator.

The SASView framework then applies:

.. math::

    I_\text{total}(q) = \text{scale}\cdot I(q) + \text{background}

Keep ``scale = 1`` for true absolute scale.

**Parameter Definitions**

``scale``
    Overall scale factor — leave at **1** for absolute scale.  Only change
    if a systematic calibration offset is needed.

``background`` (cm\ :sup:`-1`)
    Flat incoherent background.  Set to the measured empty-cell or
    incoherent level.

``radius`` (*R*, Ang)
    Mean equatorial semi-axis of the core ellipsoid.

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

``volfraction`` (*phi*)
    Volume fraction of particles.  Together with the mean particle volume
    :math:`\langle V\rangle`, it sets the absolute scattering level:
    :math:`n = \varphi/\langle V\rangle`.

``sld_core`` (10\ :sup:`-6` Ang\ :sup:`-2`)
    Scattering length density of the core material.

``sld_shell`` (10\ :sup:`-6` Ang\ :sup:`-2`)
    Scattering length density of the shell material.

``sld_solvent`` (10\ :sup:`-6` Ang\ :sup:`-2`)
    Scattering length density of the solvent (D\ :sub:`2`\ O ~ 6.35,
    H\ :sub:`2`\ O ~ -0.56).

``thickness_shell`` (*d*, Ang)
    Equatorial shell thickness.  Effective shell extent used in the
    geometry: *d_shell* = |d| + 2 |sigma_outer|.

``volfraction_hs`` (*η*)
    Hard-sphere volume fraction for the Percus-Yevick S(q).
    Set to 0 to disable inter-particle interactions.

``radius_hs`` (*R*\ :sub:`HS`, Ang)
    Hard-sphere interaction radius.  Not necessarily equal to the geometric
    particle radius; active only when ``volfraction_hs`` > 0.

``sigma_rel`` (*sigma_R/R*)
    Relative Gaussian polydispersity of the core radius.
    0 = monodisperse (a minimum of 10\ :sup:`-4` is enforced internally).

``power_law`` (*A*\ :sub:`10`)
    Amplitude of the empirical low-*q* correction
    :math:`B(q) = 1 + A_{10}(0.001/q)^m`.  Set to 0 to disable.

``exponent_2`` (*A*\ :sub:`11`)
    Sets the power-law exponent: *m* = |A\ :sub:`11`| + 2.

``sigma_outer`` (*sigma*\ :sub:`out`, Ang)
    Debye–Waller roughness of the outer shell surface.

``rg_polymer`` (*R*\ :sub:`g`, Ang)
    Radius of gyration of free polymer chains (Debye background).

``scale_polymer`` (cm\ :sup:`-1`)
    Zero-*q* intensity of the Debye polymer contribution.
    This is an *absolute* amplitude (cm\ :sup:`-1`); set to 0 to disable.

``displacement`` (*delta*, Ang)
    Core-centre offset perpendicular to the symmetry axis.
    Clamped to [0, *d_shell*] internally.  0 = concentric particle.

``sigma_core`` (*sigma*\ :sub:`core`, Ang)
    Debye–Waller roughness of the core–shell interface.

**References**

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

from numpy import inf

name  = "ABS_core_shell_displ_core"
title = "Displaced Core-Shell Ellipsoid - Absolute Scale"
category = "shape:ellipsoid"
description = """
    Absolute-scale scattering from polydisperse core-shell ellipsoids with a
    displaced core.  SLD values for core, shell, and solvent are given
    explicitly; the particle volume fraction sets the absolute intensity.
    Includes Percus-Yevick S(q) and a Debye polymer background.
    Keep scale=1 for true absolute units (cm^-1).
"""

# Parameter order must match the Iq() argument order in the C kernel exactly.
# Only radius, aspect_ratio, thickness_shell are tagged "volume" — these are
# the geometric parameters passed to form_volume() and radius_effective().
parameters = [
    #   name              units          default    [lo,   hi]   type     description
    ["radius",        "Ang",             30.8,   [0,    inf], "volume",
     "Mean equatorial semi-axis of the core ellipsoid"],
    ["aspect_ratio",  "",                 1.316,  [0,    inf], "volume",
     "Core polar/equatorial semi-axis ratio eps=c/a (>1 prolate, <1 oblate, =1 sphere)"],
    ["volfraction",   "",                 0.01,   [0,   0.74], "",
     "Particle volume fraction phi; sets the absolute scattering level n = phi/<V>"],
    ["sld_core",      "1e-6/Ang^2",       1.0,   [-inf,  inf], "",
     "Scattering length density of the core material"],
    ["sld_shell",     "1e-6/Ang^2",       4.0,   [-inf,  inf], "",
     "Scattering length density of the shell material"],
    ["sld_solvent",   "1e-6/Ang^2",       6.35,  [-inf,  inf], "",
     "Scattering length density of the solvent (D2O~6.35, H2O~-0.56)"],
    ["thickness_shell","Ang",            11.19,  [0,    inf], "volume",
     "Equatorial shell thickness d; effective shell extent = d + 2*sigma_outer"],
    ["volfraction_hs","",                 0.0,   [0,   0.74], "",
     "Hard-sphere volume fraction eta for Percus-Yevick S(q); 0 = no interactions"],
    ["radius_hs",     "Ang",            100.0,   [0,    inf], "",
     "Hard-sphere interaction radius (centre-to-centre at contact); active only when volfraction_hs > 0"],
    ["sigma_rel",     "",                 0.0205, [0,    inf], "",
     "Relative polydispersity sigma_R/R of the Gaussian size distribution; 0 = monodisperse"],
    ["power_law",     "",                 8.70,  [-inf,  inf], "",
     "Amplitude A10 of low-q power-law correction B(q)=1+A10*(0.001/q)^m; 0 = disabled"],
    ["exponent_2",    "",                 0.0748,[-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 interface"],
    ["rg_polymer",    "Ang",             10.0,   [0,    inf], "",
     "Radius of gyration of free polymer chains (Debye scattering function)"],
    ["scale_polymer", "1/cm",            1.726e-3,[-inf, inf], "",
     "Zero-q absolute intensity of the Debye polymer contribution (cm^-1); 0 = disabled"],
    ["displacement",  "Ang",             7.457,  [-inf,  inf], "",
     "Core-centre offset perpendicular to symmetry axis; 0 = concentric core-shell"],
    ["sigma_core",    "Ang",             0.0,   [0,    inf], "",
     "Debye-Waller roughness of the core-shell interface; 0 = sharp interface"],
]

source = ["lib/sas_3j1x_x.c", "ABS_core_shell_displ_core.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.5)*radius
    volfraction     = 10**np.random.uniform(-3, -1)
    sld_core        = np.random.uniform(-1, 4)
    sld_shell       = np.random.uniform(1, 6)
    sld_solvent     = np.random.uniform(5, 7)
    volfraction_hs  = np.random.uniform(0, 0.35)
    radius_hs       = np.random.uniform(0.8, 2.0)*radius
    sigma_rel       = 10**np.random.uniform(-2, -0.3)
    power_law       = np.random.uniform(0, 15)
    exponent_2      = np.random.uniform(0, 1)
    sigma_outer     = np.random.uniform(0, 2)
    rg_polymer      = 10**np.random.uniform(0, 2)
    scale_polymer   = 10**np.random.uniform(-5, -2)
    displacement    = np.random.uniform(0, 0.8*thickness_shell)
    sigma_core      = np.random.uniform(0, 2)
    return dict(
        radius=radius, aspect_ratio=aspect_ratio,
        volfraction=volfraction,
        sld_core=sld_core, sld_shell=sld_shell, sld_solvent=sld_solvent,
        thickness_shell=thickness_shell,
        volfraction_hs=volfraction_hs, radius_hs=radius_hs,
        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,
    )


# Reference values computed with the Python reimplementation of Iq_abs().
# Defaults: radius=30.8, aspect_ratio=1.316, volfraction=0.01,
#   sld_core=1.0, sld_shell=4.0, sld_solvent=6.35,
#   thickness_shell=11.19, volfraction_hs=0, radius_hs=100,
#   sigma_rel=0.0205, power_law=8.70, exponent_2=0.0748,
#   sigma_outer=0, rg_polymer=10, scale_polymer=1.726e-3,
#   displacement=7.457, sigma_core=0.
_default = {
    'scale': 1.0, 'background': 0.0,
    'radius': 30.8, 'aspect_ratio': 1.316,
    'volfraction': 0.01,
    'sld_core': 1.0, 'sld_shell': 4.0, 'sld_solvent': 6.35,
    'thickness_shell': 11.19,
    'volfraction_hs': 0.0, 'radius_hs': 100.0,
    'sigma_rel': 0.0205, 'power_law': 8.70, 'exponent_2': 0.0748,
    'sigma_outer': 0.0, 'rg_polymer': 10.0, 'scale_polymer': 1.726e-3,
    'displacement': 7.457, 'sigma_core': 0.0,
}

tests = [
    # [parameters, q, expected_I (cm^-1)]
    [_default, 0.01,  5.188854e+00],
    [_default, 0.05,  1.957152e+00],
    [_default, 0.10,  4.401413e-02],
    [_default, 0.20,  1.342650e-03],
    # With hard-sphere structure factor
    [dict(_default, volfraction_hs=0.2, radius_hs=50.0), 0.05, 1.973409e+00],
    [dict(_default, volfraction_hs=0.2, radius_hs=50.0), 0.10, 4.209512e-02],
]
Back to Model Download