Classes
class	CwSignal
	Continuous-wave signal implementation. More...

class	DecadeUpsampler
	Implements a specialized upsampler with a fixed upsampling factor of 10. More...

class	DownsamplingSink
	Stateful FIR decimator for chunked streaming output. More...

class	DspFilter
	Abstract base class for digital filters. More...

class	FirFilter
	Implements a Finite Impulse Response (FIR) filter. More...

class	FmcwChirpSignal
	FMCW linear chirp signal implementation. More...

struct	FmcwIfRateRatio

struct	FmcwIfResamplerLimits

struct	FmcwIfResamplerPlan

struct	FmcwIfResamplerRequest

struct	FmcwIfResamplerStagePlan

class	FmcwIfResamplingSink

struct	FmcwIfZeroInputResult

class	FmcwTriangleSignal
	FMCW symmetric triangular modulation signal implementation. More...

class	IirFilter
	Implements an Infinite Impulse Response (IIR) filter. More...

class	RadarSignal
	Class representing a radar signal with associated properties. More...

class	Signal
	Class for handling radar waveform signal data. More...

Enumerations
enum class	FmcwIfResamplerStageKind : std::uint8_t { HalfBandDecimateBy2 , RationalPolyphase }

enum class	FmcwChirpDirection : std::uint8_t { Up , Down }
	Sweep direction for a linear FMCW chirp. More...

Functions
void	to_json (nlohmann::json &j, const RadarSignal &rs)

void	from_json (const nlohmann::json &j, std::unique_ptr< RadarSignal > &rs)

void	upsample (const std::span< const ComplexType > in, const unsigned size, std::span< ComplexType > out)
	Upsamples a complex waveform with zero-stuffing followed by Blackman FIR filtering.

std::vector< ComplexType >	downsample (std::span< const ComplexType > in)
	Low-pass filters and decimates an oversampled complex waveform back to base rate.

FmcwIfRateRatio	approximateFmcwIfRateRatio (const RealType output_sample_rate_hz, const RealType input_sample_rate_hz, const FmcwIfResamplerLimits &limits)

FmcwIfResamplerPlan	planFmcwIfResampler (const FmcwIfResamplerRequest &request)

std::string_view	fmcwChirpDirectionToken (FmcwChirpDirection direction) noexcept
	Converts a chirp direction to the schema token.

FmcwChirpDirection	parseFmcwChirpDirection (std::string_view direction)
	Parses a schema chirp direction token.

Enumeration Type Documentation

◆ FmcwChirpDirection

enum class fers_signal::FmcwChirpDirection : std::uint8_t

strong

Sweep direction for a linear FMCW chirp.

Enumerator
Up	Instantaneous baseband frequency increases over the chirp.
Down	Instantaneous baseband frequency decreases over the chirp.

Definition at line 36 of file radar_signal.h.

    {
        Up, ///< Instantaneous baseband frequency increases over the chirp.
        Down ///< Instantaneous baseband frequency decreases over the chirp.
    };

◆ FmcwIfResamplerStageKind

enum class fers_signal::FmcwIfResamplerStageKind : std::uint8_t

strong

Enumerator
HalfBandDecimateBy2
RationalPolyphase

Definition at line 25 of file if_resampler.h.

    {
        HalfBandDecimateBy2,
        RationalPolyphase
    };

Function Documentation

◆ approximateFmcwIfRateRatio()

FmcwIfRateRatio fers_signal::approximateFmcwIfRateRatio	(	const RealType	output_sample_rate_hz,
		const RealType	input_sample_rate_hz,
		const FmcwIfResamplerLimits &	limits
	)

Definition at line 295 of file if_resampler.cpp.

    {
        const RealType target = checkedRatio(output_sample_rate_hz, input_sample_rate_hz);
        if (std::abs(target - 1.0) <= limits.ratio_relative_tolerance)
        {
            return {.numerator = 1,
                    .denominator = 1,
                    .requested_ratio = target,
                    .actual_ratio = 1.0,
                    .relative_error = std::abs(target - 1.0)};
        }
 
        std::uint64_t prev_num = 0;
        std::uint64_t num = 1;
        std::uint64_t prev_den = 1;
        std::uint64_t den = 0;
        RealType x = target;
        FmcwIfRateRatio best{.requested_ratio = target};
 
        for (std::size_t iter = 0; iter < 128; ++iter)
        {
            const auto a = static_cast<std::uint64_t>(std::floor(x));
            const auto next_num = a * num + prev_num;
            const auto next_den = a * den + prev_den;
            if (next_den == 0 || next_den > limits.max_ratio_denominator)
            {
                break;
            }
 
            const RealType actual = static_cast<RealType>(next_num) / static_cast<RealType>(next_den);
            const RealType relative_error = std::abs(actual - target) / target;
            best = {.numerator = next_num,
                    .denominator = next_den,
                    .requested_ratio = target,
                    .actual_ratio = actual,
                    .relative_error = relative_error};
            if (relative_error <= limits.ratio_relative_tolerance)
            {
                return best;
            }
 
            const RealType remainder = x - static_cast<RealType>(a);
            if (std::abs(remainder) <= std::numeric_limits<RealType>::epsilon())
            {
                break;
            }
            x = 1.0 / remainder;
            prev_num = num;
            num = next_num;
            prev_den = den;
            den = next_den;
        }
 
        throw std::runtime_error("IF resampler cannot approximate output/input sample-rate ratio within tolerance; "
                                 "increase max denominator or choose a representable IF sample rate");
    }

