tailor-aoi 0.1.0__tar.gz

tailor_aoi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AiminLi-Hi
+
+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.

tailor_aoi-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: tailor-aoi
+Version: 0.1.0
+Summary: Age-optimal sampling and preemption under heavy-tailed delays (TAILOR, IEEE ISIT 2026)
+Author: Aimin Li, Yiğit İnce, Elif Uysal
+License-Expression: MIT
+Project-URL: Paper, https://doi.org/10.1109/ISIT62367.2026.11653616
+Project-URL: arXiv, https://arxiv.org/abs/2601.16624
+Project-URL: Code, https://github.com/AiminLi-Hi/aoi-preemption-heavy-tail
+Project-URL: Project page, https://yigiti.github.io/Preemption/
+Keywords: age of information,AoI,preemption,heavy-tailed delay,optimal stopping,impulse control,queueing,status update,information freshness,policy iteration
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: System :: Networking
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == "plot"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# tailor-aoi
+
+Python implementation of **TAILOR**, the age-optimal joint sampling and preemption policy from
+*Taming the Heavy Tail: Age-Optimal Preemption* (A. Li, Y. İnce, E. Uysal, IEEE ISIT 2026,
+[DOI 10.1109/ISIT62367.2026.11653616](https://doi.org/10.1109/ISIT62367.2026.11653616)).
+
+![TAILOR vs. baselines](https://raw.githubusercontent.com/AiminLi-Hi/aoi-preemption-heavy-tail/main/assets/fig2_tailor.png)
+
+## Install
+
+```bash
+pip install tailor-aoi            # core
+pip install "tailor-aoi[plot]"    # with matplotlib helpers
+```
+
+## Use
+
+```python
+from tailor_aoi import ServiceDist, solve, compare
+
+dist = ServiceDist.pareto2(mean=2.0, variance=40.0)   # or lognormal_from_mean, exponential, from_scipy
+policy = solve(dist, kappa_s=1.0, kappa_p=1.0)        # optimal sampling + preemption policy
+print(compare(dist, 1.0, 1.0, policy=policy))         # vs. Update-or-Wait, Zero-Wait, best static
+```
+
+Command line: `python -m tailor_aoi --dist lognormal --mean 2 --sigma2 6`.
+
+- Repository and MATLAB code: https://github.com/AiminLi-Hi/aoi-preemption-heavy-tail
+- Colab quickstart: https://colab.research.google.com/github/AiminLi-Hi/aoi-preemption-heavy-tail/blob/main/python/examples/quickstart.ipynb
+- Project page: https://yigiti.github.io/Preemption/
+
+## Citation
+
+If you use this package, please cite the paper (`python -m tailor_aoi --cite` prints the BibTeX):
+
+```bibtex
+@inproceedings{li2026taming,
+  title     = {Taming the Heavy Tail: Age-Optimal Preemption},
+  author    = {Li, Aimin and {\.I}nce, Yi{\u{g}}it and Uysal, Elif},
+  booktitle = {Proc. IEEE International Symposium on Information Theory (ISIT)},
+  year      = {2026},
+  doi       = {10.1109/ISIT62367.2026.11653616}
+}
+```

tailor_aoi-0.1.0/README.md

@@ -0,0 +1,44 @@
+# tailor-aoi
+
+Python implementation of **TAILOR**, the age-optimal joint sampling and preemption policy from
+*Taming the Heavy Tail: Age-Optimal Preemption* (A. Li, Y. İnce, E. Uysal, IEEE ISIT 2026,
+[DOI 10.1109/ISIT62367.2026.11653616](https://doi.org/10.1109/ISIT62367.2026.11653616)).
+
+![TAILOR vs. baselines](https://raw.githubusercontent.com/AiminLi-Hi/aoi-preemption-heavy-tail/main/assets/fig2_tailor.png)
+
+## Install
+
+```bash
+pip install tailor-aoi            # core
+pip install "tailor-aoi[plot]"    # with matplotlib helpers
+```
+
+## Use
+
+```python
+from tailor_aoi import ServiceDist, solve, compare
+
+dist = ServiceDist.pareto2(mean=2.0, variance=40.0)   # or lognormal_from_mean, exponential, from_scipy
+policy = solve(dist, kappa_s=1.0, kappa_p=1.0)        # optimal sampling + preemption policy
+print(compare(dist, 1.0, 1.0, policy=policy))         # vs. Update-or-Wait, Zero-Wait, best static
+```
+
+Command line: `python -m tailor_aoi --dist lognormal --mean 2 --sigma2 6`.
+
+- Repository and MATLAB code: https://github.com/AiminLi-Hi/aoi-preemption-heavy-tail
+- Colab quickstart: https://colab.research.google.com/github/AiminLi-Hi/aoi-preemption-heavy-tail/blob/main/python/examples/quickstart.ipynb
+- Project page: https://yigiti.github.io/Preemption/
+
+## Citation
+
+If you use this package, please cite the paper (`python -m tailor_aoi --cite` prints the BibTeX):
+
+```bibtex
+@inproceedings{li2026taming,
+  title     = {Taming the Heavy Tail: Age-Optimal Preemption},
+  author    = {Li, Aimin and {\.I}nce, Yi{\u{g}}it and Uysal, Elif},
+  booktitle = {Proc. IEEE International Symposium on Information Theory (ISIT)},
+  year      = {2026},
+  doi       = {10.1109/ISIT62367.2026.11653616}
+}
+```

tailor_aoi-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tailor-aoi"
+version = "0.1.0"
+description = "Age-optimal sampling and preemption under heavy-tailed delays (TAILOR, IEEE ISIT 2026)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Aimin Li" },
+  { name = "Yiğit İnce" },
+  { name = "Elif Uysal" },
+]
+requires-python = ">=3.9"
+dependencies = ["numpy>=1.22", "scipy>=1.8"]
+keywords = [
+  "age of information", "AoI", "preemption", "heavy-tailed delay", "optimal stopping",
+  "impulse control", "queueing", "status update", "information freshness", "policy iteration",
+]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Mathematics",
+  "Topic :: System :: Networking",
+  "Intended Audience :: Science/Research",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.5"]
+test = ["pytest>=7"]
+
+[project.urls]
+Paper = "https://doi.org/10.1109/ISIT62367.2026.11653616"
+arXiv = "https://arxiv.org/abs/2601.16624"
+Code = "https://github.com/AiminLi-Hi/aoi-preemption-heavy-tail"
+"Project page" = "https://yigiti.github.io/Preemption/"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tailor_aoi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tailor_aoi-0.1.0/src/tailor_aoi/__init__.py

@@ -0,0 +1,59 @@
+"""tailor-aoi: age-optimal sampling and preemption under heavy-tailed delays.
+
+Quick start::
+
+    from tailor_aoi import ServiceDist, solve, compare
+
+    dist = ServiceDist.lognormal_from_mean(mean=2.0, sigma2=4.0)
+    policy = solve(dist, kappa_s=1.0, kappa_p=1.0)
+    print(policy.summary())
+    print(compare(dist, 1.0, 1.0, policy=policy))
+
+Reference: A. Li, Y. Ince, E. Uysal, "Taming the Heavy Tail: Age-Optimal
+Preemption", Proc. IEEE ISIT 2026. DOI: 10.1109/ISIT62367.2026.11653616
+"""
+
+from .baselines import StaticPolicy, optimized_static, static_cost, update_or_wait, zero_wait
+from .distributions import ServiceDist
+from .simulate import SimResult, sample_path, simulate
+from .solver import Policy, solve
+
+__version__ = "0.1.0"
+
+CITATION = """@inproceedings{li2026taming,
+  title     = {Taming the Heavy Tail: Age-Optimal Preemption},
+  author    = {Li, Aimin and {\\.I}nce, Yi{\\u{g}}it and Uysal, Elif},
+  booktitle = {Proc. IEEE International Symposium on Information Theory (ISIT)},
+  year      = {2026},
+  doi       = {10.1109/ISIT62367.2026.11653616}
+}"""
+
+
+def compare(dist, kappa_s=1.0, kappa_p=1.0, policy=None, **solve_kwargs):
+    """Average cost of TAILOR vs. the baselines used in the paper.
+
+    Baseline costs are exact (renewal-reward); TAILOR's cost is the optimal
+    average cost ``rho`` returned by the ACOE solver.
+    """
+    if policy is None:
+        policy = solve(dist, kappa_s, kappa_p, **solve_kwargs)
+    rows = [("TAILOR (Proposed)", policy.rho)]
+    rows.append(("Update-or-Wait [Sun et al. 2017]", update_or_wait(dist, kappa_s, kappa_p, rule="sun")[1]))
+    rows.append(("Zero-Wait", zero_wait(dist, kappa_s, kappa_p)[1]))
+    rows.append(("Optimized Static (D, T)", optimized_static(dist, kappa_s, kappa_p)[1]))
+    width = max(len(r[0]) for r in rows)
+    lines = [f"{dist.name}, k_s={kappa_s:g}, k_p={kappa_p:g}"]
+    lines += [f"  {n:<{width}}  {c:12.5f}   ({c / policy.rho:6.2f}x)" for n, c in rows]
+    return "\n".join(lines)
+
+
+def cite() -> str:
+    """BibTeX entry to cite when you use this package."""
+    return CITATION
+
+
+__all__ = [
+    "ServiceDist", "Policy", "solve", "StaticPolicy", "static_cost", "zero_wait",
+    "update_or_wait", "optimized_static", "simulate", "sample_path", "SimResult",
+    "compare", "cite", "CITATION",
+]

tailor_aoi-0.1.0/src/tailor_aoi/__main__.py

@@ -0,0 +1,42 @@
+"""Command-line interface.
+
+    python -m tailor_aoi --dist lognormal --mean 2 --sigma2 6 --ks 1 --kp 1
+    python -m tailor_aoi --dist pareto2 --mean 2 --var 40 --ks 1 --kp 1
+    python -m tailor_aoi --dist exponential --mean 1
+"""
+
+import argparse
+
+from . import ServiceDist, cite, compare, solve
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="tailor_aoi", description="Age-optimal sampling and preemption (TAILOR).")
+    ap.add_argument("--dist", choices=["lognormal", "pareto2", "exponential"], default="lognormal")
+    ap.add_argument("--mean", type=float, default=2.0, help="mean service time E[Y]")
+    ap.add_argument("--sigma2", type=float, default=4.0, help="log-normal: variance of ln Y")
+    ap.add_argument("--var", type=float, default=40.0, help="Pareto II: variance of Y")
+    ap.add_argument("--ks", type=float, default=1.0, help="sampling cost")
+    ap.add_argument("--kp", type=float, default=1.0, help="preemption cost")
+    ap.add_argument("--dt", type=float, default=0.005, help="grid step")
+    ap.add_argument("--cite", action="store_true", help="print the BibTeX entry and exit")
+    a = ap.parse_args(argv)
+    if a.cite:
+        print(cite())
+        return
+    if a.dist == "lognormal":
+        d = ServiceDist.lognormal_from_mean(a.mean, a.sigma2)
+    elif a.dist == "pareto2":
+        d = ServiceDist.pareto2(a.mean, a.var)
+    else:
+        d = ServiceDist.exponential(1.0 / a.mean)
+    p = solve(d, a.ks, a.kp, dt=a.dt)
+    print(p.summary())
+    print(f"  sample when AoI reaches z*(0) = {float(p.sampling_target(0.0)):.4f}")
+    print(f"  preempt a fresh service after theta*(z*(0)) = {float(p.preemption_time(p.sampling_target(0.0))):.4f}")
+    print(compare(d, a.ks, a.kp, policy=p))
+    print("\nIf this is useful in your research, please cite:  python -m tailor_aoi --cite")
+
+
+if __name__ == "__main__":
+    main()

tailor_aoi-0.1.0/src/tailor_aoi/baselines.py

@@ -0,0 +1,127 @@
+"""Benchmark policies with exact (renewal-reward) average costs.
+
+A *static* policy ``(D, T)`` waits until the AoI reaches ``D`` before sampling
+and preempts any service that is still running after ``T`` time units.  Its
+long-run average cost (time-average AoI plus sampling/preemption costs per
+unit time) follows from the renewal-reward theorem over delivery cycles:
+
+* the AoI at the start of a cycle is a completed service time ``S ~ Y | Y <= T``;
+* the cycle waits ``W = (D - S)^+`` and then runs ``N`` failed attempts of
+  length ``T`` (geometric, success probability ``F(T)``) and one successful
+  attempt ``S' ~ Y | Y <= T``.
+
+Special cases: Zero-Wait is ``(0, inf)``; Update-or-Wait is ``(beta, inf)``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy import optimize
+
+from .distributions import ServiceDist
+
+
+@dataclass(frozen=True)
+class StaticPolicy:
+    """Wait until AoI >= ``D``, then sample; preempt after ``T`` (``inf`` = never)."""
+
+    D: float
+    T: float
+    name: str = "Static"
+    kind: str = "Static"
+
+    def sampling_target(self, delta):
+        return np.maximum(np.asarray(delta, float), self.D)
+
+    def wait_time(self, delta):
+        return np.maximum(0.0, self.D - np.asarray(delta, float))
+
+    def preemption_time(self, y):
+        return np.full(np.shape(y), self.T, dtype=float)
+
+
+def static_cost(dist: ServiceDist, D: float, T: float, kappa_s: float = 1.0, kappa_p: float = 1.0) -> float:
+    """Exact long-run average cost of the static policy ``(D, T)``."""
+    D = max(float(D), 0.0)
+    T = float(T)
+    p = dist.partial_moment(0, T)  # P(Y <= T)
+    if p <= 0:
+        return np.inf
+    ES = dist.partial_moment(1, T) / p
+    ES2 = dist.partial_moment(2, T) / p
+    a = min(D, T)
+    P_a, m1_a, m2_a = (dist.partial_moment(k, a) for k in range(3))
+    EW = (D * P_a - m1_a) / p
+    idle_area = (D**2 * P_a - m2_a) / (2 * p)  # E[S W + W^2/2]
+    Ey0 = ES + EW
+    if np.isinf(T):
+        EN = EN2 = 0.0
+        EB, EB2 = ES, ES2
+    else:
+        EN = (1 - p) / p
+        EN2 = (1 - p) * (2 - p) / p**2
+        EB = T * EN + ES
+        EB2 = T**2 * EN2 + 2 * T * EN * ES + ES2
+    num = idle_area + Ey0 * EB + 0.5 * EB2 + kappa_s + kappa_p * EN
+    return float(num / (EW + EB))
+
+
+def zero_wait(dist: ServiceDist, kappa_s: float = 1.0, kappa_p: float = 1.0):
+    """Zero-Wait without preemption: sample right after every delivery."""
+    pol = StaticPolicy(0.0, np.inf, name="Zero-Wait")
+    return pol, static_cost(dist, 0.0, np.inf, kappa_s, kappa_p)
+
+
+def update_or_wait(dist: ServiceDist, kappa_s: float = 1.0, kappa_p: float = 1.0, rule: str = "sun"):
+    """Update-or-Wait without preemption (threshold policy ``z = max(Delta, beta)``).
+
+    ``rule="sun"``   : the AoI-optimal threshold of Sun et al. (IEEE TIT 2017),
+                       i.e. the root of E[X] = E[X^2] / (2 beta), X = max(Y, beta).
+                       This is the benchmark used in the ISIT 2026 paper.
+    ``rule="cost"``  : the threshold that minimises the average cost *including*
+                       the sampling cost, i.e. eq. (29) of the paper.
+    """
+    if rule == "sun":
+        def o(beta):
+            Fb = dist.partial_moment(0, beta)
+            EX = beta * Fb + dist.mean - dist.partial_moment(1, beta)
+            EX2 = beta**2 * Fb + dist.second_moment - dist.partial_moment(2, beta)
+            return EX - EX2 / (2 * beta)
+
+        hi = max(dist.mean, 1.0)
+        while o(hi) < 0:
+            hi *= 2
+        beta = optimize.brentq(o, 1e-12, hi, xtol=1e-12)
+    elif rule == "cost":
+        res = optimize.minimize_scalar(
+            lambda b: static_cost(dist, b, np.inf, kappa_s, kappa_p),
+            bounds=(0.0, 50 * dist.mean + dist.second_moment / max(dist.mean, 1e-12)),
+            method="bounded",
+            options={"xatol": 1e-10},
+        )
+        beta = float(res.x)
+    else:
+        raise ValueError("rule must be 'sun' or 'cost'")
+    pol = StaticPolicy(beta, np.inf, name="Update-or-Wait")
+    return pol, static_cost(dist, beta, np.inf, kappa_s, kappa_p)
+
+
+def optimized_static(dist: ServiceDist, kappa_s: float = 1.0, kappa_p: float = 1.0):
+    """Best static (deadline, timeout) policy, found by exact cost minimisation."""
+    f = lambda x: static_cost(dist, np.exp(x[0]), np.exp(x[1]), kappa_s, kappa_p)
+    q = [float(dist.ppf(u)) for u in (0.5, 0.9, 0.99)]
+    best = None
+    for D0 in (0.1 * dist.mean, dist.mean, 3 * dist.mean):
+        for T0 in q + [dist.mean]:
+            r = optimize.minimize(f, x0=np.log([max(D0, 1e-6), max(T0, 1e-6)]), method="Nelder-Mead",
+                                  options={"xatol": 1e-8, "fatol": 1e-10, "maxiter": 4000})
+            if best is None or r.fun < best.fun:
+                best = r
+    D, T = np.exp(best.x)
+    # compare with never preempting
+    pol_np, c_np = update_or_wait(dist, kappa_s, kappa_p, rule="cost")
+    if c_np <= best.fun:
+        return StaticPolicy(pol_np.D, np.inf, name="Optimized Static"), c_np
+    return StaticPolicy(float(D), float(T), name="Optimized Static"), float(best.fun)

tailor_aoi-0.1.0/src/tailor_aoi/distributions.py

@@ -0,0 +1,169 @@
+"""Service-time distributions used by TAILOR.
+
+A ``ServiceDist`` only needs a survival function, a density, a quantile
+function and a sampler.  Partial moments ``E[Y^n; Y <= a]`` (n = 0, 1, 2) are
+used by the exact baseline evaluators; closed forms are provided where they
+exist and numerical quadrature is used otherwise.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable
+
+import numpy as np
+from scipy import integrate, special, stats
+
+
+@dataclass(frozen=True)
+class ServiceDist:
+    """A continuous, non-negative service-time distribution ``Y``.
+
+    Use the constructors :meth:`lomax`, :meth:`pareto2`, :meth:`lognormal`,
+    :meth:`exponential` or :meth:`from_scipy` instead of building it by hand.
+    """
+
+    name: str
+    sf: Callable[[np.ndarray], np.ndarray]
+    pdf: Callable[[np.ndarray], np.ndarray]
+    ppf: Callable[[np.ndarray], np.ndarray]
+    sampler: Callable[[np.random.Generator, int], np.ndarray]
+    mean: float
+    second_moment: float
+    _partial: Callable[[int, float], float] | None = None
+
+    # ------------------------------------------------------------------ API
+    @property
+    def variance(self) -> float:
+        return self.second_moment - self.mean**2
+
+    def cdf(self, t):
+        return 1.0 - self.sf(t)
+
+    def sample(self, n: int, rng: np.random.Generator | int | None = None) -> np.ndarray:
+        rng = np.random.default_rng(rng)
+        return self.sampler(rng, int(n))
+
+    def partial_moment(self, n: int, a: float) -> float:
+        """Return ``E[Y^n ; Y <= a]`` for n in {0, 1, 2}."""
+        if a <= 0:
+            return 0.0
+        if np.isinf(a):
+            return [1.0, self.mean, self.second_moment][n]
+        if self._partial is not None:
+            return float(self._partial(n, a))
+        val, _ = integrate.quad(lambda s: s**n * float(self.pdf(np.array(s))), 0.0, a, limit=400)
+        return float(val)
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"ServiceDist({self.name}, mean={self.mean:.4g}, var={self.variance:.4g})"
+
+    # --------------------------------------------------------- constructors
+    @staticmethod
+    def lomax(alpha: float, scale: float = 1.0) -> "ServiceDist":
+        """Pareto type II (Lomax): ``P(Y > t) = (1 + t/scale)^(-alpha)``.
+
+        Requires ``alpha > 2`` so that ``E[Y^2] < inf``.
+        """
+        if alpha <= 2:
+            raise ValueError("Lomax needs alpha > 2 for a finite second moment.")
+        k, a = float(scale), float(alpha)
+        mean = k / (a - 1)
+        m2 = 2 * k**2 / ((a - 1) * (a - 2))
+
+        def partial(n, x):
+            u = 1 + x / k
+            if n == 0:
+                return 1 - u ** (-a)
+            # E[Y^n; Y<=x] = n * int_0^x s^{n-1} sf(s) ds - x^n sf(x)
+            if n == 1:
+                integral = k / (a - 1) * (1 - u ** (1 - a))
+                return integral - x * u ** (-a)
+            integral = k**2 * ((u ** (2 - a) - 1) / (2 - a) - (u ** (1 - a) - 1) / (1 - a))
+            return 2 * integral - x**2 * u ** (-a)
+
+        return ServiceDist(
+            name=f"Lomax(alpha={a:g}, scale={k:g})",
+            sf=lambda t: (1 + np.asarray(t, float) / k) ** (-a),
+            pdf=lambda t: (a / k) * (1 + np.asarray(t, float) / k) ** (-a - 1),
+            ppf=lambda p: k * ((1 - np.asarray(p, float)) ** (-1 / a) - 1),
+            sampler=lambda rng, n: k * (rng.random(n) ** (-1 / a) - 1),
+            mean=mean,
+            second_moment=m2,
+            _partial=partial,
+        )
+
+    @staticmethod
+    def pareto2(mean: float, variance: float) -> "ServiceDist":
+        """Lomax (Pareto II) parameterised by its mean and variance."""
+        # var/mean^2 = alpha / (alpha - 2)  =>  alpha = 2 r / (r - 1), r = var/mean^2
+        r = variance / mean**2
+        if r <= 1:
+            raise ValueError("Pareto II needs variance > mean^2.")
+        alpha = 2 * r / (r - 1)
+        return ServiceDist.lomax(alpha, scale=mean * (alpha - 1))
+
+    @staticmethod
+    def lognormal(mu: float, sigma: float) -> "ServiceDist":
+        """Log-normal: ``ln Y ~ N(mu, sigma^2)``."""
+        mu, s = float(mu), float(sigma)
+        d = stats.lognorm(s=s, scale=np.exp(mu))
+
+        def partial(n, x):
+            z = (np.log(x) - mu - n * s**2) / s
+            return np.exp(n * mu + 0.5 * n**2 * s**2) * special.ndtr(z)
+
+        return ServiceDist(
+            name=f"LogNormal(mu={mu:g}, sigma^2={s**2:g})",
+            sf=lambda t: d.sf(np.asarray(t, float)),
+            pdf=lambda t: d.pdf(np.asarray(t, float)),
+            ppf=lambda p: d.ppf(np.asarray(p, float)),
+            sampler=lambda rng, n: np.exp(mu + s * rng.standard_normal(n)),
+            mean=float(np.exp(mu + s**2 / 2)),
+            second_moment=float(np.exp(2 * mu + 2 * s**2)),
+            _partial=partial,
+        )
+
+    @staticmethod
+    def lognormal_from_mean(mean: float, sigma2: float) -> "ServiceDist":
+        """Log-normal with a given mean and log-variance ``sigma^2`` (as in the paper)."""
+        return ServiceDist.lognormal(np.log(mean) - sigma2 / 2, np.sqrt(sigma2))
+
+    @staticmethod
+    def exponential(rate: float) -> "ServiceDist":
+        lam = float(rate)
+
+        def partial(n, x):
+            e = np.exp(-lam * x)
+            if n == 0:
+                return 1 - e
+            if n == 1:
+                return (1 - e * (1 + lam * x)) / lam
+            return (2 - e * (2 + 2 * lam * x + (lam * x) ** 2)) / lam**2
+
+        return ServiceDist(
+            name=f"Exp(rate={lam:g})",
+            sf=lambda t: np.exp(-lam * np.asarray(t, float)),
+            pdf=lambda t: lam * np.exp(-lam * np.asarray(t, float)),
+            ppf=lambda p: -np.log1p(-np.asarray(p, float)) / lam,
+            sampler=lambda rng, n: rng.exponential(1 / lam, n),
+            mean=1 / lam,
+            second_moment=2 / lam**2,
+            _partial=partial,
+        )
+
+    @staticmethod
+    def from_scipy(frozen, name: str | None = None) -> "ServiceDist":
+        """Wrap any frozen ``scipy.stats`` continuous distribution on ``[0, inf)``."""
+        m1, m2 = frozen.mean(), frozen.moment(2)
+        if not (np.isfinite(m1) and np.isfinite(m2)):
+            raise ValueError("TAILOR needs E[Y] < inf and E[Y^2] < inf.")
+        return ServiceDist(
+            name=name or frozen.dist.name,
+            sf=lambda t: frozen.sf(np.asarray(t, float)),
+            pdf=lambda t: frozen.pdf(np.asarray(t, float)),
+            ppf=lambda p: frozen.ppf(np.asarray(p, float)),
+            sampler=lambda rng, n: frozen.rvs(size=n, random_state=rng),
+            mean=float(m1),
+            second_moment=float(m2),
+        )

tailor_aoi-0.1.0/src/tailor_aoi/plotting.py

@@ -0,0 +1,41 @@
+"""Plot helpers (matplotlib is imported lazily)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def plot_policy(policy, ax=None, y_max: float | None = None):
+    """Plot the preemption map theta*(y) and the sampling target z*(Delta)."""
+    import matplotlib.pyplot as plt
+
+    if ax is None:
+        _, ax = plt.subplots(1, 2, figsize=(9, 3.4))
+    y = policy.y
+    m = y <= (y_max if y_max is not None else y[-1])
+    ax[0].plot(y[m], policy.theta_map[m], lw=1.8)
+    ax[0].set_xlabel("busy-start AoI $y$")
+    ax[0].set_ylabel(r"preemption time $\theta^\star(y)$")
+    ax[0].grid(alpha=0.3)
+    ax[1].plot(y[m], policy.z_map[m], lw=1.8, label=r"$z^\star(\Delta)$")
+    ax[1].plot(y[m], y[m], "k:", lw=1, label=r"$z=\Delta$ (no wait)")
+    ax[1].set_xlabel(r"AoI at delivery $\Delta$")
+    ax[1].set_ylabel("sampling target")
+    ax[1].legend(frameon=False)
+    ax[1].grid(alpha=0.3)
+    ax[0].figure.tight_layout()
+    return ax
+
+
+def plot_sample_path(ts, ages, preempt_times=(), ax=None, label=None):
+    import matplotlib.pyplot as plt
+
+    if ax is None:
+        _, ax = plt.subplots(figsize=(8, 3))
+    ax.plot(ts, ages, lw=1.4, label=label)
+    for p in np.asarray(preempt_times):
+        ax.axvline(p, color="tab:red", alpha=0.25, lw=0.8)
+    ax.set_xlabel("time")
+    ax.set_ylabel("AoI")
+    ax.grid(alpha=0.3)
+    return ax

tailor_aoi-0.1.0/src/tailor_aoi/simulate.py

@@ -0,0 +1,144 @@
+"""Monte Carlo evaluation of sampling/preemption policies (SMDP-consistent).
+
+Port of ``simulate_aoi_smdp_strict_q99`` in ``Paretov2.m``: after a delivery
+the source waits until the AoI reaches the sampling target and pays
+``kappa_s``; a service still running after ``theta(y)`` is preempted, costs
+``kappa_p`` and restarts immediately with the same AoI.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .distributions import ServiceDist
+
+
+@dataclass
+class SimResult:
+    avg_cost: float
+    avg_aoi: float
+    sampling_rate: float
+    preemption_rate: float
+    q99_aoi: float
+    horizon: float
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        return (f"avg cost {self.avg_cost:.5f} | avg AoI {self.avg_aoi:.5f} | "
+                f"q99 AoI {self.q99_aoi:.4f} | samples/t {self.sampling_rate:.4f} | "
+                f"preemptions/t {self.preemption_rate:.4f}")
+
+
+def _lookup(policy):
+    """Return fast scalar callables z(delta), theta(y) for the given policy."""
+    if getattr(policy, "kind", "") == "TAILOR":
+        zm, tm, dt = policy.z_map, policy.theta_map, policy.dt
+        nz, far = zm.size, policy.rho - policy.slope
+        z_list, t_list = zm.tolist(), tm.tolist()
+
+        def z(d):
+            i = int(round(d / dt))
+            return z_list[i] if i < nz else max(d, far)
+
+        def th(y):
+            i = int(round(y / dt))
+            return t_list[i] if i < nz else t_list[-1]
+
+        return z, th
+    D, T = float(policy.D), float(policy.T)
+    return (lambda d: d if d > D else D), (lambda y: T)
+
+
+def simulate(policy, dist: ServiceDist, kappa_s: float = 1.0, kappa_p: float = 1.0,
+             n_attempts: int = 500_000, rng=None, samples: np.ndarray | None = None) -> SimResult:
+    """Simulate ``n_attempts`` service attempts and return time averages.
+
+    Pass the same ``samples`` array to compare several policies under common
+    random numbers (as done in the paper's MATLAB code).
+    """
+    S_vec = samples if samples is not None else dist.sample(n_attempts, rng)
+    S_list = np.asarray(S_vec, float).tolist()
+    z_of, th_of = _lookup(policy)
+
+    t_now = area = 0.0
+    n_samp = n_pre = 0
+    in_idle, delta, y = True, 0.0, 0.0
+    seg_a, seg_b = [], []
+    for S in S_list:
+        if in_idle:
+            z = z_of(delta)
+            w = z - delta if z > delta else 0.0
+            if w > 0:
+                seg_a.append(delta); seg_b.append(delta + w)
+            area += delta * w + 0.5 * w * w
+            t_now += w
+            n_samp += 1
+            y = delta + w
+            in_idle = False
+        th = th_of(y)
+        dur = S if S <= th else th
+        if dur > 0:
+            seg_a.append(y); seg_b.append(y + dur)
+        area += y * dur + 0.5 * dur * dur
+        t_now += dur
+        if S <= th:
+            delta, in_idle = S, True
+        else:
+            n_pre += 1
+            y += dur
+    avg_aoi = area / t_now
+    return SimResult(
+        avg_cost=(area + kappa_s * n_samp + kappa_p * n_pre) / t_now,
+        avg_aoi=avg_aoi,
+        sampling_rate=n_samp / t_now,
+        preemption_rate=n_pre / t_now,
+        q99_aoi=_time_weighted_quantile(np.array(seg_a), np.array(seg_b), 0.99),
+        horizon=t_now,
+    )
+
+
+def _time_weighted_quantile(a, b, p):
+    """Quantile of the AoI under the time-average distribution (exact sweep)."""
+    L = b - a
+    ok = (L > 0) & np.isfinite(a) & np.isfinite(b)
+    a, b, L = a[ok], b[ok], L[ok]
+    total = L.sum()
+    if total <= 0:
+        return float("nan")
+    x = np.concatenate([a, b])
+    typ = np.concatenate([np.ones(a.size), -np.ones(b.size)])
+    order = np.lexsort((typ, x))
+    x, typ = x[order], typ[order]
+    active = np.cumsum(typ)  # number of active segments right after each event
+    dx = np.diff(x)
+    mass = np.concatenate([[0.0], np.cumsum(active[:-1] * dx) / total])
+    k = np.searchsorted(mass, p)
+    if k >= mass.size:
+        return float(b.max())
+    k0 = k - 1
+    c = active[k0]
+    return float(x[k0] + (p - mass[k0]) * total / c) if c > 0 else float(x[k])
+
+
+def sample_path(policy, dist: ServiceDist, horizon: float = 50.0, rng=None):
+    """Return (time, AoI) breakpoints of one sample path, for plotting."""
+    rng = np.random.default_rng(rng)
+    z_of, th_of = _lookup(policy)
+    t, age = 0.0, 0.0
+    ts, ages, pre = [0.0], [0.0], []
+    while t < horizon:
+        w = max(0.0, z_of(age) - age)
+        if w > 0:
+            t += w; age += w
+            ts.append(t); ages.append(age)
+        while True:
+            S = float(dist.sample(1, rng)[0])
+            th = th_of(age)
+            if S <= th:
+                t += S; ts.append(t); ages.append(age + S)
+                age = S; ts.append(t); ages.append(age)
+                break
+            t += th; age += th
+            ts.append(t); ages.append(age); pre.append(t)
+    return np.array(ts), np.array(ages), np.array(pre)

tailor_aoi-0.1.0/src/tailor_aoi/solver.py

@@ -0,0 +1,336 @@
+"""TAILOR: average-cost policy iteration for joint sampling and preemption.
+
+This is a Python port of the MATLAB solver in ``Paretov2.m`` and implements
+the coupled integral ACOEs of Theorem 1 in
+
+    A. Li, Y. Ince, E. Uysal, "Taming the Heavy Tail: Age-Optimal Preemption",
+    Proc. IEEE ISIT 2026.
+
+Idle phase   h_I(D) = rho*D - D^2/2 + inf_{z>=D} { k_s + v(z) + z^2/2 - rho*z }
+Busy phase   v(y)   = inf_{theta>=0} Q(y, theta; rho)
+             Q      = (y - rho) A(theta) + J1(theta) + int_0^theta h_I dF
+                      + sf(theta) * (k_p + v(y + theta))
+
+Numerics follow Section V-A of the paper: a uniform grid in y, a hybrid
+(uniform + log-spaced) action grid for theta, and a far-field linear closure
+v(y) ~ v(y_cut) + s (y - y_cut) with slope s = E[min(Y, theta_max)].
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+from scipy import sparse
+from scipy.sparse.linalg import spsolve
+
+from .distributions import ServiceDist
+
+
+def _cumtrapz(t: np.ndarray, g: np.ndarray) -> np.ndarray:
+    out = np.zeros_like(g, dtype=float)
+    out[1:] = np.cumsum(0.5 * (g[1:] + g[:-1]) * np.diff(t))
+    return out
+
+
+@dataclass
+class Policy:
+    """Stationary TAILOR policy on the busy-start grid.
+
+    * ``sampling_target(delta)`` returns z*(delta): wait until the AoI reaches
+      this value, then sample (Theorem 1a).
+    * ``preemption_time(y)`` returns theta*(y): starting a service with AoI y,
+      preempt if it has not finished after this long (Theorem 1b).
+    """
+
+    rho: float
+    y: np.ndarray
+    v: np.ndarray
+    z_map: np.ndarray
+    theta_map: np.ndarray
+    dt: float
+    y_cut: float
+    slope: float
+    kappa_s: float
+    kappa_p: float
+    dist_name: str
+    iterations: int
+    converged: bool
+    rho_history: list = field(default_factory=list)
+    kind: str = "TAILOR"
+
+    def sampling_target(self, delta):
+        delta = np.asarray(delta, float)
+        idx = np.rint(delta / self.dt).astype(int)
+        inside = idx < self.z_map.size
+        out = np.maximum(delta, self.rho - self.slope)  # far-field rule
+        out = np.where(inside, self.z_map[np.minimum(idx, self.z_map.size - 1)], out)
+        return out
+
+    def wait_time(self, delta):
+        return np.maximum(0.0, self.sampling_target(delta) - np.asarray(delta, float))
+
+    def preemption_time(self, y):
+        idx = np.rint(np.asarray(y, float) / self.dt).astype(int)
+        return self.theta_map[np.minimum(idx, self.theta_map.size - 1)]
+
+    def summary(self) -> str:
+        return (
+            f"{self.kind} policy for {self.dist_name}: rho = {self.rho:.6f} "
+            f"(k_s={self.kappa_s:g}, k_p={self.kappa_p:g}; "
+            f"{'converged' if self.converged else 'NOT converged'} in {self.iterations} iterations)"
+        )
+
+
+def _action_grid(dt, theta_cap, theta_fine, n_log):
+    theta_fine = min(theta_fine, theta_cap)
+    dense = np.arange(0.0, theta_fine + 0.5 * dt, dt)
+    if theta_fine < theta_cap:
+        a = max(theta_fine, dt)
+        tail = np.exp(np.linspace(np.log(a), np.log(theta_cap), n_log))
+        cand = np.unique(np.concatenate([dense, tail, [theta_cap]]))
+    else:
+        cand = dense
+    cand = np.unique(np.floor(cand / dt + 1e-9) * dt)
+    idx = np.unique(np.rint(cand / dt).astype(int))
+    return idx[idx >= 1]  # forbid theta = 0
+
+
+def solve(
+    dist: ServiceDist,
+    kappa_s: float = 1.0,
+    kappa_p: float = 1.0,
+    *,
+    dt: float = 0.005,
+    y_cut: float | None = None,
+    eps_tail: float = 1e-6,
+    theta_fine: float = 8.0,
+    n_log: int = 250,
+    max_iter: int = 60,
+    tol_v: float = 1e-8,
+    tol_rho: float = 1e-10,
+    verbose: bool = False,
+) -> Policy:
+    """Compute the TAILOR (ACOE-optimal) sampling and preemption policy.
+
+    Parameters
+    ----------
+    dist : ServiceDist
+        Service-time distribution (needs E[Y^2] < inf).
+    kappa_s, kappa_p : float
+        Sampling and preemption costs.
+    dt : float
+        Grid step for the busy-start AoI ``y`` and the action ``theta``.
+    y_cut : float, optional
+        Truncation of the ``y`` grid.  Defaults to ``max(30, 15 E[Y])``.
+    eps_tail : float
+        Largest action ``theta_max`` satisfies ``P(Y > theta_max) = eps_tail``.
+    theta_fine, n_log : float, int
+        Uniform action grid on ``[0, theta_fine]`` and ``n_log`` log-spaced
+        actions on ``[theta_fine, theta_max]``.
+    """
+    if y_cut is None:
+        y_cut = max(30.0, 15.0 * dist.mean)
+    y_cut = np.floor(y_cut / dt) * dt
+
+    theta_cap = float(dist.ppf(1.0 - eps_tail))
+    theta_cap = np.floor(theta_cap / dt) * dt
+    y = np.arange(0.0, y_cut + 0.5 * dt, dt)
+    M = y.size
+    t = np.arange(0.0, theta_cap + 0.5 * dt, dt)
+    T = t.size
+
+    # Kernels: sf, density, A(theta)=int sf, J1(theta)=int s*sf(s) ds
+    barF = np.asarray(dist.sf(t), float)
+    f = np.asarray(dist.pdf(t), float)
+    f[~np.isfinite(f)] = 0.0
+    A = _cumtrapz(t, barF)
+    J1 = _cumtrapz(t, t * barF)
+    slope = float(A[-1])  # far-field slope  ~ E[min(Y, theta_max)] ~ E[Y]
+
+    cand = _action_grid(dt, theta_cap, theta_fine, n_log)
+    rho = 0.0
+    v = np.zeros(M)
+    tau_idx = np.full(M, cand[0])
+    rho_hist = []
+    converged = False
+    z_map = y.copy()
+
+    for it in range(1, max_iter + 1):
+        v_old, rho_old, tau_old = v.copy(), rho, tau_idx.copy()
+        v_cut = v[-1]
+
+        # ---- Step 1: idle envelope  m(i) = min_{j>=i} phi(j)
+        phi = kappa_s + v + 0.5 * y**2 - rho * y
+        rev = phi[::-1]
+        run_min = np.minimum.accumulate(rev)
+        # argmin of the suffix (take the smallest index attaining the min, as in MATLAB)
+        is_new = np.empty(M, bool)
+        is_new[0] = True
+        is_new[1:] = rev[1:] <= run_min[:-1]
+        pos = np.where(is_new, np.arange(M), 0)
+        pos = np.maximum.accumulate(pos)
+        m_grid = run_min[::-1]
+        arg_grid = (M - 1 - pos)[::-1]
+        z_map = y[arg_grid]
+
+        # ---- Step 2: h_I(t) on the action grid t
+        const_ext = kappa_s + v_cut - slope * y_cut
+        inside = t <= y_cut + 1e-12
+        i0 = np.minimum(np.rint(t / dt).astype(int), M - 1)
+        m1 = np.where(inside, m_grid[i0], np.inf)
+        z1 = np.where(inside, y[arg_grid[i0]], np.inf)
+        L = np.maximum(t, y_cut)
+        z2 = np.maximum(L, rho - slope)
+        m2 = 0.5 * z2**2 + (slope - rho) * z2 + const_ext
+        use1 = m1 <= m2
+        z_choice = np.where(use1, z1, z2)
+        m_star = np.where(use1, m1, m2)
+        hI = rho * t - 0.5 * t**2 + m_star
+        I_fh = _cumtrapz(t, f * hI)
+
+        # ---- Step 3: busy improvement (vectorised over y and candidate theta)
+        tc = t[cand]
+        base = J1[cand] - rho * A[cand] + I_fh[cand] + barF[cand] * kappa_p
+        tau_idx = np.empty(M, dtype=int)
+        for s in range(0, M, 512):  # chunk over y to bound memory
+            ys = y[s:s + 512]
+            yplus = ys[:, None] + tc[None, :]
+            v_shift = np.where(
+                yplus <= y_cut,
+                np.interp(np.minimum(yplus, y_cut), y, v),
+                v_cut + slope * (yplus - y_cut),
+            )
+            Q = ys[:, None] * A[cand] + base + barF[cand] * v_shift
+            tau_idx[s:s + 512] = cand[np.argmin(Q, axis=1)]
+
+        # ---- Step 4: policy evaluation (sparse linear system in (rho, v))
+        w = z_choice - t
+        Bw = _cumtrapz(t, f * w)
+        Ccost = _cumtrapz(t, f * (t * w + 0.5 * w**2 + kappa_s))
+        rho, v = _evaluate(
+            y, t, dt, y_cut, slope, f, barF, A, J1, Bw, Ccost, z_choice, tau_idx, kappa_p
+        )
+        rho_hist.append(rho)
+
+        dv = np.max(np.abs(v - v_old))
+        dr = abs(rho - rho_old)
+        dp = int(np.count_nonzero(tau_idx != tau_old))
+        if verbose:
+            print(f"iter {it:2d}: rho={rho:.8f}  |dv|={dv:.2e}  |drho|={dr:.2e}  policy changes={dp}")
+        if dv <= tol_v and dr <= tol_rho and dp == 0:
+            converged = True
+            break
+
+    return Policy(
+        rho=float(rho),
+        y=y,
+        v=v,
+        z_map=z_map,
+        theta_map=t[tau_idx],
+        dt=dt,
+        y_cut=float(y_cut),
+        slope=slope,
+        kappa_s=kappa_s,
+        kappa_p=kappa_p,
+        dist_name=dist.name,
+        iterations=it,
+        converged=converged,
+        rho_history=rho_hist,
+    )
+
+
+def _interp_weights(x, dt, M, y_cut, slope):
+    """Linear-interpolation stencil of v at points x (with far-field closure)."""
+    inside = x <= y_cut + 1e-12
+    iL = np.clip(np.floor(x / dt + 1e-12).astype(int), 0, M - 2)
+    lam = np.where(inside, x / dt - iL, 0.0)
+    lam = np.clip(lam, 0.0, 1.0)
+    iL = np.where(inside, iL, M - 1)
+    const = np.where(inside, 0.0, slope * (x - y_cut))
+    return iL, lam, inside, const
+
+
+def _evaluate(y, t, dt, y_cut, slope, f, barF, A, J1, Bw, Ccost, z_choice, tau_idx, kappa_p):
+    """Solve the Poisson equation for a fixed policy.
+
+    The integral term int_0^theta f(t) v(z(t)) dt is handled with auxiliary
+    cumulative unknowns S_j (one per distinct theta used by the policy) that
+    are chained in increasing order of theta, which keeps the system sparse.
+    """
+    M = y.size
+    used = np.unique(tau_idx)
+    U = used.size
+    n = 1 + M + U  # [rho, v_0..v_{M-1}, S_1..S_U]
+    col_v = 1
+    col_S = 1 + M
+
+    # trapezoid weights: cumulative integral up to index j is
+    #   sum_{k<=j} dt f_k g_k - dt/2 (f_0 g_0 + f_j g_j)
+    iL, lam, inside, zconst = _interp_weights(z_choice, dt, M, y_cut, slope)
+    wk = dt * f
+
+    rows, cols, vals = [], [], []
+    rhs = np.zeros(n)
+
+    # Auxiliary chain: S_u - S_{u-1} - sum_{k in (prev, j]} wk * interp_k(v) = sum wk*const
+    prev = -1
+    for a, j in enumerate(used):
+        r = col_S + a
+        rows.append(r); cols.append(col_S + a); vals.append(1.0)
+        if a > 0:
+            rows.append(r); cols.append(col_S + a - 1); vals.append(-1.0)
+        seg = slice(prev + 1, j + 1)
+        w_seg = wk[seg]
+        il, lm, ins = iL[seg], lam[seg], inside[seg]
+        cw = np.bincount(il, weights=w_seg * np.where(ins, 1 - lm, 1.0), minlength=M)
+        cw += np.bincount(np.minimum(il + 1, M - 1), weights=w_seg * np.where(ins, lm, 0.0), minlength=M)
+        nz = np.nonzero(cw)[0]
+        rows.extend([r] * nz.size); cols.extend((col_v + nz).tolist()); vals.extend((-cw[nz]).tolist())
+        rhs[r] = float(np.sum(w_seg * zconst[seg]))
+        prev = j
+    # Bellman rows i = 0..M-2 (row M-1 replaced by normalisation v(0) = 0)
+    a_of = {j: a for a, j in enumerate(used)}
+    for i in range(M - 1):
+        j = tau_idx[i]
+        r = col_v + i
+        g = A[j] + Bw[j]
+        rv = y[i] * A[j] + J1[j] + Ccost[j] + barF[j] * kappa_p
+        rows += [r, r]; cols += [0, col_v + i]; vals += [g, 1.0]
+        # - c_j . v  =  - (S_j - dt/2 f_0 interp_0(v) - dt/2 f_j interp_j(v))
+        rows.append(r); cols.append(col_S + a_of[j]); vals.append(-1.0)
+        cst = 0.0
+        for k in (0, j):
+            hw = 0.5 * dt * f[k]
+            if hw == 0.0:
+                continue
+            if inside[k]:
+                rows += [r, r]; cols += [col_v + iL[k], col_v + min(iL[k] + 1, M - 1)]
+                vals += [hw * (1 - lam[k]), hw * lam[k]]
+            else:
+                rows.append(r); cols.append(col_v + M - 1); vals.append(hw)
+                cst -= hw * zconst[k]
+        # S_j carries + sum wk*const, so c_j.v-const part: rhs gets + (S const) handled in chain;
+        # remove the half-weights' constants at the endpoints.
+        # - sf(theta) v(y_i + theta)
+        yp = y[i] + t[j]
+        if yp <= y_cut + 1e-12:
+            il = min(int(np.floor(yp / dt + 1e-12)), M - 2)
+            lm = yp / dt - il
+            rows += [r, r]; cols += [col_v + il, col_v + il + 1]
+            vals += [-barF[j] * (1 - lm), -barF[j] * lm]
+            extra = 0.0
+        else:
+            rows.append(r); cols.append(col_v + M - 1); vals.append(-barF[j])
+            extra = barF[j] * slope * (yp - y_cut)
+        rhs[r] = rv + extra + cst
+    # normalisation v(0) = 0  (replaces Bellman row at y_cut)
+    r = col_v + M - 1
+    rows.append(r); cols.append(col_v + 0); vals.append(1.0)
+    # far-field slope closure v(M-1) - v(M-2) = slope * dt (uses the rho "row")
+    rows += [0, 0]; cols += [col_v + M - 1, col_v + M - 2]; vals += [1.0, -1.0]
+    rhs[0] = slope * dt
+
+    Amat = sparse.csr_matrix((vals, (rows, cols)), shape=(n, n))
+    sol = spsolve(Amat.tocsc(), rhs)
+    return float(sol[0]), sol[col_v:col_v + M]

tailor_aoi-0.1.0/src/tailor_aoi.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: tailor-aoi
+Version: 0.1.0
+Summary: Age-optimal sampling and preemption under heavy-tailed delays (TAILOR, IEEE ISIT 2026)
+Author: Aimin Li, Yiğit İnce, Elif Uysal
+License-Expression: MIT
+Project-URL: Paper, https://doi.org/10.1109/ISIT62367.2026.11653616
+Project-URL: arXiv, https://arxiv.org/abs/2601.16624
+Project-URL: Code, https://github.com/AiminLi-Hi/aoi-preemption-heavy-tail
+Project-URL: Project page, https://yigiti.github.io/Preemption/
+Keywords: age of information,AoI,preemption,heavy-tailed delay,optimal stopping,impulse control,queueing,status update,information freshness,policy iteration
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: System :: Networking
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.5; extra == "plot"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# tailor-aoi
+
+Python implementation of **TAILOR**, the age-optimal joint sampling and preemption policy from
+*Taming the Heavy Tail: Age-Optimal Preemption* (A. Li, Y. İnce, E. Uysal, IEEE ISIT 2026,
+[DOI 10.1109/ISIT62367.2026.11653616](https://doi.org/10.1109/ISIT62367.2026.11653616)).
+
+![TAILOR vs. baselines](https://raw.githubusercontent.com/AiminLi-Hi/aoi-preemption-heavy-tail/main/assets/fig2_tailor.png)
+
+## Install
+
+```bash
+pip install tailor-aoi            # core
+pip install "tailor-aoi[plot]"    # with matplotlib helpers
+```
+
+## Use
+
+```python
+from tailor_aoi import ServiceDist, solve, compare
+
+dist = ServiceDist.pareto2(mean=2.0, variance=40.0)   # or lognormal_from_mean, exponential, from_scipy
+policy = solve(dist, kappa_s=1.0, kappa_p=1.0)        # optimal sampling + preemption policy
+print(compare(dist, 1.0, 1.0, policy=policy))         # vs. Update-or-Wait, Zero-Wait, best static
+```
+
+Command line: `python -m tailor_aoi --dist lognormal --mean 2 --sigma2 6`.
+
+- Repository and MATLAB code: https://github.com/AiminLi-Hi/aoi-preemption-heavy-tail
+- Colab quickstart: https://colab.research.google.com/github/AiminLi-Hi/aoi-preemption-heavy-tail/blob/main/python/examples/quickstart.ipynb
+- Project page: https://yigiti.github.io/Preemption/
+
+## Citation
+
+If you use this package, please cite the paper (`python -m tailor_aoi --cite` prints the BibTeX):
+
+```bibtex
+@inproceedings{li2026taming,
+  title     = {Taming the Heavy Tail: Age-Optimal Preemption},
+  author    = {Li, Aimin and {\.I}nce, Yi{\u{g}}it and Uysal, Elif},
+  booktitle = {Proc. IEEE International Symposium on Information Theory (ISIT)},
+  year      = {2026},
+  doi       = {10.1109/ISIT62367.2026.11653616}
+}
+```

tailor_aoi-0.1.0/src/tailor_aoi.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/tailor_aoi/__init__.py
+src/tailor_aoi/__main__.py
+src/tailor_aoi/baselines.py
+src/tailor_aoi/distributions.py
+src/tailor_aoi/plotting.py
+src/tailor_aoi/simulate.py
+src/tailor_aoi/solver.py
+src/tailor_aoi.egg-info/PKG-INFO
+src/tailor_aoi.egg-info/SOURCES.txt
+src/tailor_aoi.egg-info/dependency_links.txt
+src/tailor_aoi.egg-info/requires.txt
+src/tailor_aoi.egg-info/top_level.txt
+tests/test_tailor.py

tailor_aoi-0.1.0/src/tailor_aoi.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

tailor_aoi-0.1.0/src/tailor_aoi.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy>=1.22
+scipy>=1.8
+
+[plot]
+matplotlib>=3.5
+
+[test]
+pytest>=7

tailor_aoi-0.1.0/src/tailor_aoi.egg-info/top_level.txt

@@ -0,0 +1 @@
+tailor_aoi

tailor_aoi-0.1.0/tests/test_tailor.py

@@ -0,0 +1,74 @@
+import numpy as np
+import pytest
+from scipy import integrate
+
+from tailor_aoi import ServiceDist, optimized_static, simulate, solve, static_cost, update_or_wait, zero_wait
+from tailor_aoi.baselines import StaticPolicy
+
+
+@pytest.mark.parametrize("dist", [
+    ServiceDist.lomax(2.5, 1.3),
+    ServiceDist.lognormal(0.2, 0.9),
+    ServiceDist.exponential(0.7),
+])
+@pytest.mark.parametrize("a", [0.3, 1.7, 6.0])
+def test_partial_moments_match_quadrature(dist, a):
+    for n in range(3):
+        ref, _ = integrate.quad(lambda s: s**n * float(dist.pdf(np.array(s))), 0, a)
+        assert dist.partial_moment(n, a) == pytest.approx(ref, rel=1e-7, abs=1e-10)
+
+
+def test_pareto2_parameterisation():
+    d = ServiceDist.pareto2(mean=2.0, variance=40.0)
+    assert d.mean == pytest.approx(2.0)
+    assert d.variance == pytest.approx(40.0)
+
+
+def test_lognormal_from_mean():
+    d = ServiceDist.lognormal_from_mean(2.0, 3.0)
+    assert d.mean == pytest.approx(2.0)
+
+
+@pytest.mark.parametrize("D,T", [(0.0, np.inf), (1.2, np.inf), (0.5, 1.5), (2.0, 0.8)])
+def test_static_cost_matches_monte_carlo(D, T):
+    """Exact renewal-reward cost vs. simulation in a light-tailed case."""
+    d = ServiceDist.lognormal(0.0, 0.5)
+    exact = static_cost(d, D, T, kappa_s=1.0, kappa_p=2.0)
+    mc = simulate(StaticPolicy(D, T), d, 1.0, 2.0, n_attempts=400_000, rng=11).avg_cost
+    assert mc == pytest.approx(exact, rel=0.01)
+
+
+def test_zero_wait_closed_form():
+    d = ServiceDist.lognormal_from_mean(2.0, 6.0)
+    expected = (d.mean**2 + d.second_moment / 2 + 1.0) / d.mean
+    assert zero_wait(d, 1.0, 1.0)[1] == pytest.approx(expected, rel=1e-10)
+
+
+def test_exponential_theorem2():
+    """Theorem 2: v(y) = y / lambda, constant preemption threshold, z* = max(D, rho - 1/lambda)."""
+    lam = 1.0
+    p = solve(ServiceDist.exponential(lam), 1.0, 1.0, dt=0.01)
+    m = p.y <= 10
+    assert np.max(np.abs(p.v[m] - p.y[m] / lam)) < 1e-3
+    assert np.unique(np.round(p.theta_map[m], 6)).size == 1
+    assert p.z_map[0] == pytest.approx(p.rho - 1 / lam, abs=0.011)
+    # optimum for k_s = k_p = 1 equals the best static policy: 1 + sqrt(2)
+    assert p.rho == pytest.approx(1 + np.sqrt(2), abs=1e-3)
+
+
+def test_tailor_beats_baselines_and_matches_simulation():
+    d = ServiceDist.lomax(2.1, 1.0)
+    p = solve(d, 1.0, 5.0)
+    assert p.converged
+    _, c_static = optimized_static(d, 1.0, 5.0)
+    assert p.rho <= c_static + 1e-6
+    assert p.rho < update_or_wait(d, 1.0, 5.0)[1]
+    mc = simulate(p, d, 1.0, 5.0, n_attempts=400_000, rng=5).avg_cost
+    assert mc == pytest.approx(p.rho, rel=0.02)
+
+
+def test_paper_lognormal_headline():
+    """Fig. 2(b): log-normal, E[Y] = 2, sigma^2 = 6, k_s = k_p = 1 -> TAILOR ~ 1.76."""
+    d = ServiceDist.lognormal_from_mean(2.0, 6.0)
+    p = solve(d, 1.0, 1.0)
+    assert p.rho == pytest.approx(1.76, abs=0.01)