sim.h

Go to the documentation of this file.

// SPDX-License-Identifier: GPL-2.0-only
// Copyright (C) 2026 Daniel Henrique Joppi
 
/**
 * The browser adapter (#544, ADR-0021): an adapter for the shared AntHocNet
 * core, next to the ns-3 one (and NS-2's, through v1.9.0). It owns what an adapter owns -- the
 * clock, the RNGs, the timers, the pending-packet queue, a radio -- and
 * carries out the RouteDecisions the core returns. It never decides a route.
 *
 * The radio is a *teaching* model: unit disk (optionally cut by buildings,
 * or a fixed ISL adjacency), a FIFO transmitter per node with a fixed bit
 * rate, and a MAC transmit-failure report when a unicast's receiver is out of
 * range. It is not ns-3 and nothing measured on it is a benchmark number.
 *
 * Everything here is plain C++14 on top of core/, so the same sources build
 * natively and with Emscripten; the native-vs-WASM decision-trace parity test
 * (web/test/parity.sh) holds the two builds byte-identical.
 */
#ifndef AHN_WEB_SIM_H
#define AHN_WEB_SIM_H
 
#include <cstdint>
#include <deque>
#include <functional>
#include <map>
#include <memory>
#include <queue>
#include <set>
#include <string>
#include <utility>
#include <vector>
 
#include "anthocnet/core/ant_router_logic.h"
#include "anthocnet/core/config.h"
#include "anthocnet/core/ports.h"
 
