FtmwConfig

FtmwConfig is the abstract base class that unifies the digitizer configuration, RF/chirp settings, and FID storage for a CP-FTMW acquisition. It inherits both ExperimentObjective — which gives it the lifecycle interface (initialize, advance, hwReady, cleanupAndSave) — and HeaderStorage, which serializes the configuration alongside the experiment data. A concrete subclass is selected at setup time based on the FtmwType enumerator; the six concrete types are defined in ftmwconfigtypes.h and documented below.

RF and chirp settings are held by RfConfig (see RfConfig), accessible through the public member d_rfConfig. Digitizer settings are encapsulated in an FtmwDigitizerConfig shared instance (accessible via digitizerConfig()). The FTMW configuration dialog and the user-facing setup workflow are covered in FTMW Configuration; digitizer setup specifics appear in Digitizer Setup.

WaveformBuffer integration

FtmwConfig holds a non-owning pointer to a WaveformBuffer object. The buffer is created and owned by the FtmwDigitizer hardware object, which calls setWaveformBuffer() during acquisition setup; FtmwConfig must not free or outlive this pointer. AcquisitionManager retrieves the buffer through waveformBuffer() and drains it in a worker thread, calling addBatchFids() with each batch of Fid objects (see Fid).

API Reference

class FtmwConfig : public ExperimentObjective, public HeaderStorage 

Abstract base class for FTMW experiment configurations.

FtmwConfig brings together the digitizer configuration, RF/chirp configuration, and FID storage for a single CP-FTMW acquisition. Concrete subclasses (FtmwConfigSingle, FtmwConfigForever, etc.) implement the completion and storage logic appropriate for each acquisition mode.

The class also drives the chirp-quality pipeline: phase-correction cross-correlates each incoming FID against the running average to find the optimal sample shift, and chirp scoring rejects shots whose chirp RMS falls below a configurable threshold.

FtmwConfig holds a non-owning pointer to the experiment’s WaveformBuffer. The buffer is created and owned by the FtmwDigitizer hardware object; FtmwConfig receives the pointer at acquisition setup time and must not free it.

See also

RfConfig, FtmwDigitizerConfig, FidStorageBase

Subclassed by FtmwConfigDRScan, FtmwConfigDuration, FtmwConfigForever, FtmwConfigLOScan, FtmwConfigPeakUp, FtmwConfigSingle

Public Types

enum FtmwType

Selects the acquisition termination criterion.

Values:

enumerator Target_Shots: Stop after accumulating a fixed number of shots.

enumerator Target_Duration: Stop after a fixed wall-clock duration.

enumerator Forever: Accumulate indefinitely until manually stopped.

enumerator Peak_Up: Rolling-average peak-up mode; does not terminate automatically.

enumerator LO_Scan: Step the local oscillator through a frequency range.

enumerator DR_Scan: Step a double-resonance drive frequency through a range.

Public Functions

FtmwConfig(const QString &digitizerHwKey)

Construct with the hardware key of the FtmwDigitizer to use.

Parameters:: digitizerHwKey – Hardware key string identifying the digitizer.

FtmwConfig(const FtmwConfig&) = default

FtmwConfig &operator=(const FtmwConfig&) = default

virtual ~FtmwConfig()

inline FtmwDigitizerConfig &digitizerConfig(): Return a mutable reference to the digitizer configuration.

inline const FtmwDigitizerConfig &digitizerConfig() const: Return a const reference to the digitizer configuration.

virtual bool initialize() override

Initialize FID storage, the FID template, and RF configuration.

Returns:: true on success; sets d_errorString and returns false on failure.

virtual bool advance() override

Advance multi-segment acquisitions (LO/DR scans) and trigger autosave.

Returns:: true if a segment boundary was crossed, false otherwise.

virtual void hwReady() override

Update the FID template probe frequency when hardware is ready.

Called after all hardware objects report readiness. Clears the processing-paused flag so incoming FIDs are processed.

virtual bool abort() override: Abort the acquisition; always returns false (no-op for FTMW).

virtual void cleanupAndSave() override: Finalize FID storage and flush data to disk.

inline virtual bool indefinite() const override

