Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

SMOLPy

CI PyPI version Dev build Python License Docs

Python rewrite of SMOL — a Network Description Language and Discrete-Event Simulator for industrial Measurement-Diagnostics-Control (MDC) networks.

SMOLPy lets you describe a network topology in pure Python, define traffic flows, and run a discrete-event simulation that produces real metric time-series. A built-in Dear PyGui desktop dashboard shows the topology and live metric charts as the simulation runs.

Two simulation engines, one model. SMOLPy is no longer a SimPy-only simulator. A scenario, written in Python or in a .smol file, becomes one execution-independent model, and it can run on more than one engine:

  • SimPy (Python): the reference implementation. It is always installed, runs the whole model and drives the dashboards.
  • Rust (smol-engine): a native engine that gives SimPy's results bit for bit and runs about 40× faster. B1 at 10 M frames takes 4.9 s, against 200.8 s on SimPy.
result = net.simulate(duration=60_000, backend="rust")

The Rust engine runs the whole model: Ethernet, Modbus TCP, MQTT and PROFINET RT. Only the live and text dashboards need SimPy. See Simulation engine and ADR-0008.

📖 Full documentation: jwszolek.github.io/SMOLPy


Supported protocols

Protocol Runs over Communication pattern Nodes / API .smol statements Key metrics
Ethernet (generic traffic) Layer 2 frames One-way flows: constant, Poisson, bursty, batch Adapter.sends() flow throughput, latency, bytes_sent, bytes_received
MQTT TCP/IP Publish / subscribe through a broker, QoS 0 and 1 MQTTBroker, Adapter.publishes(), MQTTBroker.routes() mqtt_broker, publish, route broker_queue, latency
Modbus TCP TCP/IP Request / response polling (Read Holding Registers, FC 03) ModbusSlave, Adapter.polls() modbus_slave, poll modbus_latency
PROFINET RT Layer 2 (EtherType 0x8892), 802.1Q priority 6 Cyclic producer / consumer exchange with watchdog ProfinetDevice, Adapter.controls() profinet_device, control pn_latency, pn_jitter, pn_watchdog_expiries

Infrastructure: MAC-learning switches with 802.1Q strict-priority egress queues (qos="strict", or qos="fifo" to disable prioritisation). One Adapter can act in several roles at once — e.g. a PLC that is a Modbus master, an MQTT publisher and a PROFINET controller.

Not supported (yet): PROFINET IRT, PROFIBUS, EtherNet/IP, EtherCAT, OPC UA, Modbus RTU (serial), and Modbus write function codes. See the Architecture Decision Records for what is planned.


Install

pip install smolpy               # SimPy engine, dashboards, CLI
pip install "smolpy[rust]"       # plus the native Rust engine, about 40x faster
pip install --pre "smolpy[rust]" # the latest development build of main

Release channels. The versions below are read live from PyPI and GitHub, so this table is always current:

Channel smolpy smolpy-engine-rs Install
Stable, released by hand smolpy smolpy-engine-rs pip install "smolpy[rust]"
Development, every merge to main dev same version pip install --pre "smolpy[rust]"
  • What a development build is. Every merge to main that changes the package publishes one, as X.Y.(Z+1).devN, N commits after the latest release.
  • How to get it. It is a pre-release on PyPI, so pip installs it only with --pre.
  • Where it is on GitHub. The Development build pre-release points to its commit.
  • Releases proper are made by hand.

Without Python, from the Docker image of each release, which has SMOLPy and the Rust engine for linux/amd64 and linux/arm64:

docker run --rm -v "$PWD:/work" ghcr.io/jwszolek/smolpy run plant.smol --backend rust -o results.csv
  • The image runs headless: the live dashboard needs a display, so a .smol file needs mode=headless or mode=text.
  • It runs as uid 1000. To own the files it writes as yourself, add --user "$(id -u):$(id -g)".
  • A version is pinned as ghcr.io/jwszolek/smolpy:<version>; latest is the latest release.

From a clone, for development:

uv sync          # installs all runtime + dev dependencies

Quick start

from smolpy import Network

net    = Network("office-net")
host_a = net.adapter("host-A", ip="10.0.0.1")
server = net.adapter("server",  ip="10.0.0.10")
sw1    = net.switch("sw1", ports=8, mode="store-and-forward")

net.link(host_a, sw1, speed=1_000,  length=5)   # speed in Mb/s, length in metres
net.link(server, sw1, speed=10_000, length=2)

