most-queue 2.7__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.05"
+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/plots.py

@@ -17,6 +17,7 @@ class DependsType(Enum):
     UTILIZATION_FACTOR = 1
     CHANNELS_NUMBER = 2
     COEFFICIENT_OF_VARIATION = 3
+    NEGATIVE_RATE = 4
 
 
 class Plotter:
@@ -43,12 +44,26 @@ class Plotter:
         ax.set_ylabel(ylabel)
         if self.depends_on == DependsType.UTILIZATION_FACTOR:
             ax.set_xlabel(r"$\rho$")
+        elif self.depends_on == DependsType.NEGATIVE_RATE:
+            ax.set_xlabel(r"$\delta$")
         elif self.depends_on == DependsType.COEFFICIENT_OF_VARIATION:
             ax.set_xlabel(r"$\nu$")
         else:
             ax.set_xlabel("n")
             plt.xticks(range(1, len(self.xs) + 1))
 
+    @staticmethod
+    def _series_style():
+        """
+        Centralized plot style for series used in figures.
+        Keeps line styles (solid/dashed) but uses distinct colors for readability in print/PDF.
+        """
+        return {
+            "sim": {"color": "tab:orange", "linestyle": "--", "linewidth": 2.0},
+            "calc": {"color": "tab:blue", "linestyle": "-", "linewidth": 2.0},
+            "err": {"color": "tab:red", "linestyle": "-", "linewidth": 2.0},
+        }
+
     def plot_errors(self, save_path: str = None):
         """
         Plots the simulation and calculated moments for a given list of x values.
@@ -56,7 +71,8 @@ class Plotter:
         _fig, ax = plt.subplots()
         errors = [100 * (w_sim - w_tt) / w_tt for w_sim, w_tt in zip(self.sim_results, self.calc_results)]
 
-        ax.plot(self.xs, errors, color="black")
+        style = self._series_style()
+        ax.plot(self.xs, errors, **style["err"])
         self._configure_plot(ax, r"$\varepsilon$, %")
 
         if save_path is not None:
@@ -71,8 +87,9 @@ class Plotter:
         Plots the simulation and calculated queue waiting times.
         """
         _fig, ax = plt.subplots()
-        ax.plot(self.xs, self.sim_results, label="Sim", color="black", linestyle="--")
-        ax.plot(self.xs, self.calc_results, label="Calc", color="black")
+        style = self._series_style()
+        ax.plot(self.xs, self.sim_results, label="ИМ", **style["sim"])
+        ax.plot(self.xs, self.calc_results, label="Числ", **style["calc"])
         ax.legend()
         self._configure_plot(ax, r"$\omega_{1}$")
 
@@ -88,8 +105,9 @@ class Plotter:
         Plots the simulation and calculated sojourn times.
         """
         _fig, ax = plt.subplots()
-        ax.plot(self.xs, self.sim_results, label="Sim", color="black", linestyle="--")
-        ax.plot(self.xs, self.calc_results, label="Calc", color="black")
+        style = self._series_style()
+        ax.plot(self.xs, self.sim_results, label="ИМ", **style["sim"])
+        ax.plot(self.xs, self.calc_results, label="Числ", **style["calc"])
         ax.legend()
         self._configure_plot(ax, r"$\upsilon_{1}$")
 
@@ -99,3 +117,21 @@ class Plotter:
             plt.show()
 
         plt.close(_fig)
+
+    def plot_series(self, ylabel: str, save_path: str = None):
+        """
+        Generic plot: two series (sim vs calc) with a custom y-label.
+        """
+        _fig, ax = plt.subplots()
+        style = self._series_style()
+        ax.plot(self.xs, self.sim_results, label="ИМ", **style["sim"])
+        ax.plot(self.xs, self.calc_results, label="Числ", **style["calc"])
+        ax.legend()
+        self._configure_plot(ax, ylabel)
+
+        if save_path is not None:
+            plt.savefig(save_path, dpi=300)
+        else:
+            plt.show()
+
+        plt.close(_fig)

most_queue/misc/calc_v_pls.py

@@ -7,11 +7,11 @@ import math
 from functools import lru_cache
 
 import numpy as np
-from scipy.misc import derivative
 
 from most_queue.random.distributions import H2Distribution, H2Params
 from most_queue.theory.fifo.mgn_takahasi import MGnCalc, TakahashiTakamiParams
 from most_queue.theory.utils.conv import conv_moments
+from most_queue.theory.utils.derivative import derivative
 from most_queue.theory.utils.transforms import lst_exp
 
 

most_queue/random/distributions.py

@@ -251,6 +251,24 @@ class NormalDistribution(Distribution):
         std_dev = cv * mean
         return GaussianParams(mean, std_dev)
 
+    @staticmethod
+    def get_pdf(params: GaussianParams, t: float) -> float:
+        """
+        PDF of the Gaussian distribution. Returns 0 for t < 0 (truncated at zero).
+        """
+        if t < 0:
+            return 0.0
+        return float(stats.norm.pdf(t, loc=params.mean, scale=params.std_dev))
+
+    @staticmethod
+    def get_cdf(params: GaussianParams, t: float) -> float:
+        """
+        CDF of the Gaussian distribution. Returns 0 for t < 0 (truncated at zero).
+        """
+        if t < 0:
+            return 0.0
+        return float(stats.norm.cdf(t, loc=params.mean, scale=params.std_dev))
+
 
 class UniformDistribution(Distribution):
     """