Return false; FTMW objectives are not indefinite by default.

Subclasses that implement forever or duration-with-continue modes override this to return true under the appropriate conditions.

virtual quint64 completedShots() const = 0

Return the total number of shots accumulated so far.

Must be implemented by each concrete subclass; the value drives progress reporting and completion checks.

quint64 shotIncrement() const

Return the number of shots represented by one waveform transfer.

For block-average modes this equals d_numAverages; otherwise 1.

FidList parseWaveform(const QByteArray b) const

Parse a raw waveform byte array into a FidList.

Parameters:: b – Raw waveform bytes from the digitizer.
Returns:: Parsed FidList ready for accumulation.

FidList parseBatchFids(const std::vector<WaveformEntry> &entries) const

Parse and combine a batch of WaveformEntry objects into a FidList.

Uses parallel processing when the record is large enough to benefit.

See also

addBatchFids

Parameters:: entries – Batch of raw-waveform entries from the WaveformBuffer drain cycle.
Returns:: FidList with shot count equal to the sum of all entry shot counts.

bool addBatchFids(const std::vector<WaveformEntry> &entries)

Parse, optionally preprocess, and accumulate a batch of waveform entries.

Calls parseBatchFids(), runs chirp scoring and phase correction if enabled, then forwards the combined result to FID storage.

Parameters:: entries – Batch of raw-waveform entries.
Returns:: true if the FIDs were accepted and added; false on rejection or error.

double ftMinMHz() const: Return the minimum frequency of the FTMW spectral window in MHz.

double ftMaxMHz() const: Return the maximum frequency of the FTMW spectral window in MHz.

double ftNyquistMHz() const: Return the Nyquist frequency of the digitizer in MHz (half the sample rate).

double fidDurationUs() const: Return the FID record duration in microseconds.

inline double chirpFOM() const: Return the chirp figure of merit from the most recently processed shot.

inline double chirpShift() const: Return the phase-correction sample shift applied to the most recent shot.

inline double chirpRMS() const: Return the chirp RMS of the running average from the most recent preprocessing pass.

QPair<int, int> chirpRange() const

Calculate the start sample index and sample count of the chirp window within the FID record.

Uses the first chirp segment duration and the digitizer sample rate. The chirp start is taken from d_chirpOffsetUs when non-negative; otherwise it is derived from the Trigger marker time or the protection/gate lead time.

Returns:: QPair where the first element is the start sample index and the second is the number of samples spanning the chirp.

bool setFidsData(const QVector<QVector<qint64>> newList)

Replace the accumulated FID data for all records.

Constructs a FidList from newList using the current FID template and forwards it to FID storage.

Parameters:: newList – New raw data vectors, one per record channel.
Returns:: true if storage accepted the data.

bool addFids(const QByteArray rawData)

Parse, optionally preprocess, and accumulate a single raw waveform.

Parameters:: rawData – Raw waveform bytes from the digitizer.
Returns:: true if the FID was accepted.

bool addPreAccumulatedFids(const QByteArray &data, quint64 shotCount)

Accept and accumulate a pre-parsed array of qint64 FID values.

Used when the WaveformBuffer producer has already accumulated raw bytes into qint64 format (backpressure pre-accumulation path). Chirp scoring and phase correction are still applied if enabled.

Parameters:

data – Raw bytes encoding a flat array of qint64 samples.
shotCount – Number of shots represented by data.

Returns:

true on success.

std::shared_ptr<FidStorageBase> storage() const: Return the shared FID storage object for this configuration.

void setWaveformBuffer(WaveformBuffer *buf)

Set the non-owning pointer to the experiment’s WaveformBuffer.

The buffer is created and owned by the FtmwDigitizer hardware object. FtmwConfig stores the pointer so that AcquisitionManager can retrieve it via waveformBuffer() without accessing the hardware object directly. FtmwConfig does not take ownership and must not delete the pointer.

See also

waveformBuffer

Parameters:: buf – Pointer to the buffer, or nullptr to clear it.

WaveformBuffer *waveformBuffer() const

Return the non-owning pointer to the experiment’s WaveformBuffer.

