stopro 0.3.3__py3-none-any.whl

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/_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/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/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

stopro/competitive_lotka_volterra.py

@@ -0,0 +1,154 @@
+import numpy as np
+from math import inf
+from math import isinf
+from scipy.integrate import odeint
+from scipy.special import logsumexp
+
+def clv_particle_dynamics(n0,T,alpha,beta,omega,
+                          dt = 1, 
+                          sigma = False, 
+                          A = None, 
+                          timescale = 1):
+    
+    N = len(n0)
+    t = [0]
+    X = [tuple(n0)]
+    n = n0.copy()
+
+    if sigma is not False:
+        alpha = exponential_ornstein_uhlenbeck(T = T, dt = dt, coeff_var = sigma, mixing_matrix = A, mean = alpha, timescale = timescale)['X'][0]
+    
+    while t[-1] < T:
+
+        beta_i =  n * (beta@n)/omega
+
+        if np.ndim(alpha)>1:
+
+            alpha_i = n[:,None] * alpha
+            rtot = np.sum(alpha_i, axis = 0) + np.sum(beta_i)
+            if len(rtot) == 1: break
+            tau = stochastic_tau(rtot, dt)
+            t.append(t[-1]+(1+tau)*dt)
+            alpha_t = alpha_i[:,tau]
+            rtot = rtot[tau]
+            alpha = alpha[:,(1+tau):]
+
+        else:
+
+            alpha_i = n * alpha
+            rtot = np.sum(alpha_i) + np.sum(beta_i)
+            tau = np.random.exponential(1.0/rtot)
+            t.append(t[-1]+tau)
+            alpha_t = alpha_i 
+            
+        P1 = (alpha_t+beta_i)/rtot
+        selected_species = np.random.choice(range(N),p = P1)
+        P2 = alpha_t[selected_species]/(alpha_t[selected_species]+beta_i[selected_species])
+
+        if (np.random.rand() < P2):
+            n[selected_species]+=1
+        else:
+            n[selected_species]-=1
+
+        X.append(tuple(n))
+    
+    return (t,X)
+
+def clv_diffusion_approximation(n0,T,alpha,beta,omega,dt):
+
+    N = len(n0)
+    t = [0]
+    X = [tuple(n0)]
+    n = list(n0)
+        
+    while t[-1] < T:
+        beta_i = (beta@n)/omega
+        alpha_mean = np.sum(n*alpha)/omega
+        
+        W = np.random.normal(size=N)
+        dn = n*(alpha-beta_i)*dt + np.sqrt(n*(alpha+beta_i)*dt)*W;
+        n += dn;
+        n[n<0] = 0
+        t.append(t[-1]+dt)
+        X.append(tuple(n))
+    
+    return (t,X)
+
+def competitive_lotka_volterra(T,x0,alpha,beta,system_size,     
+          diffusion_approximation=False,
+          normalize=False, 
+          samples=1,
+          dt = 1, 
+          sigma = False, 
+          A = None, 
+          timescale = 1 
+          ):
+
+    """
+    Generates realizations of the multispecies, stochasic competitve Lokta-Volterra Model 
+    of a population of individuals of M different species 
+    that replicate and compete to the following reaction scheme:
+    .. math::
+        X_i \rightarrow 2X_i \quad \text{at rate} \quad \alpha_i 
+
+    .. math::
+        X_i + X_j \rightarrow 2X_j \quad \text{at rate} \quad \beta_{ij}/Omega 
+
+    The parameter Omega is the system size
+    Parameters
+    ----------
+    T : float
+        Time interval.
+    x0: numpy.ndarray of shape (``M``,)
+        Initial state, depending on the state_variable keyword (below) this is abundance,
+        density, fraction, or capacitance
+    alpha : numpy.ndarray of shape (``N``,)
+        Replication rates of species
+    beta : numpy.ndarray of shape (``N``,``N``)
+        Competition rate between species
+    system_size : int or inf
+        System size, i.e. a measure for the approximate total abundance of species,
+        it's the normalization of the competitive rate that makes sure beta is of the order of unity
+        If inf deterministic solution is computed, required additional keyword dt to be set
+    diffusion_approximation: True/False, default is False
+        If True computes the realizations of the diffusion approximation process for the system
+        requires to set keyword dt
+    normalize : boolean, default = False
+        If True normalizes state variable with system_size parameter Omega
+    samples : int, default = 1
+        The number of samples generated, ignored if system_size = inf (deterministic system)
+    dt: float
+        Needs to be specified if the diffusion approximation is used. This is the time increment in that
+        case
+
+    Returns
+    -------
+    result : numpy.ndarray:
+        each array element is a sample, each sample is a tuple (t,X) or time array t and array of state vectors X.
+    
+
+    """ 
+    if isinf(system_size):
+        t = np.linspace(0,T,int(T/dt))
+        ode1 = lambda x,t,a,b : x*(a-b@x)
+        sol = odeint(lambda x,t,a,b : x*(a-b@x),x0,t,args=(alpha,beta))                    
+        X = [tuple(v) for v in sol]
+        return (t,X)
+    
+    if normalize:
+        n0 = system_size*x0
+        n0 = n0.astype(int)
+    else:
+        n0 = x0
+                
+    if diffusion_approximation:
+        res = [clv_diffusion_approximation(n0,T,alpha,beta,system_size,dt) for i in range(samples)]
+    else:
+        res = [clv_particle_dynamics(n0,T,alpha,beta,system_size, dt, sigma, A, timescale) for i in range(samples)]
+    
+    if normalize:
+        for i in range(len(res)):
+            res[i]=(res[i][0],[tuple(np.array(v)/system_size) for v in res[i][1]])
+        
+    return res
+

