processing::pipeline Namespace Reference

Classes
struct	SampleSpan
	Half-open sample span used for dechirped LO-active finalization ranges. More...

Functions
void	advanceTimingModel (timing::Timing *timing_model, const radar::Receiver *receiver, RealType rate)
	Advances the receiver's timing model to the start of the next processing window.
std::tuple< RealType, RealType >	calculateJitteredStart (RealType ideal_start, RealType first_phase_noise, RealType carrier_freq, RealType rate)
	Calculates the jittered start time and fractional delay from a phase noise sample.
void	applyStreamingInterference (std::span< ComplexType > window, RealType actual_start, RealType dt, const radar::Receiver *receiver, const std::vector< core::ActiveStreamingSource > &streaming_sources, const std::vector< std::unique_ptr< radar::Target > > *targets, core::ReceiverTrackerCache &tracker_cache, const simulation::CwPhaseNoiseLookup *phase_noise_lookup=nullptr)
	Applies streaming interference to a time window.
void	applyPulsedInterference (std::vector< ComplexType > &iq_buffer, const std::vector< std::unique_ptr< serial::Response > > &interference_log)
	Renders and applies pulsed interference to a streaming IQ buffer.
void	applyPulsedInterference (std::vector< ComplexType > &iq_buffer, const std::vector< std::unique_ptr< serial::Response > > &interference_log, std::span< const SampleSpan > active_spans, RealType output_sample_rate)
	Renders and applies pulsed interference only inside active sample spans.
void	addPhaseNoiseToWindow (std::span< const RealType > noise, std::span< ComplexType > window)
	Applies a pre-generated sequence of phase noise samples to an I/Q buffer.
RealType	applyDownsamplingAndQuantization (std::vector< ComplexType > &buffer)
	Downsamples and quantizes an IQ buffer.
void	applyDownsampling (std::vector< ComplexType > &buffer)
	Downsamples an IQ buffer to the configured output rate without quantization.
void	exportStreamingToHdf5 (const std::string &filename, const std::vector< ComplexType > &iq_buffer, RealType fullscale, RealType ref_freq, const core::OutputFileMetadata *metadata=nullptr, RealType sample_rate=0.0)
	Exports a finalized streaming IQ buffer to an HDF5 file.

Function Documentation

addPhaseNoiseToWindow()

void processing::pipeline::addPhaseNoiseToWindow	(	std::span< const RealType >	noise,
		std::span< ComplexType >	window
	)

Applies a pre-generated sequence of phase noise samples to an I/Q buffer.

This function performs the complex multiplication IQ_out = IQ_in * e^(j*phase_noise) for each sample in the window, effectively modulating the phase of the signal.

Parameters

noise	A span of phase noise samples in radians.
window	The I/Q buffer to be modified.

Definition at line 230 of file finalizer_pipeline.cpp.

    {
        for (auto [n, w] : std::views::zip(noise, window))
        {
            w *= std::polar(1.0, n);
        }
    }

References max.

Referenced by processing::runPulsedFinalizer().

Here is the caller graph for this function:

advanceTimingModel()

void processing::pipeline::advanceTimingModel	(	timing::Timing *	timing_model,
		const radar::Receiver *	receiver,
		RealType	rate
	)

Advances the receiver's timing model to the start of the next processing window.

This function handles the "dead time" between receive windows. For sync-on-pulse models, it resets the phase and skips to the window's start offset. For free-running models, it skips the number of samples corresponding to the inter-pulse period.

Parameters

timing_model	The stateful timing model instance to advance.
receiver	The receiver whose properties (sync mode, PRF, etc.) determine how to advance the model.
rate	The oversampled simulation rate, used to calculate samples to skip.

Definition at line 67 of file finalizer_pipeline.cpp.

    {
 
        if ((timing_model == nullptr) || !timing_model->isEnabled())
        {
            return;
        }
 
        // Convert the duration-derived sample advance to a signed temporary first.
        // The physical calculation can legitimately produce a negative or zero result
        // (for example due to floor() or an inter-pulse gap that is not positive),
        // but skipSamples() models advancing by a non-negative sample count only.
        // After validating that the computed value is > 0, cast to std::size_t for
        // the skipSamples() call chain:
        //   Timing::skipSamples -> ClockModelGenerator::skipSamples ->
        //   MultirateGenerator::skipSamples.
        // This preserves the sign until validation and avoids passing invalid negative
        // counts into the timing/noise generators.
        if (timing_model->getSyncOnPulse())
        {
            timing_model->reset();
            const auto skip_samples = static_cast<long long>(std::floor(rate * receiver->getWindowSkip()));
            if (skip_samples > 0)
            {
                timing_model->skipSamples(static_cast<std::size_t>(skip_samples));
            }
        }
        else
        {
            const RealType inter_pulse_skip_duration = 1.0 / receiver->getWindowPrf() - receiver->getWindowLength();
            const auto samples_to_skip = static_cast<long long>(std::floor(rate * inter_pulse_skip_duration));
            if (samples_to_skip > 0)
            {
                timing_model->skipSamples(static_cast<std::size_t>(samples_to_skip));
            }
        }
    }