@@ -637,6 +655,26 @@ class DeterministicDistribution(Distribution):
         b = f1
         return b
 
+    @staticmethod
+    def get_pdf(_params, _t: float) -> float:
+        """
+        Deterministic distribution has no density function.
+
+        Raises ``ValueError`` unconditionally — size-based SRPT/SJF/PSJF
+        formulas require a continuous service distribution.
+        """
+        raise ValueError(
+            "Deterministic distribution ('D') has no density function; "
+            "SRPT/SJF/PSJF formulas require a continuous service distribution."
+        )
+
+    @staticmethod
+    def get_cdf(params, t: float) -> float:
+        """
+        CDF of D(b): Heaviside step at b.  *params* is the deterministic value b (float).
+        """
+        return 0.0 if t < float(params) else 1.0
+
 
 class ParetoDistribution(Distribution):
     """
@@ -802,6 +840,16 @@ class ErlangDistribution(Distribution):
         """
         return 1.0 - ErlangDistribution.get_cdf(params, t)
 
+    @staticmethod
+    def get_pdf(params: ErlangParams, t: float) -> float:
+        """
+        PDF of the Erlang(r, mu) distribution: f(t) = mu^r * t^(r-1) * exp(-mu*t) / (r-1)!
+        """
+        if t < 0:
+            return 0.0
+        r, mu = params.r, params.mu
+        return (mu**r) * (t ** (r - 1)) * math.exp(-mu * t) / math.factorial(r - 1)
+
     @staticmethod
     def calc_theory_moments(params: ErlangParams, num: int = 3) -> list[float]:
         """
@@ -891,6 +939,20 @@ class ExpDistribution(Distribution):
         """
         return 1 / f1
 
