desna-interval 0.0.1__py3-none-any.whl

desna_interval/__init__.py

@@ -0,0 +1,77 @@
+"""Monitoring interval with a guarantee on the accumulated deficit.
+
+rule          closed-form interval rule, aged snapshots, expected-cost optimum
+estimators    upper bounds on the demand growth rate, Kalman adapter
+scheduler     per-object or common polling schedule
+replay        offline comparison of polling policies on a trace
+libvirt_loop  live loop for KVM guests (needs libvirt-python)
+
+>>> from desna_interval import next_interval_aged
+>>> round(next_interval_aged(s=256.0, v=128.0, eps=128.0, age=1.0), 3)
+2.414
+"""
+
+from .estimators import (
+    FixedRate,
+    KalmanRate,
+    RateEstimator,
+    RateFilter,
+    RateFilterAdapter,
+    WindowQuantile,
+    burst_rate,
+    growth_rates,
+    history_quantile,
+    per_series_quantiles,
+    pooled_quantile,
+)
+from .replay import (
+    BackoffPolicy,
+    DeficitRulePolicy,
+    ExpectedCostPolicy,
+    FixedPolicy,
+    ReplayResult,
+    replay,
+)
+from .rule import (
+    blind_deficit_bound,
+    burst_deficit_integral,
+    expected_cost_rate,
+    interval_unclipped,
+    min_slack,
+    next_interval,
+    next_interval_aged,
+    optimal_interval_expected,
+)
+from .scheduler import MonitorScheduler
+
+__version__ = "0.0.1"
+
+__all__ = [
+    "BackoffPolicy",
+    "DeficitRulePolicy",
+    "ExpectedCostPolicy",
+    "FixedPolicy",
+    "FixedRate",
+    "KalmanRate",
+    "MonitorScheduler",
+    "RateEstimator",
+    "RateFilter",
+    "RateFilterAdapter",
+    "ReplayResult",
+    "WindowQuantile",
+    "__version__",
+    "blind_deficit_bound",
+    "burst_deficit_integral",
+    "burst_rate",
+    "expected_cost_rate",
+    "growth_rates",
+    "history_quantile",
+    "interval_unclipped",
+    "min_slack",
+    "next_interval",
+    "next_interval_aged",
+    "optimal_interval_expected",
+    "per_series_quantiles",
+    "pooled_quantile",
+    "replay",
+]

desna_interval/cli.py

