Metadata-Version: 2.4
Name: python-drs
Version: 0.1.4
Summary: PyTorch-inspired, event-driven Discrete Rate Simulation (DRS) framework for fast, exact continuous-flow modeling in Python.
Author: Jonathan Lamontagne Kratz
License: MIT License
        
        Copyright (c) 2026 Jonathan Lamontagne Kratz
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/epicgamer17/python-drs
Project-URL: Repository, https://github.com/epicgamer17/python-drs
Project-URL: Documentation, https://python-drs.readthedocs.io/
Keywords: simulation,discrete-rate-simulation,drs,discrete-event-simulation,continuous-flow,event-driven,modeling,simulation-framework,python-simulation,system-dynamics,hybrid-simulation,process-simulation,power-systems,scientific-computing,pytorch,engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: pandas>=1.3
Requires-Dist: matplotlib>=3.4
Requires-Dist: seaborn>=0.12
Provides-Extra: progress
Requires-Dist: rich>=13.0; extra == "progress"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

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

[![PyPI version](https://img.shields.io/pypi/v/python-drs.svg)](https://pypi.org/project/python-drs/)
[![Python versions](https://img.shields.io/pypi/pyversions/python-drs.svg)](https://pypi.org/project/python-drs/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**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** — `Level`s 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:

```bash
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:

```python
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](docs/tutorials/01_introduction.md).

---

## 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

[![Documentation](https://readthedocs.org/projects/python-drs/badge/?version=latest)](https://python-drs.readthedocs.io/)

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

- [Tutorial 1: Introduction to DRS](docs/tutorials/01_introduction.md)
- [Tutorial 2: Event-Driven Time Jumping](docs/tutorials/02_advanced_dynamics.md)
- [Tutorial 3: Streaming Inputs & Data Sources](docs/tutorials/03_data_streams.md)
- [Tutorial 4: Telemetry & Control Policies](docs/tutorials/05_telemetry_callbacks.md)
- [Tutorial 5: Design Patterns: Operating Modes](docs/tutorials/06_operating_modes.md)

---

## 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](https://pypi.org/project/python-drs/).

## License

MIT — see [LICENSE](LICENSE).
