Aerial TV

Test vector utilities for RAN runtime validation and verification.

Overview

The Aerial Test Vector (TV) library provides utilities for loading and managing CUPHY test vectors from HDF5 files. It enables validation of physical layer processing by providing reference data, parameters, and helper functions for comparing processing results against known-good outputs.

Key Features

• HDF5 Test Vector Loading: Read gNB, UE group, and transport block parameters from test files

• Parameter Conversion: Convert test vectors to PhyParams and other configuration structures

• Validation Utilities: Check processing results against reference data (SINR, noise variance, payloads)

• Lazy Loading: Efficient memory usage with on-demand parameter loading

• Type-Safe Access: Template-based HDF5 dataset reading with compile-time type checking

Quick Start

Loading a Test Vector

// Load a PUSCH test vector from an HDF5 file
const ran::aerial_tv::CuphyPuschTestVector test_vector(TEST_FILE);

Reading gNB Parameters

const ran::aerial_tv::CuphyPuschTestVector test_vector(TEST_FILE);

// Access gNB parameters from the test vector
const auto &gnb_params = test_vector.get_gnb_params();

// Use gNB parameters for configuration
const std::uint32_t num_rx_antennas = gnb_params.n_rx;
const std::uint32_t num_prbs = gnb_params.n_prb;
const std::uint32_t subcarrier_spacing = gnb_params.mu;

Reading Transport Block Parameters

const ran::aerial_tv::CuphyPuschTestVector test_vector(TEST_FILE);

// Access transport block parameters
const auto &tb_params_vec = test_vector.get_tb_params();

// Process each transport block
for (const auto &tb_params : tb_params_vec) {
    // Use TB parameters for processing
    const std::uint32_t num_layers = tb_params.num_layers;
    const std::uint32_t mcs_index = tb_params.mcs_index;
    const std::uint32_t tb_size_bytes = tb_params.n_tb_byte;

    RT_LOG_DEBUG(
            "TB params: layers=%u, MCS=%u, size=%u bytes",
            num_layers,
            mcs_index,
            tb_size_bytes);
}

Core Concepts

Test Vector Structure

A CuphyPuschTestVector represents a complete PUSCH test scenario loaded from an HDF5 file. Each test vector contains three main parameter groups:

• gNB Parameters (CuphyPuschTvGnbParams): Cell configuration including number of PRBs, receive antennas, subcarrier spacing, and algorithm selections for channel estimation, LDPC decoding, and CSI processing

• UE Group Parameters (CuphyPuschTvUeGrpParams): Resource allocation per UE group including PRB allocation, symbol ranges, and DMRS configuration

• Transport Block Parameters (CuphyPuschTvTbParams): Per-TB configuration including MCS, redundancy version, layer mapping, and UCI (HARQ-ACK, CSI) parameters

Parameters are loaded lazily on first access, improving performance when only specific parameter groups are needed.

Reading HDF5 Datasets

The library provides flexible dataset reading capabilities:

Scalar Values

const ran::aerial_tv::CuphyPuschTestVector test_vector(TEST_FILE);

// Read scalar values from HDF5 datasets
const auto noise_var_db = test_vector.read_scalar<float>("reference_noiseVardB");
const auto cfo_angle = test_vector.read_scalar<float>("reference_cfoAngle");

Array Data

const ran::aerial_tv::CuphyPuschTestVector test_vector(TEST_FILE);

// Read array data from HDF5 dataset
const auto array_data = test_vector.read_array<float>("WFreq");

// Access data and dimensions
const std::vector<float> &data = array_data.data;
const std::vector<std::size_t> &dims = array_data.dimensions;

// Process array data (dimensions: [dim0, dim1, dim2, ...])
const std::size_t total_elements = data.size();

Arrays are returned with their data flattened in row-major order and dimension information preserved.

Parameter Conversion

Convert test vector parameters to framework types:

const ran::aerial_tv::CuphyPuschTestVector test_vector(TEST_FILE);

// Convert test vector parameters to PhyParams structure
const ran::common::PhyParams phy_params = ran::aerial_tv::to_phy_params(test_vector);

// Use PhyParams for PHY layer configuration
const std::uint32_t num_prb = phy_params.num_prb;
const std::uint16_t num_rx_ant = phy_params.num_rx_ant;
const std::uint16_t bandwidth = phy_params.bandwidth;

Other Configuration Conversions

const ran::aerial_tv::CuphyPuschTestVector test_vector(TEST_FILE);

// Convert test vector to PUSCH outer receiver parameters
const ran::ldpc::PuschOuterRxParams outer_rx_params =
        ran::aerial_tv::to_pusch_outer_rx_params(test_vector);

