core Namespace Reference

Classes
class	Config
	Configuration structure for the application. More...
struct	Event
	Represents a single event in the simulation's time-ordered queue. More...
struct	EventComparator
	A custom comparator for the event priority queue. More...
class	ProgressReporter
	A thread-safe wrapper for the simulation progress callback. More...
struct	RenderingJob
	A data packet containing all information needed to process one receive window. More...
struct	SimulationState
	Holds the dynamic global state of the simulation. More...
class	World
	The World class manages the simulator environment. More...

Enumerations
enum class	EventType {   TX_PULSED_START , RX_PULSED_WINDOW_START , RX_PULSED_WINDOW_END , TX_CW_START ,   TX_CW_END , RX_CW_START , RX_CW_END }
	Enumerates the types of events that can occur in the simulation. More...

Functions
RealType	besselJ1 (const RealType x) noexcept
	Computes the Bessel function of the first kind (order 1) for a given value.
unsigned	countProcessors () noexcept
	Detects the number of CPUs on the machine.
std::string	toString (const EventType type)
	Converts an EventType enum to its string representation.
void	runEventDrivenSim (World *world, pool::ThreadPool &pool, const std::function< void(const std::string &, int, int)> &progress_callback)
	Runs the unified, event-driven radar simulation.
void	showHelp (const char *programName) noexcept
	Displays the help message.
void	showVersion () noexcept
	Displays the version information.
std::expected< Config, std::string >	parseArguments (int argc, char *argv[]) noexcept
	Parses command-line arguments.

Enumeration Type Documentation

EventType

enum class core::EventType

strong

Enumerates the types of events that can occur in the simulation.

Enumerator
TX_PULSED_START	A pulsed transmitter begins emitting a pulse.
RX_PULSED_WINDOW_START	A pulsed receiver opens its listening window.
RX_PULSED_WINDOW_END	A pulsed receiver closes its listening window.
TX_CW_START	A continuous-wave transmitter starts transmitting.
TX_CW_END	A continuous-wave transmitter stops transmitting.
RX_CW_START	A continuous-wave receiver starts listening.
RX_CW_END	A continuous-wave receiver stops listening.

Definition at line 27 of file sim_events.h.

    {
        TX_PULSED_START, ///< A pulsed transmitter begins emitting a pulse.
        RX_PULSED_WINDOW_START, ///< A pulsed receiver opens its listening window.
        RX_PULSED_WINDOW_END, ///< A pulsed receiver closes its listening window.
        TX_CW_START, ///< A continuous-wave transmitter starts transmitting.
        TX_CW_END, ///< A continuous-wave transmitter stops transmitting.
        RX_CW_START, ///< A continuous-wave receiver starts listening.
        RX_CW_END, ///< A continuous-wave receiver stops listening.
    };

Function Documentation

besselJ1()

RealType core::besselJ1 ( const RealType  x )

noexcept

Computes the Bessel function of the first kind (order 1) for a given value.

Parameters

x	The value for which the Bessel function is to be computed.

Returns

The computed value of the Bessel function of the first kind (order 1).

Definition at line 28 of file portable_utils.h.

{ return j1(x); }

countProcessors()

unsigned core::countProcessors ( )

noexcept

Detects the number of CPUs on the machine.

Returns

The number of CPUs detected, or 1 if detection fails.

Definition at line 35 of file portable_utils.h.

    {
        if (const unsigned hardware_threads = std::thread::hardware_concurrency(); hardware_threads > 0)
        {
            return hardware_threads;
        }
        LOG(logging::Level::ERROR, "Unable to get CPU count, assuming 1.");
        return 1;
    }

References logging::ERROR, and LOG.

parseArguments()

std::expected< Config, std::string > core::parseArguments ( int  argc, char *  argv[]  )

noexcept

Parses command-line arguments.

Processes the command-line arguments, validating them and extracting configurations like script file, logging level, and thread count.

Parameters

argc	The argument count.
argv	The argument vector.

Returns

std::expected<Config, std::string> Parsed configuration or an error message.

Definition at line 201 of file arg_parser.cpp.

         :
  <scriptfile>            Path to the simulation script file (XML)
 
Example:
  )" << programName
                  << R"( simulation.fersxml --log-level=DEBUG --log-file=output.log -n=4
 