References max, and receiver.

Referenced by processing::runPulsedFinalizer().

Here is the caller graph for this function:

applyDownsampling()

void processing::pipeline::applyDownsampling

(

std::vector< ComplexType > &

buffer

)

Downsamples an IQ buffer to the configured output rate without quantization.

This is used by streaming output sinks that must apply their own fixed-scale quantization after all producer-side physics, interference, and noise are complete.

Parameters

buffer

The I/Q buffer to downsample in place when oversampling is configured.

Definition at line 244 of file finalizer_pipeline.cpp.

    {
        if (params::oversampleRatio() > 1)
        {
            buffer = std::move(fers_signal::downsample(buffer));
        }
    }

References fers_signal::downsample(), max, and params::oversampleRatio().

Referenced by applyDownsamplingAndQuantization(), and processing::runPulsedFinalizer().

Here is the call graph for this function:

Here is the caller graph for this function:

applyDownsamplingAndQuantization()

RealType processing::pipeline::applyDownsamplingAndQuantization

(

std::vector< ComplexType > &

buffer

)

Downsamples and quantizes an IQ buffer.

This function performs the final processing steps. If oversampling is enabled, it first downsamples the buffer to the final output rate. It then simulates an ADC by quantizing and scaling the data.

Parameters

buffer

The I/Q buffer to be processed. This is an in-out parameter; it will be replaced by the downsampled buffer if applicable.

Returns

The full-scale value (RealType) calculated during quantization, which is needed for HDF5 metadata.

Definition at line 238 of file finalizer_pipeline.cpp.

    {
        applyDownsampling(buffer);
        return quantizeAndScaleWindow(buffer);
    }

References applyDownsampling(), max, and processing::quantizeAndScaleWindow().

Here is the call graph for this function:

applyPulsedInterference() [1/2]

void processing::pipeline::applyPulsedInterference	(	std::vector< ComplexType > &	iq_buffer,
		const std::vector< std::unique_ptr< serial::Response > > &	interference_log
	)

Renders and applies pulsed interference to a streaming IQ buffer.

Processes a log of Response objects that represent pulsed signals received during a streaming receiver's operation. Each response is rendered into a temporary buffer and then added to the main streaming IQ buffer at the correct time offset.

Parameters

iq_buffer	The main, simulation-long IQ buffer for the streaming receiver.
interference_log	A list of Response objects representing the pulsed interference.

Definition at line 173 of file finalizer_pipeline.cpp.

    {
        const std::array active_spans{SampleSpan{.start = 0, .end_exclusive = iq_buffer.size()}};
        applyPulsedInterference(iq_buffer, interference_log, active_spans,
                                params::rate() * static_cast<RealType>(params::oversampleRatio()));
    }

References applyPulsedInterference(), max, params::oversampleRatio(), params::rate(), and processing::pipeline::SampleSpan::start.

Referenced by applyPulsedInterference().

Here is the call graph for this function:

Here is the caller graph for this function:

applyPulsedInterference() [2/2]

void processing::pipeline::applyPulsedInterference	(	std::vector< ComplexType > &	iq_buffer,
		const std::vector< std::unique_ptr< serial::Response > > &	interference_log,
		std::span< const SampleSpan >	active_spans,
		RealType	output_sample_rate
	)

Renders and applies pulsed interference only inside active sample spans.

Parameters

iq_buffer	The main, simulation-long IQ buffer for the streaming receiver.
interference_log	A list of Response objects representing the pulsed interference.
active_spans	Half-open sample spans where LO-active output should receive interference.
output_sample_rate	The sample rate used by iq_buffer, in hertz.

