Skip to main content

Crate c3mesh

Crate c3mesh 

Source
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 delay

The 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::step advances to one observable event.
  • Simulator::run returns all remaining events in deterministic order.
  • Simulator::run_with invokes a callback as each event occurs.
  • Simulator::advance_to processes 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:

  • fifo preserves admission order.
  • strict_priority serves larger priority values first, with FIFO ties.
  • weighted_fair serves 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: 500000000

Use 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_jamming

The examples cover direct delivery, static switch forwarding, routed multi-hop delivery, a moving aircraft radio link, and intermittent receiver jamming.

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_link

Distance 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.0 contributes no interference.
  • 1.0 is 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 delay

If 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_jamming

For 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-features

Useful expected event sequences are:

  • Degraded but stable: TransmissionStarted, DataReceived, then delivery or forwarding at the lower bitrate.
  • Severed at start: one PacketDropped event at the receiver.
  • Off-band interference: the normal unjammed event sequence.
  • A worsening in-flight pulse: TransmissionStarted, then PacketDropped at 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

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§

ChannelConfig
A serializable point-to-point channel definition.
ChannelId
A stable identifier for a channel in a topology.
ChannelMetrics
Distance-derived channel conditions at a specific virtual time.
ChannelOptions
Optional packet-engine behavior on a channel.
ChannelQueueMetrics
Instantaneous waiting-queue occupancy, excluding packets already on the wire.
DeviceConfig
A serializable device definition.
DeviceId
A stable identifier for a device in a topology.
DistanceChannel
Physical behavior for a channel connecting positioned devices.
FrequencyBand
A half-open radio-frequency interval, [lower_hz, upper_hz).
InterferenceResponse
Linear mapping from normalized interference to radio-link health.
NetworkConfig
A serializable description of an entire network topology.
Packet
A unit of data moving through the simulated network.
PacketId
A simulator-assigned packet identifier.
PacketMetadata
Generic endpoint-supplied metadata; routers never inspect the payload.
Position3D
A Cartesian position in meters.
QueueConfig
Bounds and selection policy for a waiting queue; in-flight packets are excluded.
RadioChannel
Wireless behavior attached to a point-to-point channel.
ReceiverInterference
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.
SimulatorOptions
Runtime options separate from the backward-compatible topology schema.
TransmissionMetrics
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§

ChannelState
The operating state of a channel.
ConfigError
An invalid network configuration.
ConfigLoadError
An error loading a serialized network configuration.
DeviceKind
The fundamental behavior assigned to a device.
DistanceRateModel
A deterministic distance-to-bitrate model.
DropReason
The reason a packet could not continue through the network.
MobilityModel
A deterministic description of a device’s movement.
NetworkEvent
An observable event produced by the simulator.
QueueDiscipline
Selection policy for packets waiting on one channel direction.
SimulationError
An operation that could not be performed by the simulator.