Coaverage

For combining FIDs across separate Blackchirp experiments, the blackchirp package exports two module-level helpers alongside its classes. They live at the package root because their inputs span more than one BCExperiment and their outputs are not methods on any single existing object.

coaverage_fids() performs the coaverage in the time domain. It returns a BCFid whose raw integer data is the sample-by-sample sum of every input and whose shot count is the sum of input shot counts; voltage data is recomputed from those sums and the shared vmult. Phase correction is optional: when both pc_start_us and pc_end_us are supplied each non-reference FID is shifted along the time axis by the integer offset that maximises the cross-correlation between its windowed data and that of the reference FID. The reference defaults to the highest-shot input but may be selected by index. A single shift per FID is applied to all frames by default, on the assumption that the frames share a clock; per_frame_pc=True switches to one shift per frame.

coaverage_spectra() performs a shot-weighted coaverage of magnitude spectra. Each input FID is Fourier-transformed with the same processing kwargs and the resulting magnitudes are combined as \(y = \sum_i s_i\, |Y_i| / \sum_i s_i\) where \(s_i\) is the shot count of FID \(i\). This avoids time-domain alignment entirely but does not reduce the noise floor — the Rayleigh-distributed noise mean is invariant under averaging, only its fluctuation drops. Reach for this function when phase drift across experiments defeats time-domain alignment; otherwise prefer coaverage_fids().

Both entry points enforce strict compatibility between their inputs: matching spacing, size, sideband, probefreq, vmult, and frame count. Float-valued fields are compared with exact equality; mismatches raise ValueError rather than being silently coerced. The C++ acquisition path does not have an analogous cross-experiment coaverage primitive, so the Python module is the canonical home.

API Reference

blackchirp.coaverage_fids(fids: Sequence[BCFid], *, pc_start_us: float = None, pc_end_us: float = None, reference: int | str = 'max_shots', per_frame_pc: bool = False) → BCFid

Coaverage of multiple FIDs in the time domain.

The result is a BCFid whose raw integer data is the sample-by-sample sum of every input’s raw data and whose fidparams.shots is the sum of every input’s shot count. Voltage data is recomputed as rawdata * vmult / total_shots.

All input FIDs must agree on spacing, size, sideband, probefreq, vmult, and frame count; mismatches raise ValueError. Coaverage of FIDs taken with different digitizer settings is not supported — preprocess inputs to a common representation before calling.

Phase correction is optional: when both pc_start_us and pc_end_us are supplied, each non-reference FID is shifted along the time axis by the integer offset that maximises the cross-correlation between its windowed data and the windowed data of the reference FID. A single shift is applied to all frames of a given FID, which assumes the frames share a clock; pass per_frame_pc=True to compute and apply one shift per frame instead.

Parameters:

  • fids – Sequence of FIDs to coaverage. Already-loaded BCFid objects only — paths are not accepted, so callers can choose backups, differential FIDs, or frame-averaged FIDs as inputs.

  • pc_start_us – Start of the phase-correction window, in μs. If either bound is None, phase correction is disabled and the FIDs are summed without alignment. The window should cover a signal-rich portion of the FID (e.g. the chirp ring-down) — cross-correlation is computed on de-meaned data, so a window that is mostly noise will return an unreliable shift.

  • pc_end_us – End of the phase-correction window, in μs.

  • reference – Index of the FID to use as the phase-correction reference, or the string "max_shots" (default) to pick the FID with the highest shot count. Ties resolve to the first match.

  • per_frame_pc – If True, compute a separate shift for each (FID, frame) pair instead of one shift per FID.

Returns:

A new BCFid containing the coaveraged data. Inputs are not mutated.

Raises:

  • ValueError – If fids is empty, if any compatibility check fails, if exactly one of pc_start_us/pc_end_us is provided, if the resolved phase-correction window is outside [0, size), or if reference is an invalid index or string.

  • TypeError – If any element of fids is not a BCFid or if reference is neither int nor str.

blackchirp.coaverage_spectra(fids: Sequence[BCFid], **ft_kwargs) → tuple[numpy.ndarray, numpy.ndarray]

Shot-weighted coaverage of magnitude spectra.

Each input FID is Fourier-transformed via BCFid.ft() with the supplied processing kwargs, and the magnitude spectra are combined as

\[y = \frac{\sum_i s_i\, |Y_i|}{\sum_i s_i}\]

where \(s_i\) is the shot count of FID \(i\). The same compatibility checks as coaverage_fids() apply, ensuring every spectrum lands on the same frequency grid.

Note that magnitude-spectrum coaveraging does not reduce the noise floor — the Rayleigh-distributed noise mean is invariant under averaging — only its fluctuation. Use coaverage_fids() when phase coherence between experiments is good enough to align in the time domain; reach for this function when phase drift defeats time-domain alignment.

Parameters:

  • fids – Sequence of FIDs to coaverage.

  • **ft_kwargs – Forwarded to BCFid.ft(). The same kwargs are applied to every FID so that all spectra share a frequency grid and processing.

Returns:

Frequency array (in the units selected by the freq_units kwarg, default MHz) and the shot-weighted magnitude-spectrum array. The intensity array preserves the per-frame second axis from BCFid.ft().

Raises:

ValueError – If fids is empty, if any compatibility check fails, or if any FID’s ft() returns a frequency array that disagrees with the reference (which should not happen given the compatibility checks but is asserted defensively).