// Use outer receiver params for PUSCH receiver configuration

Static Reading Methods

For direct parameter access without creating a test vector object:

// Read parameters directly without creating test vector object
const auto gnb_params =
        ran::aerial_tv::CuphyPuschTestVector::read_gnb_params_from_file(TEST_FILE);

const auto ue_grp_params =
        ran::aerial_tv::CuphyPuschTestVector::read_ue_grp_params_from_file(TEST_FILE);

const auto tb_params =
        ran::aerial_tv::CuphyPuschTestVector::read_tb_params_from_file(TEST_FILE);

These static methods are useful for quick parameter inspection or when only a specific parameter group is needed.

UE Group Parameters

Access UE group-specific resource allocation:

const ran::aerial_tv::CuphyPuschTestVector test_vector(TEST_FILE);

// Access UE group parameters
const auto &ue_grp_params_vec = test_vector.get_ue_grp_params();

// Process each UE group
for (const auto &ue_grp_params : ue_grp_params_vec) {
    const std::uint16_t start_prb = ue_grp_params.start_prb;
    const std::uint16_t num_prbs = ue_grp_params.n_prb;
    const std::uint8_t start_symbol = ue_grp_params.start_symbol_index;
    const std::uint8_t num_symbols = ue_grp_params.nr_of_symbols;

    RT_LOG_DEBUG(
            "UE group: PRB range [%u-%u], symbol range [%u-%u]",
            start_prb,
            start_prb + num_prbs - 1,
            start_symbol,
            start_symbol + num_symbols - 1);
}

API Reference

constexpr std::array<std::string_view, 2> ran::aerial_tv::TEST_HDF5_FILES{"TVnr_7201_PUSCH_gNB_CUPHY_s0p0.h5", "TVnr_7204_PUSCH_gNB_CUPHY_s0p0.h5"}

Common HDF5 test vector files for testing.

constexpr std::size_t ran::aerial_tv::MAX_CSI2_MAPS_BUFFER_SIZE = 20U

Maximum CSI-2 maps buffer entries.

constexpr std::size_t ran::aerial_tv::MAX_CSI2_REPORTS_PER_TB = 16U

Maximum CSI-2 reports per transport block.

constexpr std::size_t ran::aerial_tv::MAX_TOTAL_CSI1_PARAMETERS_PER_TB = 64U

Maximum total CSI-1 parameters across all CSI-2 reports (16 reports × 4 params each)

ran::common::PhyParams ran::aerial_tv::to_phy_params(

const CuphyPuschTestVector &test_vector,

)

Convert CuphyPuschTestVector to PhyParams structure

Extracts physical layer configuration parameters from the gNB parameters section of the test vector and populates a PhyParams object.

Parameters:

test_vector – [in] PUSCH test vector containing gNB parameters

Returns:

Physical layer parameters extracted from the test vector

ran::ldpc::PuschOuterRxParams ran::aerial_tv::to_pusch_outer_rx_params(

const CuphyPuschTestVector &test_vector,

)

Read from a CuphyPuschTestVector into a PuschOuterRxParams object.

Parameters:

test_vector – [in] PUSCH test vector

Returns:

PUSCH receiver outer_rx parameters object

void ran::aerial_tv::check_post_eq_noise_var(

const std::vector<float> &obtained,

const CuphyPuschTestVector &test_vector,

const float tolerance = 0.0F,

)

Read reference post-EQ noise variance from test vector and compare against obtained values

Parameters:

• obtained – [in] Obtained post-EQ noise variance values

• test_vector – [in] Test vector containing reference data

• tolerance – [in] Absolute tolerance for comparison (default: 0.0 for exact match)

void ran::aerial_tv::check_post_eq_sinr(

const std::vector<float> &obtained,

const CuphyPuschTestVector &test_vector,

const float tolerance = 0.0F,

)

Read reference post-EQ SINR from test vector and compare against obtained values

Parameters:

• obtained – [in] Obtained post-EQ SINR values

• test_vector – [in] Test vector containing reference data

• tolerance – [in] Absolute tolerance for comparison (default: 0.0 for exact match)

void ran::aerial_tv::check_tb_payloads(

const std::span<const framework::pipeline::DeviceTensor> tb_payload_tensors,

const CuphyPuschTestVector &test_vector,

cudaStream_t stream,

)

Validate transport block payloads against reference data from test vector

This function reads the expected TB payloads from the test vector, copies the obtained TB payloads from device to host using stream-aware async copies, and compares them byte-by-byte. It handles multiple transport blocks and accounts for CRC bytes in the reference data.

Parameters:

