Model Hierarchy¶

Abstract base class and concrete model implementations for heterodyne XPCS correlation functions. The factory function create_model() selects the appropriate model variant based on configuration.

Model class hierarchy for heterodyne correlation analysis.

class heterodyne.core.models.HeterodyneModelBase[source]

Bases: ABC

Abstract base class for heterodyne models.

abstract property n_params: int: Number of model parameters.

abstract property param_names: tuple[str, ...]: Parameter names in order.

abstractmethod compute_correlation(params, t, q, dt, phi_angle, contrast=1.0, offset=1.0)[source]

Compute model correlation matrix.

Parameters:

params (Array) – Parameter array
t (Array) – Time array
q (float) – Wavevector
dt (float) – Time step
phi_angle (float) – Detector phi angle (degrees)
contrast (float) – Speckle contrast (beta), default 1.0
offset (float) – Baseline offset, default 1.0

Return type:

Array

Returns:

Correlation matrix

abstractmethod get_default_params()[source]

Get default parameter values.

Return type:: ndarray

class heterodyne.core.models.TwoComponentModel[source]

Bases: HeterodyneModelBase

Two-component heterodyne correlation model.

Implements the 14-parameter model: - Reference transport (3): D0_ref, alpha_ref, D_offset_ref - Sample transport (3): D0_sample, alpha_sample, D_offset_sample - Velocity (3): v0, beta, v_offset - Fraction (4): f0, f1, f2, f3 - Angle (1): phi0

__post_init__()[source]

Set default parameter values.

Return type:: None

property n_params: int: Number of parameters (14).

property param_names: tuple[str, ...]: Parameter names in canonical order.

compute_correlation(params, t, q, dt, phi_angle, contrast=1.0, offset=1.0)[source]

Compute two-time heterodyne correlation.

Parameters:

params (Array) – Parameter array, shape (14,)
t (Array) – Time array
q (float) – Scattering wavevector
dt (float) – Time step
phi_angle (float) – Detector phi angle (degrees)
contrast (float) – Speckle contrast (beta), default 1.0
offset (float) – Baseline offset, default 1.0

Return type:

Array

Returns:

Correlation matrix c2(t1, t2), shape (N, N)

get_default_params()[source]

Get default parameter values as array.

Return type:: ndarray

params_to_dict(params)[source]

Convert parameter array to dictionary.

Parameters:: params (ndarray | Array) – Parameter array, shape (14,)
Return type:: dict[str, float]
Returns:: Dict mapping names to values

dict_to_params(param_dict)[source]

Convert parameter dictionary to array.

Parameters:: param_dict (dict[str, float]) – Dict with parameter names as keys
Return type:: ndarray
Returns:: Parameter array, shape (14,)

compute_g1_reference(params, t, q)[source]

Compute reference g1 correlation only (1D visualization helper).

Note

Uses pointwise g1(t) = exp(-q²J(t)), which does not represent the two-time integral physics. For production correlation, use compute_correlation which uses the integral formulation.

Parameters:

params (ndarray | Array) – Full parameter array
t (Array) – Time array
q (float) – Wavevector

Return type:

Array

Returns:

g1_ref array

compute_g1_sample(params, t, q)[source]

Compute sample g1 correlation only (1D visualization helper).

Note

Uses pointwise g1(t) = exp(-q²J(t)), which does not represent the two-time integral physics. For production correlation, use compute_correlation which uses the integral formulation.

Parameters:

params (ndarray | Array) – Full parameter array
t (Array) – Time array
q (float) – Wavevector

Return type:

Array

Returns:

g1_sample array

compute_fraction(params, t)[source]

Compute sample fraction only.

Parameters:

params (ndarray | Array) – Full parameter array
t (Array) – Time array

Return type:

Array

Returns:

f_sample array in [0, 1]

__init__(_defaults=<factory>)

class heterodyne.core.models.ReducedModel[source]

Bases: HeterodyneModelBase

Reduced heterodyne model with a subset of active parameters.

Inactive parameters are held fixed at their canonical default values. Useful for simplified analysis modes (e.g., reference-only diffusion).

Parameters:: _active_params (tuple[str, ...]) – Ordered tuple of parameter names that are free to vary.

__post_init__()[source]

Validate active params and precompute expansion constants.

Return type:: None

property n_params: int: Number of active (free) parameters.

property param_names: tuple[str, ...]: Active parameter names in order.

get_default_params()[source]

Get default values for active parameters only.

Return type:: ndarray

compute_correlation(params, t, q, dt, phi_angle, contrast=1.0, offset=1.0)[source]

Compute model correlation from reduced parameter set.

Inactive parameters are held at canonical defaults.

Parameters:

params (Array) – Active-parameter array, shape (n_params,)
t (Array) – Time array
q (float) – Scattering wavevector
dt (float) – Time step
phi_angle (float) – Detector phi angle (degrees)
contrast (float) – Speckle contrast (beta), default 1.0
offset (float) – Baseline offset, default 1.0

Return type:

Array

Returns:

Correlation matrix c2(t1, t2), shape (N, N)

__init__(_active_params, _FULL_DEFAULTS=<factory>)

heterodyne.core.models.create_model(mode)[source]

Factory function that returns a model for the requested analysis mode.

Parameters:: mode (str) – One of "static_ref", "static_both", "two_component".
Return type:: HeterodyneModelBase
Returns:: TwoComponentModel for "two_component"; ReducedModel for all other recognised modes.
Raises:: ValueError – If mode is not a recognised analysis mode.