BCFTMW

BCFTMW is the CP-FTMW container exposed by BCExperiment as exp.ftmw whenever the experiment folder contains an fid/ subdirectory. It loads fid/fidparams.csv and fid/processing.csv once at construction and serves BCFid objects on demand through get_fid; the per-FID waveform data is read lazily, so opening a large experiment is cheap.

The ftmw_type attribute carries the FtmwType value from objectives.csv and gates the API surface that is meaningful for each acquisition mode. Target_Shots, Target_Duration, and Forever acquisitions store their cumulative final FID as 0.csv and intermediate backups as 1.csv, 2.csv, …; get_differential_fid exposes shots collected between two backup points by subtracting their raw integer data. LO_Scan, DR_Scan, and Peak_Up acquisitions store independent segments instead, so get_differential_fid is rejected for those modes and num_backups returns zero.

process_sideband performs the same sideband deconvolution that Blackchirp’s GUI applies to LO-scan acquisitions. Frequency-shifted copies of every segment’s FT are interpolated onto a common global grid, the chosen sideband(s) are co-averaged, and the result is returned in the requested frequency units. The algorithm and the upper / lower / both options are described in detail on the CP-FTMW user-guide page under “Sideband Deconvolution”.

API Reference

class blackchirp.BCFTMW(path: str, sep: str, ftmw_type: str = '')

Storage object for CP-FTMW data

The BCFTMW class loads FID and processing data for CP-FTMW experiments. It provides functions for accessing FIDs and for performing processing tasks that involve analyzing multiple FIDs in a single operation (e.g., sideband deconvolution in an LO Scan experiment).

This class is not meant to be initialized directly by the user; it is created automatically by BCExperiment.

Parameters:

  • path – Path to fid directory

  • sep – CSV delimiter

  • ftmw_type – FtmwType value from objectives.csv. Used to gate the differential-FID API to single-segment acquisitions.

Examples

Loading an experiment and reading a FID (0.csv):

from blackchirp import *

exp = BCExperiment('path/to/experiment')

# The BCFTMW object is exp.ftmw if the experiment contains CP-FTMW data.

fid = exp.ftmw.get_fid()

Performing upper sideband deconvolution, harmonic mean, FT range 0.1-1.0 GHz per segment:

x, y = exp.ftmw.process_sideband(which='upper',
                                 avg='harmonic',
                                 min_ft_offset=100.0,
                                 max_ft_offset=1000.0)

Viewing only the shots collected after the second backup, mirroring Blackchirp’s “differential backup” view:

diff_fid = exp.ftmw.get_differential_fid(start=2)
x, y = diff_fid.ft()
fidparams

Contents of fidparams.csv file

Type:

DataFrame

proc

Contents of processing.csv file

Type:

dict

numfids

Number of FIDs specified in fidparams.csv

Type:

int

ftmw_type

FtmwType value from objectives.csv (e.g. "Forever", "LO_Scan").

Type:

str

get_differential_fid(start: int = 0, end: int = -1) → BCFid

Build a FID from shots collected between two backup points.

Mirrors Blackchirp’s “differential backup” view, with a more general two-bound interface. The returned BCFid represents the shots collected between backup start and backup end: its raw integer data is raw[end] - raw[start] and its fidparams.shots is shots[end] - shots[start].

Parameters:

  • start – Backup index to subtract. 0 (default) means do not subtract anything — the differential begins at the start of the experiment. A positive value loads start.csv and subtracts it from the upper-bound FID.

  • end – Backup index to use as the upper bound. -1 (default) means the cumulative final FID (0.csv). A positive value loads end.csv.

Returns:

A BCFid containing the differential data, with fidparams.shots and shots set to the shot difference.

Raises:

ValueError – If the experiment is multi-segment (LO_Scan, DR_Scan, Peak_Up — backups do not exist for these modes), if start or end is out of range, if the resolved (start, end) pair is not strictly ordered, or if the start and end FIDs have a different number of frames.

get_fid(num: int = 0) → BCFid

Loads a (potentially multi-frame) FID from disk.

For standard acquisition modes (Target Shots, Target Time, and Forever), the complete FID is stored as 0.csv and would correspond to num=0, the default. Any other CSV files are backups and are accessed by providing the desired backup number for num.

For other acquisition modes that consist of several segments (LO Scan, DR Scan), num corresponds to the desired segment.

Parameters:

num – Number of FID file to load.

Returns:

A BCFid object containing the requested FID

Raises:

ValueError – If num is out of range for this experiment.

is_multi_segment() → bool

Indicate whether the FID files represent independent segments.

Returns:

True for LO_Scan, DR_Scan, and Peak_Up acquisitions, where each N.csv is an independent segment rather than a backup. False for Target_Shots, Target_Duration, and Forever, where 0.csv is the cumulative final FID and 1.csv, 2.csv, … are intermediate backups.

num_backups() → int

Return the number of backup FIDs available.

Returns:

Number of intermediate backup FIDs available (len(fidparams) - 1 for single-segment acquisitions; 0 for multi-segment acquisitions, which do not have backups).

process_sideband(which: str = 'both', avg: str = 'harmonic', min_ft_offset: float = None, max_ft_offset: float = None, frame: int = 0, verbose: bool = False, freq_units: str = 'MHz', **proc_kwargs) → tuple[numpy.ndarray, numpy.ndarray]

Performs sideband deconvolution on an LO Scan experiment

See Sideband Deconvolution for an explanation of the purpose of the algorithm. The arguments correspond to the options available in the Sideband Processing and FID processing menus in Blackchirp.

Parameters:

  • which – {‘both’, ‘upper’, ‘lower’} Sideband to use in deconvolution.

  • avg – {‘harmonic’, ‘geometric’} Whether to use a harmonic or geometric mean for overlapped segments.

  • min_ft_offset – Minimum offset frequency for sideband, in MHz. Value is relative to the Downconversion LO frequency. Defaults to 0.0 MHz.

  • max_ft_offset – Maximum offset frequency for sideband, in MHz. Value is relative to the Downconversion LO frequency. Defaults to the FT bandwidth.

  • frame – Frame number (indexed from 0). If negative, all frames will be averaged

  • verbose – If true, print a progress message during the deconvolution.

  • freq_units – Units for the returned frequency array. One of "Hz", "kHz", "MHz" (default), "GHz", "THz". min_ft_offset and max_ft_offset are always interpreted in MHz regardless of this choice.

  • **proc_kwargs – FID processing settings passed as **kwargs to BCFid.ft. A freq_units entry here is ignored — the deconvolution is computed in MHz and rescaled at the end via the explicit freq_units argument.

Returns:

Frequency (in freq_units) and intensity arrays for the processed spectrum.

Raises:

ValueError – If which is not one of 'both', 'upper', 'lower'; if avg is not 'harmonic' or 'geometric'; if min_ft_offset or max_ft_offset is non-positive; if freq_units is not a recognised frequency-unit string; or if any FID’s sideband value is unrecognised (propagated from BCFid.is_lower_sideband).