• tb_payload_tensors – [in] Device tensors containing the TB payloads to validate

• test_vector – [in] Test vector containing reference TB payload data and outer_rx params

• stream – [in] CUDA stream to use for async memory copies (ensures proper synchronization)

class CuphyPuschTestVector

#include <cuphy_pusch_tv.hpp>

Test vector class for CUPHY (CUDA PHY) PUSCH operations in the Aerial framework.

This class provides functionality to load and manage PUSCH test vectors from files for CUDA-based physical layer processing validation and testing.

Public Functions

explicit CuphyPuschTestVector(std::string filename)

Constructs a PUSCH test vector from the specified file.

Parameters:

filename – [in] Path to the test vector file to load

const CuphyPuschTvGnbParams &get_gnb_params() const

Gets the gNB parameters from the loaded PUSCH test vector. Parameters are loaded lazily on first access.

Returns:

Reference to the gNB parameters structure

const std::vector<CuphyPuschTvUeGrpParams> &get_ue_grp_params(

) const

Gets the UE group parameters from the loaded PUSCH test vector. Parameters are loaded lazily on first access.

Returns:

Reference to the vector of UE group parameters structures

const CuphyPuschTvUeGrpParams &get_ue_grp_params(

std::size_t ue_grp_idx,

) const

Gets a specific UE group parameters by index from the loaded PUSCH test vector.

Parameters:

ue_grp_idx – [in] Index of the UE group (0-based)

Throws:

std::out_of_range – if ue_grp_idx is invalid

Returns:

Reference to the UE group parameters structure at the specified index

const std::vector<CuphyPuschTvTbParams> &get_tb_params() const

Gets the transport block parameters from the loaded PUSCH test vector. Parameters are loaded lazily on first access.

Returns:

Reference to the vector of transport block parameters structures

const CuphyPuschTvTbParams &get_tb_params(std::size_t tb_idx) const

Gets a specific transport block parameters by index from the loaded PUSCH test vector.

Parameters:

tb_idx – [in] Index of the transport block (0-based)

Throws:

std::out_of_range – if tb_idx is invalid

Returns:

Reference to the transport block parameters structure at the specified index

template<Hdf5Compatible T>
T read_scalar(

const std::string_view dataset_name,

) const

Reads a scalar value from an HDF5 dataset.

Template Parameters:

T – The data type to read (must satisfy Hdf5Compatible)

Parameters:

dataset_name – [in] Name of the dataset in the HDF5 file

Throws:

std::runtime_error – if dataset is not found, empty, or not scalar-compatible

Returns:

The scalar value from the dataset

template<Hdf5Compatible T>
Hdf5Array<T> read_array(

const std::string_view dataset_name,

) const

Reads an array dataset of any dimensionality from the HDF5 file.

Template Parameters:

T – The element data type (must satisfy Hdf5Compatible)

Parameters:

dataset_name – [in] Name of the dataset in the HDF5 file

Throws:

std::runtime_error – if dataset is not found or cannot be read

Returns:

Hdf5Array containing flattened data and dimensions

template<ComplexArrayType T>
Hdf5Array<T> read_complex_array(

const std::string_view dataset_name,

) const

Reads a complex-valued array from HDF5 as a real-valued array with extra dimension

Reads HDF5 compound types with ‘re’ and ‘im’ fields and converts them to a real-valued array where the last dimension is 2 (index 0 = real, index 1 = imag).

Note

The added dimension is the last dimension, i.e. the fastest changing in memory.

Template Parameters:

T – The real-valued data type (must be floating point or half-precision)

Parameters:

dataset_name – [in] Name of the dataset in the HDF5 file

Throws:

std::runtime_error – if dataset is not found, not a complex type, or cannot be read

Returns:

Hdf5Array containing flattened data and dimensions (last dimension is 2)

Public Static Functions

static CuphyPuschTvGnbParams read_gnb_params_from_file(

const std::string_view filename,

)

Reads gNB parameters from an HDF5 PUSCH test vector file.

Parameters:

filename – [in] Path to the HDF5 test vector file

Throws:

std::runtime_error – if file cannot be opened or gnb_pars dataset is missing/invalid

Returns:

gNB parameters structure loaded from the file

static std::vector<CuphyPuschTvUeGrpParams> read_ue_grp_params_from_file(

const std::string_view filename,

)

Reads UE group parameters from an HDF5 PUSCH test vector file.

Parameters:

filename – [in] Path to the HDF5 test vector file

Throws:

std::runtime_error – if file cannot be opened or ueGrp_pars dataset is missing/invalid

Returns:

Vector of UE group parameters structures loaded from the file

