most-queue 2.8__py3-none-any.whl → 2.11__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/io/serving.py

@@ -0,0 +1,258 @@
+"""Audited request-level serving measurements and joint TTFT/TPOT SLOs.
+
+Reference serializer: vLLM v0.33.0rc3, commit
+4ba787ec9959e566d3b587a796dff07673324da5, vllm/benchmarks/serve.py.
+TTFT and latency are client measurements; queue_times is CLIENT semaphore
+waiting. Server timings are separate optional measurements, never inferred.
+The SGLang array reader explicitly uses the span of streamed output events
+when full per-request latencies are absent. See docs/serving_measurements.md.
+"""
+
+import json
+import math
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class ServingRequest:
+    """One offered request; all durations are seconds and counts are actual.
+
+    A pending request has an unknown final latency/TPOT. Failed and cancelled
+    requests remain in the offered denominator. An absent measurement is None.
+    """
+
+    input_tokens: int
+    output_tokens: int
+    status: str
+    ttft: float | None = None
+    latency: float | None = None
+    client_queue_time: float | None = None
+    server_queue_time: float | None = None
+    server_ttft: float | None = None
+
+    def __post_init__(self):
+        if self.status not in {"completed", "failed", "cancelled", "pending"}:
+            raise ValueError("unknown request status")
+        for count in (self.input_tokens, self.output_tokens):
+            if isinstance(count, bool) or not isinstance(count, (int, np.integer)) or count < 0:
+                raise ValueError("token counts must be nonnegative integers")
+        for value in (self.ttft, self.latency, self.client_queue_time, self.server_queue_time, self.server_ttft):
+            if value is not None and (not math.isfinite(value) or value < 0):
+                raise ValueError("measured durations must be finite and nonnegative, or None")
+        if self.status == "completed":
+            if min(self.input_tokens, self.output_tokens) < 1 or self.ttft is None or self.latency is None:
+                raise ValueError("completed text requests require positive lengths, TTFT and latency")
+            if self.latency < self.ttft:
+                raise ValueError("latency cannot precede the first token")
+        elif self.latency is not None:
+            raise ValueError("only completed requests have a final latency")
+
+    @property
+    def tpot(self):
+        """Per-request TPOT, excluding the first token; None for <=1 token."""
+        if self.status != "completed" or self.output_tokens <= 1:
+            return None
+        return (self.latency - self.ttft) / (self.output_tokens - 1)
+
+
+@dataclass(frozen=True)
+class ServingBenchmark:
+    """A finite offered cohort and its explicit measurement-window duration."""
+
+    requests: tuple[ServingRequest, ...]
+    duration: float
+    metadata: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        if not self.requests or not all(isinstance(row, ServingRequest) for row in self.requests):
+            raise ValueError("a benchmark requires a nonempty request cohort")
+        if not math.isfinite(self.duration) or self.duration <= 0:
+            raise ValueError("duration must be finite and positive")
+
+
+def _read_arrays(source, schema):
+    data = json.loads(Path(source).read_text(encoding="utf-8")) if isinstance(source, (str, Path)) else source
+    if not isinstance(data, dict):
+        raise ValueError("expected a single benchmark JSON object")
+    required = ["input_lens", "output_lens", "ttfts", "errors"]
+    required += ["latencies"] if schema == "vllm-bench-serve" else ["itls"]
+    if any(not isinstance(data.get(key), list) for key in required):
+        raise ValueError("detailed per-request arrays are required; aggregate percentiles are insufficient")
+    count = len(data["input_lens"])
+    if not count or any(len(data[key]) != count for key in required):
+        raise ValueError("per-request arrays must be nonempty and aligned")
+    optional = ["queue_times", "server_queue_times", "server_ttfts"]
+    for key in optional:
+        if key in data and (not isinstance(data[key], list) or len(data[key]) != count):
+            raise ValueError(f"{key} must align with the request arrays")
+    rows = []
+    for index in range(count):
+        error = data["errors"][index]
+        if not isinstance(error, str):
+            raise ValueError("each error must be a string")
+        completed = error == "" and data["output_lens"][index] > 0
+        latency = None
+        if completed:
+            if schema == "vllm-bench-serve":
+                latency = data["latencies"][index]
+            else:
+                gaps = np.asarray(data["itls"][index], dtype=float)
+                if gaps.ndim != 1 or not np.all(np.isfinite(gaps)) or np.any(gaps < 0):
+                    raise ValueError("stream gaps must be finite nonnegative vectors")
+                latency = float(data["ttfts"][index] + gaps.sum())
+        timings = {key: data[key][index] if completed and key in data else None for key in optional}
+        rows.append(
+            ServingRequest(
+                input_tokens=data["input_lens"][index],
+                output_tokens=data["output_lens"][index],
+                status="completed" if completed else "failed",
+                ttft=data["ttfts"][index] if completed else None,
+                latency=latency,
+                client_queue_time=timings["queue_times"],
+                server_queue_time=timings["server_queue_times"],
+                server_ttft=timings["server_ttfts"],
+            )
+        )
+    successes = sum(row.status == "completed" for row in rows)
+    if data.get("completed") != successes or ("failed" in data and data["failed"] != count - successes):
+        raise ValueError("aggregate completion/failure counts disagree with detailed outcomes")
+    if "num_prompts" in data and data["num_prompts"] != count:
+        raise ValueError("num_prompts disagrees with offered cohort; do not silently drop requests")
+    metadata = {
+        key: data[key]
+        for key in ["model_id", "backend", "max_concurrency", "request_rate", "dataset_name"]
+        if key in data
+    }
+    metadata.update(schema=schema, latency_basis="client_latency" if schema == "vllm-bench-serve" else "stream_span")
+    if metadata.get("request_rate") == math.inf:
+        metadata["request_rate"] = "inf"
+    return ServingBenchmark(tuple(rows), data["duration"], metadata)
+
+
+def read_vllm_benchmark(source, *, measurement_profile=None):
+    """Read vLLM detailed JSON; preserve absent server metrics as None.
+
+    The caller must retain the producer version and hardware provenance. This
+    is a schema adapter, not detection of the engine/version from latency data.
+    """
+    result = _read_arrays(source, "vllm-bench-serve")
+    result.metadata["measurement_profile"] = measurement_profile
+    return result
+
+
+def read_sglang_stream_benchmark(source, *, measurement_profile=None):
+    """Read detailed streaming arrays with TTFT + sum(ITL) as observed span.
+
+    The span ends at the last output event, not necessarily HTTP completion.
+    ITL entries can contain multiple tokens; TPOT uses actual output_tokens.
+    """
+    result = _read_arrays(source, "sglang-stream-arrays")
+    result.metadata["measurement_profile"] = measurement_profile
+    return result
+
+
+def _quantiles(values):
+    if not values:
+        return None
+    return {
+        "count": len(values),
+        "mean": float(np.mean(values)),
+        **dict(zip(["p50", "p90", "p99"], np.percentile(values, [50, 90, 99]).tolist())),
+    }
+
+
+def summarize_serving_slo(benchmark, *, ttft_limit, tpot_limit):
+    """Joint request SLO with all offered outcomes and pending-outcome bounds.
+
+    Completed one-token replies pass the TPOT condition by the vLLM goodput
+    convention but are excluded from TPOT means/quantiles. Pending requests
+    are unknown unless their already-observed TTFT violates its limit.
+    Counts/quantiles describe this cohort, without an iid confidence claim.
+    """
+    if any(not math.isfinite(value) or value < 0 for value in (ttft_limit, tpot_limit)):
+        raise ValueError("SLO limits must be finite nonnegative seconds")
+    counts = {status: 0 for status in ["completed", "failed", "cancelled", "pending"]}
+    passed, unknown, single_token = 0, 0, 0
+    ttfts, tpots = [], []
+    for row in benchmark.requests:
+        counts[row.status] += 1
+        if row.status == "completed":
+            ttfts.append(row.ttft)
+            if row.tpot is None:
+                single_token += 1
+            else:
+                tpots.append(row.tpot)
+            passed += row.ttft <= ttft_limit and (row.tpot is None or row.tpot <= tpot_limit)
+        elif row.status == "pending" and (row.ttft is None or row.ttft <= ttft_limit):
+            unknown += 1
+    offered = len(benchmark.requests)
+    return {
+        "offered": offered,
+        **counts,
+        "single_token_completed": single_token,
+        "joint_passed": passed,
+        "joint_unknown": unknown,
+        "joint_fraction_bounds": [passed / offered, (passed + unknown) / offered],
+        "observed_goodput": passed / benchmark.duration,
+        "duration": benchmark.duration,
+        "ttft_limit": ttft_limit,
+        "tpot_limit": tpot_limit,
+        "completed_ttft_seconds": _quantiles(ttfts),
+        "completed_multitoken_tpot_seconds": _quantiles(tpots),
+        "server_queue_observed": sum(row.server_queue_time is not None for row in benchmark.requests),
+        "server_ttft_observed": sum(row.server_ttft is not None for row in benchmark.requests),
+        "latency_basis": benchmark.metadata.get("latency_basis", "explicit_request_records"),
+        "uncertainty": "pending-outcome bounds; no iid confidence interval",
+    }
+
+
+def from_prefill_decode(result, arrivals, inputs, outputs, *, horizon=None):
+    """Convert token DES timestamps; optionally censor at a fixed horizon.
+
+    Future requests are outside the offered cohort. Future completions and
+    tokens are hidden rather than counted as successful outcomes at the cut.
+    No steady-state or stationarity assertion is made for the drained cohort.
+    """
+    arrivals = np.asarray(arrivals, dtype=float)
+    if arrivals.ndim != 1 or not arrivals.size or not np.all(np.isfinite(arrivals)) or np.any(np.diff(arrivals) < 0):
+        raise ValueError("arrivals must be nonempty finite chronological times")
+    if any(len(values) != len(arrivals) for values in [inputs, outputs, result.output_times, result.completion_times]):
+        raise ValueError("DES arrays must align")
+    for lengths in (inputs, outputs):
+        values = np.asarray(lengths, dtype=float)
+        if not np.all(np.isfinite(values)) or np.any(values <= 0) or np.any(values != np.floor(values)):
+            raise ValueError("DES token lengths must be positive integers")
+    for arrival, count, stamps, completion in zip(arrivals, outputs, result.output_times, result.completion_times):
+        stamps = np.asarray(stamps, dtype=float)
+        if stamps.ndim != 1 or stamps.size != count or not np.all(np.isfinite(stamps)):
+            raise ValueError("DES token timestamps must align with output lengths and be finite")
+        if (
+            np.any(np.diff(stamps) < 0)
+            or stamps[0] < arrival
+            or not math.isfinite(completion)
+            or stamps[-1] != completion
+        ):
+            raise ValueError("DES token timestamps, output lengths and completion must agree")
+    end = max(result.completion_times) if horizon is None else horizon
+    if not math.isfinite(end) or end <= arrivals[0]:
+        raise ValueError("observation horizon must follow the first arrival")
+    rows = []
+    for index, arrival in enumerate(arrivals):
+        if arrival > end:
+            break
+        tokens = result.output_times[index]
+        observed = [stamp for stamp in tokens if stamp <= end]
+        completed = result.completion_times[index] <= end
+        rows.append(
+            ServingRequest(
+                input_tokens=int(inputs[index]),
+                output_tokens=int(outputs[index]) if completed else len(observed),
+                status="completed" if completed else "pending",
+                ttft=tokens[0] - arrival if observed else None,
+                latency=result.completion_times[index] - arrival if completed else None,
+            )
+        )
+    return ServingBenchmark(tuple(rows), float(end - arrivals[0]), {"latency_basis": "token_DES"})