Definition at line 181 of file finalizer_pipeline.cpp.

    {
        for (const auto& response : interference_log)
        {
            unsigned psize = 0;
            RealType prate = std::numeric_limits<RealType>::quiet_NaN();
            const auto rendered_pulse = response->renderBinary(prate, psize, 0.0);
            const RealType rate_tolerance = std::numeric_limits<RealType>::epsilon() *
                std::max(std::abs(prate), std::abs(output_sample_rate)) * 16.0;
            if (std::abs(prate - output_sample_rate) > rate_tolerance)
            {
                throw std::runtime_error(
                    "Pulsed interference sample rate must match the streaming output sample rate.");
            }
 
            const RealType pulse_end_time = response->startTime() + static_cast<RealType>(psize) / prate;
            const auto pulse_start_index =
                static_cast<long long>(std::floor((response->startTime() - params::startTime()) * output_sample_rate));
            const auto pulse_end_index =
                static_cast<long long>(std::ceil((pulse_end_time - params::startTime()) * output_sample_rate));
            const auto buffer_end_index = static_cast<long long>(iq_buffer.size());
 
            for (const auto& span : active_spans)
            {
                const auto span_start = static_cast<long long>(std::min(span.start, iq_buffer.size()));
                const auto span_end = static_cast<long long>(std::min(span.end_exclusive, iq_buffer.size()));
                const auto dest_begin = std::max({span_start, pulse_start_index, 0LL});
                const auto dest_end = std::min({span_end, pulse_end_index, buffer_end_index});
                if (dest_begin >= dest_end)
                {
                    continue;
                }
 
                const auto copy_count = static_cast<std::size_t>(dest_end - dest_begin);
                auto source_index = dest_begin - pulse_start_index;
                for (std::size_t i = 0; i < copy_count; ++i, ++source_index)
                {
                    if (source_index >= 0 && source_index < static_cast<long long>(rendered_pulse.size()))
                    {
                        iq_buffer[static_cast<std::size_t>(dest_begin) + i] +=
                            rendered_pulse[static_cast<std::size_t>(source_index)];
                    }
                }
            }
        }
    }

References max, and params::startTime().

Here is the call graph for this function:

applyStreamingInterference()

void processing::pipeline::applyStreamingInterference	(	std::span< ComplexType >	window,
		RealType	actual_start,
		RealType	dt,
		const radar::Receiver *	receiver,
		const std::vector< core::ActiveStreamingSource > &	streaming_sources,
		const std::vector< std::unique_ptr< radar::Target > > *	targets,
		core::ReceiverTrackerCache &	tracker_cache,
		const simulation::CwPhaseNoiseLookup *	phase_noise_lookup = nullptr
	)

Applies streaming interference to a time window.

Iterates through each sample of a processing window, calculating the combined direct and reflected path contributions from all active streaming sources at that precise moment in time. The resulting complex sample is added to the window.

Parameters

window	The I/Q buffer for the receive window to which interference will be added.
actual_start	The jittered, sample-aligned start time of the window.
dt	The time step between samples (1.0 / rate).
receiver	The receiver being interfered with.
streaming_sources	A list of currently active streaming transmitters.
targets	The list of all targets for calculating reflected paths.
tracker_cache	Caller-owned reusable tracker storage for FMCW path boundary state.

Definition at line 114 of file finalizer_pipeline.cpp.

    {
        const simulation::CwPhaseNoiseLookup* lookup = phase_noise_lookup;
        std::optional<simulation::CwPhaseNoiseLookup> owned_lookup;
        if (lookup == nullptr)
        {
            std::unordered_map<SimId, std::shared_ptr<timing::Timing>> unique_timings;
            unique_timings.try_emplace(receiver->getTiming()->getId(), receiver->getTiming());
            for (const auto& streaming_source : streaming_sources)
            {
                unique_timings.try_emplace(streaming_source.transmitter->getTiming()->getId(),
                                           streaming_source.transmitter->getTiming());
            }
 
            std::vector<std::shared_ptr<timing::Timing>> timings;
            timings.reserve(unique_timings.size());
            for (const auto& entry : unique_timings)
            {
                timings.push_back(entry.second);
            }
 
            const RealType end_time =
                actual_start + dt * static_cast<RealType>(window.empty() ? 0 : (window.size() - 1));
            owned_lookup = simulation::CwPhaseNoiseLookup::build(timings, actual_start, end_time);
            lookup = &*owned_lookup;
        }
 
        prepareWindowTrackerCache(tracker_cache, streaming_sources.size(), targets->size());
 
        RealType t_sample = actual_start;
        for (auto& window_sample : window)
        {
            ComplexType streaming_interference_sample{0.0, 0.0};
            for (std::size_t source_index = 0; source_index < streaming_sources.size(); ++source_index)
            {
                const auto& streaming_source = streaming_sources[source_index];
                if (!receiver->checkFlag(radar::Receiver::RecvFlag::FLAG_NODIRECT))
                {
                    streaming_interference_sample += simulation::calculateStreamingDirectPathContribution(
                        streaming_source, receiver, t_sample, lookup, &tracker_cache.direct[source_index]);
                }
                for (std::size_t target_index = 0; target_index < targets->size(); ++target_index)
                {
                    const auto& target_ptr = (*targets)[target_index];
                    streaming_interference_sample += simulation::calculateStreamingReflectedPathContribution(
                        streaming_source, receiver, target_ptr.get(), t_sample, lookup,
                        &tracker_cache.reflected[source_index][target_index]);
                }
            }
            window_sample += streaming_interference_sample;
            t_sample += dt;
        }
    }