namespace ahn_web {
 
using anthocnet::core::NodeAddress;
 
/// SplitMix64: tiny, portable, and bit-identical on every platform (integer
/// arithmetic only; the double is an exact 53-bit scaling).
class SplitMix64 {
public:
    /// A stream starting from `seed` (every seed is valid).
    explicit SplitMix64(std::uint64_t seed) : state_(seed) {}
    /// Next raw 64-bit value.
    std::uint64_t next();
    /// Uniform double in [0, 1), from the top 53 bits.
    double uniform();
    /// Uniform double in [lo, hi).
    double uniform(double lo, double hi) { return lo + (hi - lo) * uniform(); }
    /// Uniform integer in [0, n); 0 when n <= 0.
    int uniformInt(int n);
 
private:
    std::uint64_t state_;
};
 
/// A position in metres (z = altitude; 0 on planar worlds).
struct Vec3 {
    double x = 0;  ///< east
    double y = 0;  ///< north
    double z = 0;  ///< up
};
 
/// One straight leg of a node's trajectory: p0 at t0 to p1 at t1.
struct Leg {
    double t0;  ///< start time (s)
    double t1;  ///< end time (s); 1e18 = forever
    Vec3 p0;    ///< position at t0
    Vec3 p1;    ///< position at t1 (linear in between)
};
 
/// How a node moves. Values are part of the JS API (setMobility's `kind`).
enum class MobilityKind {
    Static,          ///< never moves (until dragged)
    RandomWaypoint,  ///< straight legs to uniform waypoints, optional pause
    GaussMarkov,     ///< correlated speed and heading, 1 s steps, optionally 3-D
    Manhattan,       ///< street grid: straight 0.5, left/right 0.25 at each corner
    Orbit,           ///< circular orbit around the field's centre (satellites)
    Route,           ///< #575: a fixed route (a bus line): waypoint to waypoint, looping
};
 
/// A node's mobility model and its parameters.
struct Mobility {
    MobilityKind kind = MobilityKind::Static;  ///< which model
    double speedMin = 1;                       ///< RWP / Manhattan: leg speed lower bound (m/s)
    double speedMax = 10;                      ///< RWP / Manhattan: leg speed upper bound (m/s)
    double pause = 0;                          ///< RWP: pause at each waypoint (s)
    double gmMeanSpeed = 10;                   ///< Gauss-Markov: mean speed (m/s)
    double gmAlpha = 0.85;    ///< Gauss-Markov: memory (0 = random walk, 1 = straight line)
    bool threeD = false;      ///< Gauss-Markov: also move in z
    double orbitRadius = 0;   ///< Orbit: distance from the field's centre (m)
    double orbitInc = 0;      ///< Orbit: inclination (rad)
    double orbitRaan = 0;     ///< Orbit: right ascension of the ascending node (rad)
    double orbitPhase = 0;    ///< Orbit: argument of latitude at t = 0 (rad)
    double orbitRate = 0;     ///< Orbit: angular speed (rad/s)
    std::vector<Vec3> route;  ///< Route: waypoints, driven in order at speedMin, looping
};
 
/// sin / cos from arithmetic only (range reduction + Taylor series), so the
/// native and WASM builds compute bit-identical orbits: libm's transcendental
/// functions are not guaranteed to round the same on both.
double detSin(double x);
double detCos(double x);
 
/// Where an Orbit puts a node at time t (centre = the field's centre, z = 0).
Vec3 orbitPosition(const Mobility& m, const Vec3& centre, double t);
 
/// Which link rule the teaching radio uses.
enum class ChannelKind {
    Disk,   ///< linked iff within range()
    Urban,  ///< within range() and no building on the line of sight
    Isl,    ///< linked iff an inter-satellite link was added (and not cut)
    Mixed,  ///< #582: ground, air and space in one world (see setMixedChannel)
};
 
/// Event kinds of the log the front end animates and the parity test diffs.
/// Append only: the JS front end and the trace format index these numerically.
enum class Ev : int {
    TxAnt = 1,      ///< node -> peer (-1 = broadcast); a=AntType, b=dir, v=arrival time
    RxAnt = 2,      ///< node received from peer; a=AntType, b=dir
    TxData = 3,     ///< node -> peer; a=flow, b=seq, v=arrival time
    Deliver = 4,    ///< node = destination; a=flow, b=seq, v=end-to-end delay
    Drop = 5,       ///< node; a=flow, b=seq, peer=DropReason
    RouteAdd = 6,   ///< node; peer=next hop, a=destination
    RouteDel = 7,   ///< node; peer=next hop, a=destination
    Queue = 8,      ///< node; a=flow, b=seq, peer=destination
    TxFail = 9,     ///< node -> peer unicast failed (out of range)
    NodeDown = 10,  ///< node switched off
    NodeUp = 11,    ///< node switched on
};
 
/// Why a data packet was lost (the `peer` field of an Ev::Drop event).
enum class DropReason : int {
    Ttl = 1,            ///< hop limit reached (a loop)
    QueueTimeout = 2,   ///< waited QueueTimeout (3 s) for a route, or queue full
    HoldCap = 3,        ///< a reconvergence hold outlived ReconvHoldCap (200 ms)
    RepairDiscard = 4,  ///< a local repair expired: the core's DiscardPending
    NodeOff = 5,        ///< the holding or receiving node was switched off
};
 
/// One entry of the event log (see Ev for what each field means per kind).
struct LogEvent {
    double t;  ///< simulated time (s)
    Ev kind;   ///< what happened
    int node;  ///< where it happened
    int peer;  ///< the other node, -1 for broadcast, or a DropReason
    int a;     ///< kind-specific (AntType, flow, destination)
    int b;     ///< kind-specific (AntDirection, sequence number)
    double v;  ///< kind-specific (arrival time, end-to-end delay)
};
 
/// A constant-bit-rate data flow and its running totals.
struct Flow {
    int src;              ///< source node
    int dst;              ///< destination node
    double rate;          ///< packets per second
    double start;         ///< first packet (s)
    double stop;          ///< no packets after this (s)
    int sent = 0;         ///< packets originated
    int delivered = 0;    ///< packets that reached dst
    double delaySum = 0;  ///< sum of end-to-end delays of delivered packets (s)
};
 
class World;
 
/// One AntHocNet node: the core logic plus the adapter state around it.
class Node : public anthocnet::core::IClock,
             public anthocnet::core::IRng,
             public anthocnet::core::IRouterObserver,
             public anthocnet::core::IEnergy,
             public anthocnet::core::IKinematics {
public:
    /// Created by World::addNode(); `seed` derives the node's streams.
    Node(World& w, int id, std::uint64_t seed);
 
    /// IClock: the world's simulated time.
    anthocnet::core::Time now() const override;
    /// IRng: this node's own stream (independent of every other node's).
    double uniform() override { return rng_.uniform(); }
    /// IRng: uniform integer in [0, n).
    int uniformInt(int n) override { return rng_.uniformInt(n); }
 
    /// IKinematics (ADR-0025): position and the current leg's velocity. Read
    /// by the core only when Config::shareKinematics is on.
    bool self(anthocnet::core::Kinematics& out) const override;
 
    /// IEnergy (#575, #145): the battery's residual fraction, NaN without a
    /// battery. Read only by the energy metric.
    double residualEnergyFraction() const override;
 
    /// IRouterObserver: report-only -- route changes feed the event log.
    void onRouteChanged(NodeAddress dest, NodeAddress nb, bool added) override;
 
    /// This node's address (its index in the World).
    int id() const { return id_; }
    /// The core state machine (valid after World::start()).
    anthocnet::core::AntRouterLogic& logic() { return *logic_; }
    /// The core state machine, read-only (inspection).
    const anthocnet::core::AntRouterLogic& logic() const { return *logic_; }
 
private:
    friend class World;
    /// A data packet, in flight or held in the pending queue.
    struct Pending {
        int flow, seq, src, dst, ttl, hops;
        NodeAddress prev;  ///< previous hop (A1 loop exclusion; re-injection)
        double created, firstQueued, expire;
        bool reconv;  ///< held while a known route re-forms (#21 HOLD_RECONV)
    };
 
    World& w_;
    int id_;
    SplitMix64 rng_;       ///< the core's IRng
    SplitMix64 timerRng_;  ///< adapter timer jitter (as ns-3's m_timerRng)
    // Mobility is generated lazily but from a per-node stream, so a node's
    // trajectory never depends on when (or whether) another node was queried.
    mutable SplitMix64 mobRng_;
    mutable double gmSpeed_ = 0;
    mutable Vec3 gmDir_{1, 0, 0};
    mutable int mhDir_ = 0;
    mutable bool rwpPaused_ = false;
    std::unique_ptr<anthocnet::core::AntRouterLogic> logic_;
    bool up_ = true;
    double range_ = -1;     ///< own radio range (#568); < 0 = the world's
    double busyUntil_ = 0;  ///< FIFO transmitter
    std::deque<Pending> pending_;
    std::set<NodeAddress> everRouted_;
    Mobility mob_;
    mutable std::vector<Leg> legs_;
    mutable std::size_t routeIdx_ = 0;  ///< Route: the waypoint the current leg ends at
    double battery0_ = -1;              ///< #575: initial energy (J); < 0 = no battery
    double battery_ = 0;                ///< energy left (J)
    double batteryAt_ = 0;              ///< when battery_ was last brought up to date
    double groundMinSinEl_ = 2;         ///< #575: sin(min elevation); > 1 = not a ground station
    bool satellite_ = false;            ///< #582: a satellite on the Mixed channel
};
 
/// The whole simulation: nodes, radio, mobility, traffic and the event queue.
class World {
public:
    /// An empty world; `seed` derives every random stream in it.
    explicit World(std::uint64_t seed);
 
