Network¶

Network topology, links, partitions, and predefined network condition factories.

Network simulation components.

This package provides abstractions for modeling network behavior including latency, bandwidth constraints, packet loss, and network topologies.

NetworkLink `dataclass` ¶

NetworkLink(
    name: str,
    latency: LatencyDistribution,
    bandwidth_bps: float | None = None,
    packet_loss_rate: float = 0.0,
    jitter: LatencyDistribution | None = None,
    egress: Entity | None = None,
)

Bases: Entity

Simulates network transmission delay and bandwidth constraints.

Models a point-to-point network connection. Events sent through the link experience configurable latency, optional jitter, and may be dropped based on a packet loss rate. Bandwidth limits add transmission delay based on payload size.

The link forwards events to its configured egress after applying delays. If no egress is set, events are dropped with a warning.

Attributes:

Name	Type	Description
`name`	`str`	Identifier for logging and debugging.
`latency`	`LatencyDistribution`	Base one-way delay distribution.
`bandwidth_bps`	`float \| None`	Link capacity in bits per second. None means infinite.
`packet_loss_rate`	`float`	Probability [0, 1] of dropping each packet.
`jitter`	`LatencyDistribution \| None`	Optional additional random delay distribution.
`egress`	`Entity \| None`	Destination entity for forwarded events.

current_utilization `property` ¶

current_utilization: float

Current link utilization as fraction of bandwidth.

Returns 0.0 if bandwidth is infinite (None).

link_stats `property` ¶

link_stats: NetworkLinkStats

Frozen snapshot of current link statistics.

set_clock ¶

set_clock(clock: Clock) -> None

Inject the simulation clock.

handle_event ¶

handle_event(
    event: Event,
) -> Generator[float, None, list[Event] | Event | None]

Process an event through the network link.

Applies packet loss, calculates total delay (latency + jitter + transmission time), and forwards the event to the egress.

Parameters:

Name	Type	Description	Default
`event`	`Event`	The event to transmit through the link.	required

Yields:

Type	Description
`float`	Total transmission delay in seconds.

Returns:

Type	Description
`list[Event] \| Event \| None`	Forwarded event targeting the egress, or None if dropped.

NetworkLinkStats `dataclass` ¶

NetworkLinkStats(
    bytes_transmitted: int = 0,
    packets_sent: int = 0,
    packets_dropped: int = 0,
)

Frozen snapshot of NetworkLink statistics.

Attributes:

Name	Type	Description
`bytes_transmitted`	`int`	Total bytes successfully transmitted.
`packets_sent`	`int`	Number of packets successfully transmitted.
`packets_dropped`	`int`	Number of packets dropped (loss).

LinkStats `dataclass` ¶

LinkStats(
    source: str = "",
    destination: str = "",
    packets_sent: int = 0,
    packets_dropped: int = 0,
    bytes_transmitted: int = 0,
)

Per-connection-pair traffic statistics.

Attributes:

Name	Type	Description
`source`	`str`	Name of the source entity.
`destination`	`str`	Name of the destination entity.
`packets_sent`	`int`	Number of packets successfully transmitted.
`packets_dropped`	`int`	Number of packets dropped (loss).
`bytes_transmitted`	`int`	Total bytes transmitted.

Network `dataclass` ¶

Network(name: str, default_link: NetworkLink | None = None)

Bases: Entity

Routes events through configured network topology.

Network acts as a routing layer that directs events through appropriate NetworkLinks based on source and destination entities. Events must have 'source' and 'destination' in their context metadata to be routed.

Supports network partitions where events between partitioned groups are dropped, simulating network failures or split-brain scenarios.

Attributes:

Name	Type	Description
`name`	`str`	Identifier for logging and debugging.
`default_link`	`NetworkLink \| None`	Link used when no specific route is configured.

set_clock ¶

set_clock(clock: Clock) -> None

Inject the simulation clock and propagate to all links.

add_link ¶

add_link(
    source: Entity, dest: Entity, link: NetworkLink
) -> None

Configure a unidirectional link between two entities.

Parameters:

Name	Type	Description	Default
`source`	`Entity`	The sending entity.	required
`dest`	`Entity`	The receiving entity.	required
`link`	`NetworkLink`	The NetworkLink to use for this route.	required

add_bidirectional_link ¶

add_bidirectional_link(
    a: Entity, b: Entity, link: NetworkLink
) -> None

Configure a bidirectional link between two entities.

Creates two routes (a->b and b->a) using the same link characteristics. Note: This creates a copy of the link for the reverse direction to allow independent statistics tracking.

Parameters:

Name	Type	Description	Default
`a`	`Entity`	First entity.	required
`b`	`Entity`	Second entity.	required
`link`	`NetworkLink`	The NetworkLink to use (copied for reverse direction).	required

partition ¶

partition(
    group_a: list[Entity],
    group_b: list[Entity],
    *,
    asymmetric: bool = False,
) -> Partition

