Analysis Modes¶

Homodyne provides two analysis modes for XPCS data: Static mode for equilibrium systems and Laminar Flow mode for systems under shear. This section documents the physical parameters, bounds, and usage for each mode.

Mode Overview¶

Analysis Mode Comparison¶
Mode	Physical Parameters	Description	Typical Applications
Static	3	Anomalous diffusion without flow	Colloidal suspensions, gels, glasses
Laminar Flow	7	Full nonequilibrium with shear	Rheology, microfluidics, active matter

Static Mode¶

Static mode analyzes systems at equilibrium without macroscopic flow. The correlation function simplifies to:

\[c_2(t_1, t_2) = \text{offset} + \text{contrast} \times \exp\left[-q^2 J(t_1, t_2)\right]\]

Physical Parameters (3)¶

Static Mode Parameters¶
Parameter	Symbol	Units	Description
D0	\(D_0\)	Varies with \(\alpha\)	Baseline diffusion coefficient. For \(\alpha = 0\), units are [length ² /time].
alpha	\(\alpha\)	dimensionless	Diffusion scaling exponent. \(\alpha = 0\) for normal diffusion, \(\alpha < 0\) for subdiffusion, \(\alpha > 0\) for superdiffusion.
D_offset	\(D_{\text{offset}}\)	[length ² /time]	Additive offset for baseline correction. Can be negative for jammed/arrested systems.

Parameter Bounds (Static Mode)¶

Static Mode Default Bounds¶
Parameter	Min	Max	Notes
D0	100	100,000	Consistent with Stokes-Einstein range for nm-scale particles
alpha	-2.0	2.0	Covers subdiffusive to superdiffusive regimes
D_offset	-100,000	100,000	Negative values allowed for arrested systems

Diffusion Integral¶

The diffusion integral over the time window \([t_1, t_2]\):