References a, max, fers_signal::FmcwIfResamplerLimits::max_ratio_denominator, and fers_signal::FmcwIfResamplerLimits::ratio_relative_tolerance.

Referenced by planFmcwIfResampler().

Here is the caller graph for this function:

◆ downsample()

std::vector< ComplexType > fers_signal::downsample ( std::span< const ComplexType > in )

Low-pass filters and decimates an oversampled complex waveform back to base rate.

Downsamples a signal by a given ratio.

The same fixed-length FIR design is reused for anti-alias filtering, and unsupported ratios fail fast before filtering begins.

Parameters

in	Input span of oversampled complex samples.

Returns: Base-rate complex samples truncated to floor(in.size() / oversampleRatio()).

Exceptions

std::invalid_argument	if `in` is empty.
std::runtime_error	if the configured oversampling ratio is unsupported.

Parameters

in	Input span of complex samples.

Exceptions

std::invalid_argument if the input or output spans are empty or the ratio is zero.

Definition at line 183 of file dsp_filters.cpp.

    {
        if (in.empty())
        {
            throw std::invalid_argument("Input span is empty in Downsample");
        }
 
        const unsigned ratio = params::oversampleRatio();
        // TODO: Replace with a more efficient multirate downsampling implementation.
        validateOversamplingConfig(ratio);
        const unsigned filter_length = params::renderFilterLength();
        const auto design = blackmanFir(1 / static_cast<RealType>(ratio), ratio, filter_length);
        const auto filt_length = design.coeffs.size();
 
        std::vector tmp(in.size() + filt_length, ComplexType{0, 0});
 
        std::ranges::copy(in, tmp.begin());
 
        const FirFilter filt(design.coeffs);
        filt.filter(tmp);
 
        const auto downsampled_size = in.size() / ratio;
        std::vector<ComplexType> out(downsampled_size);
        const auto filter_delay = filt_length / 2;
        for (std::size_t i = 0; i < downsampled_size; ++i)
        {
            const auto source_index = i * static_cast<std::size_t>(ratio) + filter_delay;
            out[i] = tmp[source_index] / static_cast<RealType>(ratio);
        }
 
        return out;
    }

References max, params::oversampleRatio(), and params::renderFilterLength().

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

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fmcwChirpDirectionToken()

std::string_view fers_signal::fmcwChirpDirectionToken ( const FmcwChirpDirection direction )

noexcept

Converts a chirp direction to the schema token.

Definition at line 30 of file radar_signal.cpp.

    {
        return direction == FmcwChirpDirection::Down ? "down" : "up";
    }

References Down, and max.

Referenced by serial::xml_serializer_utils::serializeWaveform(), and to_json().

Here is the caller graph for this function:

◆ from_json()

void fers_signal::from_json	(	const nlohmann::json &	j,
		std::unique_ptr< RadarSignal > &	rs
	)