host_a.sends(to=server, rate=8_000, size=1_518, pattern="constant")

net.observe("throughput",  on=server, every=100)   # sample every 100 ms
net.observe("queue_depth", on=sw1,    every=50)

result = net.simulate(duration=30_000, live=True)  # 30 s simulation with live dashboard
result.report()                                     # print summary table to terminal

Run it:

uv run smolpy run my_script.py

Dashboard

When live=True the simulation runs in a background thread while a full-screen Dear PyGui window opens immediately.

Topology panel (left)

Each node is drawn as a coloured circle:

Colour Node type
Blue Adapter (host / server / NIC / PLC)
Green Switch
Purple MQTTBroker
Coral red ModbusSlave
Teal ProfinetDevice

Node fill changes dynamically during the simulation:

Appearance Meaning
Dim (faded) Node idle — no traffic yet
Pulsing bright fill Node actively transmitting (bytes_sent > 0)
Solid bright fill Node forwarding traffic (switch)
Pulsing amber outer ring Node actively receiving data (bytes_received > 0)

Animated particles flow along every link to show live traffic direction.

Metrics panel (right)

One chart per observed metric. All series update in real time. Axes auto-scale to fit the data.

Simulation controls

Three controls appear in the title bar during a live simulation:

Control Effect
⏸ Pause Freezes simulation time; dashboard stays interactive. Click again to resume.
▶ Resume Continues from the exact pause point.
⏹ Stop Ends the simulation early; plots freeze at the last collected sample.

Status indicator:

  • ● Simulating… — running
  • ● Paused — paused by user
  • ● Done — completed normally
  • ● Stopped — ended by user

DSL reference

Topology builders

adapter = net.adapter("name", ip="10.0.0.1")          # NIC / host / server
switch  = net.switch("name",  ports=16, mode="store-and-forward")   # qos="strict" (default) or "fifo"
broker  = net.mqtt_broker("name", ip="10.0.2.1")       # MQTT message broker
slave   = net.modbus_slave("name", ip="10.0.0.10", unit_id=1)  # Modbus TCP slave
device  = net.profinet_device("name", ip="10.0.4.1")   # PROFINET IO device
net.link(a, b, speed=1_000, length=10)                 # Mb/s and metres

Multiple switches can be chained to model hierarchical topologies:

core_sw = net.switch("core-sw", ports=16, mode="store-and-forward")
edge_sw = net.switch("edge-sw", ports=8,  mode="store-and-forward")
net.link(edge_sw, core_sw, speed=1_000, length=5)      # inter-switch uplink

Traffic

# Basic Ethernet send
src.sends(to=dst, rate=8_000, size=1_518, pattern="constant")

# Delayed start (useful for staggered scenarios)
src.sends(to=dst, rate=8_000, size=1_518, pattern="constant", delay_ms=5_000)

# MQTT publish (sensor-style, constant-rate)
sensor.publishes(to=broker, topic="plant/temp", rate=1.0, payload=20, qos=1)
sensor.publishes(to=broker, topic="plant/temp", rate=1.0, payload=20, qos=0, delay_ms=2_000)

# Broker topic routing — must be called before simulate()
broker.routes("plant/temp", to=[server])

# Modbus TCP poll (master → slave, Read Holding Registers)
plc.polls(slave, register=40001, count=10, rate=1.0)
plc.polls(slave, register=30001, count=5, rate=2.0, delay_ms=500)

# PROFINET RT cyclic I/O (controller ↔ device), 4 ms update time
plc.controls(device, cycle=4, inputs=32, outputs=16, hold=3)
Parameter Type Description
to Adapter Destination adapter
rate float Frames per second
size int | "imix" Ethernet frame size in bytes, FCS included, at least 64; or Internet Mix distribution
pattern str "constant", "poisson", "bursty", or "batch"
delay_ms float Simulation time before this flow starts (default 0)
priority int 802.1Q priority (PCP) 0–7 (default 0)

publishes() parameters

Parameter Type Description
to MQTTBroker Target broker
topic str MQTT topic string
rate float Messages per second (default 1.0)
payload int Payload bytes (default 20)
qos int 0 = fire-and-forget, 1 = PUBACK acknowledgement
delay_ms float Simulation time before publishing starts (default 0)

polls() parameters

