HardwareLoadout

HardwareLoadout is the value-typed record that represents one named set of member profiles and the FTMW operating points associated with it. A loadout records each member profile’s identity ("<Type>.<label>" — for example, "FtmwDigitizer.default" or "AWG.frontPanel") together with the driver key the profile carried at the time the loadout was last saved, and owns a collection of named FtmwPreset records that capture full FTMW configurations against that hardware selection. Loadouts are created, stored, and switched by LoadoutManager; the user-facing model is described in the Loadouts chapter.

A loadout’s hardwareMap field has the same shape as the active selection table held by RuntimeHardwareConfig: switching loadouts replaces the active set with the loadout’s stored member identities (after the drift-detection prompt in RuntimeHardwareConfigDialog). The driver half of each hardwareMap entry is denormalized — the canonical driver lives on the profile in HardwareProfileManager — and is used by the dialog to detect when a previously-saved member profile has been removed or recreated under a different driver. The ftmwPresets collection is keyed by user-visible preset name; the reserved name __LastUsed__ identifies the per-loadout sentinel preset described under LoadoutManager. The currentFtmwPresetName field points at whichever preset most recently drove the FTMW configuration widget; the active preset cannot be deleted without first switching away from it.

FtmwPreset

FtmwPreset is the named FTMW operating point owned by a loadout. It aggregates the four pieces of state that fully describe an FTMW measurement:

• an RfConfigSnapshot for the RF chain and clock frequencies,

• a ChirpConfig for the chirp waveform,

• an FtmwDigitizerConfig for the digitizer settings, and

• the digitizer’s hardware key (digiHwKey), which is used to validate that a preset is being applied against the digitizer it was captured from.

Presets cannot exist outside a loadout; their lifetime is managed entirely by LoadoutManager. AWG sample rate is a hardware-derived value and is reconstructed from the active AWG profile on read rather than being stored in the preset. The user-facing model for naming, switching, and editing presets is described in the FTMW Presets chapter.

LifPreset

LifPreset is the LIF counterpart to FtmwPreset: a named LIF operating point owned by a loadout. It carries a single LifConversionSnapshot — the frequency-conversion wiring (each stage’s input references and the excitation-beam marker) captured against the active LIF laser — together with a lastModified timestamp. Unlike FtmwPreset, it deliberately holds conversion wiring only; the per-stage operation and harmonic order are hardware identity read from each stage’s settings snapshot at assembly time, not persisted in the preset. The lifPresets collection and currentLifPresetName field on HardwareLoadout mirror their FTMW equivalents, and are managed by the same LoadoutManager CRUD. The user-facing model is described in the LIF Presets chapter.

Persistence helpers

The BC::Loadout namespace declares the free-function helpers that LoadoutManager uses to flatten loadout and preset structs into SettingsStorage::SettingsMap records and to reconstruct them on read. Two groups are exposed:

• RfConfigSnapshot conversions — rfConfigScalarsMap, rfConfigClocksArray, and rfConfigSnapshotFromMaps translate between an RfConfigSnapshot and the scalar/array records persisted under each preset’s rfScalars and rfClocks sub-groups.

• Hardware-map conversions — hardwareMapArray and hardwareMapFromArray translate between a loadout’s hardwareMap and the array record persisted under its hardwareMap sub-group.

• LifConversionSnapshot conversions — lifConversionScalarsMap, lifConversionWiringArray, and lifConversionSnapshotFromMaps translate between a LifConversionSnapshot and the scalar/array records persisted under each LIF preset’s conversion sub-groups, mirroring the RfConfigSnapshot helpers above.

copyClocksMatching and copyRfScalars support the per-component copy operations exposed by the FTMW configuration dialog tabs: they move a subset of fields between two snapshots without touching the remaining state. Chirp- and digitizer-side conversions are declared in chirpconfigloadout.h and ftmwdigitizerloadout.h respectively; they follow the same pattern but are omitted from this reference page because their surface area is purely persistence plumbing.

The keys used by these helpers are declared in two namespaces: extensions to BC::Store::RFC for the RF-side fields appear in the header below, and the loadout-level key vocabulary lives in BC::Store::LM (documented on LoadoutManager).

API Reference

struct HardwareLoadout

Named set of member profiles plus the FTMW presets it owns.

