parameters.h

Go to the documentation of this file.

// SPDX-License-Identifier: GPL-2.0-only
//
// Copyright (c) 2006-2008 Marc Brooker and Michael Inggs
// Copyright (c) 2008-present FERS Contributors (see AUTHORS.md).
//
// See the GNU GPLv2 LICENSE file in the FERS project root for more information.
 
/**
 * @file parameters.h
 * @brief Defines the Parameters struct and provides methods for managing simulation parameters.
 */
 
#pragma once
 
#include <cstdint>
#include <expected>
#include <optional>
#include <string>
#include <string_view>
 
#include "config.h"
#include "logging.h"
 
namespace params
{
    /**
     * @enum CoordinateFrame
     * @brief Defines the coordinate systems supported for KML/geospatial export.
     */
    enum class CoordinateFrame : std::uint8_t
    {
        ENU, ///< East-North-Up local tangent plane (default)
        UTM, ///< Universal Transverse Mercator
        ECEF ///< Earth-Centered, Earth-Fixed
    };
 
    /**
     * @enum RotationAngleUnit
     * @brief Defines the units used at external rotation-path boundaries.
     */
    enum class RotationAngleUnit : std::uint8_t
    {
        Degrees, ///< Compass azimuth and elevation expressed in degrees
        Radians ///< Compass azimuth and elevation expressed in radians
    };
 
    /**
     * @class Parameters
     * @brief Struct to hold simulation parameters.
     */
    struct Parameters
    {
        constexpr static RealType DEFAULT_C = 299792458.0; ///< Speed of light (m/s)
        constexpr static RealType DEFAULT_BOLTZMANN_K = 1.3806503e-23; ///< Boltzmann constant
        RealType c = DEFAULT_C; ///< Speed of light (modifiable)
        RealType boltzmann_k = DEFAULT_BOLTZMANN_K; ///< Boltzmann constant
        RealType start = 0; ///< Start time for the simulation.
        RealType end = 0; ///< End time for the simulation.
        RealType sim_sampling_rate = 1000; ///< Time-step sampling rate for radar pulse simulation.
 
        // KML/geospatial export defaults to the location of the University of Cape Town in South Africa.
        double origin_latitude = -33.957652; ///< KML ENU geodetic origin latitude
        double origin_longitude = 18.4611991; ///< KML ENU geodetic origin longitude
        double origin_altitude = 111.01; ///< KML ENU geodetic origin altitude (in meters)
        CoordinateFrame coordinate_frame = CoordinateFrame::ENU; ///< KML/geospatial export coordinate frame
        RotationAngleUnit rotation_angle_unit = RotationAngleUnit::Degrees; ///< External rotation angle unit
        int utm_zone = 0; ///< KML UTM zone (1-60), if applicable
        bool utm_north_hemisphere = true; ///< KML UTM hemisphere, if applicable
        RealType rate = 0; ///< Rendering sample rate.
        std::optional<unsigned> random_seed; ///< Random seed for simulation.
        unsigned adc_bits = 0; ///< ADC quantization bits.
        unsigned filter_length = 33; ///< Default render filter length.
        unsigned render_threads = 1; ///< Number of worker threads to use for parallel tasks.
        std::string simulation_name; ///< The name of the simulation, from the XML.
        unsigned oversample_ratio = 1; ///< Oversampling ratio.
 
        /**
         * @brief Resets the parameters to their default-constructed state.
         * This ensures all members are restored to the values specified by their
         * default member initializers.
         */
        void reset() noexcept { *this = Parameters{}; }
    };
 
    inline Parameters params; ///< Global simulation parameter state.
 
    /**
     * @brief Get the speed of light.
     * @return The speed of light in meters per second.
     */
    inline RealType c() noexcept { return params.c; }
 
    /**
     * @brief Get the Boltzmann constant.
     * @return The Boltzmann constant.
     */
    inline RealType boltzmannK() noexcept { return params.boltzmann_k; }
 
    /**
     * @brief Get the start time for the simulation.
     * @return Start time for the simulation.
     */
    inline RealType startTime() noexcept { return params.start; }
 
    /**
     * @brief Get the end time for the simulation.
     * @return End time for the simulation.
     */
    inline RealType endTime() noexcept { return params.end; }
 