\[J(t_1, t_2) = \int_{t_1}^{t_2} D(t') \, dt'\]

This is always evaluated numerically via cumulative trapezoid on the discrete time grid (see Computational Methods for implementation details).

Laminar Flow Mode¶

Laminar flow mode analyzes systems under shear with the full nonequilibrium correlation function:

\[c_2(\phi, t_1, t_2) = \text{offset} + \text{contrast} \times c_1^{\text{diff}} \times \left[c_1^{\text{shear}}\right]^2\]

where the shear contribution introduces angular anisotropy.

Physical Parameters (7)¶

Laminar Flow Mode Parameters¶
Parameter	Symbol	Units	Description
D0	\(D_0\)	Varies with \(\alpha\)	Baseline diffusion coefficient
alpha	\(\alpha\)	dimensionless	Diffusion scaling exponent
D_offset	\(D_{\text{offset}}\)	[length ² /time]	Diffusion additive offset
gamma_dot_t0	\(\dot{\gamma}_0\)	Varies with \(\beta\)	Baseline shear rate
beta	\(\beta\)	dimensionless	Shear rate scaling exponent
gamma_dot_t_offset	\(\dot{\gamma}_{\text{offset}}\)	[s ^-1]	Shear rate additive offset
phi0	\(\phi_0\)	[degrees]	Flow direction angle offset

Parameter Bounds (Laminar Flow Mode)¶

Laminar Flow Mode Default Bounds¶
Parameter	Min	Max	Notes
D0	100	100,000	Consistent with Stokes-Einstein range for nm-scale particles
alpha	-2.0	2.0	Covers subdiffusive to superdiffusive regimes
D_offset	-100,000	100,000	Allows negative for arrested systems
gamma_dot_t0	1e-6	10,000	Spans quasi-static to high shear rate regimes
beta	-2.0	2.0	Covers shear thinning to thickening regimes
gamma_dot_t_offset	0.01	100	Positive baseline shear rate
phi0	-10.0	10.0	Flow direction angle offset (degrees)

Shear Integral¶

The shear integral over the time window \([t_1, t_2]\):

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

This is always evaluated numerically via cumulative trapezoid on the discrete time grid, matching the diffusion integral method (see Computational Methods).

Parameter Bounds and Priors (NLSQ & CMC)¶

Where bounds come from: Both NLSQ and CMC read bounds from the parameter_space section of the YAML. If a parameter is omitted, defaults from ParameterManager are used; if those are missing, the fallbacks are: - contrast: [0.0, 1.0] - offset: [0.5, 1.5] - D0: [100, 1e5] - D_offset: [-1e5, 1e5] - other parameters: [0.0, 1.0]
NLSQ usage: Bounds are used for deterministic optimization only; NLSQ does not sample priors.
CMC usage: Bounds are used to build priors via ParameterSpace (see homodyne.config.parameter_space and homodyne.optimization.cmc.priors). Per-angle parameters contrast_i / offset_i are always included; if you only supply a base contrast/offset bound or prior, it applies to all angles.
Default priors when not specified: - Type: TruncatedNormal - Location: midpoint of the bound interval - Scale: one quarter of the interval width If no prior spec exists at all for a parameter, the runtime fallback is Uniform(min, max).
Supported prior types in CMC: TruncatedNormal, Uniform, LogNormal, HalfNormal, Normal, BetaScaled (Beta on [min, max]). All require finite bounds; BetaScaled computes the Beta concentrations from mu/sigma on the scaled interval.

Example YAML snippet¶

parameter_space:
  model: laminar_flow
  bounds:
    - name: D0
      min: 1e2
      max: 1e5
      prior_mu: 1e3
      prior_sigma: 1e3
      type: TruncatedNormal
    - name: alpha
      min: -2.0
      max: 2.0
      prior_mu: 0.0
      prior_sigma: 0.5
      type: Normal
    - name: contrast        # applies to all contrast_i
      min: 0.0
      max: 1.0
      prior_mu: 0.5
      prior_sigma: 0.2
      type: BetaScaled

Per-Angle Scaling¶

Per-angle scaling is mandatory for both modes. This accounts for instrumental variations across different detector positions.

Scaling Parameters (Per Angle)¶

For each azimuthal angle \(\phi_i\), two scaling parameters are fitted:

Per-Angle Scaling Parameters¶
Parameter	Symbol	Range	Description
contrast_i	\(\beta_i\)	[0.0, 1.0]	Per-angle contrast (instrumental coherence)
offset_i	\(c_{0,i}\)	[0.5, 1.5]	Per-angle baseline offset (ideal: 1.0)

Total Parameter Count¶

The total number of parameters depends on the number of azimuthal angles \(n_\phi\):

\[N_{\text{total}} = N_{\text{physical}} + 2 \times n_\phi\]

Examples:

Static mode with 3 angles: \(3 + 2 \times 3 = 9\) parameters
Laminar flow mode with 3 angles: \(7 + 2 \times 3 = 13\) parameters
Laminar flow mode with 5 angles: \(7 + 2 \times 5 = 17\) parameters

Parameter Ordering¶

For MCMC initialization, parameters must follow a specific ordering:

Per-angle contrast: contrast_0, contrast_1, ..., contrast_{n_phi-1}
Per-angle offset: offset_0, offset_1, ..., offset_{n_phi-1}
Physical parameters: D0, alpha, D_offset, [gamma_dot_t0, beta, gamma_dot_t_offset, phi0]

This ordering is critical for proper MCMC initialization with NumPyro.

Mode Selection Guidelines¶

When to Use Static Mode¶

Equilibrium colloidal suspensions
Gels and glasses near arrest transition
Systems without macroscopic flow
Initial exploratory analysis

When to Use Laminar Flow Mode¶

Rheology experiments with shear cells
Microfluidic flow measurements
Active matter under flow
Systems with time-dependent shear rates

Physical Constraints¶

The optimization respects physical constraints:

Positivity Constraints:

\(D_0 > 0\): Baseline diffusion must be positive
\(\dot{\gamma}_0 \geq 0\): Non-negative baseline shear rate
\(\text{contrast}_i \in [0, 1]\): Physical contrast bounds

Scaling Exponent Bounds:

\(|\alpha| \leq 2\): Physically reasonable diffusion scaling
\(|\beta| \leq 2\): Physically reasonable shear scaling

Angular Constraints:

\(\phi_0 \in [-10^\circ, 10^\circ]\): Tight bounds for MCMC convergence

Configuration Example¶

YAML configuration for laminar flow mode with 3 angles:

physics:
  mode: laminar_flow  # or "static"

initial_parameters:
  parameter_names:
    - D0
    - alpha
    - D_offset
    - gamma_dot_t0
    - beta
    - gamma_dot_t_offset
    - phi0
  values:
    - 1000.0    # D0 (bounds: [100, 1e5])
    - 0.0       # alpha (bounds: [-2, 2])
    - 0.0       # D_offset (bounds: [-1e5, 1e5])
    - 0.01      # gamma_dot_t0 (bounds: [1e-6, 0.5])
    - 0.0       # beta (bounds: [-2, 2])
    - 0.0       # gamma_dot_t_offset (bounds: [-0.1, 0.1])
    - 0.0       # phi0 in degrees (bounds: [-10, 10])

# Per-angle scaling is automatically enabled

See Configuration Templates for complete configuration templates.