processing Namespace Reference

Namespaces
namespace	pipeline

Functions
void	runPulsedFinalizer (radar::Receiver *receiver, const std::vector< std::unique_ptr< radar::Target > > *targets, std::shared_ptr< core::ProgressReporter > reporter, const std::string &output_dir, std::shared_ptr< core::OutputMetadataCollector > metadata_collector=nullptr)
	The main function for a dedicated pulsed-mode receiver finalizer thread.
void	finalizeCwReceiver (radar::Receiver *receiver, pool::ThreadPool *pool, std::shared_ptr< core::ProgressReporter > reporter, const std::string &output_dir, std::shared_ptr< core::OutputMetadataCollector > metadata_collector=nullptr)
	The finalization task for a continuous-wave (CW) mode receiver.
void	renderWindow (std::vector< ComplexType > &window, RealType length, RealType start, RealType fracDelay, std::span< const std::unique_ptr< serial::Response > > responses)
	Renders a time-window of I/Q data from a collection of raw radar responses.
void	applyThermalNoise (std::span< ComplexType > window, RealType noiseTemperature, std::mt19937 &rngEngine)
	Applies thermal (Johnson-Nyquist) noise to a window of I/Q samples.
RealType	quantizeAndScaleWindow (std::span< ComplexType > window)
	Simulates ADC quantization and scales a window of complex I/Q samples.

Function Documentation

applyThermalNoise()

void processing::applyThermalNoise	(	std::span< ComplexType >	window,
		RealType	noiseTemperature,
		std::mt19937 &	rngEngine
	)

Applies thermal (Johnson-Nyquist) noise to a window of I/Q samples.

Simulates the addition of white Gaussian noise based on the receiver's noise temperature and the simulation bandwidth.

Parameters

window	A span of I/Q data to which noise will be added.
noiseTemperature	The effective noise temperature in Kelvin.
rngEngine	A random number generator engine to use for noise generation.

Definition at line 110 of file signal_processor.cpp.

    {
        if (noiseTemperature == 0)
        {
            return;
        }
 
        const RealType b = params::rate() / (2.0 * params::oversampleRatio());
        const RealType total_power = params::boltzmannK() * noiseTemperature * b;
 
        // Split total power equally between the I and Q channels
        const RealType per_channel_power = total_power / 2.0;
        const RealType stddev = std::sqrt(per_channel_power);
 
        noise::WgnGenerator generator(rngEngine, stddev);
        for (auto& sample : window)
        {
            sample += ComplexType(generator.getSample(), generator.getSample());
        }
    }

References params::boltzmannK(), noise::WgnGenerator::getSample(), params::oversampleRatio(), and params::rate().

Referenced by finalizeCwReceiver(), and runPulsedFinalizer().

Here is the call graph for this function:

Here is the caller graph for this function:

finalizeCwReceiver()

void processing::finalizeCwReceiver	(	radar::Receiver *	receiver,
		pool::ThreadPool *	pool,
		std::shared_ptr< core::ProgressReporter >	reporter,
		const std::string &	output_dir,
		std::shared_ptr< core::OutputMetadataCollector >	metadata_collector = nullptr
	)

The finalization task for a continuous-wave (CW) mode receiver.

This function is submitted to the main thread pool when a CW receiver finishes its operation. It processes the entire collected I/Q buffer, applies interference and noise, and writes the final data to a file.

Parameters

receiver	A pointer to the CW-mode receiver to finalize.
pool	A pointer to the main thread pool for parallelizing sub-tasks.
reporter	Shared pointer to the progress reporter for status updates.
output_dir	Output directory for the simulation files.