This program runs radar simulations based on an XML script file.
Make sure the script file follows the correct format to avoid errors.
)";
    }
 
    void showVersion() noexcept
    {
        std::cout << R"(
/------------------------------------------------\
| FERS - The Flexible Extensible Radar Simulator |
| Version 1.0.0                                  |

Referenced by main().

Here is the caller graph for this function:

runEventDrivenSim()

void core::runEventDrivenSim	(	World *	world,
		pool::ThreadPool &	pool,
		const std::function< void(const std::string &, int, int)> &	progress_callback
	)

Runs the unified, event-driven radar simulation.

This function is the core engine of the simulator. It advances time by processing events from a global priority queue. It handles both pulsed and continuous-wave (CW) physics, dispatching finalization tasks to worker threads for asynchronous processing.

Parameters

world	A pointer to the simulation world containing all entities and state.
pool	A reference to the thread pool for executing tasks.
progress_callback	An optional callback function for reporting progress.

Definition at line 57 of file sim_threading.cpp.

    {
        auto& event_queue = world->getEventQueue();
        auto& [t_current, active_cw_transmitters] = world->getSimulationState();
        const RealType end_time = params::endTime();
        const RealType dt_sim = 1.0 / (params::rate() * params::oversampleRatio());
 
        // Create shared thread-safe reporter
        auto reporter = std::make_shared<ProgressReporter>(progress_callback);
 
        if (progress_callback)
        {
            reporter->report("Initializing event-driven simulation...", 0, 100);
        }
 
        // Start dedicated finalizer threads for each pulsed receiver. This creates a
        // one-thread-per-receiver pipeline for asynchronous data processing.
        std::vector<std::jthread> finalizer_threads;
        for (const auto& receiver_ptr : world->getReceivers())
        {
            if (receiver_ptr->getMode() == OperationMode::PULSED_MODE)
            {
                finalizer_threads.emplace_back(processing::runPulsedFinalizer, receiver_ptr.get(), &world->getTargets(),
                                               reporter);
            }
        }
 
        LOG(Level::INFO, "Starting unified event-driven simulation loop.");
 
        // Throttling state for the main loop
        auto last_report_time = std::chrono::steady_clock::now();
        int last_reported_percent = -1;
        const auto report_interval = std::chrono::milliseconds(100); // Max 10 updates/sec
 
        // Main Simulation Loop
        while (!event_queue.empty() && t_current <= end_time)
        {
            // Advance Clock to the next scheduled event
            const auto [timestamp, event_type, source_object] = event_queue.top();
            event_queue.pop();
 
            const RealType t_event = timestamp;
 
            // Before processing the event, run a time-stepped inner loop to calculate
            // physics for any active continuous-wave systems. This handles the "continuous"
            // part of the simulation between discrete events.
            if (t_event > t_current)
            {
                const RealType t_next_event = t_event;
 
                const auto start_index = static_cast<size_t>(std::ceil((t_current - params::startTime()) / dt_sim));
                const auto end_index = static_cast<size_t>(std::ceil((t_next_event - params::startTime()) / dt_sim));
 
                for (size_t sample_index = start_index; sample_index < end_index; ++sample_index)
                {
                    const RealType t_step = params::startTime() + static_cast<RealType>(sample_index) * dt_sim;
 
                    for (const auto& receiver_ptr : world->getReceivers())
                    {
                        if (receiver_ptr->getMode() == OperationMode::CW_MODE && receiver_ptr->isActive())
                        {
                            ComplexType total_sample{0.0, 0.0};
                            // Query active CW sources
                            for (const auto& cw_source : active_cw_transmitters)
                            {
                                // Calculate direct and reflected paths
                                if (!receiver_ptr->checkFlag(Receiver::RecvFlag::FLAG_NODIRECT))
                                {
                                    total_sample += simulation::calculateDirectPathContribution(
                                        cw_source, receiver_ptr.get(), t_step);
                                }
                                for (const auto& target_ptr : world->getTargets())
                                {
                                    total_sample += simulation::calculateReflectedPathContribution(
                                        cw_source, receiver_ptr.get(), target_ptr.get(), t_step);
                                }
                            }
                            // Store sample in the receiver's main buffer using the correct index
                            receiver_ptr->setCwSample(sample_index, total_sample);
                        }
                    }
                }
            }
 
            t_current = t_event;
 
            // Process the discrete event
            switch (event_type)
            {
            case EventType::TX_PULSED_START:
                {
                    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast): Type is guaranteed by event_type
                    auto* tx = static_cast<Transmitter*>(source_object);
                    // For each pulse, calculate its interaction with every receiver and target.
                    for (const auto& rx_ptr : world->getReceivers())
                    {
                        // Calculate unique Response objects for direct and reflected paths.
                        if (!rx_ptr->checkFlag(Receiver::RecvFlag::FLAG_NODIRECT))
                        {
                            if (auto response =
                                    simulation::calculateResponse(tx, rx_ptr.get(), tx->getSignal(), t_event))
                            {
                                if (rx_ptr->getMode() == OperationMode::PULSED_MODE)
                                {
                                    rx_ptr->addResponseToInbox(std::move(response));
                                }
                                else
                                {
                                    rx_ptr->addInterferenceToLog(std::move(response));
                                }
                            }
                        }
                        for (const auto& target_ptr : world->getTargets())
                        {
                            if (auto response = simulation::calculateResponse(tx, rx_ptr.get(), tx->getSignal(),
                                                                              t_event, target_ptr.get()))
                            {
                                if (rx_ptr->getMode() == OperationMode::PULSED_MODE)
                                {
                                    rx_ptr->addResponseToInbox(std::move(response));
                                }
                                else
                                {
                                    rx_ptr->addInterferenceToLog(std::move(response));
                                }
                            }
                        }
                    }
                    // Schedule next pulse
                    const RealType next_theoretical_time = t_event + 1.0 / tx->getPrf();
 
                    // Use schedule to determine actual next time (handles gaps in schedule)
                    if (const auto next_pulse_opt = tx->getNextPulseTime(next_theoretical_time);
                        next_pulse_opt && *next_pulse_opt <= end_time)
                    {
                        event_queue.push({*next_pulse_opt, EventType::TX_PULSED_START, tx});
                    }
                    break;
                }
            case EventType::RX_PULSED_WINDOW_START:
                {
                    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast): Type is guaranteed by event_type
                    auto* rx = static_cast<Receiver*>(source_object);
                    rx->setActive(true);
                    event_queue.push({t_event + rx->getWindowLength(), EventType::RX_PULSED_WINDOW_END, rx});
                    break;
                }
            case EventType::RX_PULSED_WINDOW_END:
                {
                    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast): Type is guaranteed by event_type
                    auto* rx = static_cast<Receiver*>(source_object);
                    rx->setActive(false);
                    // The receive window is over. Package all received data into a RenderingJob.
                    RenderingJob job{.ideal_start_time = t_event - rx->getWindowLength(),
                                     .duration = rx->getWindowLength(),
                                     .responses = rx->drainInbox(),
                                     .active_cw_sources = active_cw_transmitters};
                    // Offload the job to the dedicated finalizer thread for this receiver.
                    rx->enqueueFinalizerJob(std::move(job));
 
                    // Schedule the start of the next receive window based on schedule
                    const RealType next_theoretical = t_event - rx->getWindowLength() + 1.0 / rx->getWindowPrf();
 
                    if (const auto next_start = rx->getNextWindowTime(next_theoretical);
                        next_start && *next_start <= end_time)
                    {
                        event_queue.push({*next_start, EventType::RX_PULSED_WINDOW_START, rx});
                    }
                    break;
                }
            case EventType::TX_CW_START:
                {
                    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast): Type is guaranteed by event_type
                    auto* tx = static_cast<Transmitter*>(source_object);
                    active_cw_transmitters.push_back(tx);
                    break;
                }
            case EventType::TX_CW_END:
                {
                    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast): Type is guaranteed by event_type
                    auto* tx = static_cast<Transmitter*>(source_object);
                    std::erase(active_cw_transmitters, tx);
                    break;
                }
            case EventType::RX_CW_START:
                {
                    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast): Type is guaranteed by event_type
                    auto* rx = static_cast<Receiver*>(source_object);
                    rx->setActive(true);
                    break;
                }
            case EventType::RX_CW_END:
                {
                    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-static-cast-downcast): Type is guaranteed by event_type
                    auto* rx = static_cast<Receiver*>(source_object);
                    rx->setActive(false);
                    // Do NOT finalize here. CW data is a continuous buffer; 'Ending' a schedule period
                    // just means we stop recording active signal (leaving zeros/silence in the buffer).
                    break;
                }
            }
 
            // Throttled Progress Reporting
            if (progress_callback)
            {
                const int progress = static_cast<int>(t_current / end_time * 100.0);
 
                // Only report if percentage changed significantly OR enough time elapsed
                if (const auto now = std::chrono::steady_clock::now();
                    progress != last_reported_percent || now - last_report_time >= report_interval)
                {
                    reporter->report(std::format("Simulating... {:.2f}s / {:.2f}s", t_current, end_time), progress,
                                     100);
                    last_reported_percent = progress;
                    last_report_time = now;
                }
            }
        }
 
        // Shutdown Phase
        LOG(Level::INFO, "Main simulation loop finished. Waiting for finalization tasks...");
        reporter->report("Main simulation finished. Waiting for data export...", 100, 100);
 
        // 1. Queue CW Finalization Tasks
        // We finalize CW receivers here to ensure the full timeline (including all schedule periods) is exported once.
        for (const auto& receiver_ptr : world->getReceivers())
        {
            if (receiver_ptr->getMode() == OperationMode::CW_MODE)
            {
                pool.enqueue(processing::finalizeCwReceiver, receiver_ptr.get(), &pool, reporter);
            }
        }
 
        // 2. Signal pulsed finalizer threads to shut down
        for (const auto& receiver_ptr : world->getReceivers())
        {
            if (receiver_ptr->getMode() == OperationMode::PULSED_MODE)
            {
                RenderingJob shutdown_job{.duration = -1.0};
                receiver_ptr->enqueueFinalizerJob(std::move(shutdown_job));
            }
        }
 
        // Wait for any remaining CW finalization tasks in the main pool to complete.
        pool.wait();
 
        // The std::jthread finalizer threads are automatically joined here at the end of scope.
        LOG(Level::INFO, "All finalization tasks complete.");
 
        if (progress_callback)
        {
            reporter->report("Simulation complete", 100, 100);
        }
        LOG(Level::INFO, "Event-driven simulation loop finished.");
    }