    // --- scenario construction (before start()) ---------------------------
    /// Field size in metres (z > 0 enables altitude).
    void setArea(double x, double y, double z);
    /// Unit-disk links of radius `range` metres.
    void setDiskChannel(double range);
    /// Unit disk cut by the buildings of a blocksX x blocksY street grid.
    void setUrbanChannel(double range, int blocksX, int blocksY, double streetWidth);
    /// Links only where addIslLink() says, delay tracking distance.
    void setIslChannel();
    /// Add an inter-satellite link (ChannelKind::Isl, Mixed).
    void addIslLink(int a, int b);
    /// #582: ground, air and space nodes in one world. Satellites (see
    /// setSatellite) link only by their ISLs and to the ground stations that
    /// see them; every other pair links by the disk rule, in 3-D, with the
    /// world range `range` for nodes without their own. Unlike the Isl
    /// channel, a ground station also links to its neighbours by the disk
    /// rule (a HAPS holds both its ring and its uplink). Every link's delay is
    /// its length at the speed of light.
    void setMixedChannel(double range);
    /// #582: mark `node` as a satellite on the Mixed channel.
    void setSatellite(int node);
    /// Transmitter bit rate (default 2 Mbit/s).
    void setBitrate(double bps) { bitrate_ = bps; }
    /// Independent per-reception loss probability (default 0).
    void setLossProbability(double p) { loss_ = p; }
    /// Add a node at (x, y, z); returns its address.
    int addNode(double x, double y, double z);
    /// Give `node` its own radio range in metres (#568: a device class). On
    /// the disk and urban channels two nodes link iff they are within
    /// min(range_a, range_b). A node never given one uses the world range(),
    /// so every existing world is unchanged.
    void setNodeRange(int node, double range);
    /// `node`'s radio range: its own, else the world range().
    /// Give `node` a mobility model (Manhattan snaps it to an intersection).
    void setMobility(int node, const Mobility& m);
    /// #575: inside the polygon `xy` (x0, y0, x1, y1, ...) and below `top`
    /// metres, radio range is scaled by `factor` (a canopy, rubble: a drone
    /// above the trees is not in it). A link uses each end's own scaled
    /// range; where zones overlap the smallest factor applies.
    void addAttenuationZone(const std::vector<double>& xy, double factor, double top = 30);
    /// #575: give `node` a battery of `joules`. It drains at kIdleW all the
    /// time and kTxW while transmitting, and the node switches off when it is
    /// empty. Accounting only: it never touches a routing decision.
    void setBattery(int node, double joules);
    /// #575: energy left in `node`'s battery (J), or -1 without one.
    double batteryLeft(int node);
    /// #575: make `node` a ground station on the satellite (Isl) channel. It
    /// links to any satellite at least `minElevationDeg` above its horizon,
    /// the horizon being the plane normal to the Earth's radius through it
    /// (the Earth's centre is the field's centre, as for orbits).
    void setGroundStation(int node, double minElevationDeg);
    /// #582: a jamming zone. While from <= t < until, any disk or urban link
    /// with an end inside the polygon `xy` (x0, y0, x1, y1, ...), or crossing
    /// it, fails. The polygon moves at (vx, vy) m/s from `from` on (a fire
    /// front); (0, 0) holds it still (a jammer). It covers every altitude.
    /// Satellite links are never jammed.
    void addJammingZone(const std::vector<double>& xy, double from, double until, double vx = 0,
                        double vy = 0);
    /// #582: a scripted event -- switch `node` off (up = false) or back on at
    /// simulated time t (an aftershock, a device restored), as setNodeUp.
    void scheduleNodeUp(int node, double t, bool up);
    /// Add a CBR flow; returns its index.
    int addFlow(int src, int dst, double rate, double start, double stop);
    /// #579: the link metric every node is built with, by registry name
    /// ("classic", "sinr", "energy"); false if unknown. Before start() only:
    /// an upgrade, like a mission knob, never a world's default.
    bool setLinkMetric(const std::string& name);
    /// The protocol Config every node is built with -- the core defaults.
    /// Worlds never change it (ADR-0019); a mission's labelled knob may.
    anthocnet::core::Config& config() { return config_; }
 