Parameter Type Description
slave ModbusSlave Target slave to poll
register int Starting holding-register address
count int Number of registers to read
rate float Polls per second (default 1.0)
delay_ms float Simulation time before polling starts (default 0)

controls() parameters

Parameter Type Description
device ProfinetDevice Target IO device
cycle int Update time in ms: 1, 2, 4, … 512
inputs int Input data bytes per frame (device → controller), 1–1440
outputs int Output data bytes per frame (controller → device), 1–1440
hold int Data hold factor: watchdog = hold × cycle (default 3)
delay_ms float Simulation time before cyclic exchange starts (default 0)

Traffic patterns

Pattern Description
"constant" Fixed inter-frame gap — models a saturated link
"poisson" Exponentially distributed gaps — models random/bursty traffic
"bursty" Pareto-distributed burst lengths — models ON/OFF sources

Frame sizes

Value Description
integer Fixed size in bytes (e.g. 512, 1_518), at least 64
"imix" 40 % × 64 B, 57 % × 594 B, 3 % × 1 518 B

Sizes are Ethernet frames, FCS included. On the link each frame also takes a preamble and SFD (8 B) and an inter-frame gap (12 B), so links carry what real Ethernet carries.

Observations

net.observe(metric, on=node, every=interval_ms)
Metric Unit Observed on
throughput Mb/s Adapter
latency µs Adapter
frame_loss % Adapter
bytes_sent MB Adapter (sender)
bytes_received MB Adapter (receiver)
queue_depth frames Switch
utilization % Any node
broker_queue msgs MQTTBroker
modbus_latency µs Adapter (master)
pn_latency µs Adapter (controller), ProfinetDevice
pn_jitter µs Adapter (controller), ProfinetDevice
pn_watchdog_expiries count Adapter (controller), ProfinetDevice

Simulation

result = net.simulate(duration=30_000)              # headless — silent, fastest
result = net.simulate(duration=30_000, text=True)   # rich text dashboard in terminal
result = net.simulate(duration=30_000, live=True)   # full Dear PyGui desktop window

result.report()   # print summary table (avg / min / max per metric)
result.plot()     # open static dashboard for a completed result

# Export metric time-series (format inferred from extension)
result.export("results.csv")    # long CSV: time_ms, metric, value
result.export("results.json")   # JSON dict of lists-of-pairs
result.export("out.csv", format="csv")   # explicit format override

Text mode (text=True) displays a live updating table in the terminal — no display server or GUI toolkit required. Ideal for headless servers, SSH sessions, and CI environments.

Many runs

from smolpy import run_many

batch = run_many(net, runs=30, duration=10_000)   # seeds 42 … 71, on all CPU cores
batch.raise_on_failure()
results = batch.results()                         # one SimulationResult per run
summary = batch.summary()                         # per window: mean, std, 95 % CI
batch.report()                                    # per metric: mean ± CI across runs
batch.export("runs.csv")                          # every run, with its seed

base = net.to_scenario(duration=10_000)           # a sweep: one scenario per rate
sweep = run_many([base.with_flow_rate(r, source="bulk") for r in (1_000, 4_000)], runs=10)

A .smol file does the same with simulate ... runs=30, or with smolpy run plant.smol --runs 30 --workers 8 -o runs.csv.

Replications and parameter sweeps run in parallel worker processes; see the DSL Reference.

Quick demo

smolpy demo          # built-in 3-client scenario, text mode, no script needed

SMOL external DSL

Network topologies can also be described in a standalone .smol file — no Python required. smolpy run executes .smol files directly, using the same simulation engine underneath.

network "office-net" {
    adapter host-A ip=10.0.0.1
    adapter server ip=10.0.0.10
    switch  sw1    ports=8 mode=store-and-forward

    link host-A -- sw1 speed=1000  length=5
    link server -- sw1 speed=10000 length=2

    flow host-A -> server rate=8000 size=1518 pattern=constant

    observe throughput  on server every=100
    observe queue_depth on sw1    every=50

    simulate duration=30000 mode=text
}
uv run smolpy run topology.smol

Malformed or semantically invalid .smol files (undeclared node references, wrong node type for a statement, an unsupported metric, ...) produce a clean file:line: message error — no Python traceback. See the SMOL Language Reference for the complete syntax.


MQTT publish-subscribe

SMOLPy models application-layer MQTT traffic on top of the standard Ethernet/IP/TCP wire model.

