Heterodyne Model¶

Main model wrapper that composes the two-component correlation physics with parameter management, providing the primary interface for both NLSQ and CMC fitting pipelines.

Main heterodyne model wrapper class.

class heterodyne.core.heterodyne_model.HeterodyneModel[source]

Bases: object

Main heterodyne correlation model with stateful parameter management.

This class provides a convenient interface for: - Managing model parameters through ParameterManager - Computing correlation matrices - Computing residuals for fitting - Accessing pre-computed physics factors

Example

>>> model = HeterodyneModel.from_config(config)
>>> c2 = model.compute_correlation(phi_angle=45.0)
>>> residuals = model.compute_residuals(c2_data, phi_angle=45.0)

param_manager: ParameterManager

scaling: PerAngleScaling

classmethod from_config(config)[source]

Create model from configuration dictionary.

Parameters:: config (dict[str, Any]) – Configuration with temporal, scattering, and parameters sections
Return type:: HeterodyneModel
Returns:: Configured HeterodyneModel

property n_params: int: Total number of model parameters (14).

property n_varying: int: Number of varying parameters.

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

property varying_names: list[str]: Names of varying parameters.

property q: float: Scattering wavevector magnitude.

property dt: float: Time step.

property t: Array: Time array.

property n_times: int: Number of time points.

sync_time_axis(t)[source]

Trim model time axis to match post-exclusion data length.

The data pipeline may remove leading time points (e.g. t=0 singularity exclusion), shrinking the data array. This method trims the same number of leading points from the model’s own seconds-based time axis (computed from start_frame and dt) so shapes align without discarding the correct absolute-time values.

Return type:: None

get_params()[source]

Get current full parameter array.

Return type:: ndarray
Returns:: Array of shape (14,)

get_params_dict()[source]

Get current parameters as dictionary.

Return type:: dict[str, float]

set_params(params)[source]

Set parameter values.

Parameters:: params (ndarray | dict[str, float]) – Either array of shape (14,) or dict with param names
Return type:: None

compute_correlation(phi_angle=0.0, params=None, contrast=None, offset=None, angle_idx=0)[source]

Compute two-time correlation matrix.

Parameters:

phi_angle (float) – Detector phi angle (degrees)
params (ndarray | None) – Optional parameter array (uses stored values if None)
contrast (float | None) – Speckle contrast override. If None, uses per-angle scaling.
offset (float | None) – Baseline offset override. If None, uses per-angle scaling.
angle_idx (int) – Angle index for per-angle scaling lookup (0-based).

Return type:

Array

Returns:

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

compute_residuals(c2_data, phi_angle=0.0, params=None, weights=None, contrast=None, offset=None, angle_idx=0)[source]

Compute residuals between model and data.

Parameters:

c2_data (ndarray | Array) – Experimental correlation data
phi_angle (float) – Detector phi angle
params (ndarray | None) – Optional parameter array
weights (ndarray | Array | None) – Optional weights (1/sigma²)
contrast (float | None) – Speckle contrast override. If None, uses per-angle scaling.
offset (float | None) – Baseline offset override. If None, uses per-angle scaling.
angle_idx (int) – Angle index for per-angle scaling lookup (0-based).

Return type:

Array

Returns:

Flattened residual array

compute_g1_reference(params=None)[source]

Compute reference g1 correlation.

Parameters:: params (ndarray | None) – Optional parameter array
Return type:: Array
Returns:: g1_ref array, shape (N,)

compute_g1_sample(params=None)[source]

Compute sample g1 correlation.

Parameters:: params (ndarray | None) – Optional parameter array
Return type:: Array
Returns:: g1_sample array, shape (N,)

compute_fraction(params=None)[source]

Compute sample fraction evolution.

Parameters:: params (ndarray | None) – Optional parameter array
Return type:: Array
Returns:: f_sample array, shape (N,)

create_residual_function(c2_data, phi_angle, weights=None, angle_idx=0)[source]

Create a residual function for optimization.

Returns a function that takes varying parameters and returns residuals.

Parameters:

c2_data (ndarray | Array) – Experimental correlation data
phi_angle (float) – Detector phi angle
weights (ndarray | Array | None) – Optional weights
angle_idx (int) – Index into per-angle scaling for contrast/offset lookup.

Return type:

Any

Returns:

Callable that maps varying params -> residuals

summary()[source]

Return summary of model configuration.

Return type:: str
Returns:: Multi-line summary string

__init__(_model=<factory>, param_manager=<factory>, _factors=None, scaling=<factory>, _t=None)