    /// Build the nodes' core logic and arm their timers and the flows.
    void start();
 
    // --- running ----------------------------------------------------------
    /// Process every event up to simulated time `t` (starts if needed).
    void advanceTo(double t);
    /// Current simulated time (s).
    double now() const { return now_; }
    /// The seed this world was built from.
    std::uint64_t seed() const { return seed_; }
 
    // --- interaction (any time) -------------------------------------------
    /// Drag `node` to (x, y, z) and pin it there (it stops moving).
    void moveNode(int node, double x, double y, double z);
    /// Switch `node` off (its held packets are dropped) or back on.
    void setNodeUp(int node, bool up);
    /// Remove an inter-satellite link.
    void cutIslLink(int a, int b);
 
    // --- inspection (read-only) -------------------------------------------
    /// Number of nodes.
    int nodeCount() const { return static_cast<int>(nodes_.size()); }
    /// Where `node` is now.
    Vec3 position(int node) const { return positionAt(node, now_); }
    /// Whether `node` is switched on.
    bool nodeUp(int node) const { return nodes_[node]->up_; }
    /// Whether a and b can hear each other now.
    bool linkUp(int a, int b) const { return linkUpAt(a, b, now_); }
    /// Node `i` (for read-only inspection of its core state).
    const Node& node(int i) const { return *nodes_[i]; }
    /// The flows and their running totals.
    const std::vector<Flow>& flows() const { return flows_; }
    /// Data packets `node` holds waiting for a route.
    int pendingCount(int node) const { return static_cast<int>(nodes_[node]->pending_.size()); }
    /// Events since the last clearLog().
    const std::vector<LogEvent>& log() const { return log_; }
    /// Forget the logged events (the front end drains them every frame).
    void clearLog() { log_.clear(); }
    /// Ant transmissions so far (control overhead).
    std::uint64_t antTransmissions() const { return antTx_; }
    /// X-ray (#637): how many ant transmissions the ring keeps.
    static constexpr std::size_t kXrayRing = 512;
    /// X-ray (#637): the serialized bytes of ant transmission `id` -- the
    /// id-th TxAnt event since start(), from 0 -- if it is among the last
    /// kXrayRing; else empty. A copy kept for inspection: no decision reads it.
    const std::vector<std::uint8_t>& antBytes(std::uint64_t id) const;
    /// Street grid blocks along x (Urban).
    int urbanBlocksX() const { return blocksX_; }
    /// Street grid blocks along y (Urban).
    int urbanBlocksY() const { return blocksY_; }
    /// Street width in metres (Urban).
    double streetWidth() const { return streetWidth_; }
    /// Radio range in metres (Disk, Urban).
    double range() const { return range_; }
    double nodeRange(int node) const;
    /// The link rule in use.
    ChannelKind channel() const { return channel_; }
    /// #575: the attenuation zones as [factor, n, x0, y0, ... x(n-1), y(n-1), ...].
    std::vector<double> zonesFlat() const;
    /// #582: the jamming zones active now, where they are now, as
    /// [n, x0, y0, ... x(n-1), y(n-1), ...].
    std::vector<double> jamZonesFlat() const;
    /// Field size in metres.
    Vec3 area() const { return area_; }
 