References simulation::CwPhaseNoiseLookup::build(), simulation::calculateStreamingDirectPathContribution(), simulation::calculateStreamingReflectedPathContribution(), radar::Receiver::FLAG_NODIRECT, max, and receiver.

Referenced by processing::runPulsedFinalizer().

Here is the call graph for this function:

Here is the caller graph for this function:

calculateJitteredStart()

std::tuple< RealType, RealType > processing::pipeline::calculateJitteredStart	(	RealType	ideal_start,
		RealType	first_phase_noise,
		RealType	carrier_freq,
		RealType	rate
	)

Calculates the jittered start time and fractional delay from a phase noise sample.

Converts the first phase noise sample (in radians) of a window into a time jitter offset. It then decomposes the resulting "actual" start time into a component aligned with the sample clock and a fractional delay to be handled by the rendering engine's interpolation filter.

Parameters

ideal_start	The perfect, jitter-free start time of the window.
first_phase_noise	The first phase noise sample (radians) for this window.
carrier_freq	The carrier frequency, needed to convert phase to time.
rate	The sampling rate, used for sample clock alignment.

Returns

A tuple containing:

1. The sample-aligned start time (RealType).
2. The fractional sample delay (RealType).

Definition at line 105 of file finalizer_pipeline.cpp.

    {
        const RealType actual_start = ideal_start + first_phase_noise / (2.0 * PI * carrier_freq);
        const RealType rounded_start = std::round(actual_start * rate) / rate;
        const RealType fractional_delay = actual_start * rate - std::round(actual_start * rate);
        return {rounded_start, fractional_delay};
    }

References max, and PI.

Referenced by processing::runPulsedFinalizer().

Here is the caller graph for this function:

exportStreamingToHdf5()

void processing::pipeline::exportStreamingToHdf5	(	const std::string &	filename,
		const std::vector< ComplexType > &	iq_buffer,
		RealType	fullscale,
		RealType	ref_freq,
		const core::OutputFileMetadata *	metadata = nullptr,
		RealType	sample_rate = 0.0
	)

Exports a finalized streaming IQ buffer to an HDF5 file.

Creates an HDF5 file, splits the complex buffer into real (I) and imaginary (Q) components, writes them as separate datasets, and adds relevant simulation parameters (sample rate, start time, etc.) as file attributes.

Parameters

filename	The path to the output HDF5 file.
iq_buffer	The final, processed I/Q data to write.
fullscale	The full-scale value from quantization, saved as metadata.
ref_freq	The reference carrier frequency, saved as metadata.
metadata	Optional structured output metadata to attach to the file.
sample_rate	Output sample rate to store in the file, or params::rate() when unset.

Definition at line 252 of file finalizer_pipeline.cpp.

    {
        std::scoped_lock const lock(serial::hdf5_global_mutex);
        try
        {
            HighFive::File file(filename, HighFive::File::Truncate);
 
            std::vector<RealType> i_data(iq_buffer.size());
            std::vector<RealType> q_data(iq_buffer.size());
            std::ranges::transform(iq_buffer, i_data.begin(), [](const auto& c) { return c.real(); });
            std::ranges::transform(iq_buffer, q_data.begin(), [](const auto& c) { return c.imag(); });
 
            HighFive::DataSet i_dataset = file.createDataSet<RealType>("I_data", HighFive::DataSpace::From(i_data));
            i_dataset.write(i_data);
            HighFive::DataSet q_dataset = file.createDataSet<RealType>("Q_data", HighFive::DataSpace::From(q_data));
            q_dataset.write(q_data);
 
            file.createAttribute("sampling_rate", sample_rate > 0.0 ? sample_rate : params::rate());
            file.createAttribute("start_time", params::startTime());
            file.createAttribute("fullscale", fullscale);
            file.createAttribute("reference_carrier_frequency", ref_freq);
            if (metadata != nullptr)
            {
                serial::writeOutputFileMetadataAttributes(file, *metadata);
            }
 
            LOG(logging::Level::INFO, "Successfully exported streaming data to '{}'", filename);
        }
        catch (const HighFive::Exception& err)
        {
            LOG(logging::Level::FATAL, "Error writing streaming data to HDF5 file '{}': {}", filename, err.what());
        }
    }

References c, logging::FATAL, serial::hdf5_global_mutex, logging::INFO, LOG, max, params::rate(), params::startTime(), and serial::writeOutputFileMetadataAttributes().

Referenced by serial::Hdf5OutputSink::Impl::closeStreamingStream().

Here is the call graph for this function:

Here is the caller graph for this function: