stopro 0.3.3__tar.gz

stopro-0.3.3/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.3
+Name: stopro
+Version: 0.3.3
+Summary: Stochastic processes in Python
+Keywords: stochastic-processes,sde,wiener,ornstein-uhlenbeck
+Author: Dirk Brockmann
+Author-email: Dirk Brockmann <dirk.brockmann@tu-dresden.de>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.9
+Requires-Dist: jupyter ; extra == 'examples'
+Requires-Dist: matplotlib ; extra == 'examples'
+Requires-Dist: palettable ; extra == 'examples'
+Maintainer: Dirk Brockmann
+Maintainer-email: Dirk Brockmann <dirk.brockmann@tu-dresden.de>
+Requires-Python: >=3.9
+Project-URL: Repository, https://github.com/dirkbrockmann/stopro
+Provides-Extra: examples
+Description-Content-Type: text/markdown
+
+# stopro — Elementary Stochastic Processes
+
+**stopro** is a small Python library for generating and simulating common
+(multivariate) stochastic processes.
+
+Currently included processes:
+
+1. Wiener process  
+2. Ornstein–Uhlenbeck process  
+3. Integrated Ornstein–Uhlenbeck process  
+4. Exponential Ornstein–Uhlenbeck process  
+5. Geometric Brownian Motion  
+6. Colored Geometric Brownian Motion  
+7. Gillespie Replicator  
+8. Kimura Replicator  
+9. White Replicator  
+10. Colored Replicator  
+11. Multispecies Moran process  
+    (discrete particle kinetics & diffusion approximation)  
+12. Competitive Lotka–Volterra process  
+    (discrete particle kinetics & diffusion approximation)
+
+Examples and documentation are provided as Jupyter notebooks.
+
+---
+
+## Quick start (recommended)
+
+This project uses **uv**, a fast Python package manager and virtual environment
+tool. You need to install uv on your system first. When that's done:
+
+```bash
+git clone https://github.com/dirkbrockmann/stopro.git
+cd stopro
+make notebook
+```
+
+---
+
+## Using stopro in your own code
+
+```python
+import stopro
+```
+
+---
+
+
+## Installation via pip
+
+Download and install the latest source:
+
+```bash
+pip install git+https://github.com/dirkbrockmann/stopro.git
+```
+
+Clone and work with code locally:
+
+```bash
+git clone https://github.com/dirkbrockmann/stopro.git
+cd stopro
+pip install -e .
+````
+
+---
+
+## License
+
+MIT

stopro-0.3.3/README.md

@@ -0,0 +1,69 @@
+# stopro — Elementary Stochastic Processes
+
+**stopro** is a small Python library for generating and simulating common
+(multivariate) stochastic processes.
+
+Currently included processes:
+
+1. Wiener process  
+2. Ornstein–Uhlenbeck process  
+3. Integrated Ornstein–Uhlenbeck process  
+4. Exponential Ornstein–Uhlenbeck process  
+5. Geometric Brownian Motion  
+6. Colored Geometric Brownian Motion  
+7. Gillespie Replicator  
+8. Kimura Replicator  
+9. White Replicator  
+10. Colored Replicator  
+11. Multispecies Moran process  
+    (discrete particle kinetics & diffusion approximation)  
+12. Competitive Lotka–Volterra process  
+    (discrete particle kinetics & diffusion approximation)
+
+Examples and documentation are provided as Jupyter notebooks.
+
+---
+
+## Quick start (recommended)
+
+This project uses **uv**, a fast Python package manager and virtual environment
+tool. You need to install uv on your system first. When that's done:
+
+```bash
+git clone https://github.com/dirkbrockmann/stopro.git
+cd stopro
+make notebook
+```
+
+---
+
+## Using stopro in your own code
+
+```python
+import stopro
+```
+
+---
+
+
+## Installation via pip
+
+Download and install the latest source:
+
+```bash
+pip install git+https://github.com/dirkbrockmann/stopro.git
+```
+
+Clone and work with code locally:
+
+```bash
+git clone https://github.com/dirkbrockmann/stopro.git
+cd stopro
+pip install -e .
+````
+
+---
+
+## License
+
+MIT

