most-queue 2.8__py3-none-any.whl → 2.9__py3-none-any.whl

most_queue/__init__.py

@@ -5,12 +5,18 @@ This package provides both simulation and numerical calculation methods
 for various types of queueing systems and networks.
 """
 
-__version__ = "2.7"
+from importlib.metadata import PackageNotFoundError, version
 
 # Import main simulation and theory classes for easy access
 from most_queue.sim.base import QsSim
 from most_queue.theory.base_queue import BaseQueue
 
+try:
+    # single source of truth for the version: the installed package metadata
+    __version__ = version("most-queue")
+except PackageNotFoundError:  # running from a source checkout that is not installed
+    __version__ = "0.0.0.dev0"
+
 __all__ = [
     "QsSim",
     "BaseQueue",

most_queue/random/map_fit.py

@@ -0,0 +1,137 @@
+"""
+Fitting a Markovian Arrival Process (MAP) to data.
+
+The workhorse is the two-state MMPP (MMPP-2): a Poisson process whose rate
+switches between two levels driven by a two-state Markov chain. It is fitted
+by matching three interarrival statistics — the rate, the squared coefficient
+of variation (SCV) and the lag-1 autocorrelation — for which the MAP has
+closed-form expressions (see ``most_queue.random.map_ph``).
+
+An MMPP is always overdispersed and positively correlated: SCV >= 1 and
+lag-1 correlation >= 0. Targets outside this region cannot be represented by
+an MMPP-2 and raise a clear error.
+
+References:
+    Fischer W., Meier-Hellstern K. The Markov-modulated Poisson process (MMPP)
+        cookbook. Performance Evaluation, 18(2), 1993.
+        doi:10.1016/0166-5316(93)90035-s.
+    Heffes H., Lucantoni D. A Markov modulated characterization of packetized
+        voice and data traffic. IEEE JSAC, 4(6), 1986. doi:10.1109/JSAC.1986.1146428.
+"""
+
+import numpy as np
+from scipy.optimize import least_squares
+
+from most_queue.random.map_ph import MAP, MAPParams
+
+
+def map_statistics(params: MAPParams) -> tuple[float, float, float]:
+    """
+    Return (rate, scv, lag1) of a MAP: fundamental arrival rate, squared
+    coefficient of variation and lag-1 autocorrelation of interarrival times.
+    """
+    rate = MAP.arrival_rate(params)
+    moments = MAP.calc_theory_moments(params, 2)
+    m1, m2 = moments[0], moments[1]
+    scv = m2 / (m1 * m1) - 1.0
+    lag1 = MAP.lag_correlation(params, 1)
+    return rate, scv, lag1
+
+
+def _mmpp2_from_vector(x: np.ndarray) -> MAPParams:
+    """Build an MMPP-2 from log-parameters x = log([l1, l2, q12, q21])."""
+    l1, l2, q12, q21 = np.exp(x)
+    return MAP.mmpp([l1, l2], np.array([[-q12, q12], [q21, -q21]]))
+
+
+def fit_mmpp2(
+    rate: float,
+    scv: float,
+    lag1: float,
+    n_restarts: int = 6,
+    tol: float = 1e-9,
+) -> MAPParams:
+    """
+    Fit an MMPP-2 matching the given interarrival rate, SCV and lag-1
+    autocorrelation.
+
+    :param rate: target fundamental arrival rate (> 0)
+    :param scv: target squared coefficient of variation (>= 1 for an MMPP)
+    :param lag1: target lag-1 autocorrelation (>= 0 for an MMPP)
+    :param n_restarts: number of random restarts for the local optimizer
+    :param tol: acceptable residual norm to stop early
+    :return: MAPParams of the fitted MMPP-2
+    :raises ValueError: if the target is outside the MMPP-representable region
+    """
+    if rate <= 0:
+        raise ValueError(f"rate must be positive, got {rate}")
+    if scv < 1.0 - 1e-6:
+        raise ValueError(f"an MMPP-2 requires SCV >= 1 (overdispersed), got {scv:.4f}")
+    if lag1 < -1e-6:
+        raise ValueError(f"an MMPP-2 requires non-negative lag-1 correlation, got {lag1:.4f}")
+
+    target = np.array([rate, scv, lag1])
+    weights = np.array([1.0 / max(rate, 1e-9), 1.0, 1.0])
+
+    def residuals(x: np.ndarray) -> np.ndarray:
+        try:
+            stats = np.array(map_statistics(_mmpp2_from_vector(x)))
+        except (np.linalg.LinAlgError, ValueError):
+            return np.full(3, 1e3)
+        return (stats - target) * weights
+
+    rng = np.random.default_rng(12345)
+    best = np.log([rate, rate, 0.1 * rate + 1e-3, 0.1 * rate + 1e-3])
+    best_cost = np.inf
+    for k in range(max(1, n_restarts)):
+        if k == 0:
+            # deterministic heuristic start: rates spread by the overdispersion,
+            # slow switching to create the correlation
+            spread = 1.0 + np.sqrt(max(scv - 1.0, 0.0))
+            x0 = np.log([rate * spread, rate / spread, 0.1 * rate + 1e-3, 0.1 * rate + 1e-3])
+        else:
+            x0 = np.log(rate) + rng.uniform(-2.0, 2.0, size=4)
+        # trf (not lm): the 4-parameter MMPP-2 is under-determined by the
+        # 3 target statistics, so residuals < variables is expected
+        sol = least_squares(residuals, x0, method="trf", max_nfev=2000)
+        if sol.cost < best_cost:
+            best, best_cost = sol.x, sol.cost
+            if np.linalg.norm(sol.fun) < tol:
+                break
+
+    fitted = _mmpp2_from_vector(best)
+    achieved = map_statistics(fitted)
+    err = np.abs(np.array(achieved) - target) * weights
+    if np.max(err) > 1e-2:
+        raise ValueError(
+            f"failed to fit MMPP-2 to (rate={rate:.4f}, scv={scv:.4f}, lag1={lag1:.4f}); "
+            f"achieved (rate={achieved[0]:.4f}, scv={achieved[1]:.4f}, lag1={achieved[2]:.4f}). "
+            "The target may be near the boundary of the MMPP-representable region."
+        )
+    return fitted
+
+
+def trace_statistics(interarrivals) -> tuple[float, float, float]:
+    """
+    Empirical (rate, scv, lag1) of a sequence of interarrival times.
+    """
+    x = np.asarray(interarrivals, dtype=float)
+    if x.size < 3:
+        raise ValueError("need at least 3 interarrival samples")
+    mean = x.mean()
+    scv = x.var() / (mean * mean)
+    lag1 = float(np.corrcoef(x[:-1], x[1:])[0, 1])
+    return 1.0 / mean, scv, lag1
+
+
+def fit_map_from_trace(interarrivals, **kwargs) -> MAPParams:
+    """
+    Fit an MMPP-2 to a trace of interarrival times by matching its empirical
+    rate, SCV and lag-1 autocorrelation.
+
+    :param interarrivals: sequence of interarrival times
+    :param kwargs: forwarded to :func:`fit_mmpp2`
+    :return: MAPParams of the fitted MMPP-2
+    """
+    rate, scv, lag1 = trace_statistics(interarrivals)
+    return fit_mmpp2(rate, max(scv, 1.0), max(lag1, 0.0), **kwargs)

most_queue/random/map_ph.py

@@ -43,6 +43,54 @@ class MAPParams:
     D1: np.ndarray  # transitions generating an arrival, shape (m, m)
 
 
+@dataclass
+class BMAPParams:
+    """
+    Batch Markovian Arrival Process parameters: a list of matrices
+    D[0], D[1], D[2], ... where D[0] holds phase transitions without arrivals
+    and D[k] (k >= 1) holds transitions that generate a batch of k arrivals.
+    sum_k D[k] is the generator of the phase process.
+    """
+
+    D: list  # [D0, D1, D2, ...], each an (m, m) matrix
+
+
+def bmap_poisson_batch(rate: float, batch_probs: list) -> BMAPParams:
+    """
+    Single-phase BMAP: batches arrive as a Poisson process of intensity
+    ``rate`` with batch-size probabilities ``batch_probs`` (batch_probs[k-1] is
+    P(batch size = k)). Equivalent to the M^[X]/... batch arrival stream.
+    """
+    p = np.asarray(batch_probs, dtype=float)
+    if abs(p.sum() - 1.0) > 1e-9 or np.any(p < 0):
+        raise ValueError("batch_probs must be a probability vector")
+    d = [np.array([[-rate]])]
+    for pk in p:
+        d.append(np.array([[rate * pk]]))
+    return BMAPParams(D=d)
+
+
+def bmap_from_map(params: MAPParams) -> BMAPParams:
+    """A MAP as a BMAP with only size-1 batches (D[1] = D1)."""
+    return BMAPParams(D=[np.asarray(params.D0, dtype=float), np.asarray(params.D1, dtype=float)])
+
+
+def bmap_arrival_rate(params: BMAPParams) -> float:
+    """
+    Fundamental arrival rate of a BMAP: pi @ (sum_k k * D[k]) @ 1, where pi is
+    the stationary distribution of the phase generator sum_k D[k].
+    """
+    mats = [np.asarray(x, dtype=float) for x in params.D]
+    gen = np.sum(mats, axis=0)
+    m = gen.shape[0]
+    a = np.vstack([gen.T, np.ones(m)])
+    b = np.zeros(m + 1)
+    b[-1] = 1.0
+    pi, *_ = np.linalg.lstsq(a, b, rcond=None)
+    batch_rate = np.sum([k * mats[k] for k in range(1, len(mats))], axis=0)
+    return float(pi @ batch_rate @ np.ones(m))
+
+
 def _validate_ph(alpha: np.ndarray, T: np.ndarray) -> None:
     if T.ndim != 2 or T.shape[0] != T.shape[1]:
         raise ValueError("T must be a square matrix")

most_queue/sim/aoi.py

@@ -0,0 +1,133 @@
+"""
+Discrete-event simulator for Age of Information (AoI).
+
+Tracks the sawtooth age process Delta(t) = t - u(t), where u(t) is the
+generation time of the freshest *delivered* update, and reports the time-average
+AoI and the average peak AoI (PAoI). Supports FCFS, LCFS (non-preemptive) and
+LCFS-preemptive (a fresh arrival preempts and discards the in-service update)
+disciplines on one or more servers.
+"""
+
+from most_queue.random.utils.create import create_distribution
+from most_queue.sim.base_core import BaseSimulationCore
+from most_queue.structs import AoIResults
+
+
+class AoISim(BaseSimulationCore):
+    """
+    Age-of-Information simulator.
+
+    :param num_channels: number of servers.
+    :param discipline: "FCFS", "LCFS" (non-preemptive) or "LCFS-PR" (preemptive:
+        a new update preempts and discards the one in service).
+    :param seed: RNG seed for reproducible runs.
+    """
+
+    def __init__(self, num_channels: int = 1, discipline: str = "FCFS", seed: int | None = None):
+        super().__init__(seed=seed)
+        self.n = num_channels
+        self.discipline = discipline.upper()
+        if self.discipline == "LCFS-PR" and num_channels != 1:
+            raise ValueError("LCFS-PR is only supported for a single server")
+        self.source = None
+        self.server = None
+        self.is_sources_set = False
+        self.is_servers_set = False
+
+    def set_sources(self, params, kendall_notation: str = "M"):
+        """Set the arrival (update generation) process."""
+        self.source = create_distribution(params, kendall_notation, self.generator)
+        self.is_sources_set = True
+
+    def set_servers(self, params, kendall_notation: str = "M"):
+        """Set the service (update delivery) process."""
+        self.server = create_distribution(params, kendall_notation, self.generator)
+        self.is_servers_set = True
+
+    def run(self, num_updates: int, warmup_fraction: float = 0.05) -> AoIResults:
+        """
+        Run until `num_updates` fresh deliveries have been counted after warm-up.
+
+        :param warmup_fraction: initial fraction of deliveries discarded before
+            age accounting begins (removes transient bias).
+        """
+        if not (self.is_sources_set and self.is_servers_set):
+            raise RuntimeError("sources and servers must be set before run()")
+
+        INF = float("inf")
+        t = 0.0
+        next_arrival = self.source.generate()
+        server_done = [INF] * self.n  # completion time per server
+        server_gen = [0.0] * self.n  # generation time of the update in service
+        queue: list[float] = []  # generation times of waiting updates (arrival order)
+
+        freshest_gen = 0.0  # generation time of the freshest delivered update
+        area = 0.0  # integral of the age over the accounting window
+        peak_sum = 0.0
+        delivered = 0
+        counted = 0  # fresh deliveries counted after warm-up
+        accounting = False
+        acct_start_t = 0.0
+        last_t = 0.0
+        warmup = int(num_updates * warmup_fraction)
+        target = num_updates + warmup
+
+        def free_server():
+            for i in range(self.n):
+                if server_done[i] == INF:
+                    return i
+            return -1
+
+        def start(gen_time):
+            i = free_server()
+            server_gen[i] = gen_time
+            server_done[i] = t + self.server.generate()
+
+        while delivered < target:
+            done_idx = min(range(self.n), key=lambda i: server_done[i])
+            next_done = server_done[done_idx]
+
+            if next_arrival <= next_done:
+                # ---- arrival of a new update ----
+                t = next_arrival
+                next_arrival = t + self.source.generate()
+                gen = t
+                if self.discipline == "LCFS-PR":
+                    server_gen[0] = gen
+                    server_done[0] = t + self.server.generate()
+                elif free_server() != -1:
+                    start(gen)
+                else:
+                    queue.append(gen)
+            else:
+                # ---- delivery of an update ----
+                t = next_done
+                gen = server_gen[done_idx]
+                server_done[done_idx] = INF
+                delivered += 1
+                is_fresh = gen > freshest_gen
+
+                if accounting and is_fresh:
+                    # age grew as (t - freshest_gen) then resets: accumulate the
+                    # trapezoid and record the peak (age just before the reset)
+                    area += ((t - freshest_gen) ** 2 - (last_t - freshest_gen) ** 2) / 2.0
+                    peak_sum += t - freshest_gen
+                    last_t = t
+                    counted += 1
+                if is_fresh:
+                    freshest_gen = gen
+
+                if not accounting and delivered >= warmup:
+                    accounting = True
+                    acct_start_t = t
+                    last_t = t
+                    freshest_gen = gen
+
+                if queue:
+                    nxt = queue.pop() if self.discipline == "LCFS" else queue.pop(0)
+                    start(nxt)
+
+        # area is accumulated up to the last fresh delivery (last_t); the window
+        # is [acct_start_t, last_t]
+        window = max(last_t - acct_start_t, 1e-12)
+        return AoIResults(avg_aoi=area / window, peak_aoi=peak_sum / max(counted, 1))

most_queue/sim/base.py

@@ -26,15 +26,16 @@ class QsSim(BaseSimulationCore):
     Base class for Queueing System Simulator
     """
 
