RfConfig

RfConfig bridges FtmwConfig and ChirpConfig by holding the full RF frequency chain for an FTMW acquisition: the upconversion path from AWG output to the sample, the downconversion path from the received signal to the digitizer, all clock assignments, sweep parameters, and the embedded ChirpConfig. RfConfig is stored as FtmwConfig::d_rfConfig and is a child HeaderStorage node in the experiment header tree. The user-facing RF configuration controls are described in RF Configuration.

Clock semantics

Clocks are assigned by logical role (RfConfig::ClockType): UpLO and DownLO for the up- and downconversion mixers, AwgRef and DigRef for instrument reference inputs, ComRef for a shared 10 MHz (or other) distribution, and DRClock for double-resonance pump sources. When d_commonUpDownLO is true a single hardware source serves both UpLO and DownLO; setting either role via RfConfig::setClockFreqInfo() automatically mirrors the assignment to the other.

Each RfConfig::ClockFreq record holds a desired output frequency, a multiplication or division factor, and the hardware key of the clock source. RfConfig::clockFrequency() returns the desired output frequency; RfConfig::rawClockFrequency() inverts the factor to recover the hardware oscillator frequency that the driver programs.

For non-scan acquisitions the clock configuration list is empty until RfConfig::prepareForAcquisition() is called, at which point the template is copied to form a single-step list. For LO and DR scans, RfConfig::addLoScanClockStep() and RfConfig::addDrScanClockStep() append one entry per frequency point before acquisition begins. Calling RfConfig::advanceClockStep() increments the active step index and, when the step list wraps to zero, increments d_completedSweeps.

Frequency chain calculations

The chirp frequency reaching the sample for a given AWG output frequency is:

chirpFreq = (awgFreq × awgMult ± upLO) × chirpMult

where the sign is positive for the upper sideband and negative for the lower sideband. RfConfig::calculateChirpFreq() and RfConfig::calculateAwgFreq() perform these conversions in both directions. RfConfig::calculateChirpAbsOffset() returns the absolute difference between the chirp frequency and the down-LO, which is the nominal IF center frequency at the digitizer input. The full FTMW digitizer configuration is documented on FtmwConfig.

API Reference

class RfConfig : public HeaderStorage

RF/microwave chain configuration bridging FtmwConfig and ChirpConfig.

RfConfig encapsulates the complete RF frequency chain for an FTMW experiment: the upconversion path (AWG output → mixer → optional multiplier → sample), the downconversion path (received signal → mixer), the clock assignments for up-LO, down-LO, AWG reference, digital-receiver reference, common reference, and double-resonance (DR) sources, the target sweep count, and the embedded ChirpConfig.

Clock frequencies are stored in two layers:

• A clock template (d_clockTemplate) holds the single-point frequency configuration used for standard (non-scan) acquisitions and serves as the base from which scan steps are derived.

• A clock step list (d_clockConfigs) holds one hash per acquisition segment; for LO and DR scans each element differs only in the scanned clock’s desired frequency. The list is empty for non-scan acquisitions, in which case prepareForAcquisition() initializes it from the template.

clockFrequency() and getClocks() always return from the active step (indexed by d_currentClockIndex). rawClockFrequency() converts the desired output frequency back to the hardware oscillator frequency via the multiplication or division factor stored in each ClockFreq record.

The chirp frequency at the sample for a given AWG output frequency is:

///   chirpFreq = (awgFreq × awgMult ± upLO) × chirpMult
///

where the sign depends on \c d_upMixSideband (upper = +, lower = −).
The received signal is mixed with the down-LO and the digitizer captures the
IF; \c d_downMixSideband selects which mixing product is the signal.
\c calculateChirpFreq() and \c calculateAwgFreq() perform these conversions.

\sa ChirpConfig, FtmwConfig

Public Types

enum MultOperation

Whether a clock frequency is multiplied or divided to reach the desired output.

Values:

enumerator Multiply

Output frequency = oscillator frequency × factor.

enumerator Divide

Output frequency = oscillator frequency / factor.

enum Sideband

Mixer sideband selection for up- and downconversion.

Values:

enumerator UpperSideband

Sum product: IF = RF + LO.

enumerator LowerSideband

Difference product: IF = LO − RF.

enum ClockType

Logical role for a clock source in the RF chain.

Values:

enumerator UpLO

Local oscillator for the upconversion mixer.

enumerator DownLO

Local oscillator for the downconversion mixer.

enumerator AwgRef

Reference clock input to the AWG.

enumerator DRClock

Double-resonance pump source.

enumerator DigRef

Reference clock input to the digitizer.

enumerator ComRef

Common 10 MHz (or other) reference distributed to all instruments.

Public Functions

RfConfig()

Constructs an RfConfig with default single-step, single-sweep settings.

~RfConfig()

bool prepareForAcquisition()

Validates and initializes the clock step list for acquisition.

If no clock steps have been added (non-scan case) the template is copied to produce a single-step list. Resets d_currentClockIndex to 0 and d_completedSweeps to 0. Returns false if the chirp list is empty.

void setCurrentClocks(const QHash<ClockType, ClockFreq> clocks)

Replaces the active clock step with clocks.

If clock steps have been populated, updates the entry at d_currentClockIndex; otherwise updates the template.

void setClockDesiredFreq(ClockType t, double f)

Sets the desired frequency for clock type t in the active step.

void setClockFreqInfo(ClockType t, const ClockFreq &cf)

Sets the full ClockFreq record for type t in the clock template.