@@ -0,0 +1,96 @@
+"""Command line: ``desna-interval {interval,min-slack,optimal,replay}``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+import numpy as np
+
+from . import __version__
+from .estimators import FixedRate, WindowQuantile, burst_rate, history_quantile
+from .replay import BackoffPolicy, DeficitRulePolicy, FixedPolicy, PollingPolicy, replay
+from .rule import min_slack, next_interval_aged, optimal_interval_expected
+
+
+def _parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="desna-interval",
+        description="Monitoring interval from a tolerance on accumulated deficit.",
+    )
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("interval", help="delta* = s/v + sqrt(2 eps/v) - age, clipped")
+    p.add_argument("--slack", type=float, required=True, help="slack s, MiB")
+    p.add_argument("--rate", type=float, required=True, help="growth bound v, MiB/s")
+    p.add_argument("--eps", type=float, required=True, help="tolerance eps, MiB*s")
+    p.add_argument("--age", type=float, default=0.0, help="snapshot age, s")
+    p.add_argument("--dmin", type=float, default=1.0)
+    p.add_argument("--dmax", type=float, default=10.0)
+
+    p = sub.add_parser("min-slack", help="smallest slack admitting interval delta")
+    p.add_argument("--delta", type=float, required=True)
+    p.add_argument("--rate", type=float, required=True)
+    p.add_argument("--eps", type=float, required=True)
+
+    p = sub.add_parser("optimal", help="interval minimising expected cost")
+    p.add_argument("--slack", type=float, required=True)
+    p.add_argument("--rate", type=float, required=True)
+    p.add_argument("--rho", type=float, required=True, help="burst onset rate, 1/s")
+    p.add_argument("--cost", type=float, required=True, help="price of one poll, MiB*s")
+    p.add_argument("--dmin", type=float, default=1.0)
+    p.add_argument("--dmax", type=float, default=10.0)
+
+    p = sub.add_parser("replay", help="compare policies on a CSV trace with columns t,d")
+    p.add_argument("csv", help="CSV file: header, then time (s) and demand (MiB)")
+    p.add_argument("--eps", type=float, default=64.0)
+    p.add_argument("--slack", type=float, default=256.0)
+    p.add_argument("--fixed", type=float, nargs="*", default=[1.0, 2.0, 5.0, 10.0])
+    return ap
+
+
+def _replay(args: argparse.Namespace) -> None:
+    data = np.loadtxt(args.csv, delimiter=",", skiprows=1, ndmin=2)
+    t, d = data[:, 0], data[:, 1]
+    v = history_quantile(t, d)
+    rho = burst_rate(t, d)
+    print(f"trace: {t[-1] - t[0]:.0f} s, v(q=0.99) = {v:.1f} MiB/s, rho = {rho:.4f} 1/s")
+    print("policy,polls,mean_interval_s,deficit_mib_s,violation_share")
+    policies: list[tuple[str, PollingPolicy]] = [
+        (f"fixed_{x:g}s", FixedPolicy(x)) for x in args.fixed
+    ]
+    policies += [
+        ("backoff", BackoffPolicy()),
+        ("rule_history_v", DeficitRulePolicy(args.eps, args.slack, FixedRate(v))),
+        ("rule_window_v", DeficitRulePolicy(args.eps, args.slack, WindowQuantile())),
+    ]
+    for name, pol in policies:
+        r = replay(t, d, pol, args.slack)
+        print(
+            f"{name},{r.polls},{r.mean_interval:.3f},{r.deficit:.1f},"
+            f"{r.violation_share(args.eps):.4f}"
+        )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run the command line and return the exit status."""
+    args = _parser().parse_args(argv)
+    if args.cmd == "interval":
+        iv = next_interval_aged(args.slack, args.rate, args.eps, args.age, args.dmin, args.dmax)
+        print(f"{iv:.10g}")
+    elif args.cmd == "min-slack":
+        print(f"{min_slack(args.delta, args.rate, args.eps):.10g}")
+    elif args.cmd == "optimal":
+        iv = optimal_interval_expected(
+            args.slack, args.rate, args.rho, args.cost, args.dmin, args.dmax
+        )
+        print(f"{iv:.10g}")
+    else:
+        _replay(args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

desna_interval/estimators.py

@@ -0,0 +1,270 @@
+"""Upper bounds on the demand growth rate ``v`` used by the interval rule.
+
+The guarantee holds only if ``v`` also bounds growth at the start of a new
+burst. The main estimate is therefore a robust quantile over a long history.
+The window estimate tracks the current regime. An external estimator, for
+example a Kalman filter, plugs in through :class:`RateFilterAdapter`;
+:class:`KalmanRate` is a small built-in one.
+
+Every online estimator exposes ``update(t, d)`` and ``upper() -> float``.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import deque
+from collections.abc import Iterable, Sequence
+from typing import Protocol
+
+import numpy as np
+import numpy.typing as npt
+
+FloatArray = npt.NDArray[np.float64]
+
+
+class RateEstimator(Protocol):
+    """Online estimator of an upper bound on the growth rate."""
+
+    def update(self, t: float, d: float) -> None:
+        """Feed one observation: time ``t`` and demand ``d``."""
+        ...
+
+    def upper(self) -> float:
+        """Return the current upper bound on the growth rate."""
+        ...
+
+
+class RateFilter(Protocol):
+    """External filter, e.g. a Kalman filter, returning ``(rate, variance)``."""
+
+    def update(self, t: float, d: float) -> None:
+        """Feed one observation: time ``t`` and demand ``d``."""
+        ...
+
+    def rate(self) -> tuple[float, float]:
+        """Estimated growth rate and its variance."""
+        ...
+
+
+class WindowQuantile:
+    """Quantile of growth rates over the last ``window`` seconds.
+
+    ``q = 1.0`` gives the maximum rate in the window. Decreasing demand counts
+    as zero growth. The estimate is bounded below by ``v_floor``.
+
+    >>> est = WindowQuantile(window=30.0, q=1.0, v_floor=0.0)
+    >>> for k in range(10):
+    ...     est.update(float(k), 50.0 * k)
+    >>> est.upper()
+    50.0
+    """
+
+    def __init__(self, window: float = 300.0, q: float = 1.0, v_floor: float = 2.0) -> None:
+        self.window, self.q, self.v_floor = float(window), float(q), float(v_floor)
+        self._obs: deque[tuple[float, float]] = deque()
+
+    def update(self, t: float, d: float) -> None:
+        """Feed one observation: time ``t`` and demand ``d``."""
+        self._obs.append((float(t), float(d)))
+        while self._obs and self._obs[0][0] < t - self.window:
+            self._obs.popleft()
+
+    def upper(self) -> float:
+        """Return the current upper bound on the growth rate."""
+        if len(self._obs) < 2:
+            return self.v_floor
+        arr = np.asarray(self._obs, dtype=np.float64)
+        steps = np.diff(arr[:, 0])
+        ok = steps > 0
+        if not ok.any():
+            return self.v_floor
+        rates = np.maximum(np.diff(arr[:, 1])[ok], 0.0) / steps[ok]
+        return max(float(np.quantile(rates, self.q)), self.v_floor)
+
+
+class FixedRate:
+    """Constant bound, e.g. a robust quantile computed offline.
+
+    >>> FixedRate(128.0).upper()
+    128.0
+    """
+
+    def __init__(self, v: float) -> None:
+        self.v = float(v)
+
+    def update(self, t: float, d: float) -> None:
+        """Feed one observation: time ``t`` and demand ``d``."""
+
+    def upper(self) -> float:
+        """Return the current upper bound on the growth rate."""
+        return self.v
+
+
+class KalmanRate:
+    """Scalar Kalman filter of demand level and growth rate (constant velocity).
+
+    State ``(level, rate)``; the level is observed with variance ``r``. The
+    rate is a random walk driven by white acceleration of intensity ``q``.
+    Use it with :class:`RateFilterAdapter`, which turns the output into the
+    upper bound ``rate + z*sqrt(variance)``.
+
+    >>> kf = KalmanRate(q=1.0, r=1.0)
+    >>> for k in range(200):
+    ...     kf.update(float(k), 30.0 * k)
+    >>> round(kf.rate()[0], 2)
+    30.0
+    """
+
+    def __init__(self, q: float = 1.0, r: float = 25.0) -> None:
+        if q < 0.0 or r <= 0.0:
+            msg = "q must be non-negative and r positive"
+            raise ValueError(msg)
+        self.q, self.r = float(q), float(r)
+        self._t: float | None = None
+        self._x = (0.0, 0.0)
+        self._p = ((r, 0.0), (0.0, 1e4))
+
+    def update(self, t: float, d: float) -> None:
+        """Feed one observation: time ``t`` and demand ``d``."""
+        if self._t is None:
+            self._t, self._x = float(t), (float(d), 0.0)
+            return
+        dt = float(t) - self._t
+        if dt <= 0.0:
+            return
+        self._t = float(t)
+        (p00, p01), (_, p11) = self._p
+        # predict with F = [[1, dt], [0, 1]] and Q = q * [[dt^3/3, dt^2/2], [dt^2/2, dt]]
+        x0 = self._x[0] + dt * self._x[1]
+        x1 = self._x[1]
+        q = self.q
+        p00n = p00 + dt * (p01 + p01) + dt * dt * p11 + q * dt**3 / 3.0
+        p01n = p01 + dt * p11 + q * dt * dt / 2.0
+        p11n = p11 + q * dt
+        # update with H = [1, 0]
+        s = p00n + self.r
+        k0, k1 = p00n / s, p01n / s
+        innov = float(d) - x0
+        self._x = (x0 + k0 * innov, x1 + k1 * innov)
+        self._p = (
+            (p00n - k0 * p00n, p01n - k0 * p01n),
+            (p01n - k1 * p00n, p11n - k1 * p01n),
+        )
+
+    def rate(self) -> tuple[float, float]:
+        """Estimated growth rate and its variance."""
+        return self._x[1], self._p[1][1]
+
+
+class RateFilterAdapter:
+    """Wraps an external rate filter: upper bound = rate + z * sqrt(variance).
+
+    >>> adapter = RateFilterAdapter(KalmanRate(q=0.0, r=1.0), z=0.0, v_floor=0.0)
+    >>> for k in range(50):
+    ...     adapter.update(float(k), 20.0 * k)
+    >>> round(adapter.upper(), 1)
+    20.0
+    """
+
+    def __init__(self, filt: RateFilter, z: float = 2.33, v_floor: float = 2.0) -> None:
+        self.filt, self.z, self.v_floor = filt, float(z), float(v_floor)
+
+    def update(self, t: float, d: float) -> None:
+        """Feed one observation: time ``t`` and demand ``d``."""
+        self.filt.update(t, d)
+
+    def upper(self) -> float:
+        """Return the current upper bound on the growth rate."""
+        v, var = self.filt.rate()
+        return max(v + self.z * math.sqrt(max(var, 0.0)), self.v_floor)
+
+
+def growth_rates(t: npt.ArrayLike, d: npt.ArrayLike, step: float = 1.0) -> FloatArray:
+    """Non-negative growth rates over a regular grid with spacing ``step``.
+
+    >>> growth_rates([0.0, 10.0], [0.0, 50.0], step=5.0).tolist()
+    [5.0]
+    """
+    tt = np.asarray(t, dtype=np.float64)
+    dd = np.asarray(d, dtype=np.float64)
+    grid = np.arange(tt[0], tt[-1], step)
+    if grid.size < 2:
+        return np.empty(0, dtype=np.float64)
+    return np.maximum(np.diff(np.interp(grid, tt, dd)), 0.0) / step
+
+
+def history_quantile(
+    t: npt.ArrayLike, d: npt.ArrayLike, q: float = 0.99, step: float = 1.0, v_floor: float = 2.0
+) -> float:
+    """Robust bound from a long history: the q-quantile of growth over ``step``.
+
+    >>> t = [0.0, 1.0, 2.0, 3.0, 4.0]
+    >>> history_quantile(t, [0.0, 30.0, 60.0, 90.0, 120.0], q=0.5)
+    30.0
+    """
+    r = growth_rates(t, d, step)
+    return max(float(np.quantile(r, q)), v_floor) if r.size else v_floor
+
+
+def pooled_quantile(
+    series: Iterable[tuple[npt.ArrayLike, npt.ArrayLike]],
+    q: float = 0.99,
+    step: float = 1.0,
+    v_floor: float = 2.0,
+) -> float:
+    """Return a common robust bound over several similar machines.
+
+    ``series`` is an iterable of ``(t, d)`` pairs. For identical workloads a
+    pooled bound is more stable than separate per-machine bounds.
+
+    >>> t = [0.0, 1.0, 2.0]
+    >>> pooled_quantile([(t, [0.0, 10.0, 20.0]), (t, [0.0, 40.0, 80.0])], q=1.0)
+    40.0
+    """
+    parts = [growth_rates(t, d, step) for t, d in series]
+    parts = [p for p in parts if p.size]
+    if not parts:
+        return v_floor
+    return max(float(np.quantile(np.concatenate(parts), q)), v_floor)
+
+
+def per_series_quantiles(
+    t: npt.ArrayLike,
+    rows: Sequence[npt.ArrayLike],
+    q: float = 0.99,
+    step: float = 1.0,
+    v_floor: float = 2.0,
+) -> FloatArray:
+    """:func:`history_quantile` for each row of a matrix sharing the time axis ``t``."""
+    return np.array([history_quantile(t, row, q, step, v_floor) for row in rows], dtype=np.float64)
+
+
+def burst_rate(
+    t: npt.ArrayLike,
+    d: npt.ArrayLike,
+    step: float = 1.0,
+    rise: float = 128.0,
+    window: float = 30.0,
+    min_gap: float = 30.0,
+) -> float:
+    """Rate of burst onsets ``rho``, 1/s.
+
+    A moment is hot if demand exceeds its minimum over the last ``window``
+    seconds by more than ``rise``. Hot moments closer than ``min_gap`` belong
+    to one burst. Pick ``rise`` well above the noise range. The result feeds
+    :func:`desna_interval.rule.optimal_interval_expected`.
+    """
+    tt = np.asarray(t, dtype=np.float64)
+    dd = np.asarray(d, dtype=np.float64)
+    grid = np.arange(tt[0], tt[-1], step)
+    if grid.size < 2:
+        return 0.0
+    dg = np.interp(grid, tt, dd)
+    w = max(1, round(window / step))
+    pad = np.concatenate([np.full(w - 1, dg[0]), dg])
+    low = np.lib.stride_tricks.sliding_window_view(pad, w).min(axis=1)
+    hot = np.flatnonzero(dg - low > rise)
+    if hot.size == 0:
+        return 0.0
+    starts = 1 + int(np.sum(np.diff(hot) * step > min_gap))
+    return starts / (grid.size * step)

desna_interval/libvirt_loop.py

@@ -0,0 +1,202 @@
+"""Live monitoring loop for KVM guests through libvirt.
+
+Polls domains on a :class:`~desna_interval.scheduler.MonitorScheduler`
+schedule, computes demand, calls a controller and applies targets through
+the balloon. Without ``apply=True`` nothing is changed (dry run).
+Requires ``libvirt-python`` (extra ``desna-interval[libvirt]``); the module
+itself does not import libvirt, so it can be tested with fake domains.
+
+``memoryStats()`` keys: ``available`` is guest MemTotal, ``usable`` is guest
+MemAvailable, ``actual`` is the current balloon size, all in KiB.
+``last_update`` is the host time in whole seconds when QEMU received the
+statistics from the guest.
+
+Demand: d = (available - usable) / 1024 + reserve, MiB. Without
+``autodeflate`` (the default) the guest kernel shrinks MemTotal by the balloon
+size, so no correction is needed. With ``autodeflate='on'`` balloon pages stay
+in MemTotal; set ``balloon_in_total=True`` to subtract maxMemory - actual.
+
+Snapshot age. ``memoryStats()`` returns QEMU's last snapshot, refreshed once
+per stats period (whole seconds, at least 1 s). Age = time.time() -
+last_update; it is never smaller than the true age because last_update is
+rounded down. The next interval is shortened by the age.
+
+Example::
+
+    import libvirt
+    from desna_interval.libvirt_loop import run, reserve_controller
+
+    conn = libvirt.open("qemu:///system")
+    doms = {n: conn.lookupByName(n) for n in ["vm1", "vm2"]}
+    run(
+        doms,
+        reserve_controller(),
+        eps=128,
+        reserve_mib=256,
+        duration_s=7200,
+        log_path="live.csv",
+        apply=True,
+        stats_period=1,
+    )
+"""
+
+from __future__ import annotations
+
+import csv
+import math
+import time
+from collections.abc import Callable, Hashable, Mapping
+from pathlib import Path
+from typing import Any
+
+from .estimators import RateEstimator, WindowQuantile
+from .scheduler import IntervalScheduler, MonitorScheduler
+
+# libvirt-domain.h: VIR_DOMAIN_AFFECT_LIVE = 1 << 0
+VIR_DOMAIN_AFFECT_LIVE = 1
+
+# (demand, allocation, freshly polled objects) -> targets in MiB for objects to change
+Controller = Callable[
+    [dict[Hashable, float], dict[Hashable, float], set[Hashable]], dict[Hashable, float]
+]
+
+
+def read_state(
+    dom: Any,
+    reserve_mib: float,
+    balloon_in_total: bool = False,
+    wall: Callable[[], float] = time.time,
+) -> tuple[float, float, float]:
+    """Return (allocation MiB, demand MiB, snapshot age s) of a domain.
+
+    Without the ``last_update`` key (old libvirt) the age is zero.
+    """
+    st = dom.memoryStats()
+    actual = st["actual"] / 1024.0
+    used = (st["available"] - st["usable"]) / 1024.0
+    if balloon_in_total:
+        used -= max(dom.maxMemory() / 1024.0 - actual, 0.0)
+    age = max(wall() - float(st["last_update"]), 0.0) if "last_update" in st else 0.0
+    return actual, used + reserve_mib, age
+
+
+def reserve_controller(s_target: float = 256.0, deadband: float = 64.0) -> Controller:
+    """Build an example controller: target = demand + slack, with a dead band.
+
+    A real system's logic plugs in as a function with the same signature.
+    """
+
+    def ctrl(
+        demand: dict[Hashable, float], actual: dict[Hashable, float], fresh: set[Hashable]
+    ) -> dict[Hashable, float]:
+        out: dict[Hashable, float] = {}
+        for vm in fresh:
+            target = demand[vm] + s_target
+            if actual[vm] < demand[vm] or abs(target - actual[vm]) > deadband:
+                out[vm] = target
+        return out
+
+    return ctrl
+
+
+def run(
+    domains: Mapping[Hashable, Any],
+    controller: Controller,
+    eps: float,
+    reserve_mib: float,
+    duration_s: float,
+    log_path: str | Path,
+    dmin: float = 1.0,
+    dmax: float = 10.0,
+    mode: str = "per_vm",
+    estimator_factory: Callable[[], RateEstimator] | None = None,
+    apply: bool = False,
+    balloon_in_total: bool = False,
+    stats_period: int | None = None,
+    adapt_stats_period: bool = False,
+    clock: Callable[[], float] = time.monotonic,
+    sleep: Callable[[float], None] = time.sleep,
+    wall: Callable[[], float] = time.time,
+    scheduler: IntervalScheduler | None = None,
+) -> int:
+    """Run the monitoring loop. Returns the number of domain polls.
+
+    ``scheduler`` replaces the default :class:`MonitorScheduler` when given, for
+    example a heuristic schedule; ``eps``, ``mode`` and the estimator are then unused.
+    """
+    sched: IntervalScheduler
+    if scheduler is not None:
+        sched = scheduler
+    else:
+        sched = MonitorScheduler(
+            domains, eps, estimator_factory or (WindowQuantile), dmin, dmax, mode
+        )
+    period: dict[Hashable, int] = {}
+    if stats_period is not None:
+        for vm, dom in domains.items():
+            dom.setMemoryStatsPeriod(int(stats_period), VIR_DOMAIN_AFFECT_LIVE)
+            period[vm] = int(stats_period)
+    demand: dict[Hashable, float] = {}
+    actual: dict[Hashable, float] = {}
+    age: dict[Hashable, float] = {}
+    n_polls = 0
+    t0 = clock()
+    with Path(log_path).open("w", newline="") as fh:
+        w = csv.writer(fh)
+        w.writerow(
+            [
+                "t_s",
+                "vm",
+                "actual_mib",
+                "demand_mib",
+                "target_mib",
+                "applied",
+                "interval_s",
+                "age_s",
+                "stats_period_s",
+            ]
+        )
+        while True:
+            now = clock() - t0
+            if now >= duration_s:
+                break
+            due = sched.due(now)
+            if not due:
+                sleep(max(min(sched.next_wakeup(), duration_s) - now, 0.0))
+                continue
+            for vm in due:
+                actual[vm], demand[vm], age[vm] = read_state(
+                    domains[vm], reserve_mib, balloon_in_total, wall
+                )
+            n_polls += len(due)
+            targets = controller(demand, actual, set(due))
+            slack, applied = {}, {}
+            for vm in due:
+                target = targets.get(vm, actual[vm])
+                applied[vm] = bool(apply and vm in targets)
+                if applied[vm]:
+                    domains[vm].setMemoryFlags(int(target * 1024), VIR_DOMAIN_AFFECT_LIVE)
+                slack[vm] = target - demand[vm]
+            intervals = sched.observe(
+                now, {vm: demand[vm] for vm in due}, slack, {vm: age[vm] for vm in due}
+            )
+            for vm in due:
+                if adapt_stats_period:
+                    p = max(1, math.floor(intervals[vm]))
+                    if period.get(vm) != p:
+                        domains[vm].setMemoryStatsPeriod(p, VIR_DOMAIN_AFFECT_LIVE)
+                        period[vm] = p
+                w.writerow(
+                    [
+                        f"{now:.3f}",
+                        vm,
+                        f"{actual[vm]:.1f}",
+                        f"{demand[vm]:.1f}",
+                        f"{targets.get(vm, actual[vm]):.1f}",
+                        int(applied[vm]),
+                        f"{intervals[vm]:.3f}",
+                        f"{age[vm]:.3f}",
+                        period.get(vm, ""),
+                    ]
+                )
+    return n_polls

desna_interval/replay.py

@@ -0,0 +1,192 @@
+"""Offline replay of polling policies on a demand trace.
+
+Simplified controller: on every poll at time ``p`` the allocation is reset to
+``d(p) + slack``. Between polls the allocation stays constant and the deficit
+is the integral of ``(d(t) - allocation)^+``. This isolates the effect of the
+polling interval from the rest of the control logic and lets one compare
+policies on the same trace.
+
+A policy is any object with ``next_interval(t, d) -> float``, called with the
+time and the observed demand of each poll.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Protocol
+
+import numpy as np
+import numpy.typing as npt
+
+from .estimators import RateEstimator
+from .rule import next_interval, optimal_interval_expected
+
+
+class PollingPolicy(Protocol):
+    """Protocol of a polling policy: an object with ``next_interval``."""
+
+    def next_interval(self, t: float, d: float) -> float:
+        """Interval until the next poll, given the time and observed demand."""
+        ...
+
+
+class FixedPolicy:
+    """Constant interval.
+
+    >>> FixedPolicy(4.0).next_interval(0.0, 1000.0)
+    4.0
+    """
+
+    name = "fixed"
+
+    def __init__(self, delta: float) -> None:
+        self.delta = float(delta)
+
+    def next_interval(self, t: float, d: float) -> float:
+        """Return the constant interval."""
+        return self.delta
+
+
+class BackoffPolicy:
+    """Exponential back-off, a common heuristic for polling without a bound.
+
+    The interval is multiplied by ``factor`` while demand changes by less than
+    ``threshold`` between polls and is reset to ``dmin`` otherwise. It gives no
+    bound on the deficit, so it serves here as a baseline.
+
+    >>> bo = BackoffPolicy(dmin=1.0, dmax=8.0, factor=2.0, threshold=64.0)
+    >>> [bo.next_interval(float(k), 100.0) for k in range(4)]
+    [1.0, 2.0, 4.0, 8.0]
+    """
+
+    name = "backoff"
+
+    def __init__(
+        self, dmin: float = 1.0, dmax: float = 10.0, factor: float = 2.0, threshold: float = 64.0
+    ) -> None:
+        self.dmin, self.dmax, self.factor = float(dmin), float(dmax), float(factor)
+        self.threshold = float(threshold)
+        self._prev: float | None = None
+        self._iv = self.dmin
+
+    def next_interval(self, t: float, d: float) -> float:
+        """Grow the interval while demand is calm, reset it otherwise."""
+        if self._prev is not None and abs(d - self._prev) < self.threshold:
+            self._iv = min(self._iv * self.factor, self.dmax)
+        else:
+            self._iv = self.dmin
+        self._prev = d
+        return self._iv
+
+
+class DeficitRulePolicy:
+    """The rule ``delta* = s/v + sqrt(2*eps/v)`` with an online bound on ``v``.
+
+    >>> from desna_interval.estimators import FixedRate
+    >>> pol = DeficitRulePolicy(eps=128.0, slack=256.0, estimator=FixedRate(128.0))
+    >>> round(pol.next_interval(0.0, 1000.0), 3)
+    3.414
+    """
+
+    name = "deficit_rule"
+
+    def __init__(
+        self,
+        eps: float,
+        slack: float,
+        estimator: RateEstimator,
+        dmin: float = 1.0,
+        dmax: float = 10.0,
+    ) -> None:
+        self.eps, self.slack, self.est = float(eps), float(slack), estimator
+        self.dmin, self.dmax = float(dmin), float(dmax)
+
+    def next_interval(self, t: float, d: float) -> float:
+        """Update the rate bound and return the rule interval."""
+        self.est.update(t, d)
+        return next_interval(self.slack, self.est.upper(), self.eps, self.dmin, self.dmax)
+
+
+class ExpectedCostPolicy:
+    """Interval minimising the expected cost for known ``v``, ``rho`` and poll price ``c``.
+
+    >>> pol = ExpectedCostPolicy(slack=0.0, v=128.0, rho=0.01, c=64.0, dmin=0.0, dmax=99.0)
+    >>> round(pol.next_interval(0.0, 1000.0), 3)
+    5.313
+    """
+
+    name = "expected_cost"
+
+    def __init__(
+        self, slack: float, v: float, rho: float, c: float, dmin: float = 1.0, dmax: float = 10.0
+    ) -> None:
+        self.delta = optimal_interval_expected(slack, v, rho, c, dmin, dmax)
+
+    def next_interval(self, t: float, d: float) -> float:
+        """Return the precomputed optimal interval."""
+        return self.delta
+
+
+@dataclass
+class ReplayResult:
+    """Outcome of one replay."""
+
+    polls: int
+    duration: float
+    deficit: float
+    gap_deficits: npt.NDArray[np.float64] = field(repr=False)
+    intervals: npt.NDArray[np.float64] = field(repr=False)
+
+    @property
+    def mean_interval(self) -> float:
+        """Mean interval between polls, s."""
+        return self.duration / max(self.polls, 1)
+
+    def violation_share(self, eps: float) -> float:
+        """Share of blind gaps whose deficit exceeds ``eps``."""
+        g = self.gap_deficits
+        return float(np.mean(g > eps)) if g.size else 0.0
+
+
+def replay(t: npt.ArrayLike, d: npt.ArrayLike, policy: PollingPolicy, slack: float) -> ReplayResult:
+    """Replay ``policy`` on the trace ``(t, d)`` sampled on a fine grid.
+
+    Demand is piecewise linear between samples; the deficit is integrated with
+    the trapezoidal rule on the trace grid plus the poll times.
+
+    >>> import numpy as np
+    >>> tt = np.arange(0.0, 41.0, 1.0)
+    >>> r = replay(tt, 10.0 * tt, FixedPolicy(4.0), slack=0.0)
+    >>> r.polls, r.mean_interval
+    (10, 4.0)
+    """
+    tt = np.asarray(t, dtype=np.float64)
+    dd = np.asarray(d, dtype=np.float64)
+    if tt.ndim != 1 or tt.shape != dd.shape or tt.size < 2:
+        msg = "t and d must be 1-D arrays of equal length >= 2"
+        raise ValueError(msg)
+    if np.any(np.diff(tt) <= 0):
+        msg = "t must be strictly increasing"
+        raise ValueError(msg)
+    t_end = float(tt[-1])
+    p = float(tt[0])
+    gaps: list[float] = []
+    ivs: list[float] = []
+    while p < t_end:
+        dp = float(np.interp(p, tt, dd))
+        alloc = dp + slack
+        iv = float(policy.next_interval(p, dp))
+        if iv <= 0:
+            msg = "policy returned a non-positive interval"
+            raise ValueError(msg)
+        q = min(p + iv, t_end)
+        inner = tt[(tt > p) & (tt < q)]
+        grid = np.concatenate([[p], inner, [q]])
+        short = np.maximum(np.interp(grid, tt, dd) - alloc, 0.0)
+        gaps.append(float(np.sum((short[1:] + short[:-1]) * np.diff(grid)) / 2.0))
+        ivs.append(iv)
+        p = q
+    g = np.asarray(gaps, dtype=np.float64)
+    return ReplayResult(
+        len(gaps), t_end - float(tt[0]), float(g.sum()), g, np.asarray(ivs, dtype=np.float64)
+    )

desna_interval/rule.py

@@ -0,0 +1,166 @@
+"""Interval rule from a tolerance on accumulated deficit.
+
+The accumulated deficit ``D(E) = integral over E of f dλ`` is absolutely
+continuous with respect to time, and the instantaneous deficit ``f`` is its
+Radon-Nikodym derivative (Halmos, *Measure Theory*, §30–31). Requirement: the
+deficit over any blind gap between two observations stays below a tolerance
+``eps``. If demand grows no faster than ``v``, this gives a closed-form
+interval ``delta* = s/v + sqrt(2*eps/v)``.
+
+Units are free but must be consistent. The documentation uses MiB for memory,
+s for time, MiB/s for the rate and MiB*s for the deficit.
+"""
+
+from __future__ import annotations
+
+import math
+
+
+def blind_deficit_bound(s: float, v: float, delta: float) -> float:
+    """Upper bound on the deficit over a blind gap of length ``delta``.
+
+    ``s`` is the slack right after the decision, ``v`` the upper bound on the
+    demand growth rate. For ``s >= 0`` it equals the integral of
+    ``(v*tau - s)^+`` over ``tau`` in ``[0, delta]``.
+
+    >>> blind_deficit_bound(256.0, 128.0, 4.0)
+    256.0
+    >>> blind_deficit_bound(256.0, 128.0, 1.0)
+    0.0
+    """
+    if delta <= 0.0:
+        return 0.0
+    if v <= 0.0:
+        return max(-s, 0.0) * delta
+    if s >= 0.0:
+        x = v * delta - s
+        return x * x / (2.0 * v) if x > 0.0 else 0.0
+    return -s * delta + v * delta * delta / 2.0
+
+
+def interval_unclipped(s: float, v: float, eps: float) -> float:
+    """Largest ``delta`` with ``blind_deficit_bound(s, v, delta) <= eps``.
+
+    ``delta* = s/v + sqrt(2*eps/v)``, valid for ``s >= 0`` and ``v > 0``.
+    The first term is the time to exhaust the slack, the second the time to
+    accumulate the tolerated deficit ``eps``.
+
+    >>> round(interval_unclipped(256.0, 128.0, 128.0), 6)
+    3.414214
+    >>> interval_unclipped(0.0, 0.0, 1.0)
+    Traceback (most recent call last):
+    ...
+    ValueError: the growth bound v must be positive
+    """
+    if v <= 0.0:
+        msg = "the growth bound v must be positive"
+        raise ValueError(msg)
+    return s / v + math.sqrt(2.0 * eps / v)
+
+
+def next_interval(s: float, v: float, eps: float, dmin: float = 1.0, dmax: float = 10.0) -> float:
+    """Interval until the next observation, clipped to ``[dmin, dmax]``.
+
+    >>> next_interval(-1.0, 10.0, 10.0)
+    1.0
+    >>> next_interval(100.0, 0.0, 10.0)
+    10.0
+    """
+    return next_interval_aged(s, v, eps, 0.0, dmin, dmax)
+
+
+def next_interval_aged(
+    s: float, v: float, eps: float, age: float = 0.0, dmin: float = 1.0, dmax: float = 10.0
+) -> float:
+    """Interval corrected for the age of the observed snapshot.
+
+    Statistics such as virtio-balloon memory stats arrive ``age`` seconds late.
+    The blind gap then runs from the snapshot to the next poll and lasts
+    ``age + delta``, so ``age`` is subtracted from ``delta*``. ``s`` is the
+    slack relative to the demand at the time of the snapshot. Without slack
+    the shortest interval ``dmin`` is returned; without growth, ``dmax``.
+
+    >>> round(next_interval_aged(s=256.0, v=128.0, eps=128.0, age=1.0), 3)
+    2.414
+    >>> next_interval_aged(s=256.0, v=128.0, eps=128.0, age=100.0)
+    1.0
+    """
+    if s <= 0.0:
+        return dmin
+    if v <= 0.0:
+        return dmax
+    return min(max(interval_unclipped(s, v, eps) - max(age, 0.0), dmin), dmax)
+
+
+def min_slack(delta: float, v: float, eps: float) -> float:
+    """Smallest slack that makes the interval ``delta`` admissible.
+
+    ``s_min(delta) = (v*delta - sqrt(2*v*eps))^+``, the inverse of
+    :func:`interval_unclipped`. It prices a rare poll in units of reserved
+    memory.
+
+    >>> round(min_slack(5.0, 128.0, 128.0), 6)
+    458.980664
+    """
+    if v <= 0.0:
+        msg = "the growth bound v must be positive"
+        raise ValueError(msg)
+    return max(v * delta - math.sqrt(2.0 * v * eps), 0.0)
+
+
+def burst_deficit_integral(delta: float, s: float, v: float) -> float:
+    """``G(delta) = integral over r in [0, delta] of ((v*r - s)^+)^2 / (2v)``.
+
+    The integrand is the deficit accrued from a burst that starts ``r``
+    seconds before the next poll. ``G`` is convex, which gives the
+    equal-interval result (claim 1.4).
+
+    >>> round(burst_deficit_integral(4.0, 0.0, 1.0), 6)
+    10.666667
+    """
+    x = v * delta - s
+    return x**3 / (6.0 * v * v) if x > 0.0 and v > 0.0 else 0.0
+
+
+def expected_cost_rate(delta: float, s: float, v: float, rho: float, c: float) -> float:
+    """Return the expected cost per unit time, ``(rho*G(delta) + c) / delta``.
+
+    ``rho`` is the rate of burst onsets (1/s), ``c`` the price of one poll in
+    deficit units. Assumptions: at most one burst onset per interval
+    (``rho*delta << 1``), growth lasts until the next poll, and every poll
+    restores the slack ``s``.
+    """
+    return (rho * burst_deficit_integral(delta, s, v) + c) / delta
+
+
+def optimal_interval_expected(
+    s: float, v: float, rho: float, c: float, dmin: float = 1.0, dmax: float = 10.0
+) -> float:
+    """Interval that minimises :func:`expected_cost_rate` (claim 1.5).
+
+    The optimality condition is ``x^3/3 + s*x^2/2 = c*v^2/rho`` with
+    ``x = v*delta - s``. The left side increases for ``x > 0``, so the root is
+    unique and is found by bisection. For ``s = 0`` the answer is
+    ``delta = (3c / (rho*v))^(1/3)``.
+
+    >>> round(optimal_interval_expected(0.0, 128.0, 0.01, 64.0, dmin=0.0, dmax=99.0), 4)
+    5.3133
+    """
+    if s < 0.0:
+        return dmin
+    if v <= 0.0 or rho <= 0.0:
+        return dmax
+    if c <= 0.0:
+        return min(max(s / v, dmin), dmax)
+    k = c * v * v / rho
+    lo, hi = 0.0, float((3.0 * k) ** (1.0 / 3.0))
+    for _ in range(200):
+        mid = 0.5 * (lo + hi)
+        if mid**3 / 3.0 + s * mid * mid / 2.0 < k:
+            lo = mid
+        else:
+            hi = mid
+        if hi - lo <= 1e-15 * max(hi, 1.0):
+            break
+    x = 0.5 * (lo + hi)
+    return min(max((x + s) / v, dmin), dmax)

desna_interval/scheduler.py

@@ -0,0 +1,110 @@
+"""Polling schedule: one common interval, or an individual interval per object."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable, Iterable, Mapping
+from typing import Protocol
+
+from .estimators import RateEstimator
+from .rule import next_interval_aged
+
+
+class IntervalScheduler(Protocol):
+    """Anything that decides which objects to poll and when.
+
+    :class:`MonitorScheduler` implements it. Other policies, for example the
+    current heuristic, implement the same three methods and are passed to
+    :func:`desna_interval.libvirt_loop.run` as ``scheduler``.
+    """
+
+    def due(self, now: float) -> list[Hashable]:
+        """Objects that should be polled at time ``now``."""
+        ...
+
+    def next_wakeup(self) -> float:
+        """Time of the earliest scheduled poll."""
+        ...
+
+    def observe(
+        self,
+        now: float,
+        demand: Mapping[Hashable, float],
+        slack: Mapping[Hashable, float],
+        age: Mapping[Hashable, float] | None = None,
+    ) -> dict[Hashable, float]:
+        """Take the observations and return the interval assigned to each polled object."""
+        ...
+
+
+class MonitorScheduler:
+    """Keeps the next poll time of every monitored object.
+
+    ``mode="per_vm"``: each object gets its own interval from the rule.
+    ``mode="global"``: all objects are polled together, the common interval
+    is the minimum over the objects. ``estimator_factory()`` creates one
+    :class:`~desna_interval.estimators.RateEstimator` per object.
+
+    >>> from desna_interval.estimators import FixedRate
+    >>> sch = MonitorScheduler(["a", "b"], eps=128.0, estimator_factory=lambda: FixedRate(128.0))
+    >>> iv = sch.observe(0.0, {"a": 1000.0, "b": 1000.0}, {"a": 256.0, "b": 2048.0})
+    >>> round(iv["a"], 3), iv["b"]
+    (3.414, 10.0)
+    """
+
+    def __init__(
+        self,
+        vms: Iterable[Hashable],
+        eps: float,
+        estimator_factory: Callable[[], RateEstimator],
+        dmin: float = 1.0,
+        dmax: float = 10.0,
+        mode: str = "per_vm",
+    ) -> None:
+        if mode not in ("per_vm", "global"):
+            msg = "mode must be 'per_vm' or 'global'"
+            raise ValueError(msg)
+        self.vms: list[Hashable] = list(vms)
+        self.eps, self.dmin, self.dmax, self.mode = float(eps), float(dmin), float(dmax), mode
+        self.est: dict[Hashable, RateEstimator] = {vm: estimator_factory() for vm in self.vms}
+        self.next_t: dict[Hashable, float] = dict.fromkeys(self.vms, 0.0)
+        self.last_interval: dict[Hashable, float] = dict.fromkeys(self.vms, self.dmin)
+
+    def due(self, now: float, tol: float = 1e-9) -> list[Hashable]:
+        """Objects that should be polled at time ``now``."""
+        if self.mode == "global":
+            return list(self.vms) if self.next_wakeup() <= now + tol else []
+        return [vm for vm in self.vms if self.next_t[vm] <= now + tol]
+
+    def next_wakeup(self) -> float:
+        """Time of the earliest scheduled poll."""
+        return min(self.next_t.values())
+
+    def observe(
+        self,
+        now: float,
+        demand: Mapping[Hashable, float],
+        slack: Mapping[Hashable, float],
+        age: Mapping[Hashable, float] | None = None,
+    ) -> dict[Hashable, float]:
+        """Update the estimators of the polled objects and schedule their next polls.
+
+        ``demand`` is the observed demand, ``slack`` the slack after the
+        decision, ``age`` the snapshot age in seconds if known. The estimator
+        receives the snapshot time, and the interval is shortened by the age.
+        Returns the assigned intervals.
+        """
+        ages = age or {}
+        intervals: dict[Hashable, float] = {}
+        for vm, dm in demand.items():
+            a = float(ages.get(vm, 0.0))
+            self.est[vm].update(now - a, dm)
+            intervals[vm] = next_interval_aged(
+                slack[vm], self.est[vm].upper(), self.eps, a, self.dmin, self.dmax
+            )
+        if self.mode == "global" and intervals:
+            common = min(intervals.values())
+            intervals = dict.fromkeys(intervals, common)
+        for vm, iv in intervals.items():
+            self.next_t[vm] = now + iv
+            self.last_interval[vm] = iv
+        return intervals

desna_interval-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,13 @@
+desna_interval/__init__.py,sha256=S9By362XaGL9H2_BayGtGIRKgmCFQ164k0jnD_CenQI,1803
+desna_interval/cli.py,sha256=91juFH-0OBsa52A6LHQveZOu0tt1Ra3jBMGJt0PljRg,4068
+desna_interval/estimators.py,sha256=Ld7unbGc27kONYVRxCz7ZWGGSLYw5y32cIzY6j_0WoI,9132
+desna_interval/libvirt_loop.py,sha256=YUz38X9CWL4VzR-Sg_cYxEFTmT58CNIlG65RWssyrag,7190
+desna_interval/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+desna_interval/replay.py,sha256=AyczwNCiHv3p0WdtaHim9sPwzCqo6jJvPlGtkd_40qU,6406
+desna_interval/rule.py,sha256=8PBOkE1HJynAK3AE4DDoDNL1XjS5sGvrZNtzmXHjDjE,5889
+desna_interval/scheduler.py,sha256=_dxOVXa0_8lL49bJ507Q7LYzLkuUHW5crh3ZjPWlwGo,4266
+desna_interval-0.0.1.dist-info/licenses/LICENSE,sha256=vBZIvozzvvIPDJPwlCiWyXZZ6gPwXRi8EeTdUCuulAI,1085
+desna_interval-0.0.1.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
+desna_interval-0.0.1.dist-info/entry_points.txt,sha256=SzaHVEjQ5lLuaK060JMOTsETZEN8hUUpInADn9usbgg,60
+desna_interval-0.0.1.dist-info/METADATA,sha256=JVGtajbWWqtk8crDLriPJJrui2_HQm5PxGfFCAhvJp4,8441
+desna_interval-0.0.1.dist-info/RECORD,,

desna_interval-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.7
+Root-Is-Purelib: true
+Tag: py3-none-any

desna_interval-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+desna-interval = desna_interval.cli:main
+

desna_interval-0.0.1.dist-info/licenses/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.