SEC.Models.LognormalPore

SEC.Models.LognormalPore#

SEC.Models.LognormalPore.py

compute_mode(mu, sigma)#
compute_stdev(mu, sigma)#
Ksec(Rg, r, m)#
distribution_func(r, mu, sigma)#
gec_lognormal_pore_integrand_impl(r, w, N, T, me, mp, mu, sigma, Rg)#
gec_lognormal_pore_cf(w, N, T, me, mp, mu, sigma, Rg, x0, const_rg_limit=False)#
gec_lognormal_pore_pdf(x, scale, N, T, me, mp, mu, sigma, Rg, x0)#
sdm_lognormal_pore_cf(w, N, T, me, mp, mu, sigma, Rg, N0, t0, const_rg_limit=False)#

SDM with lognormal pore distribution and exponential residence time.

Adds mobile phase dispersion (Brownian term) to GEC lognormal model.

Parameters:

  • w (array) – Frequency array

  • N (float) – Pore interaction scale parameter

  • T (float) – Residence time scale parameter

  • me (float) – Pore entry exponent

  • mp (float) – Pore residence exponent

  • mu (float) – Log-mean of pore size distribution

  • sigma (float) – Log-std of pore size distribution

  • Rg (float) – Molecule radius of gyration (lower integration limit)

  • N0 (float) – Plate number (mobile phase dispersion parameter)

  • t0 (float) – Mobile phase hold-up time (drift term)

  • const_rg_limit (bool, optional) – Use constant integration limit (default: False)

Returns:

Characteristic function values

Return type:

complex array

Notes

CF structure: φ(ω) = exp(Z + Z²/(2*N0)) where Z = [lognormal pore integral] + iω*t0

The Z²/(2*N0) term represents axial dispersion in mobile phase.

sdm_lognormal_pore_pdf(x, scale, N, T, me, mp, mu, sigma, Rg, N0, t0)#

PDF for SDM with lognormal pore distribution.

Parameters:

  • x (array) – Time points

  • scale (float) – Amplitude scaling factor

  • N (float) – Pore interaction parameters

  • T (float) – Pore interaction parameters

  • me (float) – Pore interaction parameters

  • mp (float) – Pore interaction parameters

  • mu (float) – Lognormal distribution parameters

  • sigma (float) – Lognormal distribution parameters

  • Rg (float) – Molecule radius of gyration

  • N0 (float) – Plate number

  • t0 (float) – Mobile phase time

Returns:

Probability density values

Return type:

array

sdm_lognormal_pore_gamma_integrand_impl(r, w, N, T, k, me, mp, mu, sigma, Rg)#

Integrand for SDM lognormal pore with Gamma-distributed residence times.

Replaces exponential residence time with Gamma distribution.

Parameters:

  • r (float or array) – Pore radius (integration variable)

  • w (array) – Frequency array

  • N (float) – Pore interaction scale

  • T (float) – Residence time scale (theta parameter for Gamma)

  • k (float) – Gamma shape parameter (k=1 recovers exponential)

  • me (float) – Exponents for entry and residence

  • mp (float) – Exponents for entry and residence

  • mu (float) – Lognormal parameters

  • sigma (float) – Lognormal parameters

  • Rg (float) – Molecule radius of gyration

Returns:

Integrand values

Return type:

complex array

Notes

Gamma CF for single visit: (1 - iω*θ)^(-k) For k=1, recovers exponential case.

sdm_lognormal_pore_gamma_cf(w, N, T, k, me, mp, mu, sigma, Rg, N0, t0, const_rg_limit=False)#

SDM with lognormal pore distribution and Gamma-distributed residence times.

Most general model: combines pore size heterogeneity (lognormal) with residence time heterogeneity (Gamma) and mobile phase dispersion.

Parameters:

  • w (array) – Frequency array

  • N (float) – Pore interaction scale parameter

  • T (float) – Residence time scale parameter (Gamma scale θ)

  • k (float) – Gamma shape parameter (k=1 → exponential, k>1 → less dispersed)

  • me (float) – Pore entry exponent

  • mp (float) – Pore residence exponent

  • mu (float) – Log-mean of pore size distribution

  • sigma (float) – Log-std of pore size distribution

  • Rg (float) – Molecule radius of gyration

  • N0 (float) – Plate number (mobile phase dispersion)

  • t0 (float) – Mobile phase hold-up time

  • const_rg_limit (bool, optional) – Use constant integration limit

Returns:

Characteristic function values

Return type:

complex array

Notes

This is the most comprehensive SEC model: - Lognormal pore size distribution (structural heterogeneity) - Gamma residence time distribution (kinetic heterogeneity) - Mobile phase dispersion (Brownian component) - Size exclusion effects (Ksec with Rg)

CF structure:

φ(ω) = exp[Z + Z²/(2*N0)]
Z = iω*t0 + ∫_{Rg}^∞ L_{μ,σ}(r) * n_r * ((1 - iω*τ_r)^{-k} - 1) dr

Moment formulas (from meeting doc 2026-01-19):

M1 (mean) = t0 + k * ∫_{Rg}^∞ L_{μ,σ}(r) * n_r * τ_r dr

M2~ (variance) = k*(k+1) * ∫_{Rg}^∞ L_{μ,σ}(r) * n_r * τ_r² dr

  • M1² / N0

