Simulation.h

Go to the documentation of this file.

// Copyright 2015 - 2026, GIBIS-UNIFESP and the wiRedPanda contributors
// SPDX-License-Identifier: GPL-3.0-or-later

 
#pragma once
 
#include <chrono>
#include <memory>
 
#include <QGraphicsItem>
#include <QHash>
#include <QObject>
#include <QSet>
#include <QTimer>
 
class Clock;
class GraphicElement;
class GraphicElementInput;
class InputPort;
class OutputPort;
class SimulationHost;

class Simulation : public QObject
{
    Q_OBJECT
 
    friend class TestDanglingPointer;
    friend class TestSimulationUnit;
 
public:
    static constexpr int kMaxSettleIterations = 10;
 
    // --- Lifecycle ---

    explicit Simulation(SimulationHost *host, QObject *parent = nullptr);

    ~Simulation() override = default; // LCOV_EXCL_LINE -- destructor-ABI-variant gcov gap (Itanium ABI's separate deleting/complete-object destructors), same class as other `= default` destructors across this sweep.
 
    // --- Control ---

    void start();

    void stop();

    void setUserMuted(bool muted);

    bool isUserMuted() const;

    void restart();

    bool isRunning();

    bool isInFeedbackLoop(const GraphicElement *element) const;
 
    // --- Initialization ---

    bool initialize();
 
    // --- Step ---

    void update();

    void setVisualThrottleEnabled(bool enabled);
 
    // --- Static graph building (used by IC::initializeSimulation too) ---
 
    static void buildConnectionGraph(const QVector<GraphicElement *> &elements);
    static void connectWirelessElements(const QVector<GraphicElement *> &elements);

    static QHash<QString, GraphicElement *> buildTxMap(const QVector<GraphicElement *> &elements);

    static QHash<GraphicElement *, QVector<GraphicElement *>> buildSuccessorGraph(
        const QVector<GraphicElement *> &elements,
        const QHash<QString, GraphicElement *> &txMap);

    struct SortResult {
        QVector<GraphicElement *> sorted;                
        QHash<GraphicElement *, int> priorities;          
        QSet<GraphicElement *> feedbackNodes;             
    };

    static SortResult topologicalSort(const QVector<GraphicElement *> &elements,
                                      const QHash<GraphicElement *, QVector<GraphicElement *>> &successors);

    static bool iterativeSettle(const QVector<GraphicElement *> &elements, int maxIterations = kMaxSettleIterations);
 
signals:
    void simulationWarning(const QString &message);
 
private:
    Q_DISABLE_COPY(Simulation)
 
    // --- Helpers ---
 
    static void updatePort(InputPort *port);
    static void updatePort(OutputPort *port);
    bool updateWithIterativeSettling(const QVector<GraphicElement *> &elements);
    void sortSimElements(const QVector<GraphicElement *> &elements);

    void pushVisualStatuses(const QVector<GraphicElement *> &elements, const QVector<GraphicElement *> &outputs);

    void collectSequentialElements(const QVector<GraphicElement *> &elements);
 
    // --- Members: Timer & element lists ---
 
    QTimer m_timer;
    std::chrono::steady_clock::time_point m_pausedAt;
    bool m_hasPausedAt = false;
    QVector<Clock *> m_clocks;
    QVector<GraphicElement *> m_outputs;
    QVector<GraphicElementInput *> m_inputs;
 
    // --- Members: Host & state ---
 
    SimulationHost *m_host;
 
    // --- Members: State flags ---
 
    bool m_initialized = false;
    bool m_convergenceWarned = false;
    bool m_userMuted = false;

    bool m_atFixedPoint = false;

    bool m_visualsDirty = true;
 
    // --- Members: Visual refresh throttle ---
 
    int m_visualTickCount = 0;
    int m_visualTickInterval = 16;    
    bool m_visualThrottleEnabled = true; 
 
    // --- Members: Direct simulation graph ---
 
    QVector<GraphicElement *> m_sortedElements;
    QVector<GraphicElement *> m_sequentialElements;
    QHash<const GraphicElement *, int> m_simPriorities;
    QSet<const GraphicElement *> m_simFeedbackNodes;
    bool m_simHasFeedbackElements = false;
};