Parameter Interpretation Guide¶

Learning Objectives

By the end of this section you will understand:

The physical meaning of every parameter in both analysis modes
Typical ranges and units for real XPCS samples
How to interpret anomalous exponents (\(\alpha\), \(\beta\))
What the optical parameters (contrast, offset) tell you about your detector setup
A reference table of parameter bounds and defaults

—

Overview¶

Homodyne fits a total of 3–9 parameters depending on the analysis mode and per-angle configuration. Parameters fall into three groups:

Diffusion parameters: describe translational dynamics (\(D_0, \alpha, D_\text{offset}\))
Shear parameters: describe flow-induced advection (laminar_flow only: \(\dot\gamma_0, \beta, \dot\gamma_\text{offset}, \phi_0\))
Optical parameters: describe detector/beam properties (contrast \(\beta\), offset)

—

Diffusion Parameters¶

D₀ — Reference Diffusion Coefficient¶

Symbol: \(D_0\) Units: Å²/s

\(D_0\) is the amplitude of the diffusion coefficient at a reference time \(t_\text{ref} = \sqrt{dt \cdot t_\text{max}}\). For normal diffusion (\(\alpha = 0\)), \(D(t) = D_0 + D_\text{offset}\) is a constant.

Warning

Homodyne’s \(D_0\) absorbs a factor of 2 from the transport coefficient convention: \(D_0 = 2 D_\text{SE}\), where \(D_\text{SE}\) is the Stokes-Einstein diffusion coefficient:

\[D_\text{SE} = \frac{k_B T}{6 \pi \eta R_h}, \qquad D_0 = 2 D_\text{SE}\]

See Transport Coefficient J(t) for the derivation of this convention.

Physical interpretation:

Larger \(D_0\) → faster decay of \(C_2\) at a given \(q\)
At a fixed \(q\), the characteristic relaxation time is \(\tau_q \sim (q^2 D_0)^{-1}\)
For a 10 nm sphere in water at 25 °C: \(D_\text{SE} \approx 2.4 \times 10^4\) Å²/s, so \(D_0 \approx 4.8 \times 10^4\) Å²/s

Typical ranges:

System	\(D_0\) (Å²/s)	Notes
10 nm nanoparticles in water	~5×10⁴	Stokes-Einstein (\(2 D_\text{SE}\))
100 nm particles in water	~5×10³	—
Concentrated dispersions	10²–10³	Crowding reduces mobility
Gels / soft glasses	1–100	Caged motion
Large aggregates / very slow	0.01–10	Sub-diffusive

Default bounds: [100, 1e5] Å²/s

Note

\(D_0\) is internally reparameterized in CMC as \(\log(D_0 / t_\text{ref})\) to improve sampling efficiency across multiple orders of magnitude. The reported value is always in Å²/s.

alpha — Diffusion Time-Dependence Exponent¶

Symbol: \(\alpha\) Units: dimensionless

\(\alpha\) controls how the effective diffusion coefficient scales with time. Homodyne models:

\[D(t) = D_0 \, t^\alpha + D_\text{offset}\]

