core::SimulationEngine Class Reference

Encapsulates the state and logic of the event-driven simulation loop. More...

#include "sim_threading.h"

Public Member Functions
	SimulationEngine (World *world, pool::ThreadPool &pool, std::shared_ptr< ProgressReporter > reporter, std::string output_dir, std::shared_ptr< OutputMetadataCollector > metadata_collector=nullptr)
	Constructs the simulation engine.
void	run ()
	Starts and runs the main simulation loop until completion.
void	processCwPhysics (RealType t_event)
	Advances the time-stepped inner loop for active continuous-wave (CW) systems.
void	processEvent (const Event &event)
	Dispatches a discrete simulation event to its specific handler.
void	handleTxPulsedStart (radar::Transmitter *tx, RealType t_event)
	Handles the start of a pulsed transmission.
void	handleRxPulsedWindowStart (radar::Receiver *rx, RealType t_event)
	Handles the opening of a pulsed receiver's listening window.
void	handleRxPulsedWindowEnd (radar::Receiver *rx, RealType t_event)
	Handles the closing of a pulsed receiver's listening window, triggering finalization.
void	handleTxCwStart (radar::Transmitter *tx)
	Handles a continuous-wave transmitter turning on.
void	handleTxCwEnd (radar::Transmitter *tx)
	Handles a continuous-wave transmitter turning off.
void	handleRxCwStart (radar::Receiver *rx)
	Handles a continuous-wave receiver starting to record.
void	handleRxCwEnd (radar::Receiver *rx)
	Handles a continuous-wave receiver stopping recording.
ComplexType	calculateCwSample (radar::Receiver *rx, RealType t_step, const std::vector< radar::Transmitter * > &cw_sources) const
	Calculates the total complex I/Q sample for a receiver at a specific time step.

Detailed Description

Encapsulates the state and logic of the event-driven simulation loop.

Breaking the simulation loop into this class allows for easily testable, focused functions with low cyclomatic complexity.

Definition at line 98 of file sim_threading.h.

Constructor & Destructor Documentation

SimulationEngine()

core::SimulationEngine::SimulationEngine	(	World *	world,
		pool::ThreadPool &	pool,
		std::shared_ptr< ProgressReporter >	reporter,
		std::string	output_dir,
		std::shared_ptr< OutputMetadataCollector >	metadata_collector = nullptr
	)

Constructs the simulation engine.

Parameters

world	Pointer to the simulation world containing all entities.
pool	Reference to the thread pool for asynchronous tasks.
reporter	Shared pointer to the thread-safe progress reporter.
output_dir	Output directory for the simulation files.

Definition at line 44 of file sim_threading.cpp.

                                                                                                  :
        _world(world), _pool(pool), _reporter(std::move(reporter)), _metadata_collector(std::move(metadata_collector)),
        _last_report_time(std::chrono::steady_clock::now()), _output_dir(std::move(output_dir))
    {
    }

Member Function Documentation

calculateCwSample()

ComplexType core::SimulationEngine::calculateCwSample	(	radar::Receiver *	rx,
		RealType	t_step,
		const std::vector< radar::Transmitter * > &	cw_sources
	)		const

Calculates the total complex I/Q sample for a receiver at a specific time step.

Parameters

rx	Pointer to the receiving radar object.
t_step	The exact simulation time for the sample.
cw_sources	A list of currently active continuous-wave transmitters.

Returns

The calculated complex I/Q sample combining direct and reflected paths.

Definition at line 123 of file sim_threading.cpp.

    {
        ComplexType total_sample{0.0, 0.0};
        for (const auto& cw_source : cw_sources)
        {
            if (!rx->checkFlag(Receiver::RecvFlag::FLAG_NODIRECT))
            {
                total_sample += simulation::calculateDirectPathContribution(cw_source, rx, t_step);
            }
            for (const auto& target_ptr : _world->getTargets())
            {
                total_sample += simulation::calculateReflectedPathContribution(cw_source, rx, target_ptr.get(), t_step);
            }
        }
        return total_sample;
    }

References simulation::calculateDirectPathContribution(), simulation::calculateReflectedPathContribution(), radar::Receiver::checkFlag(), and core::World::getTargets().

Referenced by processCwPhysics().

Here is the call graph for this function:

Here is the caller graph for this function:

handleRxCwEnd()

void core::SimulationEngine::handleRxCwEnd

(

radar::Receiver *

rx

)

Handles a continuous-wave receiver stopping recording.

Parameters

rx	Pointer to the receiving radar object.

Definition at line 250 of file sim_threading.cpp.

{ rx->setActive(false); }

References radar::Receiver::setActive().

Referenced by processEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

handleRxCwStart()

void core::SimulationEngine::handleRxCwStart

