homodyne.core.theory

The theory module provides TheoryEngine, a high-level interface to all theoretical computations for homodyne scattering analysis. It wraps the low-level JAX-compiled functions in homodyne.core.jax_backend with input validation, performance monitoring, and graceful error handling.

Note

TheoryEngine is primarily useful for interactive exploration and visualisation. For batch fitting, use fit_nlsq_jax() or fit_mcmc_jax() directly. See Theory & Physics for the physics derivation.

TheoryEngine

class homodyne.core.theory.TheoryEngine[source]

Bases: object

High-level interface for theoretical homodyne calculations.

Manages model selection, parameter validation, and efficient computation orchestration for homodyne scattering analysis.

__init__(analysis_mode='laminar_flow')[source]

Initialize theory engine with specified analysis mode.

Parameters:

analysis_mode (str) – “static” or “laminar_flow”

compute_g1(params, t1, t2, phi, q, L, dt=None)[source]

Compute g1 correlation function.

Parameters:

  • params (ndarray) – Physical parameters

  • t1 (ndarray) – Time grids

  • t2 (ndarray) – Time grids

  • phi (ndarray) – Angle grid

  • q (float) – Wave vector magnitude

  • L (float) – Sample-detector distance

  • dt (float | None) – Time step (if None, will be estimated from t1)

Return type:

Any

Returns:

g1 correlation function

compute_g2(params, t1, t2, phi, q, L, contrast, offset, dt=None)[source]

Compute g2 with scaled fitting: g₂ = offset + contrast × [g₁]²

This is the core equation for homodyne analysis.

Parameters:

  • params (ndarray) – Physical parameters

  • t1 (ndarray) – Time grids

  • t2 (ndarray) – Time grids

  • phi (ndarray) – Angle grid

  • q (float) – Wave vector magnitude

  • L (float) – Sample-detector distance

  • contrast (float) – Contrast parameter

  • offset (float) – Baseline offset

  • dt (float | None) – Time step in seconds. Required — unlike compute_g1, there is no dt estimation fallback for g2 because sinc_prefactor requires an exact dt. Pass dt explicitly from configuration.

Return type:

Any

Returns:

g2 correlation function

Raises:

ValueError – If dt is None.

compute_chi_squared(params, data, sigma, t1, t2, phi, q, L, contrast, offset)[source]

Compute chi-squared goodness of fit.

Parameters:

  • params (ndarray) – Physical parameters

  • data (ndarray) – Experimental correlation data

  • sigma (ndarray) – Measurement uncertainties

  • t1 (ndarray) – Time grids

  • t2 (ndarray) – Time grids

  • phi (ndarray) – Angle grid

  • q (float) – Wave vector magnitude

  • L (float) – Sample-detector distance

  • contrast (float) – Scaling parameters

  • offset (float) – Scaling parameters

Return type:

float

Returns:

Chi-squared value

batch_computation(params_batch, data, sigma, t1, t2, phi, q, L, contrast, offset)[source]

Compute chi-squared for multiple parameter sets efficiently.

Leverages JAX vectorization for optimal performance.

Parameters:

  • params_batch (ndarray) – Array of parameter sets (n_sets, n_params)

  • data (ndarray) – Experimental correlation data

  • sigma (ndarray) – Measurement uncertainties

  • t1 (ndarray) – Time grids

  • t2 (ndarray) – Time grids

  • phi (ndarray) – Angle grid

  • q (float) – Wave vector magnitude

  • L (float) – Sample-detector distance

  • contrast (float) – Scaling parameters

  • offset (float) – Scaling parameters

Return type:

Any

Returns:

Chi-squared values for each parameter set

estimate_computation_cost(t1, t2, phi)[source]

Estimate computational cost for given data dimensions.

Helps with performance planning and memory management.

Parameters:
Return type:

dict[str, Any]

Returns:

Cost estimation dictionary

get_model_info()[source]

Get comprehensive model and engine information.

Return type:

dict[str, Any]

compute_g1

Computes the normalised field autocorrelation function:

\[g_1(\varphi, t_1, t_2) = g_1^\text{diff}(t_1, t_2) \times g_1^\text{shear}(\varphi, t_1, t_2)\]