    /**
     * @brief Get the simulation sampling rate.
     * @return The simulation sampling rate.
     */
    inline RealType simSamplingRate() noexcept { return params.sim_sampling_rate; }
 
    /**
     * @brief Get the rendering sample rate.
     * @return The rendering sample rate.
     */
    inline RealType rate() noexcept { return params.rate; }
 
    /**
     * @brief Get the random seed.
     * @return The current random seed value.
     */
    inline unsigned randomSeed() noexcept { return params.random_seed.value_or(0); }
 
    /**
     * @brief Get the ADC quantization bits.
     * @return Number of ADC quantization bits.
     */
    inline unsigned adcBits() noexcept { return params.adc_bits; }
 
    /**
     * @brief Get the render filter length.
     * @return The length of the render filter.
     */
    inline unsigned renderFilterLength() noexcept { return params.filter_length; }
 
    /**
     * @brief Get the number of worker threads.
     * @return The number of worker threads.
     */
    inline unsigned renderThreads() noexcept { return params.render_threads; }
 
    /**
     * @brief Get the oversampling ratio.
     * @return The oversampling ratio.
     */
    inline unsigned oversampleRatio() noexcept { return params.oversample_ratio; }
 
    /**
     * @brief Gets the maximum supported oversampling ratio.
     * @return The maximum supported oversampling ratio.
     */
    inline constexpr unsigned maxSupportedOversampleRatio() noexcept { return 8u; }
 
    /**
     * @brief Validates that an oversampling ratio is supported.
     * @param ratio The oversampling ratio to validate.
     * @throws std::runtime_error if the ratio is outside the supported range.
     */
    inline void validateOversampleRatio(const unsigned ratio)
    {
        if (ratio == 0)
        {
            throw std::runtime_error("Oversample ratio must be >= 1");
        }
        if (ratio > maxSupportedOversampleRatio())
        {
            throw std::runtime_error("Oversampling ratios > 8 are not supported with the current fixed filter length "
                                     "of 33. Signal attenuation will occur.");
        }
    }
 
    /**
     * @brief Set the speed of light.
     * @param cValue The new speed of light.
     */
    inline void setC(RealType cValue) noexcept
    {
        params.c = cValue;
        LOG(logging::Level::INFO, "Propagation speed (c) set to: {:.5f}", cValue);
    }
 
    /**
     * @brief Set the start and end times for the simulation.
     * @param startTime Start time for the simulation.
     * @param endTime End time for the simulation.
     */
    inline void setTime(const RealType startTime, const RealType endTime) noexcept
    {
        params.start = startTime;
        params.end = endTime;
        LOG(logging::Level::INFO, "Simulation time set from {:.5f} to {:.5f} seconds", startTime, endTime);
    }
 
    /**
     * @brief Set the simulation sampling rate.
     * @param rate The new simulation sampling rate.
     */
    inline void setSimSamplingRate(const RealType rate) noexcept
    {
        params.sim_sampling_rate = rate;
        LOG(logging::Level::DEBUG, "Simulation sampling rate set to: {:.5f} Hz", rate);
    }
 
    /**
     * @brief Set the rendering sample rate.
     * @param rateValue The new sample rate for rendering.
     */
    inline void setRate(RealType rateValue)
    {
        if (rateValue <= 0)
        {
            throw std::runtime_error("Sampling rate must be > 0");
        }
        params.rate = rateValue;
        LOG(logging::Level::DEBUG, "Sample rate set to: {:.5f}", rateValue);
    }
 
    /**
     * @brief Set the random seed.
     * @param seed The new random seed value.
     */
    inline void setRandomSeed(const unsigned seed) noexcept
    {
        params.random_seed = seed;
        LOG(logging::Level::DEBUG, "Random seed set to: {}", seed);
    }
 
    /**
     * @brief Set the ADC quantization bits.
     * @param bits The new ADC quantization bits.
     */
    inline void setAdcBits(const unsigned bits) noexcept
    {
        params.adc_bits = bits;
        LOG(logging::Level::DEBUG, "ADC quantization bits set to: {}", bits);
    }
 
    /**
     * @brief Set the oversampling ratio.
     * @param ratio The new oversampling ratio.
     * @throws std::runtime_error if the ratio is zero.
     */
    inline void setOversampleRatio(unsigned ratio)
    {
        validateOversampleRatio(ratio);
        params.oversample_ratio = ratio;
        LOG(logging::Level::DEBUG, "Oversampling enabled with ratio: {}", ratio);
    }
 