Create a network partition between two groups.

Events between entities in group_a and entities in group_b will be dropped. Events within the same group are unaffected.

Parameters:

Name	Type	Description	Default
`group_a`	`list[Entity]`	First group of entities.	required
`group_b`	`list[Entity]`	Second group of entities.	required
`asymmetric`	`bool`	If True, only block traffic from group_a to group_b (group_b can still send to group_a). Default is False (bidirectional partition).	`False`

Returns:

Type	Description
`Partition`	A Partition handle that can be used to selectively heal this
`Partition`	partition without affecting others.

heal_partition ¶

heal_partition() -> None

Remove all network partitions, restoring full connectivity.

is_partitioned ¶

is_partitioned(source_name: str, dest_name: str) -> bool

Check if two entities are separated by a partition.

Checks both bidirectional (frozenset) and directed (tuple) partitions.

Parameters:

Name	Type	Description	Default
`source_name`	`str`	Name of the source entity.	required
`dest_name`	`str`	Name of the destination entity.	required

Returns:

Type	Description
`bool`	True if the entities are partitioned in the given direction.

get_link ¶

get_link(
    source_name: str, dest_name: str
) -> NetworkLink | None

Get the link for a source-destination pair.

Parameters:

Name	Type	Description	Default
`source_name`	`str`	Name of the source entity.	required
`dest_name`	`str`	Name of the destination entity.	required

Returns:

Type	Description
`NetworkLink \| None`	The configured link, or the default link if no specific route exists.

traffic_matrix ¶

traffic_matrix() -> list[LinkStats]

Per-connection-pair traffic statistics.

Iterates all configured routes and collects each link's stats into a list of LinkStats.

Returns:

Type	Description
`list[LinkStats]`	A list of LinkStats, one per configured route.

handle_event ¶

handle_event(
    event: Event,
) -> Generator[float, None, list[Event] | Event | None]

Route an event through the appropriate network link.

The event must have 'source' and 'destination' in its context metadata to be routed. If the route is partitioned, the event is dropped.

Parameters:

Name	Type	Description	Default
`event`	`Event`	The event to route.	required

Yields:

Type	Description
`float`	Delay from the underlying network link.

Returns:

Type	Description
`list[Event] \| Event \| None`	Forwarded event(s) or None if dropped.

send ¶

send(
    source: Entity,
    destination: Entity,
    event_type: str,
    payload: dict | None = None,
    daemon: bool = False,
) -> Event

Create an event ready to be sent through the network.

Convenience method that creates an event with proper routing metadata.

Parameters:

Name	Type	Description	Default
`source`	`Entity`	The sending entity.	required
`destination`	`Entity`	The receiving entity.	required
`event_type`	`str`	Type label for the event.	required
`payload`	`dict \| None`	Optional additional metadata.	`None`
`daemon`	`bool`	Whether the event is a daemon event.	`False`

Returns:

Type	Description
`Event`	An Event configured for routing through this network.

Partition `dataclass` ¶

Partition(
    pairs: frozenset[frozenset[str]],
    directed_pairs: frozenset[tuple[str, str]],
    _network: Network,
)

Handle for a network partition, enabling selective healing.

Returned by Network.partition(). Call heal() to remove only this partition while leaving other partitions intact.

Attributes:

Name	Type	Description
`pairs`	`frozenset[frozenset[str]]`	The frozenset pairs (bidirectional) belonging to this partition.
`directed_pairs`	`frozenset[tuple[str, str]]`	The directed tuple pairs (asymmetric) belonging to this partition.

is_active `property` ¶

is_active: bool

True if any of this partition's pairs are still active.

heal ¶

heal() -> None

Remove only this partition's pairs, leaving others intact.

cross_region_network ¶

cross_region_network(
    name: str = "cross_region",
) -> NetworkLink

Create a cross-region/cross-datacenter network link.

Characteristics: - ~50ms latency (continental distance) - 1 Gbps bandwidth - Very low packet loss (0.01%) - Moderate jitter

Suitable for: multi-region deployments, cross-datacenter replication, geo-distributed systems.

Parameters:

Name	Type	Description	Default
`name`	`str`	Identifier for the link.	`'cross_region'`

Returns:

Type	Description
`NetworkLink`	NetworkLink configured for cross-region network conditions.

datacenter_network ¶

datacenter_network(name: str = 'datacenter') -> NetworkLink

Create a datacenter network link.

Characteristics: - ~0.5ms latency - 10 Gbps bandwidth - No packet loss (reliable internal network) - Minimal jitter

Suitable for: same-datacenter communication, rack-to-rack, internal microservices.

Parameters:

Name	Type	Description	Default
`name`	`str`	Identifier for the link.	`'datacenter'`

Returns:

Type	Description
`NetworkLink`	NetworkLink configured for datacenter network conditions.

internet_network ¶

internet_network(name: str = 'internet') -> NetworkLink