most_queue/random/feature_service.py

@@ -0,0 +1,175 @@
+"""History-only conditional ECDFs with audited fallback and optional scale ratios.
+
+CRPS uses the empirical energy identity, Gneiting & Raftery (2007),
+https://doi.org/10.1198/016214506000001437. It scores a full predictive CDF,
+not a random sample from it. Feature availability must be established by callers.
+"""
+
+from collections import defaultdict
+from dataclasses import dataclass
+from numbers import Integral, Real
+
+import numpy as np
+
+from most_queue.random.service_calibration import ServiceCalibration
+from most_queue.random.trace_resampling import ConditionalEmpirical
+
+
+def _positive(value, name):
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, Real) or not np.isfinite(value) or value <= 0:
+        raise ValueError(f"{name} must be positive and finite")
+    return float(value)
+
+
+def _need(value):
+    if isinstance(value, (bool, np.bool_)) or not isinstance(value, Integral) or value < 1:
+        raise ValueError("need must be a positive integer")
+    return int(value)
+
+
+def _context(value):
+    if value is not None and (not isinstance(value, str) or not value):
+        raise ValueError("context must be a nonempty string or None")
+    return value
+
+
+def request_bucket(request):
+    """Fixed right-closed request bins in seconds; unknown is distinct from zero."""
+    if request is None:
+        return None
+    value = _positive(request, "request")
+    return str(int(np.searchsorted([300, 1800, 7200, 28800, 86400], value)))
+
+
+@dataclass(frozen=True)
+class EmpiricalPrediction:
+    """An immutable selected ECDF, positive target scale and audited fit level."""
+
+    distribution: ServiceCalibration
+    scale: float = 1.0
+    level: str = "pooled"
+
+    def __post_init__(self):
+        _positive(self.scale, "scale")
+        # Check the support before sampling, not only the selected quantile.
+        _positive(self.scale * self.distribution.samples[-1], "scaled support")
+        _positive(self.scale * self.distribution.samples[0], "scaled support")
+
+    @property
+    def mean(self):
+        """Predictive mean in service-time units, not ratio units."""
+        return self.scale * self.distribution.mean
+
+    def quantile(self, probability):
+        """Inverse discrete ECDF; no interpolation or truncation at runtime budget."""
+        if isinstance(probability, (bool, np.bool_)) or not isinstance(probability, Real):
+            raise ValueError("probability must be a finite real in (0,1)")
+        return float(self.scale * self.distribution.quantiles("empirical", [probability])[0])
+
+    def probability_exceeding(self, threshold):
+        """Return P(S > threshold), with equality counted as within the budget."""
+        threshold = _positive(threshold, "threshold")
+        support = np.array(self.distribution.samples) * self.scale
+        return float(np.mean(support > threshold))
+
+    def crps(self, observed):
+        """Compute E|X-y| - .5 E|X-X'| exactly for a finite equal-weight ECDF.
+
+        For sorted support x_i the second term is sum((2i-n-1)x_i)/n².
+        Scaling before evaluation keeps score units in seconds for ratio fits.
+        """
+        observed = _positive(observed, "observed")
+        support = np.asarray(self.distribution.samples) * self.scale
+        n = len(support)
+        dispersion = np.dot((2 * np.arange(1, n + 1) - n - 1) / n, support) / n
+        score = float(np.mean(np.abs(support - observed)) - dispersion)
+        if not np.isfinite(score):
+            raise ValueError("CRPS overflow; rescale observations")
+        return max(0.0, score)
+
+
+@dataclass(frozen=True)
+class FeatureConditionalEmpirical:
+    """Joint context/need cells, then coarse/pooled fallback; fit uses history only.
+
+    Optional scales fit service/scale on known positive scales, multiplying by
+    the supplied target scale at prediction. Unknown target scale or absent
+    ratio history falls back to absolute service. No outcome or test S is used.
+    """
+
+    absolute: ConditionalEmpirical
+    pooled: ServiceCalibration | None
+    coarse: dict
+    joint: dict
+    exact_joint: dict
+    ratio: bool
+    audit: dict
+
+    @classmethod
+    def fit(
+        cls, needs, services, contexts, *, scales=None, exact=False, minimum=20
+    ):  # pylint: disable=too-many-arguments
+        """Fit context ECDFs with a fixed minimum count and explicit missing scales."""
+        needs, contexts = tuple(needs), tuple(contexts)
+        if len(contexts) != len(needs):
+            raise ValueError("contexts must match needs")
+        needs = tuple(_need(value) for value in needs)
+        contexts = tuple(_context(value) for value in contexts)
+        absolute = ConditionalEmpirical.fit(needs, services, minimum=minimum)
+        if not isinstance(exact, bool):
+            raise ValueError("exact must be boolean")
+        values = np.asarray(services, dtype=float)
+        ratio = scales is not None
+        scales = tuple(scales) if ratio else (1.0,) * len(needs)
+        if len(scales) != len(needs):
+            raise ValueError("scales must match needs")
+        pools = {"coarse": defaultdict(list), "joint": defaultdict(list), "exact": defaultdict(list)}
+        normalized = []
+        for need, service, context, scale in zip(needs, values, contexts, scales):
+            if scale is None:
+                continue
+            value = _positive(service / _positive(scale, "scale"), "scaled service")
+            group = int(np.searchsorted([1, 8, 32], need))
+            normalized.append(value)
+            pools["coarse"][group].append(value)
+            pools["joint"][group, context].append(value)
+            if exact:
+                pools["exact"][need, context].append(value)
+        fitted = {
+            name: {key: ServiceCalibration.fit(sample) for key, sample in cells.items() if len(sample) >= minimum}
+            for name, cells in pools.items()
+        }
+        pooled = ServiceCalibration.fit(normalized) if len(normalized) >= 2 else None
+        audit = {
+            "history_count": len(needs),
+            "scaled_count": len(normalized),
+            "missing_scale_count": sum(s is None for s in scales),
+            "minimum": int(minimum),
+            "exact": exact,
+            "ratio": ratio,
+            "fitted_cells": {name: len(cells) for name, cells in fitted.items()},
+        }
+        return cls(absolute, pooled, fitted["coarse"], fitted["joint"], fitted["exact"], ratio, audit)
+
+    def predict(self, need, context, *, scale=None):
+        """Return the complete predictive distribution and the fallback used."""
+        need, context = _need(need), _context(context)
+        if scale is not None:
+            _positive(scale, "scale")
+        if self.ratio and (scale is None or self.pooled is None):
+            distribution, level = self.absolute.distribution(need)
+            return EmpiricalPrediction(distribution, 1.0, f"absolute_{level}")
+        if not self.ratio and scale is not None:
+            raise ValueError("scale is only valid for a ratio fit")
+        factor = float(scale) if self.ratio else 1.0
+        group = int(np.searchsorted([1, 8, 32], need))
+        choices = (
+            (self.exact_joint.get((need, context)), "exact_context"),
+            (self.joint.get((group, context)), "coarse_context"),
+            (self.coarse.get(group), "coarse"),
+            (self.pooled, "pooled"),
+        )
+        for distribution, level in choices:
+            if distribution is not None:
+                return EmpiricalPrediction(distribution, factor, level)
+        raise ValueError("no predictive distribution available")

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")