stopro/exponential_ornstein_uhlenbeck.py

@@ -0,0 +1,83 @@
+import numpy as np
+
+from ._utils import _as_vector
+from .ornstein_uhlenbeck import ornstein_uhlenbeck
+
+
+def exponential_ornstein_uhlenbeck(
+    T,
+    dt=None,
+    *,
+    steps=None,
+    gap=1,
+    N=1,
+    samples=1,
+    mean=1.0,
+    coeff_var=1.0,
+    timescale=1.0,
+    initial_condition=None,
+    covariance=None,
+    mixing_matrix=None,
+):
+    """
+    Simulate an exponential Ornstein–Uhlenbeck (lognormal OU) process on [0, T].
+
+    Constructs X from an OU process Z via
+
+        X_i(t) = A_i * exp(B_i * Z_i(t)),
+
+    where Z has stationary mean 0 and stationary stdev 1 (OU timescale set by
+    `timescale`). A and B are chosen so that X has the specified `mean` and
+    coefficient of variation `coeff_var` (component-wise).
+
+    Provide exactly one of `dt` or `steps`. Noise correlation can be specified via
+    `covariance` or `mixing_matrix` (mutually exclusive). Use `gap>1` to subsample.
+
+    Returns
+    -------
+    dict
+        The return dict from `ornstein_uhlenbeck`, with 'X' replaced by the
+        exponential transform and added keys: 'mean', 'coeff_var', 'A', 'B'.
+    """
+    N = int(N)
+    if N <= 0:
+        raise ValueError("N must be a positive integer.")
+
+    mean = _as_vector(mean, N, "mean")
+    coeff_var = _as_vector(coeff_var, N, "coeff_var")
+
+    if np.any(mean <= 0):
+        raise ValueError("mean must be positive.")
+    if np.any(coeff_var < 0):
+        raise ValueError("coeff_var must be >= 0.")
+    if np.any(np.asarray(timescale, dtype=float) <= 0):
+        raise ValueError("timescale must be > 0.")
+
+    # For Z ~ N(0,1):  CV^2 = exp(B^2) - 1  =>  B = sqrt(log(1 + CV^2))
+    #                 E[X]  = A exp(B^2/2)  =>  A = mean / exp(B^2/2) = mean / sqrt(1 + CV^2)
+    A = mean / np.sqrt(1.0 + coeff_var**2)
+    B = np.sqrt(np.log(1.0 + coeff_var**2))
+
+    # Underlying OU: keep stationary stdev=1 so A/B calibration is correct.
+    res = ornstein_uhlenbeck(
+        T,
+        dt,
+        steps=steps,
+        gap=gap,
+        N=N,
+        samples=samples,
+        initial_condition=initial_condition,
+        stdev=1.0,
+        timescale=timescale,
+        covariance=covariance,
+        mixing_matrix=mixing_matrix,
+    )
+
+    Z = res["X"]  # (samples, N, K)
+    res["X"] = A[None, :, None] * np.exp(B[None, :, None] * Z)
+
+    res["mean"] = mean
+    res["coeff_var"] = coeff_var
+    res["A"] = A
+    res["B"] = B
+    return res