where n_r = N * Ksec(Rg, r, me) and τ_r = T * Ksec(Rg, r, mp).

The variance has two terms: - Altering-zone term: k*(k+1) * ∫… (pore residence heterogeneity) - Dispersive term: M1² / N0 (mobile phase Brownian broadening)

For special cases: - k=1: Reduces to sdm_lognormal_pore_cf (exponential residence) - N0→∞: Reduces to GEC with Gamma residence - σ→0: Reduces to sdm_monopore_gamma_cf (single pore size)

sdm_lognormal_pore_gamma_pdf(x, scale, N, T, k, me, mp, mu, sigma, Rg, N0, t0)#

PDF for SDM with lognormal pore distribution and Gamma residence times.

Parameters:

  • x (array) – Time points

  • scale (float) – Amplitude scaling factor

  • N (float) – Pore interaction and time scale parameters

  • T (float) – Pore interaction and time scale parameters

  • k (float) – Gamma shape parameter

  • me (float) – Pore entry and residence exponents

  • mp (float) – Pore entry and residence exponents

  • mu (float) – Lognormal distribution parameters

  • sigma (float) – Lognormal distribution parameters

  • Rg (float) – Molecule radius of gyration

  • N0 (float) – Plate number

  • t0 (float) – Mobile phase time

Returns:

Probability density values

Return type:

array

Examples

>>> # Fit SEC-SAXS data with full model
>>> t = np.linspace(0, 300, 1000)
>>> pdf = sdm_lognormal_pore_gamma_pdf(
...     t, scale=1.0, N=100, T=2.0, k=1.5,
...     me=2.0, mp=2.0, mu=4.2, sigma=0.3,
...     Rg=50, N0=14400, t0=5.0
... )
sdm_lognormal_pore_gamma_cf_fast(w, N, T, k, me, mp, mu, sigma, Rg, N0, t0, n_quad=64)#

Vectorized Gauss-Legendre version of sdm_lognormal_pore_gamma_cf.

sdm_lognormal_pore_gamma_pdf_fast(x, scale, N, T, k, me, mp, mu, sigma, Rg, N0, t0)#

Fast version of sdm_lognormal_pore_gamma_pdf using Gauss-Legendre quadrature.

Applies an adaptive timescale as a performance optimization: by scaling (x - t0) into the [0, 1023] range, FftInvPdf can use the default N=1024 grid rather than auto-resizing to a larger power of 2. The timescale is capped at DEFAULT_TIMESCALE (0.25) so it never exceeds the mono-model default.

Safety note: FftInvPdf now auto-resizes its FFT grid whenever the query range exceeds N (see FftUtils.py, issue #181), so this timescale is no longer required for correctness. It is kept here purely to avoid the 2× FFT cost of the N=2048 fallback during optimization (thousands of PDF evaluations).

sdm_lognormal_model_moments(rg, N, T, N0, t0, k, mu, sigma, me=1.5, mp=1.5)#

Compute (M1, Variance) of the SDM lognormal-pore gamma elution model.

Note

me and mp default to 1.5 (standard SDM SEC exponents). When using column-fitted values, pass them explicitly — they live at positions 2 and 3 of SdmColumn.get_params() (i.e., col.get_params().me) but are keyword-only here:

M1, Var = sdm_lognormal_model_moments(
    rg, N, T, N0, t0, k, mu, sigma,
    me=ln_env.me, mp=ln_env.mp)  # ln_env from estimate_sdm_lognormal_from_monopore

k (gamma shape) is not in the LognormalEnv 8-tuple; use col.get_params().k from the mono-pore result for moment-matching.

For a single component with radius of gyration rg, the residence-time distribution is gamma with shape k and per-pore mean n(r)·tau(r), weighted by the lognormal pore-size density L(r; mu, sigma).

Formulas:

M1 = t0 + k * I1 Var = k * (k + 1) * I2 + M1^2 / N0

where

I1 = integral over r in [rg, max_rg] of L(r) * n(r) * tau(r) dr I2 = integral over r in [rg, max_rg] of L(r) * n(r) * tau(r)^2 dr n(r) = N * (1 - rg/r)^me tau(r) = T * (1 - rg/r)^mp

The variance formula uses the second raw moment of the per-pore Gamma distribution (k*(k+1)*theta^2), as appropriate for the compound-Poisson structure of the SDM model.

Parameters:

  • rg (float) – Radius of gyration of the component (Å).

  • N (float) – SDM column parameters (per-pore plate count and residence time).

  • T (float) – SDM column parameters (per-pore plate count and residence time).

  • N0 (float) – Mobile-phase plate number (governs Gaussian dispersion).

  • t0 (float) – Dead time / column offset.

  • k (float) – Gamma shape parameter for residence-time distribution.

  • mu (float) – Lognormal pore-size distribution parameters.

  • sigma (float) – Lognormal pore-size distribution parameters.

  • me (float, optional) – SEC partition exponents (default 1.5).

  • mp (float, optional) – SEC partition exponents (default 1.5).

Returns:

(M1, Var) – First moment (mean) and central second moment (variance) of the elution profile.

Return type:

tuple of float

See also

sdm_lognormal_pore_gamma_pdf_fast

full elution PDF computation.