A HardwareLoadout records the profile identities ("<Type>.<label>") that make up a complete hardware configuration, alongside the implementation key each member profile carried at the time the loadout was last saved (a denormalized field, used for validation and drift detection — the canonical implementation lives on the profile in HardwareProfileManager). It also holds the named FtmwPreset operating points associated with that configuration. LoadoutManager owns the persistent collection of loadouts; instances are passed around by value and serialized into a QSettings subtree on write.

Public Members

QString name

User-visible loadout name (also the QSettings subgroup key).

std::map<QString, QString, std::less<>> hardwareMap

Member profile identities ("<Type>.<label>") and the implementation each profile carried at save time.

std::map<QString, QString, std::less<>> hardwareIdentity

Member profile identity token (hwKey -> identity), captured at save time; empty for loadouts written before identity tracking.

std::map<QString, FtmwPreset, std::less<>> ftmwPresets

Named FTMW presets owned by this loadout, including the __LastUsed__ sentinel when present.

QString currentFtmwPresetName

Name of the preset that drives initial widget population for this loadout.

std::map<QString, LifPreset, std::less<>> lifPresets

Named LIF presets owned by this loadout, including the __LastUsed__ sentinel when present.

QString currentLifPresetName

Name of the LIF preset that drives initial widget population for this loadout.

QDateTime lastModified

Timestamp of the most recent write to this loadout.

struct FtmwPreset

Named FTMW operating point owned by a HardwareLoadout.

An FtmwPreset aggregates the four pieces of state that fully describe an FTMW measurement configuration: the RF chain (RfConfigSnapshot), the chirp waveform (ChirpConfig), the digitizer settings (FtmwDigitizerConfig), and the hardware key of the digitizer the settings were captured from. Presets cannot exist outside a loadout; their lifetime is managed entirely by LoadoutManager.

Public Members

RfConfigSnapshot rfConfig

Persistable RF-chain state for the preset.

ChirpConfig chirpConfig

Chirp waveform definition.

FtmwDigitizerConfig digitizer = {""}

Digitizer configuration captured from the digitizer named by digiHwKey.

QString digiHwKey

Hardware key of the digitizer profile this preset was captured from.

QDateTime lastModified

Timestamp of the most recent write to this preset.

struct LifPreset

Named LIF operating point owned by a HardwareLoadout.

Mirrors FtmwPreset, but deliberately starts out narrower: a LifPreset currently carries only the frequency-conversion wiring (LifConversionSnapshot). LIF digitizer/processing settings could join this struct later via the same machinery, with no rework required of the surrounding LoadoutManager API.

Public Members

LifConversionSnapshot conversion

Persistable conversion-topology wiring for the preset.

QDateTime lastModified

Timestamp of the most recent write to this preset.

namespace Loadout

Free-function helpers that convert loadout structs to and from SettingsStorage::SettingsMap records.

LoadoutManager uses these helpers to flatten HardwareLoadout and FtmwPreset instances into the scalar/array QSettings layout described in :doc:/user_guide/hardware_config/loadouts and to reconstruct them on read. The copyClocksMatching and copyRfScalars helpers support the per-component copy operations exposed by the FTMW configuration dialog tabs.

Typedefs

typedef SettingsStorage::SettingsMap Map

using Maps = std::vector<SettingsStorage::SettingsMap>

using FallbackResolver = std::function<std::optional<FallbackMember>(const QString &type)>

Resolves the fallback for a hardware type: a value for a REQUIRED type (which must never be left with that type empty), or nullopt for an OPTIONAL type (the member is simply dropped).

Functions

SettingsStorage::SettingsMap chirpConfigScalarsMap(const ChirpConfig &cc)

std::vector<SettingsStorage::SettingsMap> chirpConfigSegmentsArray(const ChirpConfig &cc)

std::vector<SettingsStorage::SettingsMap> chirpConfigMarkersArray(const ChirpConfig &cc)

ChirpConfig chirpConfigFromMaps(const SettingsStorage::SettingsMap &scalars, const std::vector<SettingsStorage::SettingsMap> &segments, const std::vector<SettingsStorage::SettingsMap> &markers, double awgSampleRateSps)

SettingsStorage::SettingsMap digitizerScalarsMap(const FtmwDigitizerConfig &cfg)

std::vector<SettingsStorage::SettingsMap> digitizerAnalogArray(const FtmwDigitizerConfig &cfg)

std::vector<SettingsStorage::SettingsMap> digitizerDigitalArray(const FtmwDigitizerConfig &cfg)

