Expand description
§c3mesh
c3mesh is a deterministic, discrete-event Rust library for modeling how
long packets take to move through fixed and mobile communication networks. It
accounts for serialization rate, distance, propagation delay, channel
availability, and store-and-forward behavior without sleeping or depending on
wall-clock time.
The initial model provides four device roles:
- Sources originate packets on a configured egress channel.
- Sinks accept packets addressed to them.
- Switches forward packets using exact destination-to-channel rules.
- Routers use exact routes and an optional default route.
Channels are point-to-point and full-duplex. Each direction serializes packets independently in FIFO order and may be operational, degraded, or severed.
§Quick start
use c3mesh::{
ChannelConfig, ChannelState, DeviceConfig, DeviceKind, NetworkConfig,
NetworkEvent, SimTime, Simulator,
};
let network = NetworkConfig {
devices: vec![
DeviceConfig {
id: "sender".into(),
kind: DeviceKind::Source { egress: "link".into() },
mobility: Default::default(),
interference: vec![],
},
DeviceConfig {
id: "receiver".into(),
kind: DeviceKind::Sink,
mobility: Default::default(),
interference: vec![],
},
],
channels: vec![ChannelConfig {
id: "link".into(),
endpoints: ["sender".into(), "receiver".into()],
bit_rate_bps: 1_000_000,
propagation_delay_ns: 10_000_000,
state: ChannelState::Operational,
distance: None,
radio: None,
}],
};
let mut simulator = Simulator::new(network)?;
simulator.send("sender", "receiver", vec![0; 1_000])?;
let events = simulator.run()?;
assert!(events.iter().any(|event| matches!(
event,
NetworkEvent::PacketDelivered { at, .. }
if *at == SimTime::from_nanos(18_000_000)
)));The 1,000-byte payload takes 8 ms to serialize at 1 Mbit/s and another 10 ms to propagate, so delivery occurs at 18 ms of virtual time.
§Timing and events
For each transmission, the simulator calculates:
start = max(requested time, channel direction available time)
receive = start + ceil(payload bits / effective bit rate) + propagation delayThe channel direction becomes available after serialization finishes, allowing
packets already on the wire to propagate while the next packet serializes.
NetworkEvent::DataReceived is emitted only at receive, when the complete
packet has arrived. A switch or router can begin forwarding at that same virtual
timestamp. Sink delivery and expected failures are reported as separate events.
Events can be observed in four ways:
Simulator::stepadvances to one observable event.Simulator::runreturns all remaining events in deterministic order.Simulator::run_withinvokes a callback as each event occurs.Simulator::advance_toprocesses every event through an inclusive tick boundary, retains future events, and advances idle virtual time without overshooting.
All time is virtual and measured in integer nanoseconds. Runs perform no wall-clock sleeping and are deterministic for a given topology and send order.
§Packet engine and tick integration
Use Simulator::new_with_options to configure a channel’s packet engine
without changing the topology schema. An explicit channel entry enables a live
waiting queue. Simulator::new and channels without entries preserve the
original full-duplex FIFO reservation behavior. Sending nondefault
PacketMetadata also enables live queueing on the traversed channels; existing
wire reservations remain intact.
use c3mesh::{
ChannelOptions, NetworkConfig, PacketMetadata, QueueConfig, QueueDiscipline,
SimTime, Simulator, SimulatorOptions,
};
use std::collections::BTreeMap;
let options = SimulatorOptions {
seed: 42,
channels: BTreeMap::from([("link".into(), ChannelOptions {
mtu_bytes: Some(1_500),
wire_overhead_bytes: 28,
queue: QueueConfig {
max_packets: Some(64),
max_bytes: Some(96_000),
discipline: QueueDiscipline::StrictPriority,
},
shared_medium: Some("command-radio".into()),
loss_basis_points: 100, // 1 percent, deterministic for this seed.
..Default::default()
})]),
};
let mut simulator = Simulator::new_with_options(network, options)?;
simulator.schedule_send_with_metadata(
SimTime::ZERO, "sender", "receiver", b"move".to_vec(),
PacketMetadata {
priority: 230,
traffic_class: 1,
flow_id: 7,
expires_at: Some(SimTime::from_nanos(1_000_000_000)),
},
)?;
let events = simulator.advance_to(SimTime::from_nanos(50_000_000))?;
let waiting = simulator.channel_queue_metrics("link")?;Queue telemetry queries inspect only the selected channel: live queues use stored counters, and legacy FIFO reservations use indexed wire-start times. Packets starting exactly at the current virtual time are excluded even when other public events at that timestamp have yet to be consumed.
Queue bounds apply per direction to waiting packets and their full wire size, excluding packets already serializing or propagating. An idle serializer starts its first admitted packet immediately. A packet fitting the MTU can start immediately even if its wire size exceeds the waiting-buffer byte limit; that limit applies if the serializer or shared medium is busy, or older packets are waiting. Every packet still obeys the MTU. FIFO and weighted-fair queues drop the arriving packet when full. Strict priority can evict lower-priority waiting packets to admit a higher-priority packet; it preserves older packets on equal-priority eviction ties and never partially evicts if the arrival still cannot fit. Packets already on the wire are never preempted.
Scheduling policies select from the queue when serialization becomes available:
fifopreserves admission order.strict_priorityserves larger priority values first, with FIFO ties.weighted_fairserves by integer virtual finish time. A flow is identified by source, traffic class, and endpoint-assigned flow ID. Service cost uses wire bytes divided by the positive class weight; unspecified weights are one. Each flow retains its packet order. Assign stable flow IDs rather than a new ID for each packet when modeling sustained traffic.
A channel’s MTU includes modeled overhead. Oversized packets produce
DropReason::MtuExceeded; they are not fragmented. Overflow produces
QueueOverflow. Channel state, mobility, and receiver interference are
evaluated at the queued packet’s actual wire start, so changes during its wait
affect it. Existing in-flight reception checks continue to apply.
Channels with the same shared_medium ID share one serialization resource,
including opposite directions. Propagation does not occupy the resource.
Simultaneous contenders resolve deterministically in event order. Channels
with different IDs, and ordinary full-duplex channels, remain independent.
Loss is specified in basis points from 0 through 10,000. Loss decisions use a
stable integer hash of seed, packet identity, channel identity, and hop budget;
they are independent of tick size. Lost packets consume wire time and produce
ChannelLoss at the scheduled receive time, without a receive or delivery
event.
An expiry timestamp is an exclusive deadline. A packet already expired at
injection is dropped immediately. Waiting packets expire at their deadline and
release capacity, including when a deadline precedes an existing queue wakeup.
An in-flight packet whose arrival is at or after its deadline produces
PacketDropped { reason: Expired } at the deadline, even if serialization or
propagation would finish much later. It never emits a receive or delivery event.
Transmissions remain non-preemptive: expiry does not cancel the reserved physical
serialization time, and propagation does not reserve a shared medium.
Endpoint metadata follows the packet through routers unchanged; routers never inspect application payloads.
advance_to(boundary) returns all events at or before that boundary, including
forwarding and delivery events generated at the boundary itself. It processes
no later internal events, rejects backwards movement, and sets idle time to
the boundary. Keep queued packets pending between game ticks instead of using
run to complete future deliveries synchronously.
Run the congestion example and focused tests:
cargo run --example bounded_queues
cargo test --test packet_engine --all-features§Serialized topologies
All configuration types implement serde’s Serialize and Deserialize.
Convenience loaders are available through optional features:
[dependencies]
c3mesh = { version = "0.2", features = ["json", "yaml"] }Device variants use a kind tag. For example:
devices:
- id: client
kind: source
egress: access
- id: router
kind: router
routes:
server: backbone
default_route: backbone
- id: server
kind: sink
channels:
- id: access
endpoints: [client, router]
bit_rate_bps: 10000000
propagation_delay_ns: 100000
- id: backbone
endpoints: [router, server]
bit_rate_bps: 1000000000
propagation_delay_ns: 500000
state:
kind: degraded
effective_bit_rate_bps: 500000000Use NetworkConfig::from_json_str with the json feature and
NetworkConfig::from_yaml_str with the yaml feature. Both loaders validate
the parsed topology before returning it.
§Channel state
ChannelState::Operational uses the nominal bit rate. A degraded channel uses
its lower configured effective rate, while a severed channel rejects new
transmissions with a PacketDropped event. Changing a channel’s state affects
transmissions requested afterward; already scheduled arrivals are unchanged.
§Examples
cargo run --example direct
cargo run --example yaml_switch --features yaml
cargo run --example json_router --features json
cargo run --example moving_link
cargo run --example intermittent_jammingThe examples cover direct delivery, static switch forwarding, routed multi-hop delivery, a moving aircraft radio link, and intermittent receiver jamming.
§Moving devices and distance-aware links
Every device has a MobilityModel. Existing configurations default to a
stationary device at the coordinate origin, while physical simulations can use
a fixed 3D position, constant Cartesian velocity, or a time-ordered waypoint
trajectory. Coordinates are measured in meters but are reference-frame
agnostic, so the same API supports local maps and Earth-centered coordinates.
Add DistanceChannel to a channel to derive propagation delay, range, and
bitrate from the endpoint positions:
use c3mesh::{DistanceChannel, DistanceRateModel};
let radio = DistanceChannel {
propagation_speed_mps: 299_792_458.0,
max_range_m: 2_000_000.0,
rate_model: DistanceRateModel::Linear {
full_rate_distance_m: 500_000.0,
minimum_bit_rate_bps: 1_000_000,
},
};At a packet’s actual serialization start time, the simulator calculates the current endpoint distance. This includes any time the packet spent waiting for the channel. The selected distance determines whether the link is in range, its effective bitrate, and the signal propagation delay. Consequently, packets sent at different virtual times automatically experience the moving topology.
Use Simulator::device_position_at to inspect a trajectory and
Simulator::channel_metrics_at to query distance, availability, propagation,
and bitrate at any virtual timestamp. TransmissionStarted events also include
the sampled distance and effective bitrate. The moving_link example models a
moving aircraft and a stationary ground station:
cargo run --example moving_linkDistance is sampled at transmission start in version 0.1; acceleration, orbital mechanics, obstruction, Doppler shift, and changes during the serialization of one packet should be represented by external trajectory/link models or shorter packet intervals.
§Wireless spectrum and receiver jamming
Jamming is modeled as a condition at a receiving device. A radio channel says which frequencies a transmission occupies, while the receiver has one or more interference entries covering frequency bands. The simulator combines the entries that overlap the transmission band and converts the result into link rate or an unavailable link.
The library deliberately does not determine whether a receiver lies inside a jammed region. A terrain, propagation, electronic-warfare, or game-world model should make that determination and update the receiver’s interference snapshot. The same API represents deliberate jamming, friendly co-channel transmissions, faulty electronics, and other unintended interference.
Channels opt into this behavior with RadioChannel. A channel whose radio
field is None is bandless and ignores all receiver interference.
use c3mesh::{
FrequencyBand, InterferenceResponse, RadioChannel, ReceiverInterference,
};
let radio = RadioChannel {
// Half-open interval: 2.400 GHz is included and 2.420 GHz is excluded.
band: FrequencyBand::new(2_400_000_000, 2_420_000_000),
interference_response: InterferenceResponse {
unaffected_below: 0.1,
severed_at: 0.9,
},
};
let initial_receiver_interference = vec![ReceiverInterference {
band: FrequencyBand::new(2_405_000_000, 2_415_000_000),
jammed: 0.6,
}];Assign Some(radio) to ChannelConfig::radio. Assign the initial interference
vector to the receiving DeviceConfig::interference; an empty vector means the
receiver starts clear. Both fields use serde, so the same model can be written
in JSON or YAML:
devices:
- id: sender
kind: source
egress: radio
- id: receiver
kind: sink
interference:
- band: { lower_hz: 2405000000, upper_hz: 2415000000 }
jammed: 0.6
channels:
- id: radio
endpoints: [sender, receiver]
bit_rate_bps: 1000000
radio:
band: { lower_hz: 2400000000, upper_hz: 2420000000 }
interference_response:
unaffected_below: 0.1
severed_at: 0.9§What the 0-1 magnitude means
jammed is a normalized receiver-side severity, not dBm, SINR, a percentage,
or a packet-loss probability. Values must be finite and between 0.0 and
1.0, inclusive:
0.0contributes no interference.1.0is maximum severity when the entry covers the entire radio band.- Intermediate values represent proportional severity before spectral overlap and the radio’s configured tolerance are applied.
For each entry, the simulator multiplies jammed by the fraction of the radio
band it overlaps. Contributions are added and capped at 1.0. For example, a
0.6 entry covering half of the victim band contributes 0.3. A second
full-band 0.2 entry produces an aggregate magnitude of 0.5. Bands are
half-open, so [100, 200) and [200, 300) do not overlap.
The aggregate magnitude is mapped through InterferenceResponse. At or below
unaffected_below, the channel retains the rate already selected from channel
state and distance. At or above severed_at, it is unavailable. Between those
thresholds, rate scales linearly. With the default thresholds of 0.0 and
1.0, an aggregate magnitude of 0.5 supports half the base bitrate.
§Dynamic and intermittent interference
Interference snapshots are persistent and piecewise constant. Replacing a snapshot replaces every prior band contribution at that timestamp; pass an empty vector to clear the receiver. Scheduled changes may be inserted in any order, but cannot be scheduled before the simulator’s current time. The most recent call for a receiver and timestamp wins.
use c3mesh::{
FrequencyBand, ReceiverInterference, SimTime, SimulationError, Simulator,
};
let pulse = vec![ReceiverInterference {
band: FrequencyBand::new(2_400_000_000, 2_420_000_000),
jammed: 0.75,
}];
// Apply a live update at the simulator's current time.
simulator.set_receiver_interference("receiver", pulse.clone())?;
// Replace it with a scheduled pulse, then clear it 10 ms later.
simulator.schedule_receiver_interference(
SimTime::from_nanos(1_000_000_000),
"receiver",
pulse,
)?;
simulator.schedule_receiver_interference(
SimTime::from_nanos(1_010_000_000),
"receiver",
vec![],
)?;Rate is selected from the receiver condition at the transmission’s actual start, after any FIFO wait. The simulator then checks the entire interval in which bits reach the receiver:
serialization interval = [start, start + serialization time)
receive window = [start + propagation delay, receive_at)
receive_at = start + serialization time + propagation delayIf a pulse during that receive window would support a lower bitrate than the
one selected at transmission start, the packet is dropped at its scheduled
receive time with DropReason::ReceiverInterference. It produces no
DataReceived or PacketDelivered event. This catches a pulse that has ended
before packet completion without retroactively moving the channel’s FIFO
schedule. Interference before the first bit arrives or beginning exactly when
the complete packet arrives does not affect that packet.
Receiver interference is directional. Jamming device B affects transmissions from A to B; it does not automatically affect transmissions from B to A. It also does not automatically interfere with other receivers or turn ordinary c3mesh transmissions into interference sources. External models should update each affected receiver explicitly.
§Inspecting and testing jamming
Use Simulator::receiver_interference_at to inspect a raw scheduled snapshot.
Use Simulator::transmission_metrics_at(channel, sender, time) to see the
resolved receiver, frequency band, overlap-adjusted magnitude, base bitrate,
effective bitrate, and availability for one direction. TransmissionStarted
reports the selected bitrate and band; jamming failures appear as
PacketDropped events.
The complete degradation, recovery, unintended-interference, and intermittent pulse workflow is executable:
cargo run --example intermittent_jammingFor library development, run the focused jamming tests or the complete suite:
cargo test --test jamming
cargo test --test jamming intermittent_pulse_during_reception_corrupts_in_flight_packet
cargo test --all-features
cargo clippy --all-targets --all-features -- -D warnings
cargo test --doc --all-featuresUseful expected event sequences are:
- Degraded but stable:
TransmissionStarted,DataReceived, then delivery or forwarding at the lower bitrate. - Severed at start: one
PacketDroppedevent at the receiver. - Off-band interference: the normal unjammed event sequence.
- A worsening in-flight pulse:
TransmissionStarted, thenPacketDroppedat the previously calculated receive time.
Common mistakes are treating 50 as 50% instead of using 0.5, defining an
empty or reversed frequency interval, expecting a new snapshot to merge with
the previous one, or scheduling a pulse after the relevant receive window.
Invalid bands, thresholds, and magnitudes are rejected during topology or
runtime validation.
This is an abstract deterministic model. It does not calculate received power, noise floors, SINR, modulation/coding behavior, BER/PER, retransmission, antenna patterns, jammer propagation, adjacent-channel receiver blocking, or spectral skirts. Approximate skirts or leakage by supplying additional bands; use an external RF model when physical link-budget accuracy is required.
This boundary follows the ITU’s receiver-effect definition of interference, which covers accidental and intentional causes, and NIST findings that interference time scale can materially change link performance. The simple rectangular overlap calculation replaces the emitter-spectrum and receiver- filter convolution used in physical RF studies. See the ITU radio-interference overview, NIST time-scale study, and NTIA interference assessment.
§Model boundaries
Packets remain abstract byte payloads. Optional wire overhead contributes to serialization, queue capacity, and MTU checks; the engine does not synthesize protocol headers. Shared media model deterministic serialization contention, without collisions, carrier sensing, retransmission, or physical RF contention. There is no automatic fragmentation, dynamic routing, switch learning, multicast, obstruction, or device processing delay. Device roles are mutually exclusive built-in variants.
§Minimum supported Rust version
c3mesh requires Rust 1.85 or newer.
Continuous integration checks Rust 1.85.0 and current stable on Linux and Windows. The workflow covers formatting, strict lints, all-feature and default-feature tests, the bounded-queue example, and a package dry run. Action revisions are pinned to immutable commits; see .github/workflows/ci.yml.
When this checkout is used as a named Docker build context by a consumer, .dockerignore excludes local Cargo output, Git history, tool state, and environment files. Source, manifests, examples, and test fixtures remain available. This prevents accumulated build artifacts from being transferred with a source dependency.
§License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
§Runtime endpoints
Simulator::register_topology atomically adds devices/channels and their packet-engine
options without restarting queues, changing the loss seed, or resetting packet IDs.
Identifiers remain reserved after retirement. set_device_mobility changes a trajectory
at the current virtual time and preserves earlier trajectory queries. Advance to the
change time first; next_event_time supports synchronization with an external model.
retire_devices removes incident channels and sources whose egress disappears,
cleans forwarding references, and emits EndpointRetired once for each affected
queued or in-flight packet. Unrelated traffic and shared-medium reservations survive.
Structs§
- Channel
Config - A serializable point-to-point channel definition.
- Channel
Id - A stable identifier for a channel in a topology.
- Channel
Metrics - Distance-derived channel conditions at a specific virtual time.
- Channel
Options - Optional packet-engine behavior on a channel.
- Channel
Queue Metrics - Instantaneous waiting-queue occupancy, excluding packets already on the wire.
- Device
Config - A serializable device definition.
- Device
Id - A stable identifier for a device in a topology.
- Distance
Channel - Physical behavior for a channel connecting positioned devices.
- Frequency
Band - A half-open radio-frequency interval,
[lower_hz, upper_hz). - Interference
Response - Linear mapping from normalized interference to radio-link health.
- Network
Config - A serializable description of an entire network topology.
- Packet
- A unit of data moving through the simulated network.
- Packet
Id - A simulator-assigned packet identifier.
- Packet
Metadata - Generic endpoint-supplied metadata; routers never inspect the payload.
- Position3D
- A Cartesian position in meters.
- Queue
Config - Bounds and selection policy for a waiting queue; in-flight packets are excluded.
- Radio
Channel - Wireless behavior attached to a point-to-point channel.
- Receiver
Interference - Receiver-side interference over a frequency band.
- SimTime
- Virtual simulation time measured in nanoseconds from the start of a run.
- Simulator
- A deterministic, discrete-event simulation of a validated network topology.
- Simulator
Options - Runtime options separate from the backward-compatible topology schema.
- Transmission
Metrics - Directional link conditions for a prospective transmission.
- Velocity3D
- A Cartesian velocity in meters per second.
- Waypoint
- A position reached at a specific virtual time.
Enums§
- Channel
State - The operating state of a channel.
- Config
Error - An invalid network configuration.
- Config
Load Error - An error loading a serialized network configuration.
- Device
Kind - The fundamental behavior assigned to a device.
- Distance
Rate Model - A deterministic distance-to-bitrate model.
- Drop
Reason - The reason a packet could not continue through the network.
- Mobility
Model - A deterministic description of a device’s movement.
- Network
Event - An observable event produced by the simulator.
- Queue
Discipline - Selection policy for packets waiting on one channel direction.
- Simulation
Error - An operation that could not be performed by the simulator.