If cf has an empty hardware key the entry is removed. When d_commonUpDownLO is true, setting UpLO also updates DownLO and vice versa.

void addClockStep(QHash<ClockType, ClockFreq> h)

Appends a complete clock configuration hash as one acquisition step.

void addLoScanClockStep(double upLoMHz, double downLoMHz)

Appends an LO-scan step with the specified up- and down-LO frequencies.

Copies the clock template, replaces the UpLO and DownLO desired frequencies with upLoMHz and downLoMHz, and appends the result.

void addDrScanClockStep(double drFreqMHz)

Appends a DR-scan step with the DR clock set to drFreqMHz.

Copies the clock template, replaces the DRClock desired frequency, and appends the result.

void clearClockSteps()

Removes all clock steps and resets d_currentClockIndex to 0.

void setChirpConfig(const ChirpConfig &cc)

Replaces the embedded chirp configuration.

int advanceClockStep()

Advances to the next clock step; wraps to step 0 and increments the sweep count.

Returns the new d_currentClockIndex.

quint64 totalShots() const

Returns the total shot count for a complete run (shots × steps × sweeps).

quint64 completedSegmentShots() const

Returns the number of shots accumulated in completed steps of the current sweep.

bool canAdvance(qint64 shots) const

Returns true when shots meets or exceeds the per-sweep shot target.

int numSegments() const

Returns the number of clock steps; returns 1 for non-scan acquisitions.

QVector<QHash<ClockType, RfConfig::ClockFreq>> clockSteps() const

Returns all clock steps; if the step list is empty, returns the template as a single-element vector.

QHash<ClockType, ClockFreq> getClocks() const

Returns the clock hash for the active step, or the template if no steps are defined.

double clockFrequency(ClockType t) const

Returns the desired output frequency in MHz for clock type t in the active step.

double rawClockFrequency(ClockType t) const

Returns the hardware oscillator frequency in MHz for clock type t in the active step.

Applies the inverse of the MultOperation to convert from the desired output frequency to the raw oscillator frequency.

std::pair<double, double> clockRange(ClockType t) const

Returns the [min, max] output frequency range in MHz for clock type t.

Reads the hardware’s minFreq and maxFreq settings and converts them to output frequencies via the clock’s MultOperation and factor.

QString clockHardware(ClockType t) const

Returns the hardware key of the clock assigned to type t in the template.

bool isComplete() const

Returns true when d_completedSweeps >= d_targetSweeps.

double calculateChirpFreq(double awgFreq) const

Converts an AWG output frequency in MHz to the final chirp frequency at the sample.

Applies d_awgMult, the upconversion sideband, the up-LO, and d_chirpMult.

double calculateAwgFreq(double chirpFreq) const

Converts a chirp frequency in MHz to the required AWG output frequency.

The inverse of calculateChirpFreq().

double calculateChirpAbsOffset(double awgFreq) const

Returns the absolute frequency offset in MHz between the chirp frequency and the down-LO.

QPair<double, double> calculateChirpAbsOffsetRange() const

Returns the [min, max] chirp absolute-offset range in MHz across all non-identical chirps.

bool writeClockFile(int num) const

Writes the clock step CSV file for experiment num.

Returns false if the file cannot be opened for writing.

void loadClockSteps(BlackchirpCSV *csv, int num, QString path)

Reads and populates clock steps from the clock CSV file for experiment num.

Public Members

bool d_commonUpDownLO = {false}

When true, UpLO and DownLO share one hardware source.

int d_completedSweeps = {0}

Number of completed LO/DR sweeps (updated by advanceClockStep()).

int d_targetSweeps = {1}

Number of sweeps to complete before the experiment ends.

int d_shotsPerClockConfig = {0}

Shots co-averaged at each clock step before advancing.

double d_awgMult = {1.0}

Multiplication factor applied to the AWG output frequency.

Sideband d_upMixSideband = {UpperSideband}

Sideband selected by the upconversion mixer.

double d_chirpMult = {1.0}

Multiplication factor applied after upconversion.

Sideband d_downMixSideband = {UpperSideband}

Sideband selected by the downconversion mixer.

ChirpConfig d_chirpConfig

Embedded chirp waveform configuration.

Public Static Functions

static double getRawFrequency(const ClockFreq f)

Converts a ClockFreq's desired output frequency to the hardware oscillator frequency.

static double rawToOutputFrequency(const ClockFreq &f, double rawFreq)

Converts a hardware oscillator frequency to the output frequency given a ClockFreq record.

Protected Functions

virtual void storeValues() override

Writes RF chain scalar fields to the header storage tree.

virtual void retrieveValues() override

Reads RF chain scalar fields back from the header storage tree.

virtual void prepareChildren() override

Registers d_chirpConfig as a child HeaderStorage node.

Private Members

QHash<ClockType, ClockFreq> d_clockTemplate

QVector<QHash<ClockType, RfConfig::ClockFreq>> d_clockConfigs

int d_currentClockIndex = {-1}

struct ClockFreq

Frequency assignment for one clock role in one acquisition step.

Public Members

double desiredFreqMHz = {0.0}

Target output frequency in MHz.

MultOperation op = {Multiply}

Whether factor multiplies or divides to reach desiredFreqMHz.

double factor = {1.0}

Multiplier or divisor relating oscillator frequency to output frequency.

QString hwKey = {""}

Hardware key of the clock source ("<Type>.<label>").

int output = {0}

Output port index on the clock hardware.