May be nullptr before acquisition setup or after cleanup. The pointed-to object is owned by the FtmwDigitizer hardware object.

See also

setWaveformBuffer

void loadFids()

Reconstruct FID storage from disk for post-acquisition loading.

Creates the appropriate FidStorageBase subclass using the experiment number and path stored in d_number / d_path.

inline quint8 getBitShift() const: Public accessor for the protected bitShift() virtual.

virtual bool _init() = 0

Subclass hook called at the end of initialize().

Returns:: true on success; sets d_errorString and returns false on failure.

virtual void _prepareToSave() = 0: Subclass hook called during HeaderStorage serialization to store mode-specific fields.

virtual void _loadComplete() = 0: Subclass hook called during HeaderStorage deserialization to restore mode-specific state.

virtual std::shared_ptr<FidStorageBase> createStorage(int num, QString path = "") = 0

Factory method: create the FID storage object for this acquisition mode.

Parameters:

num – Experiment number used to construct the storage path.
path – Optional explicit base path; empty uses the default data directory.

Returns:

Shared pointer to the newly created FidStorageBase subclass.

Public Members

bool d_phaseCorrectionEnabled = {false}: Enable per-shot phase correction (cross-correlation shift).

bool d_chirpScoringEnabled = {false}: Enable chirp quality scoring; shots below threshold are rejected.

double d_chirpRMSThreshold = {0.0}: Minimum chirp RMS relative to running average (used when d_chirpScoringEnabled is true).

double d_chirpOffsetUs = {-1.0}: Manual chirp start offset in microseconds; negative means auto-detect from marker.

FtmwType d_type = {Forever}: Acquisition termination mode for this configuration.

quint64 d_objective = {0}: Numeric objective (target shots or duration ticks, depending on d_type).

RfConfig d_rfConfig: RF chain and chirp configuration for this acquisition.

Protected Functions

virtual void storeValues() override: Serialize FTMW fields into HeaderStorage.

virtual void retrieveValues() override: Deserialize FTMW fields from HeaderStorage.

virtual void prepareChildren() override: Register child HeaderStorage objects (RfConfig, FtmwDigitizerConfig).

virtual QString objectiveKey() const override: Return the experiment-config key used to identify the FtmwType.

virtual QVariant objectiveData() const override: Return the FtmwType enumerator as a QVariant for experiment config storage.

inline virtual quint8 bitShift() const

Return the bit-shift applied to waveform sample values.

The default implementation returns 0. Subclasses may override this to account for extra padding bits inserted by certain acquisition modes (e.g. peak-up rolling average). The shift is used to scale the FID voltage multiplier and to right-shift samples during waveform parsing.

Private Functions

bool preprocessChirp(const FidList l)

float calculateFom(const QVector<qint64> vec, const Fid fid, QPair<int, int> range, int trialShift)

double calculateChirpRMS(const QVector<qint64> chirp, quint64 shots = 1)

Private Members

WaveformBuffer *p_waveformBuffer = {nullptr}

std::shared_ptr<FtmwDigitizerConfig> ps_digitizerConfig

std::shared_ptr<FidStorageBase> p_fidStorage

Fid d_fidTemplate

QDateTime d_lastAutosaveTime

int d_currentShift = {0}

float d_lastFom = {0.0}

double d_lastRMS = {0.0}

class FtmwConfigSingle : public FtmwConfig 

FtmwConfig subclass for target-shots and target-duration modes.

Implements the completion logic for acquisitions that stop after a fixed number of shots (FtmwType::Target_Shots). It is also the base used when constructing a typed FtmwConfig from a deserialized FtmwConfig value object.

Public Functions

FtmwConfigSingle(const QString &digitizerHwKey)

Construct with the hardware key of the FtmwDigitizer.

Parameters:: digitizerHwKey – Hardware key string identifying the digitizer.

FtmwConfigSingle(const FtmwConfig &other)

Construct from a deserialized FtmwConfig value object.

Parameters:: other – Source FtmwConfig.

inline ~FtmwConfigSingle()

virtual int perMilComplete() const override: Return progress in per-mille (0–1000) toward the target shot count.

virtual bool isComplete() const override: Return true when the accumulated shot count reaches d_objective.