Definition at line 653 of file json_serializer.cpp.

    {
        const auto name = j.at("name").get<std::string>();
        const auto id = parse_json_id(j, "id", "waveform");
        const auto power = j.at("power").get<RealType>();
        const auto carrier = j.at("carrier_frequency").get<RealType>();
 
        if (j.contains("cw"))
        {
            auto cw_signal = std::make_unique<CwSignal>();
            rs = std::make_unique<RadarSignal>(name, power, carrier, params::endTime() - params::startTime(),
                                               std::move(cw_signal), id);
        }
        else if (j.contains("fmcw_linear_chirp"))
        {
            const auto& fmcw_json = j.at("fmcw_linear_chirp");
            const auto direction = parseFmcwChirpDirection(fmcw_json.at("direction").get<std::string>());
            std::optional<std::size_t> chirp_count;
            if (fmcw_json.contains("chirp_count"))
            {
                const auto parsed_count = fmcw_json.at("chirp_count").get<long long>();
                if (parsed_count <= 0)
                {
                    throw std::runtime_error("Waveform '" + name + "' has an invalid chirp_count.");
                }
                chirp_count = static_cast<std::size_t>(parsed_count);
            }
 
            auto fmcw_signal = std::make_unique<FmcwChirpSignal>(
                fmcw_json.at("chirp_bandwidth").get<RealType>(), fmcw_json.at("chirp_duration").get<RealType>(),
                fmcw_json.at("chirp_period").get<RealType>(), fmcw_json.value("start_frequency_offset", 0.0),
                chirp_count, direction);
            rs = std::make_unique<RadarSignal>(name, power, carrier, fmcw_signal->getChirpDuration(),
                                               std::move(fmcw_signal), id);
            validate_fmcw_waveform(*rs, "Waveform '" + name + "'");
        }
        else if (j.contains("fmcw_triangle"))
        {
            const auto& fmcw_json = j.at("fmcw_triangle");
            std::optional<std::size_t> triangle_count;
            if (fmcw_json.contains("triangle_count"))
            {
                const auto& count_json = fmcw_json.at("triangle_count");
                if (!count_json.is_number_integer() && !count_json.is_number_unsigned())
                {
                    throw std::runtime_error("Waveform '" + name + "' has an invalid triangle_count.");
                }
                const auto parsed_count = count_json.get<long long>();
                if (parsed_count <= 0)
                {
                    throw std::runtime_error("Waveform '" + name + "' has an invalid triangle_count.");
                }
                triangle_count = static_cast<std::size_t>(parsed_count);
            }
 
            auto fmcw_signal = std::make_unique<FmcwTriangleSignal>(
                fmcw_json.at("chirp_bandwidth").get<RealType>(), fmcw_json.at("chirp_duration").get<RealType>(),
                fmcw_json.value("start_frequency_offset", 0.0), triangle_count);
            rs = std::make_unique<RadarSignal>(name, power, carrier, fmcw_signal->getTrianglePeriod(),
                                               std::move(fmcw_signal), id);
            validate_fmcw_waveform(*rs, "Waveform '" + name + "'");
        }
        else if (j.contains("pulsed_from_file"))
        {
            const auto& pulsed_file = j.at("pulsed_from_file");
            const auto filename = pulsed_file.value("filename", "");
            if (filename.empty())
            {
                LOG(logging::Level::WARNING, "Skipping load of file-based waveform '{}': filename is empty.", name);
                return; // rs remains nullptr
            }
            rs = serial::loadWaveformFromFile(name, filename, power, carrier, id);
        }
        else
        {
            throw std::runtime_error("Unsupported waveform type in from_json for '" + name + "'");
        }
    }

References params::endTime(), serial::loadWaveformFromFile(), LOG, max, parseFmcwChirpDirection(), params::startTime(), and logging::WARNING.

Referenced by serial::parse_waveform_from_json().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ parseFmcwChirpDirection()

FmcwChirpDirection fers_signal::parseFmcwChirpDirection ( const std::string_view direction )

Parses a schema chirp direction token.

Definition at line 35 of file radar_signal.cpp.

    {
        if (direction == "up")
        {
            return FmcwChirpDirection::Up;
        }
        if (direction == "down")
        {
            return FmcwChirpDirection::Down;
        }
        throw std::runtime_error("Unsupported FMCW chirp direction '" + std::string(direction) + "'.");
    }

References Down, max, and Up.

Referenced by from_json(), and serial::xml_parser_utils::parseWaveform().

Here is the caller graph for this function:

◆ planFmcwIfResampler()

FmcwIfResamplerPlan fers_signal::planFmcwIfResampler ( const FmcwIfResamplerRequest & request )