Definition at line 239 of file finalizer.cpp.

    {
        LOG(logging::Level::INFO, "Finalization task started for CW receiver '{}'.", receiver->getName());
        if (reporter)
        {
            reporter->report(std::format("Finalizing CW Receiver {}", receiver->getName()), 0, 100);
        }
 
        auto& iq_buffer = receiver->getMutableCwData();
        if (iq_buffer.empty())
        {
            LOG(logging::Level::INFO, "No CW data to finalize for receiver '{}'.", receiver->getName());
            return;
        }
 
        if (reporter)
        {
            reporter->report(std::format("Rendering Interference for {}", receiver->getName()), 25, 100);
        }
        pipeline::applyPulsedInterference(iq_buffer, receiver->getPulsedInterferenceLog());
 
        const auto timing_model = receiver->getTiming()->clone();
        if (!timing_model)
        {
            LOG(logging::Level::FATAL, "Failed to clone timing model for CW receiver '{}'", receiver->getName());
            return;
        }
 
        if (reporter)
        {
            reporter->report(std::format("Applying Noise for {}", receiver->getName()), 50, 100);
        }
        applyThermalNoise(iq_buffer, receiver->getNoiseTemperature(), receiver->getRngEngine());
 
        if (timing_model->isEnabled())
        {
            std::vector pnoise(iq_buffer.size(), 0.0);
            std::ranges::generate(pnoise, [&] { return timing_model->getNextSample(); });
            pipeline::addPhaseNoiseToWindow(pnoise, iq_buffer);
        }
 
        const RealType fullscale = pipeline::applyDownsamplingAndQuantization(iq_buffer);
 
        if (reporter)
        {
            reporter->report(std::format("Writing HDF5 for {}", receiver->getName()), 75, 100);
        }
 
        std::filesystem::path out_path(output_dir);
        if (!std::filesystem::exists(out_path))
        {
            std::filesystem::create_directories(out_path);
        }
        const auto hdf5_filename = (out_path / std::format("{}_results.h5", receiver->getName())).string();
        auto file_metadata = buildCwMetadata(receiver, hdf5_filename, iq_buffer.size());
        pipeline::exportCwToHdf5(hdf5_filename, iq_buffer, fullscale, timing_model->getFrequency(), &file_metadata);
        if (metadata_collector)
        {
            metadata_collector->addFile(std::move(file_metadata));
        }
 
        if (reporter)
        {
            reporter->report(std::format("Finalized {}", receiver->getName()), 100, 100);
        }
    }

References processing::pipeline::addPhaseNoiseToWindow(), processing::pipeline::applyDownsamplingAndQuantization(), processing::pipeline::applyPulsedInterference(), applyThermalNoise(), processing::pipeline::exportCwToHdf5(), logging::FATAL, radar::Receiver::getMutableCwData(), radar::Object::getName(), radar::Receiver::getNoiseTemperature(), radar::Receiver::getPulsedInterferenceLog(), radar::Receiver::getRngEngine(), radar::Radar::getTiming(), logging::INFO, and LOG.

Here is the call graph for this function:

quantizeAndScaleWindow()

RealType processing::quantizeAndScaleWindow

(

std::span< ComplexType >

window

)

Simulates ADC quantization and scales a window of complex I/Q samples.

This function first finds the maximum absolute value in the I/Q data to determine the full-scale range. It then simulates the quantization process based on the configured number of ADC bits. If no quantization is specified (adc_bits=0), it normalizes the data to a maximum amplitude of 1.0.

Parameters

window

The window of complex I/Q samples to quantize and scale.

Returns

The full-scale value used for quantization/normalization.

Definition at line 131 of file signal_processor.cpp.

    {
        RealType max_value = 0;
        for (const auto& sample : window)
        {
            const RealType real_abs = std::fabs(sample.real());
            const RealType imag_abs = std::fabs(sample.imag());
 
            max_value = std::max({max_value, real_abs, imag_abs});
        }
 
        if (const auto adc_bits = params::adcBits(); adc_bits > 0)
        {
            adcSimulate(window, adc_bits, max_value);
        }
        else if (max_value != 0)
        {
            for (auto& sample : window)
            {
                sample /= max_value;
            }
        }
        return max_value;
    }

References params::adcBits().

Referenced by processing::pipeline::applyDownsamplingAndQuantization().

Here is the call graph for this function:

Here is the caller graph for this function:

renderWindow()

void processing::renderWindow	(	std::vector< ComplexType > &	window,
		RealType	length,
		RealType	start,
		RealType	fracDelay,
		std::span< const std::unique_ptr< serial::Response > >	responses
	)

Renders a time-window of I/Q data from a collection of raw radar responses.