    /// One trace line per logged event (the parity format).
    static std::string formatEvent(const LogEvent& e);
 
private:
    friend class Node;
    struct Scheduled {
        double t;
        std::uint64_t seq;
        std::function<void()> fn;
    };
    struct Later {
        bool operator()(const Scheduled& a, const Scheduled& b) const {
            return a.t > b.t || (a.t == b.t && a.seq > b.seq);
        }
    };
 
    void schedule(double t, std::function<void()> fn);
    void emit(double t, Ev kind, int node, int peer, int a, int b, double v);
 
    // mobility
    void extendLegs(Node& n, double until) const;
    void armTimers(Node& n);
    Vec3 positionAt(int node, double t) const;
    /// Velocity (m/s) of the leg covering t: zero when paused or pinned.
    Vec3 velocityAt(int node, double t) const;
    bool linkUpAt(int a, int b, double t) const;
    bool lineOfSight(const Vec3& a, const Vec3& b) const;
 
    // timers
    void helloTimer(int node);
    void proactiveTimer(int node);
    void retryTimer(int node);
    void flowTick(int flow);
    double jittered(Node& n, double base, bool first);
 
    // the adapter contract
    void execute(Node& n, const std::vector<anthocnet::core::RouteDecision>& ds);
    void sendAnt(Node& n, const anthocnet::core::AntMessage& m, int to);
    void recvAnt(int node, int from, const std::vector<std::uint8_t>& bytes);
    void routeData(Node& n, Node::Pending p, int prevHop);
    void sendData(Node& n, Node::Pending p, int next);
    void recvData(int node, int from, Node::Pending p);
    void enqueue(Node& n, Node::Pending p);
    void flushQueue(Node& n, NodeAddress dst);
    void discardQueue(Node& n, NodeAddress dst, DropReason why);
    void purge(Node& n);
    double txDuration(std::size_t bytes) const { return bytes * 8.0 / bitrate_; }
    double propagation(int a, int b, double t) const;
 