-    def __init__(self, num_of_channels, buffer=None, verbose=True, buffer_type="list"):
+    def __init__(self, num_of_channels, buffer=None, verbose=True, buffer_type="list", seed=None):
         """
         Initialize the queueing system with GI/G/n/r or GI/G/n model.
         :param num_of_channels: int : number of channels in the system
         :param buffer: Optional(int, None) : maximum length of the queue, None if infinite
         :param verbose: bool : whether to print detailed information during simulation
         :param buffer_type: str : type of the buffer, "list" or "deque"
+        :param seed: Optional(int, None) : RNG seed for reproducible runs (None — non-deterministic)
         """
-        super().__init__()
+        super().__init__(seed=seed)
 
         self.n = num_of_channels
         self.buffer = buffer

most_queue/sim/base_core.py

@@ -13,10 +13,14 @@ class BaseSimulationCore:
     Contains common attributes and methods shared across different simulator types.
     """
 
-    def __init__(self):
-        """Initialize the base simulation core."""
+    def __init__(self, seed: int | None = None):
+        """Initialize the base simulation core.
+
+        :param seed: optional RNG seed for reproducible simulation runs
+            (None — non-deterministic, as before).
+        """
         self.ttek = 0  # current simulation time
-        self.generator = np.random.default_rng()
+        self.generator = np.random.default_rng(seed)
         self.time_spent = 0
 
         # Statistics for busy periods

most_queue/sim/bmap.py

@@ -0,0 +1,130 @@
+"""
+Simulation of a BMAP/PH/1 queue: batch Markovian arrivals, phase-type service,
+single FCFS server. Used to validate the analytical BmapPh1Calc.
+"""
+
+import time
+
+import numpy as np
+
+from most_queue.random.map_ph import BMAPParams, PHDistribution, PHParams
+from most_queue.structs import QueueResults
+
+NUM_OF_MOMENTS = 4
+P_NUM = 100
+
+
+class BmapPh1Sim:
+    """
+    Discrete-event simulator for BMAP/PH/1. The BMAP phase process jumps between
+    phases; a jump via D[k] (k >= 1) emits a batch of k jobs; jobs are served
+    FCFS with phase-type service.
+    """
+
+    def __init__(self, bmap: BMAPParams, ph: PHParams, seed: int | None = None):
+        self.generator = np.random.default_rng(seed)
+        self.d = [np.asarray(x, dtype=float) for x in bmap.D]
+        self.bmap = bmap
+        self.ph = ph
+        self.m = self.d[0].shape[0]
+        self._build_jump_table()
+        self.ttek = 0.0
+        self.served = 0
+        self.busy_time = 0.0
+        self.v = [0.0] * NUM_OF_MOMENTS
+        self.w = [0.0] * NUM_OF_MOMENTS
+        self.p_time = [0.0] * P_NUM
+
+    def _build_jump_table(self):
+        """Per phase: list of (rate, target_phase, batch_size) and total out-rate.
+
+        The total event rate out of phase i is -D0[i][i]: the D0 diagonal
+        absorbs every outgoing rate, silent phase changes and batch arrivals
+        alike.
+        """
+        self.out_rate = -np.diag(self.d[0])
+        self.jumps = [[] for _ in range(self.m)]
+        for i in range(self.m):
+            for j in range(self.m):
+                if j != i and self.d[0][i, j] > 0:
+                    self.jumps[i].append((self.d[0][i, j], j, 0))  # silent D0 transition
+            for k in range(1, len(self.d)):
+                for j in range(self.m):
+                    if self.d[k][i, j] > 0:
+                        self.jumps[i].append((self.d[k][i, j], j, k))  # batch of k
+
+    def _next_batch(self, phase):
+        """Sample time to the next BMAP transition and its (target phase, batch size)."""
+        rate = self.out_rate[phase]
+        dt = self.generator.exponential(1.0 / rate)
+        opts = self.jumps[phase]
+        probs = np.array([o[0] for o in opts]) / rate
+        idx = int(self.generator.choice(len(opts), p=probs))
+        _, target, batch = opts[idx]
+        return dt, target, batch
+
+    def _advance(self, dt, in_sys):
+        if in_sys < P_NUM:
+            self.p_time[in_sys] += dt
+        if in_sys > 0:
+            self.busy_time += dt
+
+    def run(self, total_served: int) -> QueueResults:
+        """Run until total_served jobs have departed."""
+        start_time = time.process_time()
+        rng = self.generator
+        phase = int(rng.choice(self.m))
+        queue = []  # arrival times of waiting jobs
+        service_end = None
+        current_arr = None
+        dt, next_phase, batch = self._next_batch(phase)
+        next_bmap = self.ttek + dt
+
+        while self.served < total_served:
+            in_sys = len(queue) + (1 if service_end is not None else 0)
+            if service_end is not None and service_end <= next_bmap:
+                # service completion
+                self._advance(service_end - self.ttek, in_sys)
+                self.ttek = service_end
+                self._register(self.ttek - current_arr)
+                if queue:
+                    current_arr = queue.pop(0)
+                    service_end = self.ttek + PHDistribution(self.ph, generator=rng).generate()
+                else:
+                    service_end = None
+                    current_arr = None
+            else:
+                # BMAP transition (possibly a batch)
+                self._advance(next_bmap - self.ttek, in_sys)
+                self.ttek = next_bmap
+                for _ in range(batch):
+                    if service_end is None:
+                        current_arr = self.ttek
+                        service_end = self.ttek + PHDistribution(self.ph, generator=rng).generate()
+                    else:
+                        queue.append(self.ttek)
+                phase = next_phase
+                dt, next_phase, batch = self._next_batch(phase)
+                next_bmap = self.ttek + dt
+
+        return self._results(start_time)
+
+    def _register(self, sojourn):
+        # service = sojourn - waiting; but we only kept arrival time, so recover
+        # waiting from the job's own service is not tracked here — use sojourn and
+        # a separate service sample is not needed: W = V - S is done at aggregate
+        # level via Little in the calculator. Here we store sojourn; waiting is
+        # sojourn minus the realised service, which we did not keep, so store
+        # sojourn only and derive mean waiting as mean sojourn - mean service.
+        self.served += 1
+        for k in range(NUM_OF_MOMENTS):
+            self.v[k] += sojourn ** (k + 1)
+
+    def _results(self, start_time):
+        v = [m / self.served for m in self.v]
+        t_mat = np.asarray(self.ph.T)
+        b1 = float(np.asarray(self.ph.alpha) @ np.linalg.inv(-t_mat) @ np.ones(t_mat.shape[0]))
+        w = [v[0] - b1]  # mean waiting = mean sojourn - mean service
+        p = [float(t / self.ttek) for t in self.p_time]
+        utilization = float(self.busy_time / self.ttek)
+        return QueueResults(v=v, w=w, p=p, utilization=utilization, duration=time.process_time() - start_time)

most_queue/sim/bulk_service.py

@@ -0,0 +1,95 @@
+"""
+Discrete-event simulator for the M/G^[a,b]/1 bulk-service queue.
+
+The server waits until at least `a` customers are queued, then serves a batch of
+up to `b` of them together; the whole batch leaves after one (exponential or
+general) batch-service time, which may depend on the batch size.
+"""
+
+from most_queue.random.utils.create import create_distribution
+from most_queue.sim.base_core import BaseSimulationCore
+from most_queue.structs import QueueResults
+
+
+class BulkServiceSim(BaseSimulationCore):
+    """
+    Bulk-service single-server simulator.
+
+    :param a: minimum batch size to start service.
+    :param b: maximum batch size.
+    :param seed: RNG seed.
+    """
+
+    def __init__(self, a: int = 1, b: int = 1, seed: int | None = None):
+        super().__init__(seed=seed)
+        self.a = a
+        self.b = b
+        self.source = None
+        self.mu_fn = None
+        self.batch_kendall = "M"
+        self.is_sources_set = False
+        self.is_servers_set = False
+
+    def set_sources(self, params, kendall_notation: str = "M"):
+        """Set the arrival process."""
+        self.source = create_distribution(params, kendall_notation, self.generator)
+        self.is_sources_set = True
+
+    def set_servers(self, mu):
+        """
+        :param mu: batch-service rate — scalar (Exp(mu)) or callable mu(batch_size).
+        """
+        if callable(mu):
+            self.mu_fn = mu
+        else:
+            self.mu_fn = lambda _i, _mu=float(mu): _mu
+        self.is_servers_set = True
+
+    def run(self, total_served: int, warmup_fraction: float = 0.05) -> QueueResults:
+        """Run until `total_served` customers have departed; return mean w and v."""
+        if not (self.is_sources_set and self.is_servers_set):
+            raise RuntimeError("sources and servers must be set before run()")
+
+        INF = float("inf")
+        t = 0.0
+        next_arrival = self.source.generate()
+        queue: list[float] = []  # arrival times of waiting customers (FCFS)
+        server_busy = False
+        server_done = INF
+        batch: list[float] = []  # arrival times of the in-service batch
+        batch_start = 0.0
+
+        soj_sum = 0.0
+        wait_sum = 0.0
+        served = 0
+        warmup = int(total_served * warmup_fraction)
+
+        def maybe_start():
+            nonlocal server_busy, server_done, batch, batch_start
+            if not server_busy and len(queue) >= self.a:
+                take = min(self.b, len(queue))
+                batch = [queue.pop(0) for _ in range(take)]
+                server_busy = True
+                batch_start = t
+                server_done = t + self.generator.exponential(1.0 / self.mu_fn(take))
+
+        while served < total_served + warmup:
+            if next_arrival <= server_done:
+                t = next_arrival
+                queue.append(t)
+                next_arrival = t + self.source.generate()
+                maybe_start()
+            else:
+                t = server_done
+                for arr in batch:
+                    if served >= warmup:
+                        soj_sum += t - arr
+                        wait_sum += batch_start - arr
+                    served += 1
+                server_busy = False
+                server_done = INF
+                batch = []
+                maybe_start()
+
+        n = max(served - warmup, 1)
+        return QueueResults(v=[soj_sum / n, 0, 0, 0], w=[wait_sum / n, 0, 0, 0])