static std::vector<CuphyPuschTvTbParams> read_tb_params_from_file(

const std::string_view filename,

)

Reads transport block parameters from an HDF5 PUSCH test vector file.

Parameters:

filename – [in] Path to the HDF5 test vector file

Throws:

std::runtime_error – if file cannot be opened or tb_pars dataset is missing/invalid

Returns:

Vector of transport block parameters structures loaded from the file

struct CuphyPuschTvGnbParams

#include <cuphy_pusch_tv.hpp>

gNB parameters for CUPHY PUSCH test vectors

This structure matches the HDF5 compound data type fields in gnb_pars dataset

Public Members

double n_user_groups = {}

Number of user groups.

std::uint32_t mu = {}

Subcarrier spacing parameter (μ)

std::uint32_t n_rx = {}

Number of receive antennas.

std::uint32_t n_prb = {}

Number of physical resource blocks.

std::uint32_t cell_id = {}

Cell ID.

std::uint32_t slot_number = {}

Slot number.

std::uint32_t num_tb = {}

Number of transport blocks.

std::uint8_t enable_early_harq = {}

Enable early HARQ termination.

std::uint8_t enable_cfo_correction = {}

Enable CFO correction.

std::uint8_t enable_cfo_estimation = {}

Enable CFO estimation.

std::uint8_t enable_to_estimation = {}

Enable timing offset estimation.

std::uint8_t enable_to_correction = {}

Enable timing offset correction.

std::uint8_t tdi_mode = {}

TDI mode.

std::uint8_t enable_dft_s_ofdm = {}

Enable DFT-S-OFDM.

std::uint8_t enable_rssi_measurement = {}

Enable RSSI measurement.

std::uint8_t enable_sinr_measurement = {}

Enable SINR measurement.

std::uint8_t enable_static_dynamic_beamforming = {}

Enable static/dynamic beamforming

std::uint32_t ldpc_early_termination = {}

LDPC early termination.

std::uint32_t ldpc_algo_index = {}

LDPC algorithm index.

std::uint32_t ldpc_flags = {}

LDPC flags.

std::uint32_t ldpc_use_half = {}

LDPC use half precision.

std::uint32_t num_bbu_layers = {}

Number of BBU layers.

std::uint8_t ldpc_max_num_itr = {}

LDPC maximum iterations.

std::uint8_t ldpc_max_num_itr_alg_idx = {}

LDPC max iterations algorithm index.

std::uint8_t dmrs_ch_est_alg_idx = {}

DMRS channel estimation algorithm index.

std::uint8_t enable_per_prg_ch_est = {}

Enable per-PRG channel estimation.

std::uint8_t eq_coeff_algo_idx = {}

Equalization coefficient algorithm index.

std::uint8_t list_length = {}

List length.

std::uint8_t enable_csi_p2_fapiv3 = {}

Enable CSI Part-2 processing using FAPI v3 interface.

std::uint16_t n_csi2_maps = {}

Number of active CSI-2 size maps for this cell.

std::array<std::uint8_t, 4> csi2_maps_sum_of_prm_sizes = {}

Total parameter sizes for each of 4 CSI-2 map types.

std::array<std::uint32_t, 4> csi2_maps_buffer_start_idxs = {}

Start indices into csi2_maps_buffer for each map type

std::array<std::uint16_t, MAX_CSI2_MAPS_BUFFER_SIZE> csi2_maps_buffer = {}

Buffer storing CSI-2 mapping configuration data.

struct CuphyPuschTvTbParams

#include <cuphy_pusch_tv.hpp>

Transport Block (TB) parameters for CUPHY PUSCH test vectors

This structure matches the HDF5 compound data type fields in tb_pars dataset

Public Members

std::uint32_t n_rnti = {}

Radio Network Temporary Identifier.

std::uint32_t num_layers = {}

Number of layers.

std::uint32_t start_sym = {}

Start symbol index.

std::uint32_t num_sym = {}

Number of symbols.

std::uint32_t user_group_index = {}

User group index.

std::uint32_t data_scram_id = {}

Data scrambling ID.

std::uint32_t mcs_table_index = {}

MCS table index.

std::uint32_t mcs_index = {}

MCS index.

std::uint32_t rv = {}

Redundancy version.

std::uint32_t ndi = {}

New data indicator.

std::uint32_t n_tb_byte = {}

Transport block size in bytes.

std::uint32_t n_cb = {}

Number of code blocks.

std::uint8_t i_lbrm = {}

LBRM indicator.

std::uint8_t max_layers = {}

Maximum layers.

std::uint8_t max_qm = {}

Maximum QAM modulation order.

std::uint16_t n_prb_lbrm = {}