Parameters params must be ordered according to the analysis_mode:

  • "static": [D0, alpha, D_offset]

  • "laminar_flow": [D0, alpha, D_offset, gamma_dot0, beta, gamma_dot_t_offset, phi0]

compute_g2

Computes the normalised intensity correlation function using the Siegert relation:

\[g_2(\varphi, t_1, t_2) = \text{offset} + \text{contrast} \times [g_1(\varphi, t_1, t_2)]^2\]

Usage Examples

Static mode

import numpy as np
from homodyne.core.theory import TheoryEngine

engine = TheoryEngine(analysis_mode="static")

# Parameters: [D0, alpha, D_offset]
params = np.array([100.0, 0.5, 0.01])

t1 = np.linspace(0.001, 1.0, 100)
t2 = np.linspace(0.001, 1.0, 100)
phi = np.array([0.0])    # single angle for static mode

g1 = engine.compute_g1(params, t1, t2, phi=phi, q=0.01, L=1000.0)
g2 = engine.compute_g2(params, t1, t2, phi=phi, q=0.01, L=1000.0,
                       contrast=0.5, offset=1.0)

Laminar-flow mode (multi-angle)

import numpy as np
from homodyne.core.theory import TheoryEngine

engine = TheoryEngine(analysis_mode="laminar_flow")

# Parameters: [D0, alpha, D_offset, gamma_dot0, beta, gamma_dot_t_offset, phi0]
params = np.array([100.0, 0.5, 0.01, 1e-3, 0.0, 0.0, 0.0])

t1 = np.linspace(0.001, 2.0, 200)
t2 = np.linspace(0.001, 2.0, 200)
phi = np.array([0.0, 45.0, 90.0, 135.0])   # four azimuthal angles (degrees)

g2 = engine.compute_g2(params, t1, t2, phi=phi, q=0.01, L=1000.0,
                       contrast=0.5, offset=1.0, dt=0.001)

Checking backend availability

from homodyne.core.jax_backend import jax_available

if jax_available:
    print("JAX backend active — JIT compilation enabled")
else:
    print("Falling back to NumPy — slower but correct")

Theory Computation Engine for Homodyne

High-level interface to theoretical calculations for homodyne scattering analysis. This module provides user-friendly wrappers around the JAX backend functions with proper error handling, validation, and computational management.

The theory engine handles: - Model selection and parameter management - Efficient computation orchestration - Memory management for large datasets - Error handling and validation - Performance monitoring and optimization hints

homodyne.core.theory.compute_g2_theory(params, t1, t2, phi, q, L, contrast, offset, analysis_mode='laminar_flow', dt=None)[source]

Direct computation of g2 theory. Convenience wrapper for one-off calculations.

Note: Creates a new TheoryEngine per call (includes model init overhead, logger I/O, and jnp.array construction). For repeated calls (e.g. parameter sweeps), create a single TheoryEngine instance and call engine.compute_g2() directly.

Parameters:

  • params (ndarray) – Physical parameters

  • t1 (ndarray) – Time grids

  • t2 (ndarray) – Time grids

  • phi (ndarray) – Angle grid

  • q (float) – Wave vector magnitude

  • L (float) – Sample-detector distance

  • contrast (float) – Scaling parameters

  • offset (float) – Scaling parameters

  • analysis_mode (str) – Analysis mode

  • dt (float | None) – Time step in seconds. Required for g2 (no estimation fallback).

Return type:

Any

Returns:

g2 correlation function

homodyne.core.theory.compute_chi2_theory(params, data, sigma, t1, t2, phi, q, L, contrast, offset, analysis_mode='laminar_flow')[source]

Direct computation of chi-squared with minimal overhead.

Parameters:

  • params (ndarray) – Physical parameters

  • data (ndarray) – Experimental data

  • sigma (ndarray) – Uncertainties

  • t1 (ndarray) – Time grids

  • t2 (ndarray) – Time grids

  • phi (ndarray) – Angle grid

  • q (float) – Wave vector magnitude

  • L (float) – Sample-detector distance

  • contrast (float) – Scaling parameters

  • offset (float) – Scaling parameters

  • analysis_mode (str) – Analysis mode

Return type:

float

Returns:

Chi-squared value