virtual quint64 completedShots() const override: Return the total accumulated shot count from FID storage.

Protected Functions

virtual bool _init() override: Initialize mode-specific state at acquisition start.

virtual void _prepareToSave() override: Store mode-specific fields during HeaderStorage serialization.

virtual void _loadComplete() override: Restore mode-specific state during HeaderStorage deserialization.

virtual std::shared_ptr<FidStorageBase> createStorage(int num, QString path = "") override: Create the FID storage object for single-shot mode.

class FtmwConfigPeakUp : public FtmwConfig 

FtmwConfig subclass for peak-up (rolling-average) mode.

Maintains a rolling average of the most recent shots rather than an accumulating sum. Once the target shot count is reached, a non-zero bitShift() supplies additional effective bits of precision for the rolling average.

Public Functions

FtmwConfigPeakUp(const QString &digitizerHwKey)

Construct with the hardware key of the FtmwDigitizer.

Parameters:: digitizerHwKey – Hardware key string identifying the digitizer.

FtmwConfigPeakUp(const FtmwConfig &other)

Construct from a deserialized FtmwConfig value object.

Parameters:: other – Source FtmwConfig.

inline ~FtmwConfigPeakUp()

virtual int perMilComplete() const override: Return progress in per-mille; peak-up never completes automatically.

virtual bool isComplete() const override: Always returns false; peak-up runs indefinitely.

virtual quint64 completedShots() const override: Return the number of shots accumulated since last reset.

Protected Functions

virtual quint8 bitShift() const override: Return the bit-shift that supplies additional effective bits of precision for the rolling average once the target shot count is reached.

virtual bool _init() override: Initialize mode-specific state at acquisition start.

virtual void _prepareToSave() override: Store mode-specific fields during HeaderStorage serialization.

virtual void _loadComplete() override: Restore mode-specific state during HeaderStorage deserialization.

virtual std::shared_ptr<FidStorageBase> createStorage(int num, QString path = "") override: Create the peak-up FID storage object.

class FtmwConfigDuration : public FtmwConfig 

FtmwConfig subclass for target-duration mode.

Terminates acquisition after a wall-clock duration specified by d_objective.

Public Functions

FtmwConfigDuration(const QString &digitizerHwKey)

Construct with the hardware key of the FtmwDigitizer.

Parameters:: digitizerHwKey – Hardware key string identifying the digitizer.

FtmwConfigDuration(const FtmwConfig &other)

Construct from a deserialized FtmwConfig value object.

Parameters:: other – Source FtmwConfig.

inline ~FtmwConfigDuration()

virtual int perMilComplete() const override: Return progress in per-mille toward the target duration.

virtual bool isComplete() const override: Return true when the wall-clock target time has been reached.

virtual quint64 completedShots() const override: Return the total accumulated shot count from FID storage.

Protected Functions

virtual bool _init() override: Initialize mode-specific state and record the start and target times.

virtual void _prepareToSave() override: Store mode-specific fields during HeaderStorage serialization.

virtual void _loadComplete() override: Restore mode-specific state during HeaderStorage deserialization.

virtual std::shared_ptr<FidStorageBase> createStorage(int num, QString path = "") override: Create the FID storage object for duration mode.

Private Members

QDateTime d_startTime

QDateTime d_targetTime: Wall-clock start and target end times.

class FtmwConfigForever : public FtmwConfig 

FtmwConfig subclass for indefinite (forever) averaging mode.

Acquisition continues until manually stopped. indefinite() returns true once the shot counter first reaches the completion threshold, preventing normal completion logic from triggering.

Public Functions

FtmwConfigForever(const QString &digitizerHwKey)

Construct with the hardware key of the FtmwDigitizer.

Parameters:: digitizerHwKey – Hardware key string identifying the digitizer.

FtmwConfigForever(const FtmwConfig &other)

Construct from a deserialized FtmwConfig value object.

Parameters:: other – Source FtmwConfig.

inline ~FtmwConfigForever()

virtual int perMilComplete() const override: Return progress in per-mille; always returns 0 for forever mode.

virtual bool indefinite() const override: Return true to prevent the normal completion check from firing.

