Skip to main content

trosna-regime-control

PyPI Python License: MIT

Regime detection from reallocation decisions under irregular checks, scale-invariant monitoring intervals and simplex (Aitchison) memory allocation for adaptive KVM memory management.

An adaptive memory manager for virtual machines checks the demand at intervals, and moves memory by ballooning when the demand has changed. Each check leaves one decision bit: 1 if memory was moved, 0 if not. trosna-regime-control turns this stream of bits into the three things the manager needs:

  • the regime: is the decision rate stationary or changing? It uses a Shiryaev–Roberts detector with a guaranteed mean time to a false alarm, and it works with irregular, policy-dependent intervals;
  • the next interval: from a real-time estimate of the decision intensity with exponential forgetting, by the scale-invariant rules Δt = −ln(1 − p*)/λ̂ (or p*/λ̂, the linear form; λ̂ is the debiased rate, or the naive N/T with estimator="naive") and Δt = √(2C₁/(λ̂C₂)), not by a hand-made table;
  • the allocation: memory shares as points of the simplex, perturbed in the clr coordinates, with minimum and maximum bounds and a dead band δ against needless reallocations.

It also diagnoses the 5-bit heuristic that it replaces: the exact flicker rate of its regime, from a Markov chain, and a replay of both methods on a recorded log.

Russian version: README.ru.md. Documentation: English · Русский · Changelog · Issues

The library accompanies the article on Lie groups and martingales in adaptive KVM memory management by Andrey Ferubko and Oleg Kazakov, Bryansk State Engineering-Technological University (BGITU). The theory is in docs/en/theory.md.

Installation

pip install trosna-regime-control
# or, with uv
uv add trosna-regime-control

Requires Python 3.11 or newer and NumPy. The optional extra plot adds matplotlib for the experiment scripts.

Quick start

from trosna_regime_control import ControllerConfig, RegimeController

controller = RegimeController(ControllerConfig(rule="A", p_star=0.3))
t = 0.0
interval = controller.start(t)  # seconds until the first check
for _ in range(20):
    t += interval
    moved = False  # the real decision of the system: True if memory was moved
    step = controller.record_decision(t, moved)
    interval = step.next_dt
print(f"next check in {step.next_dt:.1f} s, non-stationary: {step.nonstationary}")

On a recorded log (checks.csv, see docs/en/log_format.md):

trosna-regime-control analyze checks.csv --rule A --p-star 0.3
trosna-regime-control flicker --heuristic config/heuristic.json

How it differs from existing packages

Compositional-data libraries, such as scikit-bio (skbio.stats.composition), composition_stats and pyCoDA, implement the centred and isometric log-ratio transforms. They do not allocate resources: none of them has bounds on the shares, a dead band against needless reallocations or a monitoring interval derived from the decisions. Change-point libraries, such as ruptures, ocpdet and changepoint-online, assume regular sampling and, mostly, Gaussian data. None of them handles Bernoulli decisions at irregular, policy-dependent intervals with a guarantee on the false-alarm rate.

Feature trosna-regime-control compositional-data libraries change-point libraries
clr and softmax, Aitchison distance yes yes no
Memory allocation on the simplex with bounds and a dead band δ yes no no
Monitoring interval by scale-invariant rules, cost model C₁/C₂ yes no no
Real-time decision intensity with exponential forgetting and debiasing yes no no
Shiryaev–Roberts and CUSUM on Bernoulli decisions at irregular intervals yes no no, they assume regular sampling
ARL lower bound for adaptive intervals (mean time to a false alarm) yes, under the model no no
Exact flicker of the 5-bit heuristic (Markov chain) yes no no
Streaming controller with JSON state and CLI yes no partly

The package does not estimate the growth of memory with Azuma–Hoeffding intervals or betting martingales. That is the task of azarovo-martingale. trosna-regime-control is about the regime of the decision stream.

Development

uv sync
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest            # fast tests; Monte Carlo ones are marked slow
uv run pytest -m slow    # Monte Carlo check of the ARL (minutes)

Commit messages in this repository have a subject of at most 8 characters and no body. Install the hook once per clone with scripts/install_hooks.sh.

Citation

See CITATION.cff or the "Cite this repository" button on GitHub.

Authors

Bryansk State Engineering-Technological University (BGITU).

License

MIT. Copyright (c) 2026 Andrey Ferubko, Oleg Kazakov. See LICENSE.

Metadata

Release files for trosna-regime-control 0.0.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for trosna-regime-control 0.0.1
File Size Uploaded Provenance Actions
trosna_regime_control-0.0.1.tar.gz 86.8 kB Without provenance Details for trosna_regime_control-0.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for trosna-regime-control 0.0.1
File Interpreter ABI Platform Actions
trosna_regime_control-0.0.1-py3-none-any.whl Python 3 none any Details for trosna_regime_control-0.0.1-py3-none-any.whl

Total release size: 136.3 kB

Release files / trosna_regime_control-0.0.1.tar.gz

Download URL trosna_regime_control-0.0.1.tar.gz
Size 86.8 kB
Tags Source
SHA-256 checksum
How to use checksums
f7ec3428ba8c1f809018492e4db72e4b323a2d9ff4fe7655017774ab878bcfd7
BLAKE2b-256 checksum
How to use checksums
d0b4ff7fda6e9515c5de489a1cb16efbbf3dbcb55440257c057c04c11dff5b73
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.9 {"installer":{"name":"uv","version":"0.11.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / trosna_regime_control-0.0.1-py3-none-any.whl

Download URL trosna_regime_control-0.0.1-py3-none-any.whl
Size 49.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f3d3ab6dc709e319b076fba762c8a7139bf71d116786b65fb38a8b8c569b1411
BLAKE2b-256 checksum
How to use checksums
7eb91c7ad413921291393d26ee4f212584a2a3e3b0f400322ed638583e55bf47
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.9 {"installer":{"name":"uv","version":"0.11.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for trosna-regime-control 0.0.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.0.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page