References simulation::calculateDirectPathContribution(), simulation::calculateReflectedPathContribution(), simulation::calculateResponse(), core::RenderingJob::duration, params::endTime(), processing::finalizeCwReceiver(), core::World::getEventQueue(), radar::Transmitter::getPrf(), core::World::getReceivers(), core::World::getSimulationState(), core::World::getTargets(), core::RenderingJob::ideal_start_time, LOG, params::oversampleRatio(), params::rate(), processing::runPulsedFinalizer(), RX_CW_END, RX_CW_START, RX_PULSED_WINDOW_END, RX_PULSED_WINDOW_START, radar::Receiver::setActive(), params::startTime(), TX_CW_END, TX_CW_START, and TX_PULSED_START.

Referenced by fers_run_simulation().

Here is the call graph for this function:

Here is the caller graph for this function:

showHelp()

void core::showHelp ( const char *  programName )

noexcept

Displays the help message.

Parameters

programName

The name of the program.

Definition at line 189 of file arg_parser.cpp.

    {
        std::cout << R"(/------------------------------------------------\
| FERS - The Flexible Extensible Radar Simulator |
| Version 1.0.0                                  |
\------------------------------------------------/

showVersion()

void core::showVersion ( )

noexcept

Displays the version information.

Definition at line 196 of file arg_parser.cpp.

       :
  --help, -h              Show this help message and exit

toString()

std::string core::toString

(

const EventType

type

)

Converts an EventType enum to its string representation.

Parameters

type	The event type.

Returns

A string representing the event type.

Definition at line 72 of file sim_events.h.

    {
        switch (type)
        {
        case EventType::TX_PULSED_START:
            return "TxPulsedStart";
        case EventType::RX_PULSED_WINDOW_START:
            return "RxPulsedWindowStart";
        case EventType::RX_PULSED_WINDOW_END:
            return "RxPulsedWindowEnd";
        case EventType::TX_CW_START:
            return "TxCwStart";
        case EventType::TX_CW_END:
            return "TxCwEnd";
        case EventType::RX_CW_START:
            return "RxCwStart";
        case EventType::RX_CW_END:
            return "RxCwEnd";
        default:
            return "UnknownEvent";
        }
    }

References RX_CW_END, RX_CW_START, RX_PULSED_WINDOW_END, RX_PULSED_WINDOW_START, TX_CW_END, TX_CW_START, and TX_PULSED_START.

Referenced by core::World::dumpEventQueue().

Here is the caller graph for this function: