deberka-jordan 0.0.1__tar.gz

deberka_jordan-0.0.1/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+## [0.0.1] — 2026-11-11
+
+First release: the reallocation plans of article 2 (A. Ferubko, O. Kazakov, BGITU). The project was
+built under the working name `jordanplan-deberka` (module `jordanplan`) and renamed to
+`deberka-jordan` (module `deberka_jordan`, command `deberka-jordan`) before publication.
+
+- `SignedMeasure` with Hahn and Jordan decompositions.
+- `jordan_plan`: least-volume plan with dead band, bounds and rationing.
+- Netting of proposal logs: `netting_report`, `netting_by_cycle`.
+- Orders and the pool invariant: `two_phase`, `recipients_first`, `shuffled`, `pairwise`.
+- Executors `execute_two_phase`, `execute_simultaneous`, simulator `RateLimitedSim`.
+- Oscillation index, `replay_reserve`, `deadband_sweep`, `choose_deadband`.
+- Optional `deberka_jordan.kvm.LibvirtBackend`, tested with fake domains.
+- Command line tool `deberka_jordan`.
+- Volume unit (default 1, bytes): `sequential_volume`, `netting_report`, `netting_by_cycle`
+  take `factor`, and `plan_volume(plan, *, factor=1.0)` is the volume of a plan. The default
+  `factor=1` counts each byte moved between two consumers once; `factor=2` gives the balloon
+  operations (a deflation at the donor and an inflation at the recipient). Must be finite and
+  positive (`ValueError`), a number (`TypeError`). The gain does not depend on it.
+- `Plan.volume` is `plan_volume(plan)` with the default `pool="max"`: `max(take, give)`, the
+  bytes moved (equal to `Plan.operations / 2` when the pool does not change).
+  `Plan.operations = Σ |ν({i})|` is the balloon-operation measure of Claim 1.
+  `lower_bound_volume` is that measure (operations).
+- Command line `plan --factor` and `net --factor` (default 1); the JSON output adds
+  `volume_factor`.
+  The `deadband` volume is not scaled: a dead-band jump is one operation on one consumer.
+- Pool term of the plan volume: `plan_volume(plan, *, factor=1.0, pool="max", pool_weight=0.5)`.
+  `pool="max"` (default) counts a byte moved into or out of the pool as a byte:
+  `factor · max(take, give)`. `pool="weighted"` gives `factor · (min(take, give) + pool_weight ·
+  |pool change|)`; `pool_weight=0.5` reproduces the balloon operations over two of earlier
+  versions. Errors: `pool` not a string (`TypeError`) or not in `("max", "weighted")`
+  (`ValueError`); `pool_weight` not a real number (`TypeError`) or not finite and
+  non-negative (`ValueError`). For a plan that does not change the pool all modes coincide.
+  `netting_report` has no pool term: its logs are transfers between consumers.
+- Command line `plan --pool-mode {max,weighted}` (default `max`) and `--pool-weight W`
+  (default 0.5); the `plan` output adds `volume_pool_mode` and `volume_pool_weight`. The
+  free pool level stays `--pool`.

deberka_jordan-0.0.1/CITATION.cff

@@ -0,0 +1,34 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+type: software
+title: "deberka-jordan: reallocation plans for a shared resource by the Hahn-Jordan decomposition"
+abstract: >-
+  A Python library for reallocation cycles of a shared resource as signed
+  measures: the Hahn and Jordan decompositions, the least-volume netting of
+  proposals, a safe two-phase order that never overdraws the pool, an executor
+  that waits for freed memory, the oscillation index and the dead-band choice
+  on demand traces, and a libvirt balloon backend for KVM virtual machines.
+version: 0.0.1
+date-released: 2026-11-11
+license: MIT
+repository-code: "https://github.com/89605502155/deberka-jordan"
+url: "https://github.com/89605502155/deberka-jordan"
+keywords:
+  - Hahn decomposition
+  - Jordan decomposition
+  - signed measure
+  - resource allocation
+  - memory ballooning
+  - KVM
+  - libvirt
+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)"