Number of PRBs for LBRM.

std::uint8_t qam_mod_order = {}

QAM modulation order.

std::uint16_t target_code_rate = {}

Target code rate.

std::uint16_t n_bits_harq = {}

Number of HARQ acknowledgment bits in UCI payload.

std::uint16_t n_bits_csi1 = {}

Number of CSI Part-1 bits (wideband channel quality)

std::uint16_t pdu_bitmap = {}

PDU bitmap indicating presence of different UCI types.

std::uint8_t alpha_scaling = {}

Alpha scaling factor for UCI power control.

std::uint8_t beta_offset_harq_ack = {}

Beta offset for HARQ ACK power scaling.

std::uint8_t beta_offset_csi1 = {}

Beta offset for CSI Part-1 power scaling.

std::uint8_t beta_offset_csi2 = {}

Beta offset for CSI Part-2 power scaling.

std::array<std::uint8_t, MAX_CSI2_REPORTS_PER_TB> n_part1_prms = {}

Number of CSI Part-1 parameters per CSI-2 report (1-4 each)

std::array<std::uint8_t, MAX_TOTAL_CSI1_PARAMETERS_PER_TB> prm_sizes = {}

Flattened array of CSI Part-1 parameter sizes (bits)

std::array<std::uint16_t, MAX_TOTAL_CSI1_PARAMETERS_PER_TB> prm_offsets = {}

Flattened array of CSI Part-1 parameter offsets (bit positions)

std::array<std::uint16_t, MAX_CSI2_REPORTS_PER_TB> csi2_size_map_idx = {}

CSI-2 size map indices for each CSI-2 report.

std::uint16_t n_csi2_reports = {}

Number of active CSI-2 reports for this TB.

std::uint16_t flag_csi_part2 = {}

Bitmap indicating which CSI Part-2 fields are present.

std::uint8_t rank_bit_offset = {}

Bit offset where rank information starts in CSI payload.

std::uint8_t rank_bit_size = {}

Number of bits used to encode rank (1-4 bits for ranks 1-16)

std::uint32_t dmrs_addl_position = {}

DMRS additional position.

std::uint32_t dmrs_max_length = {}

DMRS maximum length.

std::uint32_t dmrs_scram_id = {}

DMRS scrambling ID.

std::uint32_t n_scid = {}

Scrambling ID.

std::uint32_t dmrs_port_bmsk = {}

DMRS port bitmask.

std::uint32_t dmrs_sym_loc_bmsk = {}

DMRS symbol location bitmask.

std::uint32_t rssi_sym_loc_bmsk = {}

RSSI symbol location bitmask.

std::uint8_t num_dmrs_cdm_grps_no_data = {}

Number of DMRS CDM groups without data.

float dtx_threshold = {}

DTX threshold.

std::uint8_t enable_tf_prcd = {}

Enable transform precoding.

std::uint8_t pusch_identity = {}

PUSCH identity.

std::uint8_t n_slot_frame = {}

Number of slots per frame.

std::uint8_t n_symb_slot = {}

Number of symbols per slot.

std::uint8_t group_or_sequence_hopping = {}

Group or sequence hopping.

std::uint8_t low_papr_group_number = {}

Low PAPR group number.

std::uint16_t low_papr_sequence_number = {}

Low PAPR sequence number.

struct CuphyPuschTvUeGrpParams

#include <cuphy_pusch_tv.hpp>

UE group parameters for CUPHY PUSCH test vectors

This structure matches the HDF5 compound data type fields in ueGrp_pars dataset

Public Members

std::uint16_t n_ues = {}

Number of UEs in the group.

std::vector<std::uint16_t> ue_prm_idxs

UE parameter indices.

std::uint16_t start_prb = {}

Starting physical resource block.

std::uint16_t n_prb = {}

Number of physical resource blocks.

std::uint8_t start_symbol_index = {}

Start symbol index.

std::uint8_t nr_of_symbols = {}

Number of symbols.

std::uint16_t prg_size = {}

PRG (Physical Resource Group) size.

std::uint16_t dmrs_sym_loc_bmsk = {}

DMRS symbol location bitmask.

std::uint16_t rssi_sym_loc_bmsk = {}

RSSI symbol location bitmask.

double n_uplink_streams = {}

Number of uplink streams.

template<Hdf5Compatible T>
struct Hdf5Array

#include <cuphy_pusch_tv.hpp>

Array data and dimensions read from HDF5 test vector files

Template Parameters:

T – Element type of the array (must satisfy Hdf5Compatible)

Public Members

std::vector<T> data

Flattened array data.

std::vector<std::size_t> dimensions

Dimensions of the array.