Definition at line 353 of file if_resampler.cpp.

    {
        const auto ratio =
            approximateFmcwIfRateRatio(request.output_sample_rate_hz, request.input_sample_rate_hz, request.limits);
        validateLimit(std::isfinite(request.filter_bandwidth_hz) && request.filter_bandwidth_hz > 0.0,
                      "IF resampler filter bandwidth must be positive");
        validateLimit(request.filter_bandwidth_hz < request.output_sample_rate_hz * 0.5,
                      "IF resampler filter bandwidth must be below output Nyquist");
        validateLimit(request.limits.max_taps_per_stage > 0, "IF resampler max taps per stage must be positive");
        validateLimit(request.limits.max_macs_per_output_sample > 0.0, "IF resampler max MAC budget must be positive");
        validateLimit(request.limits.max_phase_refinement > 0, "IF resampler phase refinement limit must be positive");
 
        const RealType transition_hz = derivedTransitionWidth(request);
 
        FmcwIfResamplerPlan plan;
        plan.input_sample_rate_hz = request.input_sample_rate_hz;
        plan.requested_output_sample_rate_hz = request.output_sample_rate_hz;
        plan.actual_output_sample_rate_hz = request.input_sample_rate_hz * ratio.actual_ratio;
        plan.filter_bandwidth_hz = request.filter_bandwidth_hz;
        plan.filter_transition_width_hz = transition_hz;
        plan.stopband_attenuation_db = request.stopband_attenuation_db;
        plan.overall_ratio = ratio;
        plan.limits = request.limits;
 
        auto remaining_up = ratio.numerator;
        auto remaining_down = ratio.denominator;
        RealType current_rate_hz = request.input_sample_rate_hz;
 
        while (remaining_down % 2 == 0 && remaining_down > 1)
        {
            if (request.filter_bandwidth_hz > current_rate_hz * kHalfBandPassbandFraction)
            {
                break;
            }
 
            const RealType available_transition = current_rate_hz * 0.25 - request.filter_bandwidth_hz;
            if (available_transition <= 0.0)
            {
                break;
            }
 
            const RealType halfband_transition =
                std::min(current_rate_hz * kHalfBandTransitionFraction, available_transition);
            plan.stages.push_back(makeStage(FmcwIfResamplerStageKind::HalfBandDecimateBy2, current_rate_hz, 1, 2,
                                            request.filter_bandwidth_hz, halfband_transition,
                                            request.stopband_attenuation_db, request.limits));
            current_rate_hz *= 0.5;
            remaining_down /= 2;
        }
 
        if (remaining_up != remaining_down)
        {
            plan.stages.push_back(makeStage(FmcwIfResamplerStageKind::RationalPolyphase, current_rate_hz, remaining_up,
                                            remaining_down, request.filter_bandwidth_hz, transition_hz,
                                            request.stopband_attenuation_db, request.limits));
        }
 
        for (const auto& stage : plan.stages)
        {
            plan.group_delay_seconds += stage.group_delay_seconds;
        }
        recomputePlanCost(plan);
 
        if (plan.estimated_macs_per_output_sample > request.limits.max_macs_per_output_sample)
        {
            throw std::runtime_error(
                "IF resampler estimated MAC cost " + std::to_string(plan.estimated_macs_per_output_sample) +
                " exceeds maximum " + std::to_string(request.limits.max_macs_per_output_sample) +
                "; increase if_sample_rate, reduce if_filter_bandwidth, or increase transition width");
        }
 
        plan.group_delay_output_samples = plan.group_delay_seconds * plan.actual_output_sample_rate_hz;
        plan.warmup_discard_samples = static_cast<std::uint64_t>(std::floor(plan.group_delay_output_samples));
        plan.fractional_output_delay_samples =
            plan.group_delay_output_samples - static_cast<RealType>(plan.warmup_discard_samples);
        plan.fractional_phase_offset = plan.fractional_output_delay_samples * static_cast<RealType>(ratio.denominator);
        plan.branch_interpolation_fraction =
            plan.fractional_phase_offset * static_cast<RealType>(plan.phase_refinement) -
            std::floor(plan.fractional_phase_offset * static_cast<RealType>(plan.phase_refinement));
        plan.estimated_timing_error_seconds =
            0.5 / (plan.actual_output_sample_rate_hz * static_cast<RealType>(plan.phase_refinement));
        plan.estimated_phase_error_radians =
            2.0 * PI * request.filter_bandwidth_hz * plan.estimated_timing_error_seconds;
        configureFractionalDelay(plan);
 
        return plan;
    }

Here is the call graph for this function:

◆ to_json()

void fers_signal::to_json	(	nlohmann::json &	j,
		const RadarSignal &	rs
	)