    SplitMix64 lossRng_;  ///< channel loss draws only
    std::uint64_t seed_;
    anthocnet::core::Config config_;
    const anthocnet::core::ILinkMetric* metric_ = nullptr;  ///< #579; nullptr = classic
    Vec3 area_{1000, 1000, 0};
    ChannelKind channel_ = ChannelKind::Disk;
    double range_ = 250;
    int blocksX_ = 4, blocksY_ = 4;
    double streetWidth_ = 20;
    std::set<std::pair<int, int>> isl_;
    double bitrate_ = 2e6;
    double loss_ = 0;
    std::vector<std::unique_ptr<Node>> nodes_;
    std::vector<Flow> flows_;
    std::priority_queue<Scheduled, std::vector<Scheduled>, Later> events_;
    std::uint64_t seq_ = 0;
    double now_ = 0;
    bool started_ = false;
    std::vector<LogEvent> log_;
    std::uint64_t antTx_ = 0;
    std::deque<std::pair<std::uint64_t, std::vector<std::uint8_t>>>
        xray_;  // (id, bytes), oldest first
 
    struct Zone {
        std::vector<double> xy;
        double factor;
        double top;
    };
    std::vector<Zone> zones_;  ///< #575 attenuation zones
    struct JamZone {
        std::vector<double> xy;
        double from, until, vx, vy;
    };
    std::vector<JamZone> jams_;  ///< #582 jamming zones
    /// Whether a jamming zone active at t holds an end of a-b or crosses it.
    bool jammed(const Vec3& a, const Vec3& b, double t) const;
    /// The smallest attenuation factor of the zones containing (x, y), or 1.
    double rangeFactorAt(const Vec3& p) const;
    /// Bring `n`'s battery up to now; switch it off when empty.
    void drainBattery(Node& n, double txSeconds);
    void batteryTimer(int node);
    /// Whether ground station g sees satellite s at time t.
    bool groundSees(int g, int s, double t) const;
 
    // adapter constants: the ns-3 attribute defaults (anthocnet-routing-protocol.cc)
    static constexpr double kTimerJitter = 0.05;    // TimerJitter
    static constexpr double kQueueTimeout = 3.0;    // QueueTimeout
    static constexpr double kReconvHoldCap = 0.2;   // ReconvHoldCap
    static constexpr double kRetryInterval = 0.25;  // ReactiveRetryInterval
    static constexpr std::size_t kQueueLen = 64;    // RequestQueue maxLen
    static constexpr int kTtl = 64;
    static constexpr std::size_t kDataBytes = 64 + 28;  // payload + IP/UDP
    static constexpr int kMacRetries = 7;               // failure known after 7 tries
    // #575 battery draw: the single-antenna 802.11n NIC anthocnet-compare
    // models (Halperin et al., HotPower'10): idle 0.82 W, transmitting 1.14 W.
    static constexpr double kIdleW = 0.82;
    static constexpr double kTxW = 1.14;
};
 
}  // namespace ahn_web
 
#endif  // AHN_WEB_SIM_H