Metadata-Version: 2.3
Name: simpy-stats
Version: 0.1.0
Summary: Arena-like statistics layer for SimPy: Counter, Tally, Level, replications, and CI.
Keywords: simpy,simulation,statistics,discrete-event
License: MIT
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Dist: simpy>=4.0
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
Requires-Dist: ruff>=0.9 ; extra == 'dev'
Requires-Dist: scipy>=1.10 ; extra == 'scipy'
Requires-Python: >=3.10
Provides-Extra: dev
Provides-Extra: scipy
Description-Content-Type: text/markdown

# simpy-stats

Arena-like statistics layer for [SimPy](https://simpy.readthedocs.io/): streaming `Counter`, `Tally`, and time-weighted `Level` statistics, replication management, and t-based confidence intervals — all with no mandatory dependencies beyond SimPy itself.

## Features

- **`Counter`** — event counts and optional rates
- **`Tally`** — observation-based streaming mean, variance, min, max (Welford algorithm)
- **`Level`** — time-weighted average of a piecewise-constant signal (queue length, WIP, utilization)
- **`Stats`** — factory + registry: one call per name, `finalize()` → `Snapshot`
- **`ReplicationRunner`** — independent replications with half-width stopping rules
- **`ci_t`** — two-sided *t*-based confidence intervals (built-in table; scipy optional)
- **SimPy integrations** — `MonitoredResource`, `MonitoredStore`, `MonitoredContainer`, `attach_resource_monitors()`

## Installation

```bash
pip install simpy-stats
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add simpy-stats
```

## Quick start

```python
import simpy
import simpy_stats

env = simpy.Environment()
stats = simpy_stats.Stats(env)

wait = stats.tally("wait_time")
arrivals = stats.counter("arrivals")
queue_len = stats.level("queue_len")

# ... run simulation ...

snap = stats.finalize()
print(simpy_stats.summary_table(snap))
```

### Replications with half-width stopping

```python
from simpy_stats import ReplicationRunner

def my_rep(seed: int) -> simpy_stats.Snapshot:
    env = simpy.Environment()
    stats = simpy_stats.Stats(env)
    # ... build and run model ...
    return stats.finalize()

runner = ReplicationRunner(my_rep)
report = runner.run_until_precision(
    metrics=["wait_time.mean"],
    rel_half_width=0.05,   # 5% relative half-width
    min_reps=10,
    max_reps=200,
)
print(simpy_stats.summary_table(report))
```

### Automatic resource monitoring

```python
from simpy_stats.simpy_integration import MonitoredResource

server = MonitoredResource(env, capacity=1, stats=stats, prefix="server")
# server.queue_len and server.in_service Levels are updated automatically
```

## Development

```bash
uv sync --extra dev   # install deps
uv run pytest -q      # run tests
uv run ruff check .   # lint
```

## Milestones

| | |
|---|---|
| M1 | Core stats + Stats + 70 tests |
| M2 | ReplicationRunner + CI / half-width |
| M3 | MonitoredResource + helpers + examples |
| M4 | Docs + PyPI release |

## License

MIT