    /**
     * @brief Set the geodetic origin for ENU KML/geospatial export.
     * @param lat The latitude of the KML origin.
     * @param lon The longitude of the KML origin.
     * @param alt The altitude of the KML origin (MSL).
     */
    inline void setOrigin(const double lat, const double lon, const double alt) noexcept
    {
        params.origin_latitude = lat;
        params.origin_longitude = lon;
        params.origin_altitude = alt;
        LOG(logging::Level::INFO, "KML origin set to lat: {}, lon: {}, alt: {}", lat, lon, alt);
    }
 
    /**
     * @brief Gets the KML/geospatial export origin latitude.
     * @return The KML origin latitude in degrees.
     */
    inline double originLatitude() noexcept { return params.origin_latitude; }
 
    /**
     * @brief Gets the KML/geospatial export origin longitude.
     * @return The KML origin longitude in degrees.
     */
    inline double originLongitude() noexcept { return params.origin_longitude; }
 
    /**
     * @brief Gets the KML/geospatial export origin altitude.
     * @return The KML origin altitude in meters.
     */
    inline double originAltitude() noexcept { return params.origin_altitude; }
 
    /**
     * @brief Set the number of worker threads.
     * @param threads The number of worker threads.
     * @return A `std::expected<void, std::string>` indicating success or an error message if the number of threads is
     * invalid.
     */
    inline std::expected<void, std::string> setThreads(const unsigned threads) noexcept
    {
        if (threads == 0)
        {
            return std::unexpected("Thread count must be >= 1");
        }
        params.render_threads = threads;
        LOG(logging::Level::INFO, "Number of worker threads set to: {}", threads);
        return {};
    }
 
    /**
     * @brief Set the coordinate system for KML/geospatial export.
     * @param frame The KML coordinate frame (ENU, UTM, ECEF).
     * @param zone The KML UTM zone, if applicable.
     * @param north The KML UTM hemisphere (true for North), if applicable.
     */
    inline void setCoordinateSystem(const CoordinateFrame frame, const int zone, const bool north) noexcept
    {
        params.coordinate_frame = frame;
        params.utm_zone = zone;
        params.utm_north_hemisphere = north;
    }
 
    /**
     * @brief Gets the KML/geospatial export coordinate frame.
     * @return The KML/geospatial export coordinate frame.
     */
    inline CoordinateFrame coordinateFrame() noexcept { return params.coordinate_frame; }
 
    /**
     * @brief Gets the external rotation angle unit.
     * @return The active rotation angle unit.
     */
    inline RotationAngleUnit rotationAngleUnit() noexcept { return params.rotation_angle_unit; }
 
    /**
     * @brief Gets the configured KML UTM zone.
     * @return The KML UTM zone, or zero when UTM KML export is not configured.
     */
    inline int utmZone() noexcept { return params.utm_zone; }
 
    /**
     * @brief Gets the configured KML UTM hemisphere.
     * @return true for northern hemisphere, false for southern hemisphere.
     */
    inline bool utmNorthHemisphere() noexcept { return params.utm_north_hemisphere; }
 
    /**
     * @brief Sets the external rotation angle unit.
     * @param unit The rotation angle unit to store.
     */
    inline void setRotationAngleUnit(const RotationAngleUnit unit) noexcept { params.rotation_angle_unit = unit; }
 
    /**
     * @brief Converts a rotation angle unit to its XML token.
     * @param unit The rotation angle unit.
     * @return The corresponding token string.
     */
    inline constexpr std::string_view rotationAngleUnitToken(const RotationAngleUnit unit) noexcept
    {
        return unit == RotationAngleUnit::Radians ? "rad" : "deg";
    }
 
    /**
     * @brief Parses a rotation angle unit from an XML token.
     * @param token The token to parse.
     * @return The parsed unit, or std::nullopt if the token is unknown.
     */
    inline std::optional<RotationAngleUnit> rotationAngleUnitFromToken(const std::string_view token) noexcept
    {
        if (token == "deg")
        {
            return RotationAngleUnit::Degrees;
        }
        if (token == "rad")
        {
            return RotationAngleUnit::Radians;
        }
        return std::nullopt;
    }
}