desna-interval 0.0.1__tar.gz

desna_interval-0.0.1/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes of desna-interval are documented here. The project follows
+[Semantic Versioning](https://semver.org). Russian summary: the same entries
+apply; the documentation is in `docs/ru/`.
+
+## 0.0.1 — 2026-11-11
+
+First release: the monitoring-interval rule of article 1 (A. Ferubko, O. Kazakov, BGITU).
+Renamed from `deficit-interval` (module `deficit_interval`) before publication.
+
+* Rule `delta* = s/v + sqrt(2 eps/v)` with the age of the snapshot
+  (`interval_unclipped`, `next_interval`, `next_interval_aged`, `min_slack`).
+* Expected-cost optimum `x^3/3 + s x^2/2 = c v^2 / rho` (`expected_cost_rate`,
+  `optimal_interval_expected`), claim 1.5.
+* Bounds on the growth rate `v`: `history_quantile`, `pooled_quantile`,
+  `WindowQuantile`, `FixedRate`, the scalar Kalman filter `KalmanRate` and the
+  adapter `RateFilterAdapter` for any filter with `rate()`; `burst_rate`.
+* Per-object or common schedule (`MonitorScheduler`) and the protocol
+  `IntervalScheduler` for other schedules.
+* Offline replay of policies on a trace (`replay`, `FixedPolicy`, `BackoffPolicy`,
+  `DeficitRulePolicy`, `ExpectedCostPolicy`) and the command line `desna-interval`.
+* Live loop for libvirt guests (`libvirt_loop.run`, with an optional `scheduler`)
+  with snapshot age and an optional adaptation of the statistics period; it imports
+  without libvirt.
+* Experiments E1–E5 of article 1 in `experiments/` (optional group `experiments`):
+  scripts with `--smoke`, one configuration file, outputs as CSV and PDF/PNG,
+  a synthetic generator bit-identical with the prototype, held-out scenario D.
+* Documentation in English and Russian, four examples, tests.

desna_interval-0.0.1/CITATION.cff

@@ -0,0 +1,35 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "desna-interval: monitoring interval from a tolerance on accumulated deficit"
+abstract: >-
+  A Python library that chooses the polling interval of a virtual machine's
+  memory from a tolerance on the accumulated deficit: the rule
+  delta* = s/v + sqrt(2 eps/v), the correction for the age of a late snapshot,
+  the expected-cost optimum, the Jensen bound on the benefit of adaptation,
+  estimators of the growth rate (including a Kalman adapter), and a live loop
+  for KVM guests through libvirt.
+version: 0.0.1
+date-released: 2026-11-11
+license: MIT
+repository-code: "https://github.com/89605502155/desna-interval"
+url: "https://github.com/89605502155/desna-interval"
+keywords:
+  - memory ballooning
+  - monitoring interval
+  - accumulated deficit
+  - virtual machines
+  - KVM
+  - libvirt
+  - virtio-balloon
+authors:
+  - family-names: Ferubko
+    given-names: Andrey
+    email: ferubko1999@yandex.ru
+    orcid: "https://orcid.org/0009-0006-5625-137X"
+    affiliation: "Bryansk State Engineering-Technological University (BGITU)"
+  - family-names: Kazakov
+    given-names: Oleg
+    email: kazakov@bgitu.ru
+    orcid: "https://orcid.org/0000-0001-9665-8138"
+    affiliation: "Bryansk State Engineering-Technological University (BGITU)"

desna_interval-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Ferubko, Oleg Kazakov
+
+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.

desna_interval-0.0.1/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: desna-interval
+Version: 0.0.1
+Summary: Monitoring interval from a tolerance on accumulated deficit: the rule delta* = s/v + sqrt(2 eps/v), aged snapshots, expected-cost optimum and a libvirt loop for KVM memory ballooning
+Keywords: kvm,libvirt,virtio-balloon,memory-ballooning,monitoring-interval,adaptive-sampling,accumulated-deficit,virtual-machines,polling
+Author: Andrey Ferubko, Oleg Kazakov
+Author-email: Andrey Ferubko <ferubko1999@yandex.ru>, Oleg Kazakov <kazakov@bgitu.ru>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Operating System Kernels :: Linux
+Classifier: Typing :: Typed
+Requires-Dist: numpy>=1.26
+Requires-Dist: libvirt-python>=8.0 ; extra == 'libvirt'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/89605502155/desna-interval
+Project-URL: Documentation, https://github.com/89605502155/desna-interval/tree/main/docs
+Project-URL: Repository, https://github.com/89605502155/desna-interval
+Project-URL: Issues, https://github.com/89605502155/desna-interval/issues
+Project-URL: Changelog, https://github.com/89605502155/desna-interval/blob/main/CHANGELOG.md
+Provides-Extra: libvirt
+Description-Content-Type: text/markdown
+
+# desna-interval
+
+[![PyPI](https://img.shields.io/pypi/v/desna-interval.svg)](https://pypi.org/project/desna-interval/)
+[![Python](https://img.shields.io/pypi/pyversions/desna-interval.svg)](https://pypi.org/project/desna-interval/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/89605502155/desna-interval/blob/main/LICENSE)
+
+**How often to poll a resource so that the deficit accumulated between two polls stays below a tolerance.**
+
+desna-interval chooses the monitoring interval of a virtual machine from a
+tolerance on its accumulated memory deficit. Built for memory ballooning of KVM
+guests through libvirt; the rule is generic for any quantity whose growth rate
+is bounded.
+
+If demand grows no faster than `v` and the slack after a decision is `s`, the
+deficit over a blind gap of length `Δ` is at most `(vΔ − s)⁺² / (2v)`. The
+largest interval that keeps this below the tolerance `ε` is
+
+    Δ* = s/v + √(2ε/v)
+
+With a snapshot that is `a` seconds old (virtio-balloon statistics arrive late),
+the guarantee holds for `Δ* − a`.
+
+Русская версия: [README.ru.md](https://github.com/89605502155/desna-interval/blob/main/README.ru.md).
+Documentation: [English](https://github.com/89605502155/desna-interval/tree/main/docs/en) ·
+[Русский](https://github.com/89605502155/desna-interval/tree/main/docs/ru) ·
+[Changelog](https://github.com/89605502155/desna-interval/blob/main/CHANGELOG.md) ·
+[Issues](https://github.com/89605502155/desna-interval/issues)
+
+The library accompanies article 1 of the series by Andrey Ferubko, Bryansk State
+Engineering-Technological University (BGITU). Theory:
+[docs/en/theory.md](https://github.com/89605502155/desna-interval/blob/main/docs/en/theory.md).
+
+## Installation
+
+```sh
+pip install desna-interval                # core: numpy only
+pip install "desna-interval[libvirt]"     # live loop on a KVM host
+```
+
+Requires Python 3.11 or newer.
+
+## Quick start
+
+```python
+from desna_interval import MonitorScheduler, WindowQuantile, next_interval_aged
+
+next_interval_aged(s=256, v=128, eps=128, age=0.0)  # -> 3.414 s, fresh snapshot
+next_interval_aged(s=256, v=128, eps=128, age=1.0)  # -> 2.414 s, snapshot 1 s old
+
+sched = MonitorScheduler(["vm1", "vm2"], eps=128, estimator_factory=WindowQuantile)
+sched.observe(now=0.0, demand={"vm1": 1000, "vm2": 3000}, slack={"vm1": 256, "vm2": 64})
+```
+
+Command line:
+
+    desna-interval interval --slack 256 --rate 128 --eps 128 --age 1
+    desna-interval optimal  --slack 0 --rate 128 --rho 0.01 --cost 64
+    desna-interval replay trace.csv --eps 64 --slack 256
+
+## How it differs from existing packages
+
+Packages on PyPI that poll or sample adaptively, such as `python-adaptive`,
+choose sample points to reduce the error of a function or a metric. Retry
+packages such as `backoff` and `tenacity` implement back-off for failed calls,
+and scheduling packages such as `APScheduler` only run jobs at given times.
+None of them maps a tolerance on a resource deficit to a polling interval.
+
+| Feature | desna-interval | generic adaptive sampling / polling packages |
+|---|---|---|
+| Interval from a tolerance on accumulated deficit, `Δ* = s/v + √(2ε/v)` | yes | no, they target metric or function error |
+| Correction for the age of a late snapshot | yes | no |
+| Expected-cost optimum for a known burst rate and poll price | yes | no |
+| Bound on the growth rate from history, pooled over similar guests, or from a Kalman filter | yes | no |
+| Live loop for libvirt guests (`memoryStats`, balloon targets) | yes | no |
+| Replay of policies on a trace with the deficit as the metric | yes | no |
+
+The rule is only as good as the bound `v`: see the theory document for when
+it holds and when it does not.
+
+## When it helps and when it does not
+
+The rule bounds the deficit of each blind gap. The gain over a constant interval
+depends on the workload:
+
+- For identical machines with memoryless bursts no adaptive schedule beats a
+  constant interval with the same poll budget (claim 1.4, Jensen). The library does not
+  pretend otherwise.
+- The gain comes from differences between machines, and the rule states a bound on
+  the deficit of each gap, which generic back-off does not.
+- The guarantee is only as good as the bound on `v`. Use a long-history quantile
+  or a pooled bound for similar machines.
+
+The comparison of the strategies (synthetic traces now, testbed traces for the
+article) is the experiment E2 in [experiments/README.md](experiments/README.md).
+Synthetic results show behaviour only.
+
+## Authors
+
+- Andrey Ferubko (Андрей Ферубко), ORCID [0009-0006-5625-137X](https://orcid.org/0009-0006-5625-137X)
+- Oleg Kazakov (Олег Дмитриевич Казаков), ORCID [0000-0001-9665-8138](https://orcid.org/0000-0001-9665-8138)
+
+Bryansk State Engineering-Technological University (BGITU).
+
+## Modules
+
+| Module | Contents |
+|---|---|
+| `rule` | `blind_deficit_bound`, `interval_unclipped`, `next_interval`, `next_interval_aged`, `min_slack`, `expected_cost_rate`, `optimal_interval_expected` |
+| `estimators` | bounds on `v`: `history_quantile`, `pooled_quantile`, `WindowQuantile`, `FixedRate`, `KalmanRate`, `RateFilterAdapter`; `burst_rate` |
+| `scheduler` | `MonitorScheduler`, one interval per object or a common one; the `IntervalScheduler` protocol for other schedules |
+| `replay` | `replay` and the policies `FixedPolicy`, `BackoffPolicy`, `DeficitRulePolicy`, `ExpectedCostPolicy` |
+| `libvirt_loop` | `run` (optional `scheduler`), `read_state`, `reserve_controller`: the live loop |
+
+## Development
+
+```sh
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv run pytest
+bash scripts/install_hooks.sh   # once per clone: commit message limits
+```
+
+The experiments of article 1 need the optional group `experiments` (matplotlib):
+`uv sync --group experiments`. Their smoke modes run in `pytest`; the full runs are
+described in [experiments/README.md](experiments/README.md).
+
+Commit messages in this repository have a subject of at most 8 characters and
+no body. The `commit-msg` hook installed by `scripts/install_hooks.sh` enforces it
+(`scripts/check_commit_msg.py`). There is no CI and no automatic publishing.
+
+## Citation
+
+See [CITATION.cff](https://github.com/89605502155/desna-interval/blob/main/CITATION.cff)
+or the "Cite this repository" button on GitHub.
+
+## License
+
+MIT. Copyright (c) 2026 Andrey Ferubko, Oleg Kazakov. See [LICENSE](https://github.com/89605502155/desna-interval/blob/main/LICENSE).

desna_interval-0.0.1/README.md

@@ -0,0 +1,139 @@
+# desna-interval
+
+[![PyPI](https://img.shields.io/pypi/v/desna-interval.svg)](https://pypi.org/project/desna-interval/)
+[![Python](https://img.shields.io/pypi/pyversions/desna-interval.svg)](https://pypi.org/project/desna-interval/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/89605502155/desna-interval/blob/main/LICENSE)
+
+**How often to poll a resource so that the deficit accumulated between two polls stays below a tolerance.**
+
+desna-interval chooses the monitoring interval of a virtual machine from a
+tolerance on its accumulated memory deficit. Built for memory ballooning of KVM
+guests through libvirt; the rule is generic for any quantity whose growth rate
+is bounded.
+
+If demand grows no faster than `v` and the slack after a decision is `s`, the
+deficit over a blind gap of length `Δ` is at most `(vΔ − s)⁺² / (2v)`. The
+largest interval that keeps this below the tolerance `ε` is
+
+    Δ* = s/v + √(2ε/v)
+
+With a snapshot that is `a` seconds old (virtio-balloon statistics arrive late),
+the guarantee holds for `Δ* − a`.
+
+Русская версия: [README.ru.md](https://github.com/89605502155/desna-interval/blob/main/README.ru.md).
+Documentation: [English](https://github.com/89605502155/desna-interval/tree/main/docs/en) ·
+[Русский](https://github.com/89605502155/desna-interval/tree/main/docs/ru) ·
+[Changelog](https://github.com/89605502155/desna-interval/blob/main/CHANGELOG.md) ·
+[Issues](https://github.com/89605502155/desna-interval/issues)
+
+The library accompanies article 1 of the series by Andrey Ferubko, Bryansk State
+Engineering-Technological University (BGITU). Theory:
+[docs/en/theory.md](https://github.com/89605502155/desna-interval/blob/main/docs/en/theory.md).
+
+## Installation
+
+```sh
+pip install desna-interval                # core: numpy only
+pip install "desna-interval[libvirt]"     # live loop on a KVM host
+```
+
+Requires Python 3.11 or newer.
+
+## Quick start
+
+```python
+from desna_interval import MonitorScheduler, WindowQuantile, next_interval_aged
+
+next_interval_aged(s=256, v=128, eps=128, age=0.0)  # -> 3.414 s, fresh snapshot
+next_interval_aged(s=256, v=128, eps=128, age=1.0)  # -> 2.414 s, snapshot 1 s old
+
+sched = MonitorScheduler(["vm1", "vm2"], eps=128, estimator_factory=WindowQuantile)
+sched.observe(now=0.0, demand={"vm1": 1000, "vm2": 3000}, slack={"vm1": 256, "vm2": 64})
+```
+
+Command line:
+
+    desna-interval interval --slack 256 --rate 128 --eps 128 --age 1
+    desna-interval optimal  --slack 0 --rate 128 --rho 0.01 --cost 64
+    desna-interval replay trace.csv --eps 64 --slack 256
+
+## How it differs from existing packages
+
+Packages on PyPI that poll or sample adaptively, such as `python-adaptive`,
+choose sample points to reduce the error of a function or a metric. Retry
+packages such as `backoff` and `tenacity` implement back-off for failed calls,
+and scheduling packages such as `APScheduler` only run jobs at given times.
+None of them maps a tolerance on a resource deficit to a polling interval.
+
+| Feature | desna-interval | generic adaptive sampling / polling packages |
+|---|---|---|
+| Interval from a tolerance on accumulated deficit, `Δ* = s/v + √(2ε/v)` | yes | no, they target metric or function error |
+| Correction for the age of a late snapshot | yes | no |
+| Expected-cost optimum for a known burst rate and poll price | yes | no |
+| Bound on the growth rate from history, pooled over similar guests, or from a Kalman filter | yes | no |
+| Live loop for libvirt guests (`memoryStats`, balloon targets) | yes | no |
+| Replay of policies on a trace with the deficit as the metric | yes | no |
+
+The rule is only as good as the bound `v`: see the theory document for when
+it holds and when it does not.
+
+## When it helps and when it does not
+
+The rule bounds the deficit of each blind gap. The gain over a constant interval
+depends on the workload:
+
+- For identical machines with memoryless bursts no adaptive schedule beats a
+  constant interval with the same poll budget (claim 1.4, Jensen). The library does not
+  pretend otherwise.
+- The gain comes from differences between machines, and the rule states a bound on
+  the deficit of each gap, which generic back-off does not.
+- The guarantee is only as good as the bound on `v`. Use a long-history quantile
+  or a pooled bound for similar machines.
+
+The comparison of the strategies (synthetic traces now, testbed traces for the
+article) is the experiment E2 in [experiments/README.md](experiments/README.md).
+Synthetic results show behaviour only.
+
+## Authors
+
+- Andrey Ferubko (Андрей Ферубко), ORCID [0009-0006-5625-137X](https://orcid.org/0009-0006-5625-137X)
+- Oleg Kazakov (Олег Дмитриевич Казаков), ORCID [0000-0001-9665-8138](https://orcid.org/0000-0001-9665-8138)
+
+Bryansk State Engineering-Technological University (BGITU).
+
+## Modules
+
+| Module | Contents |
+|---|---|
+| `rule` | `blind_deficit_bound`, `interval_unclipped`, `next_interval`, `next_interval_aged`, `min_slack`, `expected_cost_rate`, `optimal_interval_expected` |
+| `estimators` | bounds on `v`: `history_quantile`, `pooled_quantile`, `WindowQuantile`, `FixedRate`, `KalmanRate`, `RateFilterAdapter`; `burst_rate` |
+| `scheduler` | `MonitorScheduler`, one interval per object or a common one; the `IntervalScheduler` protocol for other schedules |
+| `replay` | `replay` and the policies `FixedPolicy`, `BackoffPolicy`, `DeficitRulePolicy`, `ExpectedCostPolicy` |
+| `libvirt_loop` | `run` (optional `scheduler`), `read_state`, `reserve_controller`: the live loop |
+
+## Development
+
+```sh
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv run pytest
+bash scripts/install_hooks.sh   # once per clone: commit message limits
+```
+
+The experiments of article 1 need the optional group `experiments` (matplotlib):
+`uv sync --group experiments`. Their smoke modes run in `pytest`; the full runs are
+described in [experiments/README.md](experiments/README.md).
+
+Commit messages in this repository have a subject of at most 8 characters and
+no body. The `commit-msg` hook installed by `scripts/install_hooks.sh` enforces it
+(`scripts/check_commit_msg.py`). There is no CI and no automatic publishing.
+
+## Citation
+
+See [CITATION.cff](https://github.com/89605502155/desna-interval/blob/main/CITATION.cff)
+or the "Cite this repository" button on GitHub.
+
+## License
+
+MIT. Copyright (c) 2026 Andrey Ferubko, Oleg Kazakov. See [LICENSE](https://github.com/89605502155/desna-interval/blob/main/LICENSE).

desna_interval-0.0.1/README.ru.md

@@ -0,0 +1,138 @@
+# desna-interval
+
+[![PyPI](https://img.shields.io/pypi/v/desna-interval.svg)](https://pypi.org/project/desna-interval/)
+[![Python](https://img.shields.io/pypi/pyversions/desna-interval.svg)](https://pypi.org/project/desna-interval/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/89605502155/desna-interval/blob/main/LICENSE)
+
+**Как часто опрашивать ресурс, чтобы накопленный между опросами дефицит оставался ниже допуска.**
+
+desna-interval выбирает интервал мониторинга виртуальной машины по допуску на
+накопленный дефицит памяти. Создан для баллонирования памяти ВМ KVM через libvirt;
+правило общее для любой величины с ограниченной скоростью роста.
+
+Если потребность растёт не быстрее `v`, а запас после решения равен `s`, то дефицит
+за слепой промежуток длины `Δ` не превышает `(vΔ − s)⁺² / (2v)`. Наибольший интервал,
+при котором дефицит остаётся ниже допуска `ε`, равен
+
+    Δ* = s/v + √(2ε/v)
+
+Если снимок статистики старше на `a` секунд (статистика virtio-balloon приходит с
+опозданием), гарантия сохраняется для интервала `Δ* − a`.
+
+English version: [README.md](https://github.com/89605502155/desna-interval/blob/main/README.md).
+Документация: [English](https://github.com/89605502155/desna-interval/tree/main/docs/en) ·
+[Русский](https://github.com/89605502155/desna-interval/tree/main/docs/ru) ·
+[Журнал изменений](https://github.com/89605502155/desna-interval/blob/main/CHANGELOG.md) ·
+[Задачи](https://github.com/89605502155/desna-interval/issues)
+
+Библиотека сопровождает статью 1 серии А. Ферубко, Брянский государственный
+инженерно-технологический университет (БГИТУ). Теория:
+[docs/ru/theory.md](https://github.com/89605502155/desna-interval/blob/main/docs/ru/theory.md).
+
+## Установка
+
+```sh
+pip install desna-interval                # ядро: только numpy
+pip install "desna-interval[libvirt]"     # живой цикл на хосте KVM
+```
+
+Нужен Python 3.11 или новее.
+
+## Быстрый старт
+
+```python
+from desna_interval import MonitorScheduler, WindowQuantile, next_interval_aged
+
+next_interval_aged(s=256, v=128, eps=128, age=0.0)  # -> 3.414 с, свежий снимок
+next_interval_aged(s=256, v=128, eps=128, age=1.0)  # -> 2.414 с, снимок старше на 1 с
+
+sched = MonitorScheduler(["vm1", "vm2"], eps=128, estimator_factory=WindowQuantile)
+sched.observe(now=0.0, demand={"vm1": 1000, "vm2": 3000}, slack={"vm1": 256, "vm2": 64})
+```
+
+Командная строка:
+
+    desna-interval interval --slack 256 --rate 128 --eps 128 --age 1
+    desna-interval optimal  --slack 0 --rate 128 --rho 0.01 --cost 64
+    desna-interval replay trace.csv --eps 64 --slack 256
+
+## Отличия от существующих пакетов
+
+Пакеты на PyPI, которые адаптивно опрашивают или выбирают точки выборки, например
+`python-adaptive`, подбирают точки так, чтобы уменьшить ошибку функции или метрики.
+Пакеты повторных попыток (`backoff`, `tenacity`) реализуют откат для неудачных
+вызовов, а пакеты расписаний (`APScheduler`) лишь запускают задачи в заданное время.
+Ни один из них не переводит допуск на дефицит ресурса в интервал опроса.
+
+| Возможность | desna-interval | общие пакеты адаптивной выборки и опроса |
+|---|---|---|
+| Интервал из допуска на накопленный дефицит, `Δ* = s/v + √(2ε/v)` | да | нет, они целятся в ошибку метрики или функции |
+| Поправка на возраст запаздывающего снимка | да | нет |
+| Оптимум ожидаемых затрат при известной интенсивности всплесков и цене опроса | да | нет |
+| Граница скорости роста по истории, по группе однотипных ВМ или фильтром Калмана | да | нет |
+| Живой цикл для ВМ libvirt (`memoryStats`, цели баллона) | да | нет |
+| Проигрывание политик на трассе с дефицитом как метрикой | да | нет |
+
+Правило работает настолько, насколько верна граница `v`: когда оно верно и когда нет,
+описано в теории.
+
+## Когда это помогает и когда нет
+
+Правило ограничивает дефицит каждого слепого промежутка. Выигрыш перед постоянным
+интервалом зависит от нагрузки:
+
+- Для одинаковых машин со всплесками без памяти никакой адаптивный график не лучше
+  постоянного интервала при том же бюджете опросов (утверждение 1.4, Йенсен). Библиотека
+  этого не скрывает.
+- Выигрыш даёт различие между машинами, а правило задаёт границу дефицита каждого
+  промежутка, чего нет у общего отката.
+- Гарантия не лучше границы `v`. Для однотипных машин берите квантиль по длинной
+  истории или общую оценку.
+
+Сравнение стратегий (сейчас на синтетике, для статьи — на трассах стенда) — это
+эксперимент E2 в [experiments/README.ru.md](experiments/README.ru.md). Синтетические
+результаты показывают поведение, а не измерения.
+
+## Авторы
+
+- Андрей Ферубко (Andrey Ferubko), ORCID [0009-0006-5625-137X](https://orcid.org/0009-0006-5625-137X)
+- Олег Дмитриевич Казаков (Oleg Kazakov), ORCID [0000-0001-9665-8138](https://orcid.org/0000-0001-9665-8138)
+
+Брянский государственный инженерно-технологический университет (БГИТУ).
+
+## Модули
+
+| Модуль | Содержимое |
+|---|---|
+| `rule` | `blind_deficit_bound`, `interval_unclipped`, `next_interval`, `next_interval_aged`, `min_slack`, `expected_cost_rate`, `optimal_interval_expected` |
+| `estimators` | границы `v`: `history_quantile`, `pooled_quantile`, `WindowQuantile`, `FixedRate`, `KalmanRate`, `RateFilterAdapter`; `burst_rate` |
+| `scheduler` | `MonitorScheduler`: интервал у каждой ВМ или общий; протокол `IntervalScheduler` для других расписаний |
+| `replay` | `replay` и политики `FixedPolicy`, `BackoffPolicy`, `DeficitRulePolicy`, `ExpectedCostPolicy` |
+| `libvirt_loop` | `run` (необязательный `scheduler`), `read_state`, `reserve_controller`: живой цикл |
+
+## Разработка
+
+```sh
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv run pytest
+bash scripts/install_hooks.sh   # один раз в клоне: ограничения сообщений коммитов
+```
+
+Эксперименты статьи 1 требуют необязательную группу `experiments` (matplotlib):
+`uv sync --group experiments`. Их режимы `--smoke` выполняются в `pytest`; полные
+прогоны описаны в [experiments/README.ru.md](experiments/README.ru.md).
+
+Сообщения коммитов в этом репозитории: тема не длиннее 8 символов, тела нет.
+Хук `commit-msg`, который ставит `scripts/install_hooks.sh`, проверяет это правило
+(`scripts/check_commit_msg.py`). CI и автоматической публикации нет.
+
+## Цитирование
+
+См. [CITATION.cff](https://github.com/89605502155/desna-interval/blob/main/CITATION.cff)
+или кнопку «Cite this repository» на GitHub.
+
+## Лицензия
+
+MIT. Copyright (c) 2026 Andrey Ferubko, Oleg Kazakov. См. [LICENSE](https://github.com/89605502155/desna-interval/blob/main/LICENSE).

desna_interval-0.0.1/docs/en/api.md

@@ -0,0 +1,69 @@
+# API
+
+All names are re-exported from the package `desna_interval`. Units: memory in
+MiB, time in seconds, rate in MiB/s, deficit in MiB·s.
+
+## Rule (`desna_interval.rule`)
+
+| Function | Meaning |
+|---|---|
+| `blind_deficit_bound(s, v, delta)` | Upper bound on the deficit over a blind gap, claim 1.1 |
+| `interval_unclipped(s, v, eps)` | `s/v + sqrt(2 eps/v)`, claim 1.2; needs `v > 0` |
+| `next_interval(s, v, eps, dmin=1, dmax=10)` | The interval clipped to `[dmin, dmax]` |
+| `next_interval_aged(s, v, eps, age=0, dmin=1, dmax=10)` | Same, minus the snapshot age, claim 1.3 |
+| `min_slack(delta, v, eps)` | Smallest slack that admits interval `delta` |
+| `burst_deficit_integral(delta, s, v)` | `G(delta)` of claim 1.4 |
+| `expected_cost_rate(delta, s, v, rho, c)` | `(rho G(delta) + c) / delta` |
+| `optimal_interval_expected(s, v, rho, c, dmin, dmax)` | Minimiser of the expected cost, claim 1.5 |
+
+## Estimators (`desna_interval.estimators`)
+
+An online estimator has `update(t, d)` and `upper() -> float`. A filter
+(`RateFilter`) has `update(t, d)` and `rate() -> (rate, variance)`.
+
+| Name | Meaning |
+|---|---|
+| `WindowQuantile(window=300, q=1, v_floor=2)` | Quantile of growth over the last `window` seconds |
+| `FixedRate(v)` | Constant bound, e.g. from `history_quantile` |
+| `KalmanRate(q=1, r=25)` | Scalar Kalman filter of level and growth rate |
+| `RateFilterAdapter(filt, z=2.33, v_floor=2)` | `rate + z·sqrt(variance)` of any `RateFilter` |
+| `growth_rates(t, d, step=1)` | Non-negative growth rates on a regular grid |
+| `history_quantile(t, d, q=0.99, step=1, v_floor=2)` | Robust bound from one history |
+| `pooled_quantile(series, q, step, v_floor)` | Common bound over `(t, d)` pairs |
+| `per_series_quantiles(t, rows, ...)` | `history_quantile` for each row |
+| `burst_rate(t, d, step, rise, window, min_gap)` | Rate of burst onsets `rho`, 1/s |
+
+## Scheduler (`desna_interval.scheduler`)
+
+`MonitorScheduler(vms, eps, estimator_factory, dmin=1, dmax=10, mode="per_vm")`.
+
+- `due(now)`: the objects to poll now.
+- `next_wakeup()`: time of the next poll.
+- `observe(now, demand, slack, age=None)`: updates the estimators of the polled
+  objects and returns their intervals. With `mode="global"` all intervals equal
+  the smallest one.
+
+## Replay (`desna_interval.replay`)
+
+`replay(t, d, policy, slack) -> ReplayResult`. A policy has
+`next_interval(t, d) -> float`. The result has `polls`, `duration`, `deficit`,
+`gap_deficits`, `intervals`, `mean_interval` and `violation_share(eps)`.
+
+Policies: `FixedPolicy(delta)`, `BackoffPolicy(dmin, dmax, factor, threshold)`,
+`DeficitRulePolicy(eps, slack, estimator, dmin, dmax)`,
+`ExpectedCostPolicy(slack, v, rho, c, dmin, dmax)`.
+
+## Live loop (`desna_interval.libvirt_loop`)
+
+Requires `libvirt-python`; the module imports without it, so tests use fake
+domains.
+
+- `read_state(dom, reserve_mib, balloon_in_total=False, wall=time.time)`
+  returns `(allocation MiB, demand MiB, snapshot age s)`.
+- `reserve_controller(s_target=256, deadband=64)`: example controller.
+- `run(domains, controller, eps, reserve_mib, duration_s, log_path, ...)`
+  polls the domains on the schedule, applies targets when `apply=True`, writes a
+  CSV log and returns the number of polls. `adapt_stats_period=True` sets each
+  guest's statistics period to the whole part of its interval. The optional
+  `scheduler` replaces `MonitorScheduler` with any object that implements
+  `IntervalScheduler` (`due`, `next_wakeup`, `observe`), for example a heuristic.

desna_interval-0.0.1/docs/en/cli.md

@@ -0,0 +1,49 @@
+# Command line
+
+The program is `desna-interval`. Every subcommand prints one line or a table.
+
+    desna-interval --version
+
+## `interval`
+
+Interval `delta* = s/v + sqrt(2 eps/v)` minus the snapshot age, clipped.
+
+    desna-interval interval --slack 256 --rate 128 --eps 128 --age 1
+    # 2.414
+
+| Option | Meaning | Default |
+|---|---|---|
+| `--slack` | slack `s`, MiB | required |
+| `--rate` | growth bound `v`, MiB/s | required |
+| `--eps` | tolerance, MiB·s | required |
+| `--age` | snapshot age, s | 0 |
+| `--dmin`, `--dmax` | clipping bounds, s | 1, 10 |
+
+## `min-slack`
+
+Smallest slack that admits an interval.
+
+    desna-interval min-slack --delta 5 --rate 128 --eps 128
+    # 458.980664
+
+## `optimal`
+
+Interval that minimises the expected cost.
+
+    desna-interval optimal --slack 0 --rate 128 --rho 0.01 --cost 64
+    # 5.3133
+
+Options: `--slack`, `--rate`, `--rho` (burst onsets per second), `--cost` (price
+of one poll in MiB·s), `--dmin`, `--dmax`.
+
+## `replay`
+
+Compares policies on a CSV trace with the header `t,d` (time in s, demand in MiB).
+
+    desna-interval replay trace.csv --eps 64 --slack 256
+
+Prints the bound `v` (0.99 quantile of the history), the burst rate `rho` and one
+line per policy: `policy,polls,mean_interval_s,deficit_mib_s,violation_share`.
+Options: `--eps`, `--slack`, `--fixed` (list of fixed intervals, s).
+
+Exit status is 0 on success.