deberka_jordan-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.

deberka_jordan-0.0.1/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: deberka-jordan
+Version: 0.0.1
+Summary: Reallocation plans for a shared resource from the Hahn-Jordan decomposition: least-volume netting, a safe two-phase order, oscillation index and dead-band choice, with a libvirt balloon backend
+Keywords: signed-measure,jordan-decomposition,hahn-decomposition,resource-allocation,netting,dead-band,memory-ballooning,kvm,libvirt,virtual-machines
+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 :: Mathematics
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Operating System Kernels :: Linux
+Classifier: Typing :: Typed
+Requires-Dist: libvirt-python>=8.0 ; extra == 'kvm'
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/89605502155/deberka-jordan
+Project-URL: Documentation, https://github.com/89605502155/deberka-jordan/tree/main/docs
+Project-URL: Repository, https://github.com/89605502155/deberka-jordan
+Project-URL: Issues, https://github.com/89605502155/deberka-jordan/issues
+Project-URL: Changelog, https://github.com/89605502155/deberka-jordan/blob/main/CHANGELOG.md
+Provides-Extra: kvm
+Description-Content-Type: text/markdown
+
+# deberka-jordan
+
+[![PyPI](https://img.shields.io/pypi/v/deberka-jordan.svg)](https://pypi.org/project/deberka-jordan/)
+[![Python](https://img.shields.io/pypi/pyversions/deberka-jordan.svg)](https://pypi.org/project/deberka-jordan/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/89605502155/deberka-jordan/blob/main/LICENSE)
+
+**Reallocation plans for a shared resource from the Hahn–Jordan decomposition.**
+
+A reallocation cycle among consumers of one pool (memory of a host, CPU quota,
+bandwidth) is a signed measure on the set "pool and consumers". deberka-jordan
+computes:
+
+* the Hahn decomposition of the cycle: donors and recipients;
+* the Jordan plan, the netting of all proposals of a cycle with the least
+  volume of operations, `W = Σ |ν({i})|`; the volume in bytes is `plan_volume`
+  (default `pool="max"`, see the theory);
+* a safe two-phase order (donors first, then recipients) that never overdraws
+  the pool, and an executor that waits for the memory actually freed;
+* the oscillation index `κ` of a controller on the time axis and a dead band `h`
+  chosen by the replay of a demand trace.
+
+The first target is KVM memory ballooning through libvirt; nothing in the core
+is specific to it.
+
+Русская версия: [README.ru.md](https://github.com/89605502155/deberka-jordan/blob/main/README.ru.md).
+Documentation: [English](https://github.com/89605502155/deberka-jordan/tree/main/docs/en) ·
+[Русский](https://github.com/89605502155/deberka-jordan/tree/main/docs/ru) ·
+[Changelog](https://github.com/89605502155/deberka-jordan/blob/main/CHANGELOG.md) ·
+[Issues](https://github.com/89605502155/deberka-jordan/issues)
+
+The library accompanies article 2 of the series by Andrey Ferubko and Oleg Kazakov,
+Bryansk State Engineering-Technological University (BGITU). Theory:
+[docs/en/theory.md](https://github.com/89605502155/deberka-jordan/blob/main/docs/en/theory.md).
+
+## Installation
+
+```sh
+pip install deberka-jordan                # core: no dependencies
+pip install "deberka-jordan[kvm]"         # plus libvirt-python for live domains
+```
+
+Requires Python 3.11 or newer.
+
+## Quick start
+
+```python
+from deberka_jordan import SignedMeasure, jordan_plan, min_pool, netting_report
+from deberka_jordan import recipients_first, two_phase
+
+nu = SignedMeasure({"a": 3.0, "b": -1.0, "c": -2.0})
+print(nu.total(), nu.total_variation())  # 0.0 6.0
+
+current = {"vm1": 2000.0, "vm2": 3000.0, "vm3": 1500.0, "vm4": 2500.0}  # MiB
+target = {"vm1": 2600.0, "vm2": 2500.0, "vm3": 1530.0, "vm4": 2100.0}
+plan = jordan_plan(current, target, pool_free=100.0, deadband=64.0)
+print(plan.volume)  # 900.0 MiB: 600 between consumers + 300 into the pool (pool="max")
+print(min_pool(two_phase(plan), 100.0))  # 100.0: the pool never goes below its start
+print(min_pool(recipients_first(plan), 100.0))  # -500.0: the wrong order overdraws it
+
+report = netting_report([("vm1", "vm2", 300.0), ("vm2", "vm3", 300.0), ("vm3", "vm1", 100.0)])
+print(report.sequential_volume, report.jordan_volume)  # 700.0 200.0 (bytes)
+```
+
+Command line, on a state file with the columns `consumer,current,target`:
+
+    deberka-jordan plan state.csv --pool 100 --deadband 64
+    deberka-jordan net proposals.csv --out netting.csv
+    deberka-jordan deadband trace.csv --h 0,64,128 --reserve 256
+
+## How it differs from existing packages
+
+The Hahn and Jordan decompositions are classical measure theory (Halmos, §28–29).
+PyPI has packages for matrices and for topological data analysis that carry the
+same names, and none of them does what this library does:
+
+* `jordan-form` computes the Jordan normal form of a matrix, a different object;
+* `multipers` works with persistence modules in topological data analysis.
+
+Packages for resource allocation (quota schedulers, job placement) pick targets,
+they do not net a cycle of proposals into the least volume of operations, and
+they do not give a safe order of operations for a pool.
+
+| Feature | deberka-jordan | `jordan-form`, `multipers`, allocation schedulers |
+|---|---|---|
+| Hahn and Jordan decompositions of a finite signed measure on consumers and a pool | yes | no |
+| Least-volume netting of a cycle, `W = Σ |ν({i})|`, with the sequential baseline | yes | no |
+| Safe two-phase order that never overdraws the pool, with an executor that waits for freed memory | yes | no |
+| Oscillation index `κ` and dead band `h` chosen on a demand trace | yes | no |
+| Libvirt balloon backend (optional) | yes | no |
+
+## Modules
+
+| Module | Contents |
+|---|---|
+| `measure` | `SignedMeasure`, `HahnDecomposition`, `JordanDecomposition` |
+| `plan` | `jordan_plan`, `Plan`, `ration`, netting: `netting_report`, `netting_by_cycle` |
+| `order` | `two_phase`, `recipients_first`, `shuffled`, `pairwise`, `min_pool`, `is_safe` |
+| `execute` | `execute_two_phase`, `execute_simultaneous`, `RateLimitedSim` |
+| `churn` | `kappa`, `replay_reserve`, `deadband_sweep`, `choose_deadband`, `cycles_bound` |
+| `kvm` | `LibvirtBackend`, `host_mem_available` (optional, needs libvirt-python) |
+
+## When it helps
+
+The numbers of the article are measured on the testbed and are not in this
+package. The examples show the mechanisms on small inputs:
+`examples/02_netting_log.py` (a ring of proposals nets 74 % of the volume, a
+fan-out does not net at all) and `examples/03_two_phase_fake.py` (the executor
+moves memory in the safe order).
+
+## 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
+```
+
+Commit messages in this repository have a subject of at most 8 characters and no
+body. The hook is installed by `scripts/install_hooks.sh` and runs
+`scripts/check_commit_msg.py`.
+
+## Citation
+
+See [CITATION.cff](https://github.com/89605502155/deberka-jordan/blob/main/CITATION.cff)
+or the "Cite this repository" button on GitHub.
+
+## 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).
+
+## License
+
+MIT. Copyright (c) 2026 Andrey Ferubko, Oleg Kazakov. See [LICENSE](https://github.com/89605502155/deberka-jordan/blob/main/LICENSE).

deberka_jordan-0.0.1/README.md

@@ -0,0 +1,138 @@
+# deberka-jordan
+
+[![PyPI](https://img.shields.io/pypi/v/deberka-jordan.svg)](https://pypi.org/project/deberka-jordan/)
+[![Python](https://img.shields.io/pypi/pyversions/deberka-jordan.svg)](https://pypi.org/project/deberka-jordan/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/89605502155/deberka-jordan/blob/main/LICENSE)
+
+**Reallocation plans for a shared resource from the Hahn–Jordan decomposition.**
+
+A reallocation cycle among consumers of one pool (memory of a host, CPU quota,
+bandwidth) is a signed measure on the set "pool and consumers". deberka-jordan
+computes:
+
+* the Hahn decomposition of the cycle: donors and recipients;
+* the Jordan plan, the netting of all proposals of a cycle with the least
+  volume of operations, `W = Σ |ν({i})|`; the volume in bytes is `plan_volume`
+  (default `pool="max"`, see the theory);
+* a safe two-phase order (donors first, then recipients) that never overdraws
+  the pool, and an executor that waits for the memory actually freed;
+* the oscillation index `κ` of a controller on the time axis and a dead band `h`
+  chosen by the replay of a demand trace.
+
+The first target is KVM memory ballooning through libvirt; nothing in the core
+is specific to it.
+
+Русская версия: [README.ru.md](https://github.com/89605502155/deberka-jordan/blob/main/README.ru.md).
+Documentation: [English](https://github.com/89605502155/deberka-jordan/tree/main/docs/en) ·
+[Русский](https://github.com/89605502155/deberka-jordan/tree/main/docs/ru) ·
+[Changelog](https://github.com/89605502155/deberka-jordan/blob/main/CHANGELOG.md) ·
+[Issues](https://github.com/89605502155/deberka-jordan/issues)
+
+The library accompanies article 2 of the series by Andrey Ferubko and Oleg Kazakov,
+Bryansk State Engineering-Technological University (BGITU). Theory:
+[docs/en/theory.md](https://github.com/89605502155/deberka-jordan/blob/main/docs/en/theory.md).
+
+## Installation
+
+```sh
+pip install deberka-jordan                # core: no dependencies
+pip install "deberka-jordan[kvm]"         # plus libvirt-python for live domains
+```
+
+Requires Python 3.11 or newer.
+
+## Quick start
+
+```python
+from deberka_jordan import SignedMeasure, jordan_plan, min_pool, netting_report
+from deberka_jordan import recipients_first, two_phase
+
+nu = SignedMeasure({"a": 3.0, "b": -1.0, "c": -2.0})
+print(nu.total(), nu.total_variation())  # 0.0 6.0
+
+current = {"vm1": 2000.0, "vm2": 3000.0, "vm3": 1500.0, "vm4": 2500.0}  # MiB
+target = {"vm1": 2600.0, "vm2": 2500.0, "vm3": 1530.0, "vm4": 2100.0}
+plan = jordan_plan(current, target, pool_free=100.0, deadband=64.0)
+print(plan.volume)  # 900.0 MiB: 600 between consumers + 300 into the pool (pool="max")
+print(min_pool(two_phase(plan), 100.0))  # 100.0: the pool never goes below its start
+print(min_pool(recipients_first(plan), 100.0))  # -500.0: the wrong order overdraws it
+
+report = netting_report([("vm1", "vm2", 300.0), ("vm2", "vm3", 300.0), ("vm3", "vm1", 100.0)])
+print(report.sequential_volume, report.jordan_volume)  # 700.0 200.0 (bytes)
+```
+
+Command line, on a state file with the columns `consumer,current,target`:
+
+    deberka-jordan plan state.csv --pool 100 --deadband 64
+    deberka-jordan net proposals.csv --out netting.csv
+    deberka-jordan deadband trace.csv --h 0,64,128 --reserve 256
+
+## How it differs from existing packages
+
+The Hahn and Jordan decompositions are classical measure theory (Halmos, §28–29).
+PyPI has packages for matrices and for topological data analysis that carry the
+same names, and none of them does what this library does:
+
+* `jordan-form` computes the Jordan normal form of a matrix, a different object;
+* `multipers` works with persistence modules in topological data analysis.
+
+Packages for resource allocation (quota schedulers, job placement) pick targets,
+they do not net a cycle of proposals into the least volume of operations, and
+they do not give a safe order of operations for a pool.
+
+| Feature | deberka-jordan | `jordan-form`, `multipers`, allocation schedulers |
+|---|---|---|
+| Hahn and Jordan decompositions of a finite signed measure on consumers and a pool | yes | no |
+| Least-volume netting of a cycle, `W = Σ |ν({i})|`, with the sequential baseline | yes | no |
+| Safe two-phase order that never overdraws the pool, with an executor that waits for freed memory | yes | no |
+| Oscillation index `κ` and dead band `h` chosen on a demand trace | yes | no |
+| Libvirt balloon backend (optional) | yes | no |
+
+## Modules
+
+| Module | Contents |
+|---|---|
+| `measure` | `SignedMeasure`, `HahnDecomposition`, `JordanDecomposition` |
+| `plan` | `jordan_plan`, `Plan`, `ration`, netting: `netting_report`, `netting_by_cycle` |
+| `order` | `two_phase`, `recipients_first`, `shuffled`, `pairwise`, `min_pool`, `is_safe` |
+| `execute` | `execute_two_phase`, `execute_simultaneous`, `RateLimitedSim` |
+| `churn` | `kappa`, `replay_reserve`, `deadband_sweep`, `choose_deadband`, `cycles_bound` |
+| `kvm` | `LibvirtBackend`, `host_mem_available` (optional, needs libvirt-python) |
+
+## When it helps
+
+The numbers of the article are measured on the testbed and are not in this
+package. The examples show the mechanisms on small inputs:
+`examples/02_netting_log.py` (a ring of proposals nets 74 % of the volume, a
+fan-out does not net at all) and `examples/03_two_phase_fake.py` (the executor
+moves memory in the safe order).
+
+## 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
+```
+
+Commit messages in this repository have a subject of at most 8 characters and no
+body. The hook is installed by `scripts/install_hooks.sh` and runs
+`scripts/check_commit_msg.py`.
+
+## Citation
+
+See [CITATION.cff](https://github.com/89605502155/deberka-jordan/blob/main/CITATION.cff)
+or the "Cite this repository" button on GitHub.
+
+## 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).
+
+## License
+
+MIT. Copyright (c) 2026 Andrey Ferubko, Oleg Kazakov. See [LICENSE](https://github.com/89605502155/deberka-jordan/blob/main/LICENSE).

deberka_jordan-0.0.1/README.ru.md

@@ -0,0 +1,136 @@
+# deberka-jordan
+
+[![PyPI](https://img.shields.io/pypi/v/deberka-jordan.svg)](https://pypi.org/project/deberka-jordan/)
+[![Python](https://img.shields.io/pypi/pyversions/deberka-jordan.svg)](https://pypi.org/project/deberka-jordan/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/89605502155/deberka-jordan/blob/main/LICENSE)
+
+**Планы перераспределения общего ресурса на основе разложения Хана–Жордана.**
+
+Цикл перераспределения между потребителями одного пула (память хоста, квота CPU,
+полоса) — это знакопеременная мера на множестве «пул и потребители».
+deberka-jordan вычисляет:
+
+* разложение Хана цикла: доноры и получатели;
+* план Жордана: взаимозачёт всех предложений цикла с наименьшим объёмом операций,
+  `W = Σ |ν({i})|`; объём в байтах даёт `plan_volume` (по умолчанию `pool="max"`,
+  см. теорию);
+* безопасный двухфазный порядок (сначала доноры, затем получатели), который не
+  уводит пул в минус, и исполнитель, который ждёт фактически освобождённой памяти;
+* индекс колебаний `κ` контроллера на оси времени и порог нечувствительности `h`,
+  выбранный проигрыванием трассы потребности.
+
+Первая цель — баллонирование памяти ВМ KVM через libvirt; ядро библиотеки от неё
+не зависит.
+
+English version: [README.md](https://github.com/89605502155/deberka-jordan/blob/main/README.md).
+Документация: [English](https://github.com/89605502155/deberka-jordan/tree/main/docs/en) ·
+[Русский](https://github.com/89605502155/deberka-jordan/tree/main/docs/ru) ·
+[Журнал изменений](https://github.com/89605502155/deberka-jordan/blob/main/CHANGELOG.md) ·
+[Задачи](https://github.com/89605502155/deberka-jordan/issues)
+
+Библиотека сопровождает статью 2 серии А. Ферубко и О. Д. Казакова, Брянский государственный
+инженерно-технологический университет (БГИТУ). Теория:
+[docs/ru/theory.md](https://github.com/89605502155/deberka-jordan/blob/main/docs/ru/theory.md).
+
+## Установка
+
+```sh
+pip install deberka-jordan                # ядро: без зависимостей
+pip install "deberka-jordan[kvm]"         # плюс libvirt-python для живых доменов
+```
+
+Нужен Python 3.11 или новее.
+
+## Быстрый старт
+
+```python
+from deberka_jordan import SignedMeasure, jordan_plan, min_pool, netting_report
+from deberka_jordan import recipients_first, two_phase
+
+nu = SignedMeasure({"a": 3.0, "b": -1.0, "c": -2.0})
+print(nu.total(), nu.total_variation())  # 0.0 6.0
+
+current = {"vm1": 2000.0, "vm2": 3000.0, "vm3": 1500.0, "vm4": 2500.0}  # МиБ
+target = {"vm1": 2600.0, "vm2": 2500.0, "vm3": 1530.0, "vm4": 2100.0}
+plan = jordan_plan(current, target, pool_free=100.0, deadband=64.0)
+print(plan.volume)  # 900.0 МиБ: 600 между потребителями + 300 в пул (pool="max")
+print(min_pool(two_phase(plan), 100.0))  # 100.0: безопасный порядок, пул не ниже старта
+print(min_pool(recipients_first(plan), 100.0))  # -500.0: неверный порядок уводит пул в минус
+
+report = netting_report([("vm1", "vm2", 300.0), ("vm2", "vm3", 300.0), ("vm3", "vm1", 100.0)])
+print(report.sequential_volume, report.jordan_volume)  # 700.0 200.0 (байты)
+```
+
+Командная строка, на файле состояния с колонками `consumer,current,target`:
+
+    deberka-jordan plan state.csv --pool 100 --deadband 64
+    deberka-jordan net proposals.csv --out netting.csv
+    deberka-jordan deadband trace.csv --h 0,64,128 --reserve 256
+
+## Отличия от существующих пакетов
+
+Разложения Хана и Жордана — классическая теория меры (Халмош, §28–29). На PyPI есть
+пакеты с такими же названиями для матриц и топологического анализа данных, и ни один
+из них не делает того, что делает эта библиотека:
+
+* `jordan-form` вычисляет жорданову форму матрицы, это другой объект;
+* `multipers` работает с персистентными модулями в топологическом анализе данных.
+
+Пакеты распределения ресурсов (планировщики квот, размещение задач) выбирают цели,
+но не сворачивают цикл предложений к наименьшему объёму операций и не дают безопасного
+порядка операций для пула.
+
+| Возможность | deberka-jordan | `jordan-form`, `multipers`, планировщики распределения |
+|---|---|---|
+| Разложения Хана и Жордана конечной знакопеременной меры на потребителях и пуле | да | нет |
+| Взаимозачёт цикла с наименьшим объёмом `W = Σ |ν({i})|` и базой «поочерёдно» | да | нет |
+| Безопасный двухфазный порядок без уходящего в минус пула, исполнитель ждёт освобождения памяти | да | нет |
+| Индекс колебаний `κ` и порог нечувствительности `h`, выбранный на трассе потребности | да | нет |
+| Бэкенд баллона libvirt (необязательный) | да | нет |
+
+## Модули
+
+| Модуль | Содержимое |
+|---|---|
+| `measure` | `SignedMeasure`, `HahnDecomposition`, `JordanDecomposition` |
+| `plan` | `jordan_plan`, `Plan`, `ration`, взаимозачёт: `netting_report`, `netting_by_cycle` |
+| `order` | `two_phase`, `recipients_first`, `shuffled`, `pairwise`, `min_pool`, `is_safe` |
+| `execute` | `execute_two_phase`, `execute_simultaneous`, `RateLimitedSim` |
+| `churn` | `kappa`, `replay_reserve`, `deadband_sweep`, `choose_deadband`, `cycles_bound` |
+| `kvm` | `LibvirtBackend`, `host_mem_available` (необязательный, нужен libvirt-python) |
+
+## Когда это помогает
+
+Числа статьи получены на стенде и в этот пакет не входят. Примеры показывают механизмы
+на небольших входах: `examples/02_netting_log.py` (кольцо предложений даёт взаимозачёт
+74 % объёма, веер предложений не сворачивается совсем) и `examples/03_two_phase_fake.py`
+(исполнитель переносит память в безопасном порядке).
+
+## Разработка
+
+```sh
+uv sync
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+uv run pytest
+bash scripts/install_hooks.sh   # один раз в клоне: ограничения сообщений коммитов
+```
+
+Сообщения коммитов в этом репозитории: тема не длиннее 8 символов, тела нет. Хук ставит
+`scripts/install_hooks.sh` и запускает `scripts/check_commit_msg.py`.
+
+## Цитирование
+
+См. [CITATION.cff](https://github.com/89605502155/deberka-jordan/blob/main/CITATION.cff)
+или кнопку «Cite this repository» на GitHub.
+
+## Авторы
+
+- Ферубко Андрей, [ORCID 0009-0006-5625-137X](https://orcid.org/0009-0006-5625-137X)
+- Казаков Олег Дмитриевич, [ORCID 0000-0001-9665-8138](https://orcid.org/0000-0001-9665-8138)
+
+Брянский государственный инженерно-технологический университет (БГИТУ).
+
+## Лицензия
+
+MIT. Copyright (c) 2026 Andrey Ferubko, Oleg Kazakov. См. [LICENSE](https://github.com/89605502155/deberka-jordan/blob/main/LICENSE).

deberka_jordan-0.0.1/docs/en/api.md

@@ -0,0 +1,80 @@
+# API
+
+All names are re-exported from the package `deberka_jordan`. Units are free but
+must be consistent; the examples use MiB.
+
+## Measure (`deberka_jordan.measure`)
+
+`SignedMeasure(atoms, *, tol=0.0)` is a mapping `atom -> ν({atom})`.
+
+| Member | Meaning |
+|---|---|
+| `from_allocations(current, target, *, pool=None)` | Measure of the cycle; with `pool` the pool atom closes it |
+| `from_transfers(transfers)` | Netting: sum of `(source, recipient, amount)` per atom |
+| `nu(subset)` | `ν(A)` for a set of atoms |
+| `total()`, `total_variation()` | `ν(X)` and `|ν|(X)` |
+| `restrict(subset)`, `without(*atoms)` | Restrictions |
+| `hahn()` | `HahnDecomposition(positive, negative)` |
+| `jordan()` | `JordanDecomposition(plus, minus)`; `.variation` is `|ν|` |
+
+`POOL` is the default name of the pool atom.
+
+## Plan (`deberka_jordan.plan`)
+
+`jordan_plan(current, target, pool_free, *, deadband=0, force=(), floor=None,
+ceiling=None, priority=None) -> Plan`
+
+The plan has `donors`, `recipients`, `skipped`, `rationed`, `pool_before` and the
+properties `take`, `give`, `pool_change`, `pool_after`, `volume` (bytes, `pool="max"`), `operations` (balloon operations), `peak`,
+`is_empty`, and the methods `measure(pool)` and `targets(current)`.
+
+| Function | Meaning |
+|---|---|
+| `ration(demand, budget, priority=None)` | Split an insufficient budget, in proportion or by priority |
+| `net_transfers(transfers)` | Netted measure over consumers |
+| `sequential_volume(transfers, *, factor=1.0)` | `factor · Σ amount`; the default `factor=1` gives the bytes transferred, `factor=2` the balloon operations |
+| `lower_bound_volume(nu, pool=POOL)` | `W = Σ |ν({i})|` over consumers: balloon operations; in bytes `W / 2` |
+| `netting_report(transfers, cycle=None, *, factor=1.0)` | `NettingReport` with `ratio` and `gain`; the Jordan volume is `(factor / 2) Σ |net|`, the gain does not depend on `factor` |
+| `plan_volume(plan, *, factor=1.0, pool="max", pool_weight=0.5)` | `factor · (min(take, give) + w · |pool change|)`; `w = 1` for `pool="max"` (default, the bytes moved; `plan.volume`), `w = pool_weight` for `pool="weighted"`; `pool="weighted", pool_weight=0.5, factor=2` is `plan.operations` |
+| `netting_by_cycle(rows, *, factor=1.0)` | One report per cycle of `(cycle, source, recipient, amount)` rows |
+
+## Orders (`deberka_jordan.order`)
+
+`Op(consumer, delta)`. `two_phase(plan)` (donors first, the safe order),
+`recipients_first(plan)`, `shuffled(plan, rng=None)`, `pairwise(transfers)`,
+`pool_trajectory(ops, pool_free)`, `min_pool(ops, pool_free)`,
+`is_safe(ops, pool_free, tol=1e-9)`.
+
+## Executors (`deberka_jordan.execute`)
+
+A backend has `now()`, `get_actual(consumer)`, `set_target(consumer, target)` and
+`sleep(dt)`.
+
+* `execute_two_phase(backend, plan, current, *, priority=None, timeout_s=30,
+  poll_s=0.1, tol=1.0) -> ExecReport`
+* `execute_simultaneous(backend, plan, current, ...)`: a baseline, not safe.
+* `RateLimitedSim(actual, pool_free, take_rate=200, give_rate=800, reclaimable=None,
+  step=0.01)`: a simulated actuator with finite speed; it tracks `pool_min`.
+
+`ExecReport` has `freed`, `given`, `duration_s`, `pool_min`, `unfinished` and
+`rationed`.
+
+## Churn and dead band (`deberka_jordan.churn`)
+
+| Function | Meaning |
+|---|---|
+| `kappa(deltas)`, `WindowStats(variation, net).kappa` | Oscillation index |
+| `window_stats(times, deltas, t_now, window)`, `kappa_series(...)` | Sliding window |
+| `sampled_variation(samples)` | `V = Σ |d_k − d_{k−1}|` |
+| `cycles_bound(samples, h)` | `V / h`, the bound of claim 2.3 |
+| `replay_reserve(demand, dt, *, reserve, deadband, interval=None, theta=64, ...)` | `ReplayResult` |
+| `deadband_sweep(demand, dt, deadbands, **kwargs)` | Replay for each `h` |
+| `choose_deadband(results, kappa_target=0.5)` | Smallest `h` with median `κ` at most the target |
+
+## Live backend (`deberka_jordan.kvm`)
+
+`LibvirtBackend(domains, pool=None)`: `domains` maps names to objects with
+`memoryStats()` and `setMemoryFlags()`; `connect(uri, names=None)` opens libvirt
+(needs `libvirt-python`). `snapshot()` returns the balloon sizes in MiB,
+`pool_free()` the free host memory. `host_mem_available(path)` reads
+`MemAvailable` from `/proc/meminfo`.