python-drs — Discrete Rate Simulation (DRS) Framework for Python

python-drs is an open-source, PyTorch-inspired, event-driven Discrete Rate Simulation (DRS) framework for Python. It models systems where quantities flow continuously over time — water networks, chemical processing, electrical grids, energy storage, traffic, and supply chains — dramatically faster than traditional fixed-step simulation.

Discrete Rate Simulation is a hybrid of discrete-event simulation and continuous simulation: instead of ticking through time at fixed intervals, the engine calculates exactly when the next limit (threshold) will be reached, jumps the simulation clock to that precise moment, and triggers the matching state transition. The result is a Python simulation library that runs years of operation in a fraction of a second — and never misses a limit.

---

Why Discrete Rate Simulation?

Fixed-step simulation	Discrete Rate Simulation (DRS)
Checks the system at every interval	Computes exactly when the next limit is hit
Can miss events between ticks	Never misses a limit
Slow for tight tolerances	Fast, event-driven time jumping
Threshold logic bolted on	Thresholds are first-class citizens

Discrete Rate Simulation is ideal for hybrid systems where continuous physics (filling, draining, heating, discharging) meets discrete thresholds (full, empty, minimum, maximum, switch points).

---

Key Features

• Event-driven time stepping — simulate years of operation in seconds by jumping directly from event to event
• PyTorch-style architecture — every model is a Module that owns Variable, Level, and Timer state
• @engine.on_step control policies — hook control logic into the loop to drive rates and thresholds every step
• Continuous-flow modeling — Levels accumulate quantity over time (like an integral in dt) and leap straight to their thresholds
• Built-in telemetry — every state is recorded as a pandas DataFrame and plotted without custom tracking code
• Built-in components — Storage and Processor give you ready-made tanks, stockpiles, and processing units
• Door-to-door stream integration — feed discrete data streams and iterators into continuous dynamics
• NumPy/Pandas ecosystem — first-class integration with the Python scientific stack
• Pure Python — works on Python 3.9+, no external solver required

---

Installation

Install from PyPI:

pip install python-drs

---

Quickstart

Model a tank that fills at a constant rate and watch the engine jump to the exact moment it overflows:

from drs import DRSEngine, Module, Level

class Tank(Module):
    pass

model = Tank()
model.volume = Level("Volume", initial_value=100.0)

engine = DRSEngine()
engine.register(model)

@engine.on_step
def fill(policy_time):
    # Fill at 50 units per time step
    model.volume.rate = 50.0

result = engine.run(max_time=20.0)
print(result.summary())

Learn the core concepts step by step: Tutorial 1: Introduction to DRS.

---

How the Engine Works

Every simulation follows the same repeating loop:

1. Run control policies — each registered @engine.on_step handler computes the instantaneous rates and thresholds of the system.
2. Find the next event — the engine calculates how long until any Level crosses one of its thresholds.
3. Jump time — the simulation clock advances by exactly that amount, and all levels are integrated forward.
4. Repeat.

Because time jumps from event to event rather than advancing at fixed steps, python-drs scales to long-horizon problems that are intractable with naive fixed-step solvers.

---

Use Cases

• Water networks & hydraulics — storage tanks, reservoirs, pumping stations, pipe flow
• Chemical & process engineering — reactors, tanks, batch processes, separations
• Electrical grids & energy storage — charge/discharge cycles, grid balancing, batteries
• Supply chains & logistics — inventory, buffer stock, material flow, demand shocks
• Manufacturing — production lines, work-in-progress, equipment states
• Traffic & transportation — queue accumulation, congestion thresholds

If your system is best described by continuous flow crossing discrete thresholds, it is a Discrete Rate Simulation — and python-drs is the Python library built for it.

---

Documentation

Full guides, tutorials, and API reference are available at https://python-drs.readthedocs.io/:

• Tutorial 1: Introduction to DRS
• Tutorial 2: Event-Driven Time Jumping
• Tutorial 3: Streaming Inputs & Data Sources
• Tutorial 4: Telemetry & Control Policies
• Tutorial 5: Design Patterns: Operating Modes

---

Related

Looking for a Python alternative to discrete-rate simulation approaches in Simulink® or Modelica? python-drs brings PyTorch-like ergonomics to event-driven, continuous-flow simulation and lives on PyPI.

License

MIT — see LICENSE.