+    @staticmethod
+    def get_pdf(params: float, t: float) -> float:
+        """
+        PDF of the exponential distribution with rate *params* (= mu = 1/mean).
+        """
+        return ErlangDistribution.get_pdf(ErlangParams(r=1, mu=params), t)
+
+    @staticmethod
+    def get_cdf(params: float, t: float) -> float:
+        """
+        CDF of the exponential distribution with rate *params* (= mu = 1/mean).
+        """
+        return ErlangDistribution.get_cdf(ErlangParams(r=1, mu=params), t)
+
 
 class GammaDistribution(Distribution):
     """

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

@@ -0,0 +1,330 @@
+"""
+Phase-type (PH) distributions and Markovian Arrival Processes (MAP).
+
+A PH distribution is the time to absorption of a CTMC with initial vector
+alpha and sub-generator T (absorption rates t0 = -T @ 1). A MAP is defined by
+matrices (D0, D1): D0 holds phase transitions without arrivals, D1 —
+transitions that generate an arrival; D0 + D1 is the generator of the phase
+process. MAPs model correlated (bursty) traffic; a renewal PH source and the
+MMPP are special cases.
+
+References:
+    Neuts M.F. Matrix-Geometric Solutions in Stochastic Models. Johns Hopkins
+        University Press, 1981.
+    Latouche G., Ramaswami V. Introduction to Matrix Analytic Methods in
+        Stochastic Modeling. SIAM, 1999. doi:10.1137/1.9780898719734.
+    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.
+"""
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+from scipy.linalg import expm
+
+from most_queue.random.utils.params import Cox2Params, ErlangParams, H2Params
+
+
+@dataclass
+class PHParams:
+    """Phase-type distribution parameters: initial vector and sub-generator."""
+
+    alpha: np.ndarray  # initial probability row vector, shape (m,)
+    T: np.ndarray  # sub-generator matrix, shape (m, m)
+
+
+@dataclass
+class MAPParams:
+    """Markovian Arrival Process parameters."""
+
+    D0: np.ndarray  # transitions without arrivals (sub-generator), shape (m, m)
+    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")
+    if alpha.shape != (T.shape[0],):
+        raise ValueError(f"alpha shape {alpha.shape} does not match T {T.shape}")
+    if not math.isclose(float(np.sum(alpha)), 1.0, rel_tol=1e-9):
+        raise ValueError("alpha must sum to 1 (mass at zero is not supported)")
+    if np.any(np.diag(T) >= 0):
+        raise ValueError("diagonal of T must be negative")
+    exit_rates = -T @ np.ones(T.shape[0])
+    if np.any(exit_rates < -1e-12):
+        raise ValueError("row sums of T must be <= 0 (t0 = -T@1 must be non-negative)")
+
+
+class PHDistribution:
+    """
+    Phase-type distribution PH(alpha, T).
+
+    Follows the library's distribution interface: ``generate()`` draws a
+    sample by simulating the absorbing CTMC, static ``calc_theory_moments``
+    returns raw moments m_k = k! * alpha @ (-T)^{-k} @ 1.
+    """
+
+    def __init__(self, params: PHParams, generator=None):
+        self.params = params
+        self.alpha = np.asarray(params.alpha, dtype=float)
+        self.T = np.asarray(params.T, dtype=float)
+        _validate_ph(self.alpha, self.T)
+        self.t0 = -self.T @ np.ones(self.T.shape[0])
+        self.type = "PH"
+        self.generator = generator if generator is not None else np.random.default_rng()
+
+    # ------------------------------------------------------------- theory
+    @staticmethod
+    def calc_theory_moments(params: PHParams, num: int = 4) -> list[float]:
+        """
+        Raw moments of PH(alpha, T): m_k = k! * alpha @ (-T)^{-k} @ 1.
+        """
+        alpha = np.asarray(params.alpha, dtype=float)
+        T = np.asarray(params.T, dtype=float)
+        m_inv = np.linalg.inv(-T)
+        ones = np.ones(T.shape[0])
+        moments, vec = [], alpha.copy()
+        for k in range(1, num + 1):
+            vec = vec @ m_inv
+            moments.append(math.factorial(k) * float(vec @ ones))
+        return moments
+
+    @staticmethod
+    def get_pdf(params: PHParams, x: float) -> float:
+        """Probability density f(x) = alpha @ expm(T x) @ t0."""
+        alpha = np.asarray(params.alpha, dtype=float)
+        T = np.asarray(params.T, dtype=float)
+        t0 = -T @ np.ones(T.shape[0])
+        return float(alpha @ expm(T * x) @ t0) if x >= 0 else 0.0
+
+    @staticmethod
+    def get_cdf(params: PHParams, x: float) -> float:
+        """Cumulative distribution F(x) = 1 - alpha @ expm(T x) @ 1."""
+        alpha = np.asarray(params.alpha, dtype=float)
+        T = np.asarray(params.T, dtype=float)
+        return 1.0 - float(alpha @ expm(T * x) @ np.ones(T.shape[0])) if x >= 0 else 0.0
+
+    # ---------------------------------------------------------- converters
+    @staticmethod
+    def from_exp(mu: float) -> PHParams:
+        """Exponential(mu) as a single-phase PH."""
+        return PHParams(alpha=np.array([1.0]), T=np.array([[-mu]]))
+
+    @staticmethod
+    def from_erlang(params: ErlangParams) -> PHParams:
+        """Erlang-r as a chain of r exponential phases."""
+        r, mu = params.r, params.mu
+        T = -mu * np.eye(r) + mu * np.eye(r, k=1)
+        alpha = np.zeros(r)
+        alpha[0] = 1.0
+        return PHParams(alpha=alpha, T=T)
+
+    @staticmethod
+    def from_h2(params: H2Params) -> PHParams:
+        """Hyperexponential H2 (real parameters only) as a two-phase PH."""
+        p1, mu1, mu2 = float(params.p1.real), float(params.mu1.real), float(params.mu2.real)
+        return PHParams(alpha=np.array([p1, 1.0 - p1]), T=np.array([[-mu1, 0.0], [0.0, -mu2]]))
+
+    @staticmethod
+    def from_cox(params: Cox2Params) -> PHParams:
+        """Second-order Coxian as a two-phase PH."""
+        mu1, mu2, p1 = float(params.mu1.real), float(params.mu2.real), float(params.p1.real)
+        return PHParams(alpha=np.array([1.0, 0.0]), T=np.array([[-mu1, p1 * mu1], [0.0, -mu2]]))
+
+    # ------------------------------------------------------------ sampling
+    def generate(self) -> float:
+        """Draw one sample by simulating the absorbing phase process."""
+        rng = self.generator
+        m = self.T.shape[0]
+        phase = int(rng.choice(m, p=self.alpha))
+        elapsed = 0.0
+        while True:
+            rate = -self.T[phase, phase]
+            elapsed += rng.exponential(1.0 / rate)
+            # transition probabilities from `phase`: to other phases or absorb
+            probs = np.append(self.T[phase].copy(), self.t0[phase])
+            probs[phase] = 0.0
+            probs /= rate
+            nxt = int(rng.choice(m + 1, p=probs))
+            if nxt == m:
+                return elapsed
+            phase = nxt
+
+
+class MAP:
+    """
+    Markovian Arrival Process MAP(D0, D1).
+
+    ``generate()`` returns successive interarrival times (the phase is kept
+    between calls, starting from the arrival-stationary distribution).
+    """
+
+    def __init__(self, params: MAPParams, generator=None):
+        self.params = params
+        self.D0 = np.asarray(params.D0, dtype=float)
+        self.D1 = np.asarray(params.D1, dtype=float)
+        if self.D0.shape != self.D1.shape or self.D0.ndim != 2 or self.D0.shape[0] != self.D0.shape[1]:
+            raise ValueError("D0 and D1 must be square matrices of the same shape")
+        gen_row_sums = (self.D0 + self.D1) @ np.ones(self.D0.shape[0])
+        if not np.allclose(gen_row_sums, 0.0, atol=1e-9):
+            raise ValueError("D0 + D1 must be a generator (zero row sums)")
+        if np.any(self.D1 < -1e-12):
+            raise ValueError("D1 must be non-negative")
+        self.type = "MAP"
+        self.generator = generator if generator is not None else np.random.default_rng()
+        self._phase = int(self.generator.choice(self.D0.shape[0], p=MAP.arrival_stationary_phase(params)))
+
+    # ------------------------------------------------------------- theory
+    @staticmethod
+    def phase_stationary(params: MAPParams) -> np.ndarray:
+        """Stationary distribution pi of the phase generator D = D0 + D1."""
+        d = np.asarray(params.D0, dtype=float) + np.asarray(params.D1, dtype=float)
+        m = d.shape[0]
+        a = np.vstack([d.T, np.ones(m)])
+        b = np.zeros(m + 1)
+        b[-1] = 1.0
+        pi, *_ = np.linalg.lstsq(a, b, rcond=None)
+        return pi
+
+    @staticmethod
+    def arrival_rate(params: MAPParams) -> float:
+        """Fundamental arrival rate lambda = pi @ D1 @ 1."""
+        pi = MAP.phase_stationary(params)
+        return float(pi @ np.asarray(params.D1, dtype=float) @ np.ones(len(pi)))
+
+    @staticmethod
+    def arrival_stationary_phase(params: MAPParams) -> np.ndarray:
+        """Phase distribution just after an arrival: pi @ D1 / lambda."""
+        pi = MAP.phase_stationary(params)
+        d1 = np.asarray(params.D1, dtype=float)
+        vec = pi @ d1
+        return vec / vec.sum()
+
+    @staticmethod
+    def calc_theory_moments(params: MAPParams, num: int = 4) -> list[float]:
+        """
+        Raw moments of the stationary interarrival time:
+        m_k = k! * pi_a @ (-D0)^{-k} @ 1.
+        """
+        pi_a = MAP.arrival_stationary_phase(params)
+        m_inv = np.linalg.inv(-np.asarray(params.D0, dtype=float))
+        ones = np.ones(len(pi_a))
+        moments, vec = [], pi_a.copy()
+        for k in range(1, num + 1):
+            vec = vec @ m_inv
+            moments.append(math.factorial(k) * float(vec @ ones))
+        return moments
+
+    @staticmethod
+    def lag_correlation(params: MAPParams, k: int = 1) -> float:
+        """
+        Lag-k autocorrelation of interarrival times:
+        corr(X_0, X_k) with E[X_0 X_k] = pi_a @ M @ P^k @ M @ 1, M = (-D0)^{-1},
+        P = M @ D1 (phase transition matrix over one arrival).
+        """
+        if k < 1:
+            raise ValueError("lag k must be >= 1")
+        pi_a = MAP.arrival_stationary_phase(params)
+        m_inv = np.linalg.inv(-np.asarray(params.D0, dtype=float))
+        p = m_inv @ np.asarray(params.D1, dtype=float)
+        ones = np.ones(len(pi_a))
+        m1 = float(pi_a @ m_inv @ ones)
+        m2 = 2.0 * float(pi_a @ m_inv @ m_inv @ ones)
+        joint = float(pi_a @ m_inv @ np.linalg.matrix_power(p, k) @ m_inv @ ones)
+        var = m2 - m1 * m1
+        return (joint - m1 * m1) / var
+
+    # ---------------------------------------------------------- factories
+    @staticmethod
+    def poisson(rate: float) -> MAPParams:
+        """Poisson process as a trivial one-phase MAP."""
+        return MAPParams(D0=np.array([[-rate]]), D1=np.array([[rate]]))
+
+    @staticmethod
+    def from_ph_renewal(ph: PHParams) -> MAPParams:
+        """Renewal process with PH interarrival times: D0 = T, D1 = t0 @ alpha."""
+        alpha = np.asarray(ph.alpha, dtype=float)
+        T = np.asarray(ph.T, dtype=float)
+        t0 = -T @ np.ones(T.shape[0])
+        return MAPParams(D0=T, D1=np.outer(t0, alpha))
+
+    @staticmethod
+    def mmpp(rates: list[float], q: np.ndarray) -> MAPParams:
+        """
+        Markov-modulated Poisson process: Poisson rate rates[i] while the
+        modulating chain (generator q) is in state i.
+        """
+        rates_arr = np.asarray(rates, dtype=float)
+        q_arr = np.asarray(q, dtype=float)
+        if not np.allclose(q_arr @ np.ones(q_arr.shape[0]), 0.0, atol=1e-9):
+            raise ValueError("q must be a generator (zero row sums)")
+        return MAPParams(D0=q_arr - np.diag(rates_arr), D1=np.diag(rates_arr))
+
+    # ------------------------------------------------------------ sampling
+    def generate(self) -> float:
+        """Time until the next arrival (phase state persists between calls)."""
+        rng = self.generator
+        m = self.D0.shape[0]
+        elapsed = 0.0
+        while True:
+            rate = -self.D0[self._phase, self._phase]
+            elapsed += rng.exponential(1.0 / rate)
+            # competing transitions: D0 off-diagonal (no arrival) vs any D1 entry
+            probs = np.concatenate([self.D0[self._phase], self.D1[self._phase]])
+            probs[self._phase] = 0.0
+            probs = probs / rate
+            nxt = int(rng.choice(2 * m, p=probs))
+            if nxt >= m:
+                self._phase = nxt - m
+                return elapsed
+            self._phase = nxt