Ljh684/moonnet-lab/src/sim does not have a README file
Rng
pub struct Rng {
s0 : UInt64
s1 : UInt64
s2 : UInt64
s3 : UInt64
}The simulator's random source: xoshiro256**.
Why hand-roll instead of using the standard library: a reproducible
experiment must produce the same numbers on every backend and every future
version of this package. The algorithm is frozen here, its reference vectors
are pinned in the test suite, and nothing about it depends on the platform's
word size or on how a host language seeds its own generator.
Rng::fork
Derive an independent stream from this generator plus a label.
This is how the simulator gives every flow, every link and every loss
process its own randomness without any of them sharing draw order: renaming
a flow changes its stream, but adding an unrelated flow does not disturb it.
Rng::next_bool
true with probability p. p <= 0 never fires and p >= 1 always does,
which keeps scenario files free of edge-case surprises.
Rng::next_double
A uniform Double in [0, 1), built from the top 53 bits so every value is
exactly representable and the generator never returns 1.0.
Rng::next_double_between
A uniform Double in [low, high).
Rng::next_exponential
An exponential sample with the given mean, from the inverse transform
-mean * ln(U). Used for inter-arrival times and for burst gaps.
Rng::next_int
A uniform Int in [0, bound), using rejection sampling so that the
distribution is exactly uniform rather than modulo-biased. Determinism is
preserved because the number of rejections depends only on the sequence.
Rng::next_int64
A uniform Int64 in [0, bound).
Scheduled
One unit of scheduled work.
An event carries a human readable tag next to the closure so that a trace
of a run can be read (and diffed) without a debugger.
Sim
The deterministic simulation core.
A simulation is a pure function of its scenario and its seed. Sim owns
virtual time, the event queue and the random source; nothing reads the wall
clock and nothing depends on hash iteration order, so two runs of the same
configuration produce byte-identical journals and metrics.
Sim::after
Schedule action to run delay from now.
Sim::at
Schedule action at an absolute virtual time.
Sim::is_recording
Whether the journal is on.
Callers that would have to build a string to describe an event should ask
first. Building it unconditionally makes every run pay for a trace nobody
asked for, and on a transfer with tens of thousands of segments that cost
dominates everything else.
Sim::new
Create a simulator whose randomness is derived from seed.
Sim::note
Append a line to the journal, if journalling is on.
Sim::run
Drain the queue.
max_events is a safety valve: a model bug that schedules events from inside
an event handler could otherwise spin forever, and a hung experiment is worse
than a loud failure.
Sim::run_for
Run for duration of virtual time starting now.
Sim::run_until
Run every event up to deadline, leaving later events queued, and advance
the clock to deadline so that a run of an empty period still moves time
forward the way a real experiment would.
Sim::schedule_at
The single scheduling entry point.
Scheduling into the past is a bug in the model, not a recoverable condition,
so it aborts loudly with the offending tag instead of silently producing a
result that looks plausible but cannot happen on a real wire.
Sim::start_journal
Turn on the event journal. Journalling costs memory, so a long run keeps it
off unless the caller asks for a trace to inspect or to diff.
Sim::start_trace
Record explicit notes without retaining every scheduled event tag.
This is useful for protocol traces that need state transitions but not the
simulator's lower-level event schedule.
Sim::step
Run the earliest event. Returns false when the queue is empty.
Sim::step_until
Run until condition holds, and report whether it ever did.
Draining the queue tells you the simulation is over; this tells you when the
thing you were measuring actually happened. The distinction matters because a
protocol leaves superseded timer events behind: they are ignored when they
fire, but they are still events, and draining them pushes the clock past the
moment of interest. Measuring a transfer by reading the clock after a full
drain would report the last stale timer instead of the last byte.
SplitMix64
pub struct SplitMix64 {
state : UInt64
}SplitMix64, the seeding construction recommended for the xoshiro family.
A single UInt64 seed is expanded into a well-mixed state so that seeds as
similar as 1 and 2 still produce unrelated streams.
Time
Simulation time is a signed 64-bit count of picoseconds.
Picoseconds are small enough to express the serialization time of a single
64-byte frame on a 100 Gbps link (5_120 ps) without rounding, and large
enough that one Int64 spans roughly 106 days of simulated time.
Keeping time in an integer type is what makes experiments reproducible:
every scheduling decision compares exact integers, never floating point
values that could round differently on different backends.
Time::fibre_distance_km
Distance in kilometres that light travels through fibre in t.
Time::from_ms_f
Fractional milliseconds, for scenario files where 12.5ms reads better than
12500us. The conversion truncates towards zero.
Time::propagation
Propagation delay of distance_km kilometres over a medium where signals
travel at speed_km_per_s (light in fibre is about 200_000 km/s).
Time::render
Rendering picks the largest unit that keeps the value readable and always
prints three fractional digits, using integer arithmetic so that the output
is identical on every backend.
Time::serialize
Serialization time of bytes bytes on a link of bps bits per second.
The result is rounded down to a whole picosecond, which is the only rounding
the simulator ever performs. bytes * 8 * 10^12 must fit in Int64, so a
single transmission may be at most about 1.1 MB; larger transfers are modeled
as a series of packets.
Time::to_ms_f
Milliseconds as a float, for metrics and plots only. Never feed the result
back into scheduling.
fnv1a64
fn fnv1a64(text : String) -> UInt64FNV-1a over the UTF-8 bytes of a label, used to turn names into stable
numbers. Any hash would do; what matters is that it never changes.
mix64
fn mix64(a : UInt64, b : UInt64) -> UInt64Combine two 64-bit values into one, so that the pair determines the result
and the order matters.
This is what gives a packet a fate derived from its identity: the same
identity on the same link always produces the same number, whatever else
happened on that link in between.
Install
Download zipDeterministic packet-level network simulator and TCP congestion-control lab for MoonBit
simulationnetworktcpcongestion-controldeterministicdiscrete-event
Apache-2.0
Updated last month
32 downloads