(

radar::Receiver *

rx

)

Handles a continuous-wave receiver starting to record.

Parameters

rx	Pointer to the receiving radar object.

Definition at line 248 of file sim_threading.cpp.

{ rx->setActive(true); }

References radar::Receiver::setActive().

Referenced by processEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

handleRxPulsedWindowEnd()

void core::SimulationEngine::handleRxPulsedWindowEnd	(	radar::Receiver *	rx,
		RealType	t_event
	)

Handles the closing of a pulsed receiver's listening window, triggering finalization.

Parameters

rx	Pointer to the receiving radar object.
t_event	The timestamp of the window closing event.

Definition at line 217 of file sim_threading.cpp.

    {
        rx->setActive(false);
        const auto& active_cw_transmitters = _world->getSimulationState().active_cw_transmitters;
 
        RenderingJob job{.ideal_start_time = t_event - rx->getWindowLength(),
                         .duration = rx->getWindowLength(),
                         .responses = rx->drainInbox(),
                         .active_cw_sources = active_cw_transmitters};
 
        rx->enqueueFinalizerJob(std::move(job));
 
        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 <= params::endTime())
        {
            _world->getEventQueue().push({*next_start, EventType::RX_PULSED_WINDOW_START, rx});
        }
    }

References core::SimulationState::active_cw_transmitters, radar::Receiver::drainInbox(), params::endTime(), radar::Receiver::enqueueFinalizerJob(), core::World::getEventQueue(), radar::Receiver::getNextWindowTime(), core::World::getSimulationState(), radar::Receiver::getWindowLength(), radar::Receiver::getWindowPrf(), core::RenderingJob::ideal_start_time, core::RX_PULSED_WINDOW_START, and radar::Receiver::setActive().

Referenced by processEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

handleRxPulsedWindowStart()

void core::SimulationEngine::handleRxPulsedWindowStart	(	radar::Receiver *	rx,
		RealType	t_event
	)

Handles the opening of a pulsed receiver's listening window.

Parameters

rx	Pointer to the receiving radar object.
t_event	The timestamp of the window opening event.

Definition at line 211 of file sim_threading.cpp.

    {
        rx->setActive(true);
        _world->getEventQueue().push({t_event + rx->getWindowLength(), EventType::RX_PULSED_WINDOW_END, rx});
    }

References core::World::getEventQueue(), radar::Receiver::getWindowLength(), core::RX_PULSED_WINDOW_END, and radar::Receiver::setActive().

Referenced by processEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

handleTxCwEnd()

void core::SimulationEngine::handleTxCwEnd

(

radar::Transmitter *

tx

)

Handles a continuous-wave transmitter turning off.

Parameters

tx	Pointer to the transmitting radar object.

Definition at line 242 of file sim_threading.cpp.

    {
        auto& cw_txs = _world->getSimulationState().active_cw_transmitters;
        std::erase(cw_txs, tx);
    }

References core::SimulationState::active_cw_transmitters, and core::World::getSimulationState().

Referenced by processEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

handleTxCwStart()

void core::SimulationEngine::handleTxCwStart

(

radar::Transmitter *

tx

)

Handles a continuous-wave transmitter turning on.

Parameters

tx	Pointer to the transmitting radar object.

Definition at line 237 of file sim_threading.cpp.

    {
        _world->getSimulationState().active_cw_transmitters.push_back(tx);
    }

References core::SimulationState::active_cw_transmitters, and core::World::getSimulationState().

Referenced by processEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

handleTxPulsedStart()

void core::SimulationEngine::handleTxPulsedStart	(	radar::Transmitter *	tx,
		RealType	t_event
	)

Handles the start of a pulsed transmission.

Parameters

tx	Pointer to the transmitting radar object.
t_event	The timestamp of the transmission event.

Definition at line 187 of file sim_threading.cpp.

    {
        for (const auto& rx_ptr : _world->getReceivers())
        {
            if (!rx_ptr->checkFlag(Receiver::RecvFlag::FLAG_NODIRECT))
            {
                routeResponse(rx_ptr.get(), simulation::calculateResponse(tx, rx_ptr.get(), tx->getSignal(), t_event));
            }
            for (const auto& target_ptr : _world->getTargets())
            {
                routeResponse(
                    rx_ptr.get(),
                    simulation::calculateResponse(tx, rx_ptr.get(), tx->getSignal(), t_event, target_ptr.get()));
            }
        }
 
        const RealType next_theoretical_time = t_event + 1.0 / tx->getPrf();
        if (const auto next_pulse_opt = tx->getNextPulseTime(next_theoretical_time);
            next_pulse_opt && *next_pulse_opt <= params::endTime())
        {
            _world->getEventQueue().push({*next_pulse_opt, EventType::TX_PULSED_START, tx});
        }
    }

References simulation::calculateResponse(), params::endTime(), core::World::getEventQueue(), radar::Transmitter::getNextPulseTime(), radar::Transmitter::getPrf(), core::World::getReceivers(), radar::Transmitter::getSignal(), core::World::getTargets(), and core::TX_PULSED_START.

Referenced by processEvent().

Here is the call graph for this function:

Here is the caller graph for this function:

processCwPhysics()

void core::SimulationEngine::processCwPhysics

(

RealType

t_event

)

Advances the time-stepped inner loop for active continuous-wave (CW) systems.

Parameters

t_event

The timestamp of the next discrete event to process up to.

Definition at line 95 of file sim_threading.cpp.

    {
        auto& [t_current, active_cw_transmitters] = _world->getSimulationState();
 
        if (t_event <= t_current)
        {
            return;
        }
 
        const RealType dt_sim = 1.0 / (params::rate() * params::oversampleRatio());
        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_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 sample = calculateCwSample(receiver_ptr.get(), t_step, active_cw_transmitters);
                    receiver_ptr->setCwSample(sample_index, sample);
                }
            }
        }
    }

References calculateCwSample(), core::World::getReceivers(), core::World::getSimulationState(), params::oversampleRatio(), params::rate(), and params::startTime().

Referenced by run().

Here is the call graph for this function:

Here is the caller graph for this function:

processEvent()

void core::SimulationEngine::processEvent

(

const Event &

event

)

Dispatches a discrete simulation event to its specific handler.

Parameters

event

The event to process.

Definition at line 141 of file sim_threading.cpp.

    {
        // NOLINTBEGIN(cppcoreguidelines-pro-type-static-cast-downcast)
        switch (event.type)
        {
        case EventType::TX_PULSED_START:
            handleTxPulsedStart(static_cast<Transmitter*>(event.source_object), event.timestamp);
            break;
        case EventType::RX_PULSED_WINDOW_START:
            handleRxPulsedWindowStart(static_cast<Receiver*>(event.source_object), event.timestamp);
            break;
        case EventType::RX_PULSED_WINDOW_END:
            handleRxPulsedWindowEnd(static_cast<Receiver*>(event.source_object), event.timestamp);
            break;
        case EventType::TX_CW_START:
            handleTxCwStart(static_cast<Transmitter*>(event.source_object));
            break;
        case EventType::TX_CW_END:
            handleTxCwEnd(static_cast<Transmitter*>(event.source_object));
            break;
        case EventType::RX_CW_START:
            handleRxCwStart(static_cast<Receiver*>(event.source_object));
            break;
        case EventType::RX_CW_END:
            handleRxCwEnd(static_cast<Receiver*>(event.source_object));
            break;
        }
        // NOLINTEND(cppcoreguidelines-pro-type-static-cast-downcast)
    }

References handleRxCwEnd(), handleRxCwStart(), handleRxPulsedWindowEnd(), handleRxPulsedWindowStart(), handleTxCwEnd(), handleTxCwStart(), handleTxPulsedStart(), core::RX_CW_END, core::RX_CW_START, core::RX_PULSED_WINDOW_END, core::RX_PULSED_WINDOW_START, core::Event::source_object, core::Event::timestamp, core::TX_CW_END, core::TX_CW_START, core::TX_PULSED_START, and core::Event::type.

Referenced by run().

Here is the call graph for this function:

Here is the caller graph for this function:

run()

void core::SimulationEngine::run

(

)

Starts and runs the main simulation loop until completion.

Definition at line 52 of file sim_threading.cpp.

    {
        if (_reporter)
        {
            _reporter->report("Initializing event-driven simulation...", 0, 100);
        }
 
        initializeFinalizers();
 
        LOG(Level::INFO, "Starting unified event-driven simulation loop.");
 
        auto& event_queue = _world->getEventQueue();
        auto& state = _world->getSimulationState();
        const RealType end_time = params::endTime();
 
        while (!event_queue.empty() && state.t_current <= end_time)
        {
            const Event event = event_queue.top();
            event_queue.pop();
 
            processCwPhysics(event.timestamp);
 
            state.t_current = event.timestamp;
 
            processEvent(event);
            updateProgress();
        }
 
        shutdown();
    }

References params::endTime(), core::World::getEventQueue(), core::World::getSimulationState(), LOG, processCwPhysics(), and processEvent().

Referenced by core::runEventDrivenSim().

Here is the call graph for this function:

Here is the caller graph for this function:

---

The documentation for this class was generated from the following files:

• packages/libfers/src/core/sim_threading.h
• packages/libfers/src/core/sim_threading.cpp