This function orchestrates the process of converting abstract Response objects into a concrete vector of complex I/Q samples for a specific time window. It handles the superposition of multiple signals arriving at the receiver during the window and can use a thread pool for parallel processing.

Parameters

window	The output vector where the rendered I/Q samples will be added.
length	The duration of the time window in seconds.
start	The start time of the window in seconds.
fracDelay	A fractional sample delay to apply for fine-grained timing.
responses	A span of unique pointers to the Response objects to be rendered.

Definition at line 78 of file signal_processor.cpp.

    {
        const RealType end = start + length;
        std::queue<serial::Response*> work_list;
 
        for (const auto& response : responses)
        {
            if (response->startTime() <= end && response->endTime() >= start)
            {
                work_list.push(response.get());
            }
        }
 
        const RealType rate = params::rate() * params::oversampleRatio();
        const auto local_window_size = static_cast<std::size_t>(std::ceil(length * rate));
 
        std::vector local_window(local_window_size, ComplexType{});
 
        while (!work_list.empty())
        {
            const auto* resp = work_list.front();
            work_list.pop();
            processResponse(resp, local_window, rate, start, fracDelay, local_window_size);
        }
 
        for (std::size_t i = 0; i < local_window_size; ++i)
        {
            window[i] += local_window[i];
        }
    }

References params::oversampleRatio(), and params::rate().

Referenced by runPulsedFinalizer().

Here is the call graph for this function:

Here is the caller graph for this function:

runPulsedFinalizer()

void processing::runPulsedFinalizer	(	radar::Receiver *	receiver,
		const std::vector< std::unique_ptr< radar::Target > > *	targets,
		std::shared_ptr< core::ProgressReporter >	reporter,
		const std::string &	output_dir,
		std::shared_ptr< core::OutputMetadataCollector >	metadata_collector = nullptr
	)

The main function for a dedicated pulsed-mode receiver finalizer thread.

This function runs in a loop, dequeuing and processing RenderingJobs for a specific receiver. It handles all expensive rendering, signal processing, and I/O for that receiver's data.

Parameters

receiver	A pointer to the pulsed-mode receiver to process.
targets	A pointer to the world's list of targets for interference calculation.
reporter	Shared pointer to the progress reporter for status updates.
output_dir	Output directory for the simulation files.

Definition at line 111 of file finalizer.cpp.

    {
        const auto timing_model = receiver->getTiming()->clone();
        if (!timing_model)
        {
            LOG(logging::Level::FATAL, "Failed to clone timing model for receiver '{}'", receiver->getName());
            return;
        }
 
        std::filesystem::path out_path(output_dir);
        if (!std::filesystem::exists(out_path))
        {
            std::filesystem::create_directories(out_path);
        }
        const auto hdf5_filename = (out_path / std::format("{}_results.h5", receiver->getName())).string();
        core::OutputFileMetadata file_metadata{.receiver_id = receiver->getId(),
                                               .receiver_name = receiver->getName(),
                                               .mode = "pulsed",
                                               .path = hdf5_filename};
 
        std::unique_ptr<HighFive::File> h5_file;
        {
            std::scoped_lock lock(serial::hdf5_global_mutex);
            h5_file = std::make_unique<HighFive::File>(hdf5_filename, HighFive::File::Truncate);
        }
 
        unsigned chunk_index = 0;
 
        LOG(logging::Level::INFO, "Finalizer thread started for receiver '{}'. Outputting to '{}'.",
            receiver->getName(), hdf5_filename);
 
        auto last_report_time = std::chrono::steady_clock::now();
        const auto report_interval = std::chrono::milliseconds(100);
        const RealType rate = params::rate() * params::oversampleRatio();
        const RealType dt = 1.0 / rate;
 
        while (true)
        {
            core::RenderingJob job;
            if (!receiver->waitAndDequeueFinalizerJob(job))
            {
                break; // Shutdown signal received
            }
 
            const auto window_samples = static_cast<unsigned>(std::ceil(job.duration * rate));
            std::vector pnoise(window_samples, 0.0);
 
            RealType actual_start = job.ideal_start_time;
            RealType frac_delay = 0.0;
 
            if (timing_model->isEnabled())
            {
                pipeline::advanceTimingModel(timing_model.get(), receiver, rate);
                std::ranges::generate(pnoise, [&] { return timing_model->getNextSample(); });
                std::tie(actual_start, frac_delay) = pipeline::calculateJitteredStart(
                    job.ideal_start_time, pnoise[0], timing_model->getFrequency(), rate);
            }
 
            std::vector<ComplexType> window_buffer(window_samples);
 
            applyThermalNoise(window_buffer, receiver->getNoiseTemperature(receiver->getRotation(actual_start)),
                              receiver->getRngEngine());
 
            pipeline::applyCwInterference(window_buffer, actual_start, dt, receiver, job.active_cw_sources, targets);
 
            renderWindow(window_buffer, job.duration, actual_start, frac_delay, job.responses);
 
            if (timing_model->isEnabled())
            {
                pipeline::addPhaseNoiseToWindow(pnoise, window_buffer);
            }
 
            const RealType fullscale = pipeline::applyDownsamplingAndQuantization(window_buffer);
 
            const auto current_chunk_index = chunk_index++;
            const auto sample_start = file_metadata.total_samples;
            core::PulseChunkMetadata chunk_metadata{.chunk_index = current_chunk_index,
                                                    .i_dataset = std::format("chunk_{:06}_I", current_chunk_index),
                                                    .q_dataset = std::format("chunk_{:06}_Q", current_chunk_index),
                                                    .start_time = actual_start,
                                                    .sample_count = static_cast<std::uint64_t>(window_buffer.size()),
                                                    .sample_start = sample_start,
                                                    .sample_end_exclusive = sample_start +
                                                        static_cast<std::uint64_t>(window_buffer.size())};
 
            serial::addChunkToFile(*h5_file, window_buffer, actual_start, fullscale, current_chunk_index,
                                   &chunk_metadata);
            file_metadata.chunks.push_back(std::move(chunk_metadata));
            file_metadata.total_samples = file_metadata.chunks.back().sample_end_exclusive;
 
            if (reporter)
            {
                const auto now = std::chrono::steady_clock::now();
                if ((now - last_report_time) >= report_interval)
                {
                    reporter->report(std::format("Exporting {}: Chunk {}", receiver->getName(), chunk_index),
                                     static_cast<int>(chunk_index), 0);
                    last_report_time = now;
                }
            }
        }
 
        finalizePulsedMetadata(file_metadata);
        {
            std::scoped_lock lock(serial::hdf5_global_mutex);
            serial::writeOutputFileMetadataAttributes(*h5_file, file_metadata);
        }
 
        {
            // Safe destruction of the HDF5 object inside a lock
            std::scoped_lock lock(serial::hdf5_global_mutex);
            h5_file.reset();
        }
 
        if (metadata_collector)
        {
            metadata_collector->addFile(std::move(file_metadata));
        }
 
        if (reporter)
        {
            reporter->report(std::format("Finished Exporting {}", receiver->getName()), 100, 100);
        }
        LOG(logging::Level::INFO, "Finalizer thread for receiver '{}' finished.", receiver->getName());
    }

References core::RenderingJob::active_cw_sources, serial::addChunkToFile(), processing::pipeline::addPhaseNoiseToWindow(), processing::pipeline::advanceTimingModel(), processing::pipeline::applyCwInterference(), processing::pipeline::applyDownsamplingAndQuantization(), applyThermalNoise(), processing::pipeline::calculateJitteredStart(), core::PulseChunkMetadata::chunk_index, core::RenderingJob::duration, logging::FATAL, radar::Receiver::getId(), radar::Object::getName(), radar::Receiver::getNoiseTemperature(), radar::Receiver::getRngEngine(), radar::Object::getRotation(), radar::Radar::getTiming(), serial::hdf5_global_mutex, core::RenderingJob::ideal_start_time, logging::INFO, LOG, params::oversampleRatio(), params::rate(), core::OutputFileMetadata::receiver_id, renderWindow(), core::RenderingJob::responses, radar::Receiver::waitAndDequeueFinalizerJob(), and serial::writeOutputFileMetadataAttributes().

Here is the call graph for this function: