python-drs 0.1.1__tar.gz → 0.1.4__tar.gz

python_drs-0.1.4/PKG-INFO

@@ -0,0 +1,182 @@
+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).

python_drs-0.1.4/README.md

@@ -0,0 +1,125 @@
+# 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).

python_drs-0.1.4/drs/__init__.py

@@ -0,0 +1,40 @@
+import logging
+
+__version__ = "0.1.4"
+
+# Configure a NullHandler to prevent "No handler found" warnings
+# Users of the library can configure their own logging handlers
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+from .module import Module
+from .components import Storage, Processor
+from .engine import DRSEngine, SimResult
+from .variables import Variable, Level, Timer
+from .telemetry import Telemetry
+from .plot import (
+    Dashboard,
+    plot_series,
+    plot_time_series,
+    plot_safety_margin,
+    plot_dual_axis_step,
+    apply_plot_style,
+)
+
+__all__ = [
+    "DRSEngine",
+    "SimResult",
+    "Variable",
+    "Level",
+    "Timer",
+    "Module",
+    "Storage",
+    "Processor",
+    "Telemetry",
+    "Dashboard",
+    "plot_series",
+    "plot_time_series",
+    "plot_safety_margin",
+    "plot_dual_axis_step",
+    "apply_plot_style",
+]
+

python_drs-0.1.4/drs/engine.py

@@ -0,0 +1,128 @@
+from dataclasses import dataclass
+from typing import Any, Callable, List, Optional
+
+
+@dataclass
+class SimResult:
+    """Encapsulates the final results of a simulation run."""
+
+    steps: int
+    duration: float
+    history: Optional[Any] = None
+    terminated_reason: str = "until_reached"
+
+    def summary(self) -> str:
+        """Returns a string summary of the simulation run."""
+        lines = [
+            "--- Simulation Summary ---",
+            f"Termination Reason : {self.terminated_reason}",
+            f"Simulated Time     : {self.duration:.2f}",
+            f"Engine Steps       : {self.steps:,}",
+        ]
+        if self.history is not None:
+            lines.append(f"Telemetry Records  : {len(self.history):,}")
+        return "\n".join(lines)
+
+
+class DRSEngine:
+
+    def __init__(self, max_step_size: float = 1.0):
+        self.max_step_size = float(max_step_size)
+        self.components: List[Any] = []
+        self._step_handlers: List[Callable[[float], None]] = []
+        self.telemetry: Optional[Any] = None
+        self.current_time: float = 0.0
+
+    def register(self, *components: Any) -> None:
+        """Registers components to be simulated."""
+        for comp in components:
+            if comp not in self.components:
+                self.components.append(comp)
+
+    def attach_telemetry(self, telemetry: Any) -> None:
+        """Attach a Telemetry object to the engine."""
+        self.telemetry = telemetry
+
+    def variables(self):
+        """Yield every variable owned by the registered components.
+
+        Lets ``Telemetry(model=engine)`` record the full state of the flat
+        leaf components without passing a wrapper module.
+        """
+        seen = set()
+        for comp in self.components:
+            for variable in comp.variables():
+                if id(variable) not in seen:
+                    seen.add(id(variable))
+                    yield variable
+
+    def on_step(self, fn: Callable[[float], None]) -> Callable[[float], None]:
+        """Decorator to register a control policy callback."""
+        self._step_handlers.append(fn)
+        return fn
+
+    def run(
+        self, until: Optional[float] = None, max_time: Optional[float] = None
+    ) -> SimResult:
+        if until is None:
+            if max_time is not None:
+                until = max_time
+            else:
+                raise ValueError("Must specify 'until' or 'max_time'")
+        current_time = 0.0
+        self.current_time = current_time
+        steps = 0
+
+        terminated_reason = "until_reached"
+
+        if self.telemetry is not None:
+            self.telemetry.snapshot(current_time)
+
+        while current_time < until:
+            self.current_time = current_time
+
+            # Check if terminating condition is met
+            terminated = False
+            for comp in self.components:
+                if comp.is_terminating_condition_met():
+                    terminated = True
+                    break
+            if terminated:
+                terminated_reason = "condition_met"
+                break
+
+            # 1. Execute control policies at time t
+            for handler in self._step_handlers:
+                handler(current_time)
+
+            # 2. Determine time to next state boundary across all components
+            dt = self.max_step_size
+
+            # Don't step past simulation end
+            if current_time + dt > until:
+                dt = until - current_time
+
+            for comp in self.components:
+                event_dt = comp.time_to_event()
+                if event_dt >= 0.0:
+                    dt = min(dt, event_dt)
+
+            # 3. Tell each component to step forward by dt
+            for comp in self.components:
+                comp.step(dt)
+
+            current_time += dt
+            self.current_time = current_time
+            steps += 1
+
+            if self.telemetry is not None:
+                self.telemetry.snapshot(current_time)
+
+        df = self.telemetry.to_dataframe() if self.telemetry else None
+
+        return SimResult(
+            steps=steps,
+            duration=current_time,
+            history=df,
+            terminated_reason=terminated_reason,
+        )

python_drs-0.1.4/drs/module.py

@@ -0,0 +1,106 @@
+import math
+from typing import Iterator, Any
+from .variables import Variable, Level
+
+
+class Module:
+    """Base class for all DRS models and sub-components.
+
+    Modules are simple, modular components of a simulation.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the module."""
+        self.parent = None
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        super().__setattr__(name, value)
+        if name != "parent" and isinstance(value, Module):
+            value.parent = self
+
+    def variables(self) -> Iterator[Variable]:
+        """Recursively yield all variables owned by this module and its sub-components."""
+        seen = set()
+
+        def _find_vars(obj):
+            if id(obj) in seen:
+                return
+            seen.add(id(obj))
+
+            if isinstance(obj, Variable):
+                yield obj
+                return
+
+            dict_items = obj.__dict__.items()
+            for k, v in dict_items:
+                if isinstance(v, Variable):
+                    if id(v) not in seen:
+                        seen.add(id(v))
+                        yield v
+                elif (
+                    hasattr(v, "__dict__")
+                    and not k.startswith("_")
+                    and k != "parent"
+                    and not isinstance(
+                        v, (int, float, str, bool, list, dict, set, tuple)
+                    )
+                ):
+                    yield from _find_vars(v)
+
+        yield from _find_vars(self)
+
+    def modules(self) -> Iterator["Module"]:
+        """Recursively yield this module and all nested sub-modules."""
+        for _, module in self.named_modules():
+            yield module
+
+    def named_modules(self, prefix: str = "") -> Iterator[tuple[str, "Module"]]:
+        """Recursively yield (path, module) pairs using dot-separated attribute paths."""
+        seen = set()
+
+        def _get_modules(module, module_prefix):
+            module_id = id(module)
+            if module_id in seen:
+                return
+            seen.add(module_id)
+            yield module_prefix, module
+
+            for k, v in module.__dict__.items():
+                if k.startswith("_") or k == "parent":
+                    continue
+                if isinstance(v, Module):
+                    sub_prefix = k if not module_prefix else f"{module_prefix}.{k}"
+                    yield from _get_modules(v, sub_prefix)
+
+        yield from _get_modules(self, prefix)
+
+    def _owned_levels(self) -> Iterator[Level]:
+        """Yield Level instances held directly by this module (non-recursive).
+
+        Unlike :meth:`variables`, this does not descend into nested modules, so it
+        is safe to use for registering the stateful leaves owned by a component.
+        """
+        seen = set()
+        for v in self.__dict__.values():
+            if isinstance(v, Level) and id(v) not in seen:
+                seen.add(id(v))
+                yield v
+
+    def time_to_event(self) -> float:
+        """Determines time to next state boundary across all variables in this module based on current rates."""
+        min_dt = math.inf
+        for var in self.variables():
+            dt_for_var = var.time_to_event()
+            if 0.0 <= dt_for_var < min_dt:
+                min_dt = dt_for_var
+
+        return min_dt
+
+    def step(self, dt: float) -> None:
+        """Steps all variables in this module forward by dt."""
+        for var in self.variables():
+            var.step(dt)
+
+    def is_terminating_condition_met(self) -> bool:
+        """Override this to define custom stopping conditions."""
+        return False