FtmwDigitizerConfig ftmwDigitizerFromMaps(const QString &hwKey, const SettingsStorage::SettingsMap &scalars, const std::vector<SettingsStorage::SettingsMap> &analog, const std::vector<SettingsStorage::SettingsMap> &digital)

Map rfConfigScalarsMap(const RfConfigSnapshot &snap)

Flatten an RfConfigSnapshot into the scalar fields persisted under a preset’s rfScalars group.

Maps rfConfigClocksArray(const RfConfigSnapshot &snap)

Flatten an RfConfigSnapshot’s clock table into the array persisted under a preset’s rfClocks group.

RfConfigSnapshot rfConfigSnapshotFromMaps(const Map &scalars, const Maps &clocks)

Reconstruct an RfConfigSnapshot from the scalars map and clocks array read out of QSettings.

void copyClocksMatching(const RfConfigSnapshot &source, RfConfigSnapshot &dest, const std::set<QString> &allowedHwKeys)

Copy clock entries from source to dest whose hardware key is in allowedHwKeys.

void copyRfScalars(const RfConfigSnapshot &source, RfConfigSnapshot &dest)

Copy the scalar (non-clock) RF-chain fields from source to dest.

Map lifConversionScalarsMap(const LifConversionSnapshot &snap)

Flatten a LifConversionSnapshot’s provenance fields into the scalar persisted under a LIF preset’s lifConversionScalars group.

Maps lifConversionWiringArray(const LifConversionSnapshot &snap)

Flatten a LifConversionSnapshot’s wiring into the array persisted under a LIF preset’s lifConversionWiring group.

LifConversionSnapshot lifConversionSnapshotFromMaps(const Map &scalars, const Maps &wiring)

Reconstruct a LifConversionSnapshot from the scalars map and wiring array read out of QSettings.

Maps hardwareMapArray(const std::map<QString, QString, std::less<>> &hwMap, const std::map<QString, QString, std::less<>> &hwIdentity)

Flatten a hardware map (with its parallel identity map) into the array persisted under a loadout’s hardwareMap group.

void hardwareMapFromArray(const Maps &array, std::map<QString, QString, std::less<>> &hwMap, std::map<QString, QString, std::less<>> &hwIdentity)

Reconstruct both the hardware map and its identity map from the array read out of QSettings; identity entries are populated only for records that carry the field.

bool ftmwPresetReferencesHardware(const FtmwPreset &preset, const QString &hwKey)

Whether an FTMW preset references the given hardware key (its digitizer or any RF-chain clock).

bool lifPresetReferencesHardware(const LifPreset &preset, const QString &hwKey)

Whether a LIF preset references the given hardware key (a wired conversion stage or the captured laser).

bool ftmwPresetRebindHardware(FtmwPreset &preset, const QString &fromKey, const QString &toKey)

Rewrite every reference to fromKey in an FTMW preset (its digitizer and any RF-chain clock role) to toKey. Returns whether anything changed.

bool lifPresetRebindHardware(LifPreset &preset, const QString &fromKey, const QString &toKey)

Rewrite every reference to fromKey in a LIF preset (the captured laser and any wired conversion stage) to toKey. Returns whether anything changed.

struct FallbackMember

Replacement member substituted for a deleted required-type member.

Public Members

QString hwKey

Replacement member hwKey (e.g. “Clock.virtual”).

QString impl

Replacement implementation key.

QString identity

Replacement profile identity token (may be empty).

struct PruneConsequences

Consequences of deleting a profile, computed without mutating anything.

A referencing preset is rebound to the fallback (non-destructive) when a fallback exists for the deleted type, and dropped (destructive) when none does. The categories below separate the two so a confirmation dialog can alarm only where configuration is actually lost.

Public Members

std::vector<std::pair<QString, QString>> lostPresets

(loadout, named preset) pairs that will be dropped because they reference the deleted hwKey and no fallback exists.

std::vector<QString> lostWorkingConfigLoadouts

Loadouts whose current working configuration (the __LastUsed__ preset) is dropped because no fallback exists.

std::vector<std::pair<QString, QString>> reboundPresets

(loadout, named preset) pairs that will be re-pointed to the fallback (non-destructive).

std::vector<QString> modifiedLoadouts

Loadouts that lose an optional-type member (dropped, not replaced).

std::vector<FallbackSub> fallbackSubs

Loadouts whose required-type member is replaced with the system fallback.

struct FallbackSub

One required-type member substitution.

Public Members

QString loadout

QString type

QString fallbackHwKey