What is modelled

  • Publisher adapters call publishes() to emit periodic MQTT PUBLISH frames at a fixed rate toward an MQTTBroker node.
  • The broker receives PUBLISH frames and fans out one copy to each registered subscriber per topic (routes()). QoS 0 delivers silently; QoS 1 additionally sends a PUBACK frame (64 bytes, the Ethernet minimum) back toward the publisher.
  • Subscriber adapters receive forwarded copies just like normal Ethernet frames; all standard metrics (throughput, latency, bytes_received) apply.
  • broker_queue samples the broker's inbound store depth — unprocessed PUBLISH frames waiting to be forwarded. A non-zero and rising queue indicates the broker or its downstream link is becoming a bottleneck.

Frame size formula

frame_size = 58 (Ethernet+IPv4+TCP+FCS) + 2 (MQTT fixed header) + 2 (topic-length field) + len(topic) + (2 if qos > 0 else 0) + payload_bytes, at least 64

A typical small sensor message (topic="plant/temperature", payload=20, qos=1) produces a 101-byte frame, roughly 15× smaller than a maximum-size bulk frame (1 518 B).

Dashboard

MQTTBroker nodes appear as purple circles in the topology panel.


Modbus TCP master/slave polling

SMOLPy also models Modbus TCP — a request/response protocol, unlike MQTT's fire-and-forget publish/subscribe. Because Modbus TCP already wraps its PDU in a standard Ethernet/IP/TCP frame (no serial bus, no gateway required), a ModbusSlave is a first-class network node wired into the same switch fabric as any Adapter.

What is modelled

  • The master is a regular Adapter — it calls polls() to periodically send Read Holding Registers (FC 03) requests toward a ModbusSlave.
  • Each slave is addressed by its own unit_id (1–247); it replies only to requests matching its unit_id and ignores everything else. Multiple sensors can share one switch, each polled independently by the same master.
  • Every poll is a request/response round trip — both frames traverse the network and contend for bandwidth, unlike MQTT where only the publisher-to-broker leg carries the payload.
  • modbus_latency measures poll round-trip time (RTT): the time from when the master sends a request to when the matching response arrives back. This is the key metric for judging whether a polling interval is achievable on a given network.

Frame size formula

request_size  = 69 bytes                                  (constant — Ethernet/IP/TCP/FCS + MBAP + FC + address + quantity)
response_size = 66 + 2 × register_count bytes              (grows with the number of registers read; at least 64)

Dashboard

ModbusSlave nodes appear as coral red circles in the topology panel.


PROFINET RT cyclic I/O

PROFINET RT is the third industrial pattern SMOLPy models: cyclic producer–consumer exchange. Controller and device each send their process data every update time, unprompted, and each supervises the other's frames with a watchdog. RT frames are plain Layer-2 Ethernet frames (EtherType 0x8892, no IP/TCP) tagged with 802.1Q priority 6.

plc = net.adapter("plc", ip="10.0.0.1")
io1 = net.profinet_device("io1", ip="10.0.4.1")
plc.controls(io1, cycle=4, inputs=32, outputs=16, hold=3)

net.observe("pn_jitter",            on=plc, every=100)
net.observe("pn_watchdog_expiries", on=plc, every=100)

What is modelled

  • The controller is a regular Adapter; controls() sets up one Application Relationship (AR) with a ProfinetDevice.
  • Both directions are cyclic and independent — the controller sends output frames, the device sends input frames, each every cycle ms.
  • Watchdog — a consumer that receives no frame for hold × cycle counts an expiry (pn_watchdog_expiries). Real devices would drop the AR at that point; SMOLPy counts it and keeps exchanging, so the whole run stays measurable.
  • pn_jitter — the largest deviation of the frame inter-arrival time from the cycle, per sampling window. pn_latency — mean send → receive time.
  • Prioritisation matters — every egress queue serves 802.1Q priorities strictly, so RT frames (priority 6) overtake ordinary traffic (priority 0). Build the switch with qos="fifo" to see what happens without it: under bursty load the cyclic data is delayed by whole bursts and watchdogs start to expire.

Frame size formula

frame_size = max(64, 14 (Ethernet) + 4 (802.1Q tag) + 2 (FrameID) + io_bytes + 4 (APDU status) + 4 (FCS))

Not modelled

IRT (isochronous, scheduled) traffic, AR establishment (DCP / RPC connect), acyclic record data, alarms, media redundancy (MRP). Switch buffers are unbounded, so frames are delayed but never dropped.

