nexatom-downloads

Intensity Correlation (CORL/CORM)

The Intensity Correlation module provides two simultaneous real-time hardware correlators:

  1. Linear Correlator (CORL): Evaluates g²(τ) over 80 linearly spaced lag points. Ideal for short, deterministic delays.
  2. Multi-Tau Correlator (CORM): Evaluates g²(τ) over 80 logarithmically spaced lag points. Capable of evaluating 6+ decades of time (nanoseconds to seconds) with extremely low computational overhead. This is the foundation for DLS and FCS physics analysis.

Function Reference

Function Parameters (In/Out) Returns Description
nexatom_tt_enable_intensity_correlation [In] nexatom_tt_handle device
[In] bool enable		 nexatom_error_code_t Global switch for the intensity correlation engine. Must be true to use either CORL or CORM.
nexatom_tt_enable_linear_correlator [In] nexatom_tt_handle device
[In] bool enable		 nexatom_error_code_t Arms the internal Linear Correlator (CORL) hardware.
nexatom_tt_enable_multi_tau_correlator [In] nexatom_tt_handle device
[In] bool enable		 nexatom_error_code_t Arms the internal Multi-Tau Correlator (CORM) hardware.
nexatom_tt_set_intensity_correlation_channel_a [In] nexatom_tt_handle device
[In] uint8_t channel		 nexatom_error_code_t Sets the first input channel for the correlation (0-7).
nexatom_tt_set_intensity_correlation_channel_b [In] nexatom_tt_handle device
[In] uint8_t channel		 nexatom_error_code_t Sets the second input channel. If A = B, it acts as auto-correlation. If A ≠ B, it acts as cross-correlation.
nexatom_tt_set_intensity_correlation_bin_width [In] nexatom_tt_handle device
[In] uint32_t bin_width_in_8ns_units		 nexatom_error_code_t Sets the base sampling period T in units of 8 nanoseconds. For example, a value of 1 gives T = 8 ns, a value of 125 gives T = 1 μs. For CORL, τᵢ = i × T.
nexatom_tt_set_intensity_correlation_num_bins [In] nexatom_tt_handle device
[In] uint32_t num_bins		 nexatom_error_code_t Configures integration sample depth, with native profile-specific validation; not the 80 returned lag points.
nexatom_tt_start_intensity_correlation [In] nexatom_tt_handle device nexatom_error_code_t Requests START for enabled correlators; observe measurement results separately.
nexatom_tt_stop_intensity_correlation [In] nexatom_tt_handle device nexatom_error_code_t Requests stopping correlation. The correlators mark no final batch, so the result is final once no batch has arrived for 200 ms; exactly one STOPPED result follows within 2 s.
nexatom_tt_set_result_span, nexatom_tt_set_run_end, nexatom_tt_clear_result processor = NEXATOM_RESULT_PROCESSOR_CORRELATION nexatom_error_code_t One setting covers CORL and CORM: NEXATOM_RESULT_PROCESSOR_CORRELATION is the only correlator processor, so the two cannot have different spans or run ends. See the result model. A correlator batch is num_bins × T.

Data Structures: Callback Payloads

When the correlator dispatches a completed cycle, it emits either a nexatom_corl_callback_data_t or a nexatom_corm_callback_data_t via the callback registered in Section 7.8.

Both structs share a very similar 80-bin array layout, but CORM contains additional nested structures for C++ background curve fitting and embedded DLS/FCS models.

Field Type Description
g2_values float[80] The normalized g²(τ) correlation function values. Expected baseline ≈ 1.0. NaN where g² is undefined; all NaN when normalization_valid is 0.
lag_times_ns uint64_t[80] The actual τ lag time for each bin in nanoseconds. (Linear for CORL, quasi-logarithmic for CORM).
baseline_level float g²(∞) - Evaluated correlation at infinite lag.
contrast float g²(0) − g²(∞) - The amplitude of the correlation peak.
mean_intensity_a / b float Mean counts per integration sample, sum of counts divided by sample count; not rates in Hz.
fit_result (CORM Only) struct Output from the background C++ Levenberg-Marquardt engine (e.g., chi_squared, correlation_time_ns).
analysis_result (CORM Only) struct Contains nested physics data if DLS, FCS, or DCS analysis modules are activated (See sections 7.12 - 7.14).
packets_accumulated uint32_t Hardware batches pooled in this result.
result_status nexatom_result_status_t Why the result was published: RUNNING, BLOCK_COMPLETE, RUN_COMPLETE or STOPPED. See result model.
result_span nexatom_result_span_t What it covers: WHOLE_RUN or BLOCK.
block_index uint64_t Zero-based block number in BLOCK; 0 in WHOLE_RUN.
live_time_ms double Measurement time in the result, Σ N × T over the pooled batches.
live_time_exact uint8_t 1 when every batch had a known length; 0 when Stop ended a batch.

Integration and result validity

nexatom_tt_set_intensity_correlation_num_bins configures integration sample depth, not the number of returned lags (the callback arrays have 80 points). Native validates the applicable depth range: OG uses 1000–65535 and UTT requires at least 4096. The bin-width API retains 8 ns units; native translates for the active profile.

Inspect normalization_valid, sum_a_counts, sum_b_counts and sample_count. A value in the historically named g2_values array is not necessarily normalized g² when normalization is invalid. Retain the supplied lag axis and result metadata. A correlator result pools its batches before normalising (per lag Σ(mean-product × N), plus ΣA, ΣB and ΣN) and normalises g² once per published result.

The exported CORM analysis type selects one result, with DLS then FCS then DCS priority when multiple results are available. Enabling an analysis does not guarantee a successful fit or selected output; see analysis validity.