Pulse HDF5 File Loading

Description

FERS can load pulse waveform definitions from HDF5 (.h5) files when specified in the Pulse XML Definition. This loading mechanism expects a specific internal structure within the HDF5 file, containing separate datasets for the In-phase (I) and Quadrature (Q) components of the complex baseband signal. These components are expected to be stored as double-precision floating-point numbers.

Assumptions

• Assumes the specified HDF5 file exists and is readable by the application.
• Assumes the necessary HighFive HDF5 library dependency is correctly linked and available at runtime.
• Assumes the HDF5 file adheres to a specific internal structure: datasets must exist at paths /I/value and /Q/value.
• Assumes these datasets contain double-precision floating-point values.
• Assumes the /I/value and /Q/value datasets have the exact same number of samples (length).
• Assumes the stored data represents the complex baseband envelope of the desired pulse waveform.
• Crucially, assumes the sample rate at which the data inside the HDF5 file was originally generated corresponds to the simulation's params::rate() parameter. This parameter is used externally by FERS to calculate the pulse duration.

Limitations

• Rigid HDF5 Structure: The loader requires the hardcoded /I/value and /Q/value dataset paths. It cannot adapt to different internal HDF5 layouts.
• External Library Dependency: Requires the HighFive C++ library for HDF5 interaction.
• Basic Error Handling: Errors during file access or parsing typically result in a std::runtime_error, which might lack detailed context for debugging user file issues.
• Sample Rate Ambiguity: The sample rate of the waveform data is not read from the HDF5 file itself. FERS relies on the global params::rate() setting to interpret the number of samples (num_samples) read from the file and calculate the pulse duration (RadarSignal::_length = num_samples / params::rate()).
• Potential Duration Mismatch: If the waveform data within the HDF5 file was actually sampled at a rate different from params::rate(), the calculated pulse duration used in the simulation (RadarSignal::_length) will be incorrect. This can lead to inaccurate simulation results, as the time-domain representation of the pulse within the simulation will be effectively stretched or compressed relative to its intended duration.
• No Metadata Usage: Does not utilize HDF5 attributes or metadata features to store or retrieve waveform parameters like the original sample rate, center frequency, or intended power level directly from the file.

Related Components

• Pulse XML Definition (How this loading mechanism is configured)
• RadarSignal class (Stores the loaded pulse metadata, including the calculated _length)
• Signal class (Stores the raw complex sample data read from the file)
• pulse_factory.cpp (Likely contains the top-level loading logic calling the HDF5 handler)
• hdf5_handler.cpp (Likely contains the specific HighFive interaction logic for reading pulse data)
• Simulation parameter: params::rate() (Crucial for the duration calculation based on the number of samples read)

Validation Status

• Needs Verification: Currently, no specific regression tests exclusively target the HDF5 pulse loading mechanism and its potential pitfalls (e.g., sample rate mismatch). Existing tests might use HDF5 pulses, but may not stress these specific failure modes.
• Key Areas for Validation:
  • Verify successful loading of correctly formatted HDF5 files with matching I/Q lengths.
  • Confirm that appropriate errors are generated (and potentially caught/logged) for missing files, files with incorrect internal structures (missing /I/value or /Q/value), or files where I and Q datasets have different lengths.
  • Critically: Design and run tests where the sample rate implied by the data generation for the HDF5 file differs from the params::rate() used during the FERS simulation. Validate whether the resulting simulated pulse duration (RadarSignal::_length) reflects the incorrect interpretation based solely on params::rate(). Analyze the impact on simulation outputs (e.g., range resolution if the duration is wrong).
  • Assess behavior and performance when loading very large HDF5 pulse files.
• Priority: Medium (Core functionality for waveform loading, but with a significant potential failure mode related to the sample rate assumption that could silently corrupt simulation results).