Metadata-Version: 2.4
Name: most_queue
Version: 2.8
Summary: Software package for calculation and simulation of queuing systems
Project-URL: Homepage, https://github.com/xabarov/most-queue
Author-email: Xabarov Roman <xabarov1985@gmail.com>
License: Copyright (c) 2018 The Python Packaging Authority
        
        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.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: colorama
Requires-Dist: graphviz
Requires-Dist: matplotlib
Requires-Dist: networkx
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pyyaml
Requires-Dist: scipy<2.0,>=1.13.0
Requires-Dist: tqdm
Description-Content-Type: text/markdown

<div align="center">

# Most-Queue

**Queueing theory in Python: exact analytical solvers paired with discrete-event simulation — for 40+ models from M/M/1 to SRPT scheduling, vacations, negative customers and queueing networks.**

[🇷🇺 Русская версия](README.ru.md)

[![Tests](https://github.com/xabarov/most-queue/actions/workflows/tests.yml/badge.svg)](https://github.com/xabarov/most-queue/actions/workflows/tests.yml)
[![PyPI version](https://img.shields.io/pypi/v/most-queue)](https://pypi.org/project/most-queue/)
[![Python versions](https://img.shields.io/pypi/pyversions/most-queue)](https://pypi.org/project/most-queue/)
[![License](https://img.shields.io/pypi/l/most-queue)](https://github.com/xabarov/most-queue/blob/main/LICENSE)
[![Downloads](https://static.pepy.tech/badge/most-queue)](https://pepy.tech/project/most-queue)
[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/xabarov/most-queue)](https://github.com/xabarov/most-queue/commits/main)

<img src="https://raw.githubusercontent.com/xabarov/most-queue/main/assets/most-queue-nano1.jpeg" alt="Most-Queue banner" width="720"/>

</div>

## Why Most-Queue?

- **Analytics and simulation together.** Nearly every analytical calculator ships with a paired
  discrete-event simulator, and the test suite cross-validates them against each other. You get
  fast exact numbers *and* a way to check them.
- **Models you won't find elsewhere in open source**: size-based scheduling analytics
  (SRPT, SJF, PSJF, SPJF with ML-style size predictions, FB/LAS), M/G/1 vacation models,
  negative customers (RCS / disasters), unreliable servers, multi-server phase-type systems
  solved by the Takahashi–Takami method (including CV < 1 via complex-fit H₂).
- **Moments, not just means**: waiting/sojourn time raw moments, state probabilities,
  utilization — with a uniform `set_sources() / set_servers() / run()` API across all models.
- **Pure Python + NumPy/SciPy**, pip-installable, MIT license.

## Installation

```bash
pip install most-queue
```

Requires Python ≥ 3.9. For network visualization you may also need the system `graphviz` package.

## Quick start: theory vs simulation in 20 lines

```python
from most_queue.theory.fifo.mmnr import MMnrCalc
from most_queue.sim.base import QsSim

# Analytical M/M/3 with a finite queue
calc = MMnrCalc(n=3, r=100)
calc.set_sources(l=2.0)
calc.set_servers(mu=1.0)
theory = calc.run()

# The same system, simulated
sim = QsSim(3)
sim.set_sources(2.0, "M")
sim.set_servers(1.0, "M")
experiment = sim.run(100_000)

print(f"Mean waiting time: theory {theory.w[0]:.3f} vs simulation {experiment.w[0]:.3f}")
# Mean waiting time: theory 0.444 vs simulation 0.448
```

## Showcase: who pays for the scheduling discipline?

Computed by the library's own calculators — conditional slowdown `E[T(x)]/x` by job size
for FCFS, PS, FB (blind) and SRPT (size-aware):

<img src="https://raw.githubusercontent.com/xabarov/most-queue/main/docs/figures/slowdown_en.png" alt="Slowdown by job size for FCFS/PS/FB/SRPT" width="720"/>

See the executable comparison of **9 disciplines** in
[`tutorials/disciplines_comparison.ipynb`](tutorials/disciplines_comparison.ipynb).

## What's inside

| Family | Models | Method |
|---|---|---|
| Classic FIFO | M/M/c, M/M/c/r, Erlang B/C, M/G/1, GI/M/c, M/D/c, Eₖ/D/c, M/G/∞ | exact |
| Multi-server phase-type | M/H₂/c, H₂/M/c, H₂/H₂/c (CV < 1 via complex fit) | Takahashi–Takami |
| Size-based scheduling | M/G/1 SRPT, SJF, PSJF, SPJF (with size predictors), FB/LAS, PS, LCFS-PR | exact (Schrage–Miller, Mitzenmacher) |
| Priorities | M/G/1 PR/NP multi-class, M/G/c PR/NP, M/Ph/c PR | exact / invariant approximation |
| Vacations & warm-up | M/G/1 multiple vacations, N-policy, warm-up/cooling/delay (M/Ph/c) | Fuhrmann–Cooper, Takahashi–Takami |
| Negative customers | M/G/1 and M/G/c with RCS or disasters | exact / Takahashi–Takami |
| Reliability | M/G/1 with breakdowns & repairs | Avi-Itzhak–Naor |
| Matrix-analytic | MAP/PH/1, M/PH/1, PH/PH/1 — correlated (bursty) arrivals | QBD, logarithmic reduction |
| Retrial & abandonment | M/M/1 and M/G/1 retrial (orbit), Erlang-A (M/M/n+M) with staffing | exact / Falin–Templeton |
| GI/G approximations | GI/G/1, GI/G/m mean waiting time | Kingman, Krämer–Langenbach-Belz, Allen–Cunneen |
| Batch, impatience, closed | Mˣ/M/1, M/M/1+M, Engset | exact |
| Parallel service | Fork-Join, Split-Join | Markovian / order statistics |
| Networks | open networks, priority networks, networks with negative customers, routing optimization | decomposition |

Every model comes with a plain-language explanation and a diagram in the
[illustrated model catalog](docs/models.md).

## Documentation & tutorials

- 📖 [Documentation](docs/README.md) — concepts, calculation and simulation guides (English; Russian versions available via in-page switchers)
- 🎓 [Jupyter tutorials](tutorials/) — from a first M/M/1 to Takahashi–Takami and SRPT
- 🗺 [Development roadmaps](docs/epics/README.md) — what's next (matrix-analytic MAP/PH stack, retrial queues, Erlang-A)
- 🧪 [Tests](tests/) — every model validated against simulation; run with `pytest -m "not slow"`

## Applications

Capacity planning for cloud services and data centers · call-center staffing ·
manufacturing lines · telecom traffic · healthcare resource planning ·
scheduling research (SRPT/LAS with ML size predictions).

## Recent highlights

- **2026** — **Matrix-analytic stack**: PH distributions and MAPs (`most_queue.random.map_ph`),
  QBD solver with logarithmic reduction, exact MAP/PH/1 / M/PH/1 / PH/PH/1 calculators, MAP and
  PH sources in the simulator; plus retrial queues (orbit) and Erlang-A abandonment with a
  staffing helper. See [`tutorials/map_ph_correlation.ipynb`](tutorials/map_ph_correlation.ipynb).
- **2026** — Wave of exact classics: Erlang B/C, M/G/∞, GI/G approximations, M/G/1 vacation
  models (multiple vacations, N-policy), PS, LCFS-PR, FB/LAS, unreliable server — each with a
  paired simulator and tests. Illustrated model catalog with generated diagrams.
- **2026** — Size-based scheduling analytics: SRPT / SJF / PSJF / SPJF with prediction models
  (reproduces the Mitzenmacher–Shahout 2025 table in tests) + `SizeBasedQsSim`.
- **2026 (preprint)** — Multi-server queues with negative customers via Takahashi–Takami:
  [preprint & reproduction code](works/negative_queues/).
- **2025 (paper)** — Multi-channel system with warm-up, cooling and cooling delay:
  Lokhvitsky, Khabarov, Yakovlev, DOI [10.25791/aviakosmos.1.2025.1456](https://doi.org/10.25791/aviakosmos.1.2025.1456).

## Contributing

Issues and pull requests are welcome! Open an [issue](https://github.com/xabarov/most-queue/issues)
for bugs or model requests. Development conventions: [docs/PROJECT.md](docs/PROJECT.md),
definition of done: [docs/DOD.md](docs/DOD.md).

## Citation

If you use Most-Queue in research, please cite it (see [`CITATION.cff`](CITATION.cff)):

```bibtex
@software{most_queue,
  author  = {Khabarov, Roman},
  title   = {Most-Queue: queueing theory calculations and simulation in Python},
  url     = {https://github.com/xabarov/most-queue},
  license = {MIT}
}
```

## License

[MIT](LICENSE) © Roman Khabarov