Dashboard

ProfinetDevice nodes appear as teal circles in the topology panel.


Simulation engine

Every simulation goes through the same path. The Python API and .smol files build a Scenario IR, an execution-independent model (ADR-0007), and a backend runs it. Both engines follow the same written contract, Model Semantics:

  • simulated time is integer nanoseconds;
  • frames are modelled on the wire as real Ethernet, with preamble, FCS and inter-frame gap.
Backend Language What it runs Speed Install
simpy (default) Python, SimPy the whole model, the live and text dashboards reference included
rust Rust, through PyO3 the whole model, headless: Ethernet, Modbus TCP, MQTT and PROFINET RT, every metric about 40× faster: B1 at 10 M frames in 4.9 s, not 200.8 s pip install smolpy[rust] (since v1.8.0)
ns3 ns-3's IPv4 stack, from C++ the whole model, headless. Ethernet over UDP and PROFINET RT on layer 2, bit-exact with SimPy. Modbus TCP and MQTT over ns-3's TCP, which adds connection setup and acknowledgements slower: each run is an ns-3 process an ns-3 3.49 build in NS3_HOME, e.g. the image ghcr.io/jwszolek/smolpy-ns3-base:3.49
result = net.simulate(duration=60_000, backend="rust")       # one run
batch = run_many(net, runs=30, duration=60_000, backend="rust")
smolpy run plant.smol --backend rust
  • The same numbers. On deterministic scenarios the Rust engine reproduces SimPy's results bit for bit, down to the event count. Random traffic uses each engine's own generator, so there the results agree statistically. CI checks both on every pull request (ADR-0009).
  • Nothing is skipped silently. A scenario that uses something a backend does not support is rejected before the run with a message naming the element. Asking the Rust engine for a dashboard is an error too.

The model both engines implement:

  • MAC-learning switch — each switch pre-seeds its forwarding table from the topology wiring, eliminating spurious flooding toward silent endpoints (e.g. a server that only receives). Dynamic learning still operates for traffic through intermediate switches.
  • Store-and-forward model — transmission delay + propagation delay per hop.
  • Queuing — each link direction has its own egress queue with 8 strict 802.1Q priority classes (FIFO within a class, non-preemptive); qos="fifo" on a switch ignores priorities. queue_depth reports buffered frames at the switch's outbound ports.
  • Traffic shaping — constant, Poisson, Pareto-burst and batch patterns; IMIX frame-size distribution.
  • Live mode (SimPy only) — simulation runs in 200 chunks (~8 s total wall time); the dashboard reads shared metric arrays between chunks via Python's GIL.

Examples

See examples/README.md for ten ready-to-run scenarios covering single-switch saturation, oversubscription, two-tier access bottlenecks, MQTT publish-subscribe, Modbus TCP polling, and PROFINET RT cyclic I/O.

uv run smolpy run examples/example.py
uv run smolpy run examples/example_two_tier.py

Metadata

Release files for smolpy 1.9.1.dev10

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for smolpy 1.9.1.dev10
File Size Uploaded Provenance Actions
smolpy-1.9.1.dev10.tar.gz 384.8 kB Without provenance Details for smolpy-1.9.1.dev10.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for smolpy 1.9.1.dev10
File Interpreter ABI Platform Actions
smolpy-1.9.1.dev10-py3-none-any.whl Python 3 none any Details for smolpy-1.9.1.dev10-py3-none-any.whl

Total release size: 484.4 kB

Release files / smolpy-1.9.1.dev10.tar.gz

Download URL smolpy-1.9.1.dev10.tar.gz
Size 384.8 kB
Tags Source
SHA-256 checksum
How to use checksums
192c79eb9214fd1a47751980d32552c7482556e810a621b49d642134432d366f
BLAKE2b-256 checksum
How to use checksums
a6916cc1cb9f1dce0fe1690b56b89050c6d7390795deff1f0c270cd7c72c99b3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / smolpy-1.9.1.dev10-py3-none-any.whl

Download URL smolpy-1.9.1.dev10-py3-none-any.whl
Size 99.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4ed8cba34e1666f0c8bd8604e90ff1bcf539d17aa9bcf45b56802b30b35e0e16
BLAKE2b-256 checksum
How to use checksums
11407421ffb53832d419dd73edea2fef2ca9fb0dd50c9d0f040ce9e9f2005879
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Security for smolpy 1.9.1.dev10

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page