virtual bool isComplete() const override: Always returns false; the user must stop acquisition manually.

virtual quint64 completedShots() const override: Return the total accumulated shot count from FID storage.

Protected Functions

virtual bool _init() override: Initialize mode-specific state at acquisition start.

virtual void _prepareToSave() override: Store mode-specific fields during HeaderStorage serialization.

virtual void _loadComplete() override: Restore mode-specific state during HeaderStorage deserialization.

virtual std::shared_ptr<FidStorageBase> createStorage(int num, QString path = "") override: Create the FID storage object for forever mode.

class FtmwConfigLOScan : public FtmwConfig 

FtmwConfig subclass for LO-scan (frequency-sweep) mode.

Steps the local oscillator through an upward and optional downward frequency sweep, accumulating a fixed number of shots at each step. Each pair of (major, minor) step counts defines the scan grid; the minor step size is derived from the LO start/end and major step count.

Public Functions

FtmwConfigLOScan(const QString &digitizerHwKey)

Construct with the hardware key of the FtmwDigitizer.

Parameters:: digitizerHwKey – Hardware key string identifying the digitizer.

FtmwConfigLOScan(const FtmwConfig &other)

Construct from a deserialized FtmwConfig value object.

Parameters:: other – Source FtmwConfig.

inline ~FtmwConfigLOScan()

virtual int perMilComplete() const override: Return progress in per-mille toward completing all LO scan steps.

virtual bool isComplete() const override: Return true when all scan steps and their shot targets are complete.

virtual quint64 completedShots() const override: Return the total accumulated shot count across all segments.

Public Members

double d_upStart = {0.0}: Upward sweep LO start frequency in MHz.

double d_upEnd = {0.0}: Upward sweep LO end frequency in MHz.

double d_downStart = {0.0}: Downward sweep LO start frequency in MHz.

double d_downEnd = {0.0}: Downward sweep LO end frequency in MHz.

int d_upMaj = {0}: Number of major steps in the upward sweep.

int d_upMin = {0}: Number of minor steps per major step in the upward sweep.

int d_downMaj = {0}: Number of major steps in the downward sweep.

int d_downMin = {0}: Number of minor steps per major step in the downward sweep.

Protected Functions

virtual bool _init() override: Initialize mode-specific state and configure LO scan segments in RfConfig.

virtual void _prepareToSave() override: Store LO scan parameters during HeaderStorage serialization.

virtual void _loadComplete() override: Restore LO scan parameters during HeaderStorage deserialization.

virtual std::shared_ptr<FidStorageBase> createStorage(int num, QString path) override: Create the FID storage object for LO scan mode.

class FtmwConfigDRScan : public FtmwConfig 

FtmwConfig subclass for double-resonance (DR) scan mode.

Steps a second microwave source (the DR drive) through an evenly spaced frequency range while collecting a fixed number of shots per step.

Public Functions

FtmwConfigDRScan(const QString &digitizerHwKey)

Construct with the hardware key of the FtmwDigitizer.

Parameters:: digitizerHwKey – Hardware key string identifying the digitizer.

FtmwConfigDRScan(const FtmwConfig &other)

Construct from a deserialized FtmwConfig value object.

Parameters:: other – Source FtmwConfig.

inline ~FtmwConfigDRScan()

virtual int perMilComplete() const override: Return progress in per-mille toward completing all DR scan steps.

virtual bool isComplete() const override: Return true when all DR scan steps and their shot targets are complete.

virtual quint64 completedShots() const override: Return the total accumulated shot count across all DR scan segments.

Public Members

double d_start = {0.0}: DR drive start frequency in MHz.

double d_step = {1.0}: DR drive step size in MHz.

int d_numSteps = {2}: Total number of DR frequency steps.

Protected Functions

virtual bool _init() override: Initialize mode-specific state and configure DR scan segments in RfConfig.

virtual void _prepareToSave() override: Store DR scan parameters during HeaderStorage serialization.

virtual void _loadComplete() override: Restore DR scan parameters during HeaderStorage deserialization.

virtual std::shared_ptr<FidStorageBase> createStorage(int num, QString path) override: Create the FID storage object for DR scan mode.