so \(\alpha\) is the power-law exponent of the time-dependent part. The diffusion integral \(\int_{t_1}^{t_2} J(t')\,dt'\) that enters the correlation function is evaluated numerically from \(D(t)\) (see Transport Coefficient J(t)).

Physical interpretation:

Value	Classification	Physical picture
\(\alpha = 0\)	Normal diffusion	Brownian motion; \(D(t) = D_0\) constant; MSD ∝ t
\(\alpha < 0\)	Sub-diffusion	Caged motion, viscoelastic medium, aging glass; \(D(t)\) decreases
\(\alpha > 0\)	Super-diffusion	Active particles, driven systems; \(D(t)\) increases

Warning

\(\alpha < -1\) is unphysical (the diffusion integral can become negative). The default lower bound is -2.0 to allow exploration of highly sub-diffusive regimes; physical systems should not reach this limit.

Default bounds: [-2.0, 2.0]

D_offset — Baseline Diffusion¶

Symbol: \(D_\text{offset}\) Units: Å²/s

\(D_\text{offset}\) adds a constant, time-independent component to the diffusion coefficient:

\[D(t) = D_0\,t^\alpha + D_\text{offset}\]

The \(D_\text{offset}\) term contributes a linear-in-time growth to the diffusion integral, independent of \(\alpha\).

Physical interpretation:

Represents a fast-diffusing background component (solvent molecules, dissolved polymer that doesn’t contribute to the main scatterer signal)
Can also absorb contributions from laser speckle in mixed detection setups
Often near zero for pure samples; relevant for heterogeneous systems

Default bounds: [-1e5, 1e5] Å²/s

—

Shear Parameters (laminar_flow only)¶

gamma_dot_0 — Reference Shear Rate¶

Symbol: \(\dot\gamma_0\) Units: s⁻¹

\(\dot\gamma_0\) is the amplitude of the shear rate. For time-independent shear (\(\beta = 0\)), it equals the applied shear rate \(\dot\gamma\). For time-dependent shear, it is the coefficient in:

\[\dot\gamma(t) = \dot\gamma_0 \, t^\beta + \dot\gamma_\text{offset}\]

The accumulated shear strain is the numerical integral:

\[\Gamma(t_1, t_2) = \int_{t_1}^{t_2} \dot\gamma(t)\,dt\]

Physical interpretation:

In Couette flow: typically equal to the applied angular velocity × geometric factor
Typical Couette shear rates: 0.01–1000 s⁻¹
\(\dot\gamma_0 \approx 0\) for a sample at rest in the shear cell

Default bounds: [1e-6, 0.5] s⁻¹

Note

The upper bound of 0.5 s⁻¹ is aligned with the YAML template and ParameterRegistry. For multi-scale problems where \(D_0 \sim 10^4\) and \(\dot\gamma_0 \sim 10^{-3}\) (scale ratio > 10⁶), consider enabling CMA-ES global optimization. See CMA-ES for Multi-Scale Problems.

beta — Shear Rate Time-Dependence Exponent¶

Symbol: \(\beta\) Units: dimensionless

Analogous to \(\alpha\) for the shear rate:

Value	Classification	Physical picture
\(\beta = 0\)	Steady shear	Constant applied shear rate
\(\beta < 0\)	Shear rate decreasing with time	Shear thinning; time-dependent flow
\(\beta > 0\)	Shear rate increasing with time	Shear thickening; time-dependent startup flow

Default bounds: [-2.0, 2.0]

gamma_dot_t_offset — Baseline Shear Rate¶

Symbol: \(\dot\gamma_\text{offset}\) Units: s⁻¹

Constant shear rate contribution, independent of time. Analogous to \(D_\text{offset}\) for shear. Represents steady background flow superimposed on the time-dependent component.

Default bounds: [-0.1, 0.1] s⁻¹

phi_0 — Angular Offset¶

Symbol: \(\phi_0\) Units: degrees

\(\phi_0\) is the angular offset between the shear flow direction and the detector coordinate system. The shear-induced decorrelation is maximal when the scattering vector is parallel to the flow direction (\(\phi = \phi_0\)) and zero when perpendicular.

Physical interpretation:

If the scattering geometry is perfectly aligned with the flow direction, \(\phi_0 = 0\)
Misalignment between shear cell and detector introduces a non-zero \(\phi_0\)
The value should be consistent across measurements with the same cell alignment

Default bounds: [-10, 10] degrees

—

Optical Parameters¶

These parameters describe properties of the beam and detector, not the sample. They appear as per-angle corrections when per_angle_mode is not constant.

Contrast (beta_coherence)¶

Symbol: \(\beta_\phi\) Units: dimensionless, range [0, 1]

The speckle contrast is the amplitude of the correlation function at zero lag:

\[C_2(\phi, 0) = \text{offset}(\phi) + \beta(\phi)\]

It is determined by the coherence of the X-ray beam and the detector pixel size relative to the speckle size:

Perfect coherence, single speckle per pixel: \(\beta = 1\)
Partial coherence or multiple speckles per pixel: \(\beta < 1\)

Typical values: 0.01–0.5

Offset¶

Units: dimensionless

The incoherent background level in the correlation function at large lag times:

\[\lim_{|t_2 - t_1| \to \infty} C_2(\phi, t_1, t_2) = \text{offset}(\phi)\]

For an ideal experiment with no background: offset = 1.0. In practice:

Values near 1.0 indicate clean data
Values significantly above or below 1.0 suggest static or rapidly-fluctuating background contributions

—

Parameter Reference Table¶

Parameter	Symbol	Units	Default Init	Bounds	Mode
`D0`	\(D_0\)	Å²/s	1000.0	[100, 1e5]	static, laminar_flow
`alpha`	\(\alpha\)	—	0.5	[-2, 2]	static, laminar_flow
`D_offset`	\(D_\text{offset}\)	Å²/s	10.0	[-1e5, 1e5]	static, laminar_flow
`gamma_dot_t0`	\(\dot\gamma_0\)	s⁻¹	0.01	[1e-6, 0.5]	laminar_flow
`beta`	\(\beta\)	—	0.5	[-2, 2]	laminar_flow
`gamma_dot_t_offset`	\(\dot\gamma_\text{offset}\)	s⁻¹	0.0	[-0.1, 0.1]	laminar_flow
`phi0`	\(\phi_0\)	degrees	0.0	[-10, 10]	laminar_flow
`contrast`	\(\beta_\phi\)	—	0.5	[0, 1]	per-angle
`offset`	—	—	1.0	[0.5, 1.5]	per-angle

—

Setting Initial Values¶

Poor initial values are a common cause of convergence failures. Here are guidelines:

For D₀:

# Estimate from Stokes-Einstein (remember: D0_homodyne = 2 * D_SE)
# For water at 25°C: kT = 4.11e-21 J
# eta_water = 8.9e-4 Pa·s
# Rh = particle radius in meters

import numpy as np
kT = 4.11e-21  # J at 25°C
eta = 8.9e-4   # Pa·s (water)
Rh_m = 10e-9   # 10 nm in meters
D_SE = kT / (6 * np.pi * eta * Rh_m)  # Stokes-Einstein D
D0_homodyne = 2 * D_SE * 1e20         # Å²/s (factor of 2!)
print(f"D0 estimate: {D0_homodyne:.1e} Å²/s")
# D0 estimate: 4.8e+04 Å²/s

For alpha: start at -0.5 (mild sub-diffusion) as a neutral starting point.

For gamma_dot_0: use the nominal applied shear rate from your rheometer setting.

For phi_0: use 0 if the geometry is known to be aligned; scan if uncertain.

—

Overriding Parameter Bounds via YAML¶

All default bounds, priors, and initial values can be overridden through the YAML configuration file. The override chain is:

YAML config
  -> ConfigManager (parses parameter_space section)
    -> ParameterManager._load_config_bounds() (dict.update())
      -> ParameterSpace.from_config() (builds optimizer-ready arrays)
        -> NLSQ / CMC optimizer

YAML format:

parameter_space:
  model: laminar_flow   # or "static"
  bounds:
    - name: D0
      min: 500.0        # override lower bound
      max: 5e4          # override upper bound
      prior_mu: 1e3     # CMC prior mean
      prior_sigma: 5e2  # CMC prior std
      type: TruncatedNormal  # prior distribution type
    - name: alpha
      min: -1.0
      max: 1.0
    - name: contrast    # applies to all contrast_i per-angle params
      min: 0.05
      max: 0.8
      prior_mu: 0.3
      prior_sigma: 0.15
      type: BetaScaled

What can be overridden:

Bounds (min, max): Used by both NLSQ (box constraints) and CMC (truncation limits for priors).
Priors (prior_mu, prior_sigma, type): Used by CMC only. NLSQ ignores prior specifications.
Per-angle parameters: Setting contrast or offset bounds in YAML applies to all per-angle instances (contrast_0, contrast_1, etc.).

Fallback behavior when not specified:

If a parameter appears in the YAML bounds list, those values are used.
If omitted, ParameterManager supplies defaults from ParameterRegistry.
If the registry lookup fails, hard-coded fallbacks apply: contrast [0.0, 1.0], offset [0.5, 1.5], others [0.0, 1.0].
For CMC priors not specified in YAML: TruncatedNormal with mu = (min + max) / 2 and sigma = (max - min) / 4.

—

Cross-System Bounds Consistency¶

The canonical parameter bounds are maintained in ParameterRegistry (homodyne/config/parameter_registry.py) and propagated consistently to all subsystems. The following table confirms the current state across all eight sources of parameter bounds in the codebase.

Cross-System Bounds Verification¶
Parameter	Registry	Manager	Physics	Fitting	Models	Validators	Docs
D0	[100, 1e5]	[100, 1e5]	[100, 1e5]	[100, 1e5]	[100, 1e5]	v > 1e7 warn	[100, 1e5]
alpha	[-2, 2]	[-2, 2]	[-2, 2]	[-2, 2]	[-2, 2]	v < -1.5 warn	[-2, 2]
D_offset	[-1e5, 1e5]	[-1e5, 1e5]	[-1e5, 1e5]	[-1e5, 1e5]	[-1e5, 1e5]	v < 0 warn	[-1e5, 1e5]
gamma_dot_t0	[1e-6, 0.5]	[1e-6, 0.5]	[1e-6, 0.5]	[1e-6, 0.5]	[1e-6, 0.5]	v > 0.5 warn	[1e-6, 0.5]
beta	[-2, 2]	[-2, 2]	[-2, 2]	[-2, 2]	[-2, 2]	\|v\| > 2 warn	[-2, 2]
gamma_dot_t_offset	[-0.1, 0.1]	[-0.1, 0.1]	[-0.1, 0.1]	[-0.1, 0.1]	[-0.1, 0.1]	(none)	[-0.1, 0.1]
phi0	[-10, 10]	[-10, 10]	[-10, 10]	[-10, 10]	[-10, 10]	\|v\| > 10 info	[-10, 10]
contrast	[0, 1]	[0, 1]	–	–	–	v <= 0 err	[0, 1]
offset	[0.5, 1.5]	[0.5, 1.5]	–	–	–	v <= 0 err	[0.5, 1.5]

Legend: Registry = parameter_registry.py, Manager = parameter_manager.py, Physics = core/physics.py, Fitting = core/fitting.py, Models = core/models.py, Validators = physics_validators.py, Docs = this page. “–” means the parameter is not defined in that source.

Note

CMC uses these bounds to construct TruncatedNormal priors by default. The prior mean and standard deviation are set from the ParameterRegistry defaults (see table above), or from YAML prior_mu/prior_sigma overrides. Parameters marked log_space=True in the registry (D0, D_offset, gamma_dot_t0) are reparameterized in log-space for CMC sampling. Note that gamma_dot_t_offset has log_space=False because its bounds include negative values.

—

Parameter Interpretation Guide¶

Overview¶

Diffusion Parameters¶

D₀ — Reference Diffusion Coefficient¶

alpha — Diffusion Time-Dependence Exponent¶

D_offset — Baseline Diffusion¶

Shear Parameters (laminar_flow only)¶

gamma_dot_0 — Reference Shear Rate¶

beta — Shear Rate Time-Dependence Exponent¶

gamma_dot_t_offset — Baseline Shear Rate¶

phi_0 — Angular Offset¶

Optical Parameters¶

Contrast (beta_coherence)¶

Offset¶

Parameter Reference Table¶

Setting Initial Values¶

Overriding Parameter Bounds via YAML¶

Cross-System Bounds Consistency¶

See Also¶