Definition at line 601 of file json_serializer.cpp.

    {
        j = nlohmann::json{{"id", sim_id_to_json(rs.getId())},
                           {"name", rs.getName()},
                           {"power", rs.getPower()},
                           {"carrier_frequency", rs.getCarrier()}};
        if (dynamic_cast<const CwSignal*>(rs.getSignal()) != nullptr)
        {
            j["cw"] = nlohmann::json::object();
        }
        else if (const auto* fmcw = rs.getFmcwChirpSignal(); fmcw != nullptr)
        {
            j["fmcw_linear_chirp"] = {{"direction", std::string(fmcwChirpDirectionToken(fmcw->getDirection()))},
                                      {"chirp_bandwidth", fmcw->getChirpBandwidth()},
                                      {"chirp_duration", fmcw->getChirpDuration()},
                                      {"chirp_period", fmcw->getChirpPeriod()}};
            if (std::abs(fmcw->getStartFrequencyOffset()) > EPSILON)
            {
                j["fmcw_linear_chirp"]["start_frequency_offset"] = fmcw->getStartFrequencyOffset();
            }
            if (fmcw->getChirpCount().has_value())
            {
                j["fmcw_linear_chirp"]["chirp_count"] = *fmcw->getChirpCount();
            }
        }
        else if (const auto* triangle = rs.getFmcwTriangleSignal(); triangle != nullptr)
        {
            j["fmcw_triangle"] = {{"chirp_bandwidth", triangle->getChirpBandwidth()},
                                  {"chirp_duration", triangle->getChirpDuration()}};
            if (std::abs(triangle->getStartFrequencyOffset()) > EPSILON)
            {
                j["fmcw_triangle"]["start_frequency_offset"] = triangle->getStartFrequencyOffset();
            }
            if (triangle->getTriangleCount().has_value())
            {
                j["fmcw_triangle"]["triangle_count"] = *triangle->getTriangleCount();
            }
        }
        else
        {
            if (const auto& filename = rs.getFilename(); filename.has_value())
            {
                j["pulsed_from_file"] = {{"filename", *filename}};
            }
            else
            {
                throw std::logic_error("Attempted to serialize a file-based waveform named '" + rs.getName() +
                                       "' without a source filename.");
            }
        }
    }

References EPSILON, fmcwChirpDirectionToken(), and max.

Here is the call graph for this function:

◆ upsample()

void fers_signal::upsample	(	const std::span< const ComplexType >	in,
		const unsigned	size,
		std::span< ComplexType >	out
	)

Upsamples a complex waveform with zero-stuffing followed by Blackman FIR filtering.

Upsamples a signal by a given ratio.

The production path uses a fixed-length single-stage FIR, so unsupported ratios fail fast before filtering begins.

Parameters

in	Input span of base-rate complex samples.
size	Number of input samples to process from `in`.
out	Output span receiving `size` * oversampleRatio() filtered samples.

Exceptions

std::runtime_error if the configured oversampling ratio is unsupported.

Parameters

in	Input span of complex samples.
size	Size of the input signal.
out	Output span for upsampled complex samples.

Exceptions

std::invalid_argument if the input or output spans are empty or the ratio is zero.

Definition at line 145 of file dsp_filters.cpp.

    {
        const unsigned ratio = params::oversampleRatio();
        // TODO: this would be better as a multirate upsampler
        // This implementation is functional but suboptimal.
        // Users requiring higher accuracy should oversample outside FERS until this is addressed.
        validateOversamplingConfig(ratio);
        const unsigned filter_length = params::renderFilterLength();
        const auto design = blackmanFir(1 / static_cast<RealType>(ratio), ratio, filter_length);
        const auto filt_length = static_cast<unsigned>(design.coeffs.size());
 
        const auto oversampled_size = static_cast<std::size_t>(size) * static_cast<std::size_t>(ratio);
        std::vector tmp(oversampled_size + static_cast<std::size_t>(filt_length), ComplexType{0.0, 0.0});
 
        for (unsigned i = 0; i < size; ++i)
        {
            tmp[static_cast<std::size_t>(i) * static_cast<std::size_t>(ratio)] = in[i];
        }
 
        const FirFilter filt(design.coeffs);
        filt.filter(tmp);
 
        const auto delay = static_cast<std::size_t>(filt_length / 2);
        const std::span<const ComplexType> filtered_output(tmp.data() + delay, oversampled_size);
        std::ranges::copy(filtered_output, out.begin());
    }

References max, params::oversampleRatio(), and params::renderFilterLength().

Referenced by fers_signal::Signal::load(), and fers_signal::DecadeUpsampler::~DecadeUpsampler().

Here is the call graph for this function:

Here is the caller graph for this function:

Classes

Enumerations

Functions

Enumeration Type Documentation

◆ FmcwChirpDirection

◆ FmcwIfResamplerStageKind

Function Documentation

◆ approximateFmcwIfRateRatio()

◆ downsample()

◆ fmcwChirpDirectionToken()

◆ from_json()

◆ parseFmcwChirpDirection()

◆ planFmcwIfResampler()

◆ to_json()

◆ upsample()