Create an internet/WAN network link.

Characteristics: - ~100ms latency (intercontinental) - 100 Mbps bandwidth (typical business connection) - Low packet loss (0.1%) - Significant jitter

Suitable for: public internet connections, client-server communication, external API calls.

Parameters:

Name	Type	Description	Default
`name`	`str`	Identifier for the link.	`'internet'`

Returns:

Type	Description
`NetworkLink`	NetworkLink configured for internet network conditions.

local_network ¶

local_network(name: str = 'local') -> NetworkLink

Create a local/loopback network link.

Characteristics: - ~0.1ms latency (essentially instantaneous) - 1 Gbps bandwidth - No packet loss - No jitter

Suitable for: localhost connections, in-process communication, same-machine services.

Parameters:

Name	Type	Description	Default
`name`	`str`	Identifier for the link.	`'local'`

Returns:

Type	Description
`NetworkLink`	NetworkLink configured for local network conditions.

lossy_network ¶

lossy_network(
    loss_rate: float,
    name: str = "lossy",
    base_latency: float = 0.01,
) -> NetworkLink

Create a network link with configurable packet loss.

Useful for testing retry logic, fault tolerance, and degraded network conditions.

Parameters:

Name	Type	Description	Default
`loss_rate`	`float`	Probability [0, 1] of dropping each packet.	required
`name`	`str`	Identifier for the link.	`'lossy'`
`base_latency`	`float`	Base latency in seconds (default 10ms).	`0.01`

Returns:

Type	Description
`NetworkLink`	NetworkLink configured with the specified loss rate.

Raises:

Type	Description
`ValueError`	If loss_rate is not in [0, 1].

mobile_3g_network ¶

mobile_3g_network(name: str = 'mobile_3g') -> NetworkLink

Create a 3G mobile network link.

Characteristics: - ~100ms latency - 2 Mbps bandwidth - Moderate packet loss (0.5%) - High jitter

Suitable for: mobile app testing, degraded connectivity scenarios.

Parameters:

Name	Type	Description	Default
`name`	`str`	Identifier for the link.	`'mobile_3g'`

Returns:

Type	Description
`NetworkLink`	NetworkLink configured for 3G mobile network conditions.

mobile_4g_network ¶

mobile_4g_network(name: str = 'mobile_4g') -> NetworkLink

Create a 4G/LTE mobile network link.

Characteristics: - ~50ms latency - 20 Mbps bandwidth - Low packet loss (0.1%) - Moderate jitter

Suitable for: mobile app testing, typical mobile conditions.

Parameters:

Name	Type	Description	Default
`name`	`str`	Identifier for the link.	`'mobile_4g'`

Returns:

Type	Description
`NetworkLink`	NetworkLink configured for 4G mobile network conditions.

satellite_network ¶

satellite_network(name: str = 'satellite') -> NetworkLink

Create a satellite network link.

Characteristics: - ~600ms latency (geostationary orbit round-trip) - 10 Mbps bandwidth (limited satellite capacity) - Moderate packet loss (0.5%) - High jitter

Suitable for: satellite internet, remote/maritime locations, backup connectivity.

Parameters:

Name	Type	Description	Default
`name`	`str`	Identifier for the link.	`'satellite'`

Returns:

Type	Description
`NetworkLink`	NetworkLink configured for satellite network conditions.

slow_network ¶

slow_network(
    latency_seconds: float,
    name: str = "slow",
    bandwidth_bps: float = 1000000,
) -> NetworkLink

Create a slow network link with configurable latency.

Useful for testing timeout handling and latency-sensitive code.

Parameters:

Name	Type	Description	Default
`latency_seconds`	`float`	One-way latency in seconds.	required
`name`	`str`	Identifier for the link.	`'slow'`
`bandwidth_bps`	`float`	Bandwidth in bits per second (default 1 Mbps).	`1000000`

Returns:

Type	Description
`NetworkLink`	NetworkLink configured with the specified latency.

Network¶

NetworkLink dataclass ¶

current_utilization property ¶

link_stats property ¶

set_clock ¶

handle_event ¶

NetworkLinkStats dataclass ¶

LinkStats dataclass ¶

Network dataclass ¶

set_clock ¶

add_link ¶

add_bidirectional_link ¶

partition ¶

heal_partition ¶

is_partitioned ¶

get_link ¶

traffic_matrix ¶

handle_event ¶

send ¶

Partition dataclass ¶

is_active property ¶

heal ¶

cross_region_network ¶

datacenter_network ¶

internet_network ¶

local_network ¶

lossy_network ¶

mobile_3g_network ¶

mobile_4g_network ¶

satellite_network ¶

slow_network ¶

NetworkLink `dataclass` ¶

current_utilization `property` ¶

link_stats `property` ¶

NetworkLinkStats `dataclass` ¶

LinkStats `dataclass` ¶

Network `dataclass` ¶

Partition `dataclass` ¶

is_active `property` ¶