stopro-0.3.3/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "stopro"
+version = "0.3.3"
+description = "Stochastic processes in Python"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{ name = "Dirk Brockmann", email = "dirk.brockmann@tu-dresden.de" }]
+maintainers = [{ name = "Dirk Brockmann", email = "dirk.brockmann@tu-dresden.de" }]
+license = { text = "MIT" }
+
+dependencies = [
+  "numpy>=1.22",
+  "scipy>=1.9",
+]
+
+keywords = ["stochastic-processes", "sde", "wiener", "ornstein-uhlenbeck"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Repository = "https://github.com/dirkbrockmann/stopro"
+
+[project.optional-dependencies]
+examples = ["jupyter", "matplotlib", "palettable"]
+
+[dependency-groups]
+dev = ["pytest>=7"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

stopro-0.3.3/src/stopro/__init__.py

@@ -0,0 +1,34 @@
+from importlib.metadata import version
+
+__version__ = version("stopro")
+
+__all__ = [
+    "wiener",
+    "ornstein_uhlenbeck",
+    "kimura_replicator",
+    "geometric_brownian_motion",
+    "exponential_ornstein_uhlenbeck",
+    "integrated_ornstein_uhlenbeck",
+    "colored_geometric_brownian_motion",
+    "gillespie_replicator",
+    "white_replicator",
+    "colored_stochastic_replicator",
+    "colored_replicator",
+    "moran",
+    "competitive_lotka_volterra",
+    "__version__",
+]
+
+from .wiener import wiener
+from .ornstein_uhlenbeck import ornstein_uhlenbeck
+from .kimura_replicator import kimura_replicator
+from .geometric_brownian_motion import geometric_brownian_motion
+from .exponential_ornstein_uhlenbeck import exponential_ornstein_uhlenbeck
+from .integrated_ornstein_uhlenbeck import integrated_ornstein_uhlenbeck
+from .colored_geometric_brownian_motion import colored_geometric_brownian_motion
+from .gillespie_replicator import gillespie_replicator
+from .white_replicator import white_replicator
+from .colored_replicator import colored_replicator as colored_stochastic_replicator
+from .colored_replicator import colored_replicator
+from .moran import moran
+from .competitive_lotka_volterra import competitive_lotka_volterra

stopro-0.3.3/src/stopro/_utils.py

@@ -0,0 +1,171 @@
+import numpy as np
+
+# Build a uniform time grid on [0, T] from either dt or steps (exactly one must be given).
+# Returns (dt, steps, t) with t including both endpoints 0 and T.
+def _time_grid(T, dt=None, steps=None):
+    """
+    Build a uniform grid on [0, T].
+
+    Provide exactly one of dt or steps.
+    - If steps is provided: dt = T/steps.
+    - If dt is provided: choose integer steps close to T/dt, then use dt = T/steps
+      so the grid ends exactly at T.
+    """
+    if (dt is None) == (steps is None):
+        raise ValueError("Provide exactly one of dt or steps (not both, not neither).")
+
+    T = float(T)
+    if T <= 0:
+        raise ValueError("T must be > 0.")
+
+    if steps is not None:
+        steps = int(steps)
+        if steps <= 0:
+            raise ValueError("steps must be a positive integer.")
+        dt = T / steps
+        t = np.linspace(0.0, T, steps + 1)
+        return dt, steps, t
+
+    dt = float(dt)
+    if dt <= 0:
+        raise ValueError("dt must be > 0.")
+
+    steps = int(np.round(T / dt))
+    steps = max(1, steps)
+
+    dt = T / steps
+    t = np.linspace(0.0, T, steps + 1)
+    return dt, steps, t
+
+
+# Robustly factor a symmetric PSD matrix C into L such that C ≈ L @ L.T.
+# Uses Cholesky when possible, otherwise falls back to eigen-decomposition (clipping small negatives).
+def _psd_factor(C, *, jitter=0.0, tol=1e-12):
+
+    C = np.asarray(C, dtype=float)
+    C = 0.5 * (C + C.T)
+
+    if jitter and jitter > 0:
+        Cj = C + jitter * np.eye(C.shape[0])
+    else:
+        Cj = C
+
+    try:
+        return np.linalg.cholesky(Cj)
+    except np.linalg.LinAlgError:
+        w, V = np.linalg.eigh(C)
+        w = np.where(w > tol, w, 0.0)
+        return V @ np.diag(np.sqrt(w))
+
+
+# Normalize "noise specification" into a mixing matrix S with covariance C = S @ S.T.
+# Accepts either covariance (must be symmetric PSD) or a mixing_matrix; otherwise defaults to identity.
+def _mixing(*, N=None, covariance=None, mixing_matrix=None, jitter=1e-12, psd_tol=1e-12, sym_tol=1e-12):
+    if covariance is not None and mixing_matrix is not None:
+        raise ValueError("Provide only one of covariance or mixing_matrix (not both).")
+
+    if mixing_matrix is not None:
+        S = np.asarray(mixing_matrix, dtype=float)
+        if S.ndim != 2:
+            raise ValueError("mixing_matrix must be a 2D array.")
+        N_res, M = S.shape
+        if N is not None and int(N) != N_res:
+            raise ValueError(f"N={N} is inconsistent with mixing_matrix.shape[0]={N_res}.")
+        C = S @ S.T
+        C = 0.5 * (C + C.T)
+        return S, C, N_res, M
+
+    if covariance is not None:
+        C = np.asarray(covariance, dtype=float)
+        if C.ndim != 2 or C.shape[0] != C.shape[1]:
+            raise ValueError("covariance must be a square (N,N) array.")
+
+        # Require symmetry (within tolerance) for user-provided covariance
+        max_asym = float(np.max(np.abs(C - C.T)))
+        if max_asym > sym_tol:
+            raise ValueError(
+                f"covariance must be symmetric; max |C - C.T| = {max_asym:g} exceeds sym_tol={sym_tol:g}."
+            )
+
+        C = 0.5 * (C + C.T)
+
+        N_res = C.shape[0]
+        if N is not None and int(N) != N_res:
+            raise ValueError(f"N={N} is inconsistent with covariance.shape[0]={N_res}.")
+
+        lam_min = float(np.min(np.linalg.eigvalsh(C)))
+        if lam_min < -psd_tol:
+            raise ValueError(
+                f"covariance must be positive semidefinite; min eigenvalue = {lam_min:g} < -psd_tol={psd_tol:g}."
+            )
+
+        S = _psd_factor(C, jitter=jitter, tol=psd_tol)
+        M = N_res
+        return S, C, N_res, M
+    # Neither covariance nor mixing_matrix: default to independent Wiener components
+    if N is None:
+        raise ValueError("N must be provided when neither covariance nor mixing_matrix is given.")
+    N_res = int(N)
+    if N_res <= 0:
+        raise ValueError("N must be a positive integer.")
+    S = np.eye(N_res, dtype=float)
+    C = np.eye(N_res, dtype=float)
+    M = N_res
+    return S, C, N_res, M
+
+# Coerce a parameter into a length-N float vector (broadcast scalar; validate 1D shape).
+def _as_vector(x, N, name):
+    arr = np.asarray(x, dtype=float)
+    if arr.ndim == 0:
+        return np.full(int(N), float(arr))
+    if arr.shape == (int(N),):
+        return arr
+    raise ValueError(f"{name} must be a scalar or an array of shape ({N},), got shape {arr.shape}.")
+
+
+# Parse initial_condition into either ("stationary") or an explicit x0 vector of length N.
+# Used by OU/Wiener-like processes to support a convenient stationary start.
+def _parse_initial_condition(initial_condition, *, N):
+    if isinstance(initial_condition, str):
+        if initial_condition.lower() == "stationary":
+            return True, None
+        raise ValueError(f"unknown initial_condition '{initial_condition}'")
+
+    if initial_condition is None:
+        return False, np.zeros(int(N), dtype=float)
+
+    # scalar or vector
+    x0 = _as_vector(initial_condition, N, "initial_condition")
+    return False, x0
+
+
+# Create an initial condition on the probability simplex (nonnegative entries summing to 1).
+# Accepts None (uniform), scalar (broadcast then normalize), or a length-N vector (validate+normalize).
+def _simplex_initial_condition(initial_condition, *, N, name="initial_condition"):
+
+    N = int(N)
+    if N <= 0:
+        raise ValueError("N must be a positive integer.")
+
+    if initial_condition is None:
+        return np.full(N, 1.0 / N, dtype=float)
+
+    x0 = np.asarray(initial_condition, dtype=float)
+
+    if x0.ndim == 0:
+        c = float(x0)
+        if c <= 0:
+            raise ValueError(f"{name} scalar must be > 0 to normalize, got {c}.")
+        x0 = np.full(N, c, dtype=float)
+
+    if x0.shape != (N,):
+        raise ValueError(f"{name} must be None, a scalar, or an array of shape ({N},), got shape {x0.shape}.")
+
+    if np.any(x0 < 0):
+        raise ValueError(f"{name} must be nonnegative.")
+
+    s = float(np.sum(x0))
+    if s <= 0:
+        raise ValueError(f"{name} must have positive sum to normalize.")
+
+    return x0 / s

stopro-0.3.3/src/stopro/colored_geometric_brownian_motion.py

@@ -0,0 +1,81 @@
+import numpy as np
+
+from ._utils import _as_vector
+from .integrated_ornstein_uhlenbeck import integrated_ornstein_uhlenbeck
+
+
+def colored_geometric_brownian_motion(
+    T,
+    dt=None,
+    *,
+    steps=None,
+    gap=1,
+    N=1,
+    samples=1,
+    mu=1.0,
+    sigma=1.0,
+    tau=1.0,
+    initial_condition=None,
+    covariance=None,
+    mixing_matrix=None,
+):
+    """
+    Simulate multivariate colored geometric Brownian motion (cGBM) on [0, T].
+
+        dX_i(t) = mu_i X_i(t) dt + sigma_i X_i(t) Z_i(t) dt
+        tau * dZ_i(t) = -Z_i(t) dt + dW_i(t)
+
+    Hence,
+        X_i(t) = X_i(0) * exp(mu_i t + sigma_i * ∫_0^t Z_i(s) ds).
+
+    Provide exactly one of `dt` or `steps`. Noise correlation can be specified via
+    `covariance` or `mixing_matrix` (mutually exclusive). Use `gap>1` to subsample.
+    """
+    tau = float(tau)
+    if tau <= 0:
+        raise ValueError("tau must be > 0.")
+
+    N = int(N)
+    if N <= 0:
+        raise ValueError("N must be a positive integer.")
+
+    # Choose OU stdev so that: tau*dZ = -Z dt + dW  <=>  dZ = -(1/tau)Z dt + (1/tau)dW
+    # which implies stationary stdev(Z) = 1/sqrt(2*tau).
+    stdev_z = 1.0 / np.sqrt(2.0 * tau)
+
+    res_I = integrated_ornstein_uhlenbeck(
+        T,
+        dt,
+        steps=steps,
+        gap=gap,
+        N=N,
+        samples=samples,
+        stdev=stdev_z,
+        timescale=tau,
+        initial_condition="stationary",
+        covariance=covariance,
+        mixing_matrix=mixing_matrix,
+    )
+
+    I = res_I["X"]  # (samples, N, K) = ∫_0^t Z(s) ds (approx.)
+    t = res_I["t"]  # (K,)
+    N_res = res_I["N"]
+
+    mu = _as_vector(mu, N_res, "mu")
+    sigma = _as_vector(sigma, N_res, "sigma")
+
+    if initial_condition is None:
+        x0 = np.ones(N_res, dtype=float)
+    else:
+        x0 = _as_vector(initial_condition, N_res, "initial_condition")
+
+    # X_i(t) = x0_i * exp(mu_i t + sigma_i I_i(t))
+    tt = t[None, None, :]  # (1, 1, K)
+    X = x0[None, :, None] * np.exp(mu[None, :, None] * tt + sigma[None, :, None] * I)
+
+    res_I["X"] = X
+    res_I["mu"] = mu
+    res_I["sigma"] = sigma
+    res_I["tau"] = tau
+    res_I["initial_condition"] = x0
+    return res_I

stopro-0.3.3/src/stopro/colored_replicator.py

@@ -0,0 +1,110 @@
+import numpy as np
+from scipy.special import logsumexp
+
+from ._utils import _as_vector, _simplex_initial_condition
+from .integrated_ornstein_uhlenbeck import integrated_ornstein_uhlenbeck
+
+
+def colored_replicator(
+    T,
+    dt=None,
+    *,
+    steps=None,
+    N=2,
+    mu=1.0,
+    sigma=1.0,
+    tau=1.0,
+    initial_condition=None,
+    gap=1,
+    samples=1,
+    covariance=None,
+    mixing_matrix=None,
+):
+    r"""
+    Simulate the colored stochastic replicator (softmax-normalized colored log-process).
+
+    Model:
+        dX_i(t) = mu_i X_i(t) dt + sigma_i X_i(t) Z_i(t) dt
+        tau_i dZ_i(t) = -Z_i(t) dt + dW_i(t)
+
+    With I_i(t) = ∫_0^t Z_i(s) ds:
+        X_i(t) = X_i(0) * exp(mu_i t + sigma_i I_i(t))
+        Y_i(t) = X_i(t) / sum_j X_j(t)
+
+    Notes
+    -----
+    The underlying OU Z is started at zero (not stationary) to make comparisons to
+    Wiener-driven models consistent as tau -> 0.
+
+    Returns
+    -------
+    dict with keys including:
+      - "X": (samples, N, K) replicator trajectory on the saved grid
+      - "t": (K,) time grid (subsampled by gap)
+      - plus metadata from integrated_ornstein_uhlenbeck, and "mu","sigma","tau","initial_condition"
+    """
+    N = int(N)
+    if N < 2:
+        raise ValueError(f"colored_replicator requires N>=2, got N={N}.")
+
+    gap = int(gap)
+    if gap <= 0:
+        raise ValueError("gap must be a positive integer.")
+
+    samples = int(samples)
+    if samples <= 0:
+        raise ValueError("samples must be a positive integer.")
+
+    mu = _as_vector(mu, N, "mu")
+    sigma = _as_vector(sigma, N, "sigma")
+    tau = _as_vector(tau, N, "tau")
+    if np.any(tau <= 0):
+        raise ValueError("tau must be > 0 (component-wise).")
+
+    # Replicator starts on simplex
+    x0 = _simplex_initial_condition(initial_condition, N=N)
+
+    # Choose OU stdev so that tau dZ = -Z dt + dW  <=>  stationary stdev(Z) = 1/sqrt(2*tau)
+    # (even though we start Z(0)=0, this keeps the intended tau-scaling of the colored noise)
+    stdev_z = 1.0 / np.sqrt(2.0 * tau)
+
+    # I(t) = ∫ Z ds (computed on fine grid internally; returned on gap-grid)
+    # We intentionally start OU at zero for comparability (initial_condition=None).
+    res_I = integrated_ornstein_uhlenbeck(
+        T,
+        dt,
+        steps=steps,
+        gap=gap,
+        N=N,
+        samples=samples,
+        stdev=stdev_z,
+        timescale=tau,
+        initial_condition=None,
+        covariance=covariance,
+        mixing_matrix=mixing_matrix,
+    )
+
+    I = res_I["X"]  # (samples, N, K)
+    t = res_I["t"]  # (K,)
+
+    # log X_i(t) = log x0_i + mu_i t + sigma_i I_i(t)
+    # Normalize with logsumexp for numerical stability.
+    with np.errstate(divide="ignore"):
+        logx0 = np.where(x0 > 0, np.log(x0), -np.inf)  # (N,)
+
+    logX = (
+        logx0[None, :, None]
+        + mu[None, :, None] * t[None, None, :]
+        + sigma[None, :, None] * I
+    )  # (samples, N, K)
+
+    log_denom = logsumexp(logX, axis=1, keepdims=True)  # (samples, 1, K)
+    Y = np.exp(logX - log_denom)                        # (samples, N, K)
+
+    res = dict(res_I)
+    res["X"] = Y
+    res["mu"] = mu
+    res["sigma"] = sigma
+    res["tau"] = tau
+    res["initial_condition"] = x0
+    return res