random-processes 0.1.0__tar.gz

random_processes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

random_processes-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.1
+Name: random-processes
+Version: 0.1.0
+Summary: Python library for generating random processes with specified autocorrelation properties. Supports custom kernels and multivariate correlated noise.
+Author-email: Alexander Abramov <extremal.ru@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/avabr/random-processes
+Project-URL: Repository, https://github.com/avabr/random-processes
+Project-URL: Issues, https://github.com/avabr/random-processes/issues
+Keywords: random-process,colored-noise,autocorrelation,stochastic,signal-processing,spectral-method
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+
+# random-processes
+
+Generate random processes with specified autocorrelation properties.
+
+## Quick start
+
+**Exponential:** `R(tau) = D * exp(-lambda * |tau|)`
+
+```python
+from random_processes import generate, exponential_kernel
+
+k = exponential_kernel(D=1.0, lam=2.0)
+t, x = generate(k, duration=100.0, dt=0.01, seed=42)
+```
+
+**Oscillating:** `R(tau) = D * exp(-lambda * |tau|) * cos(w0 * tau)`
+
+```python
+from random_processes import generate, oscillating_kernel
+
+k = oscillating_kernel(D=2.0, lam=0.5, w0=10.0)
+t, x = generate(k, duration=200.0, dt=0.005, seed=42)
+```
+
+**Custom kernel:**
+
+```python
+import numpy as np
+from random_processes import generate, AutocorrKernel
+
+k = AutocorrKernel(func=lambda tau: np.exp(-tau**2), name="gaussian")
+t, x = generate(k, duration=50.0, dt=0.01, seed=7)
+```
+
+
+
+![Exponential kernel](figures/exponential.png)
+
+
+
+![Oscillating kernel](figures/oscillating.png)
+
+## Multivariate correlated noise
+
+```python
+import numpy as np
+from random_processes import generate, exponential_kernel, oscillating_kernel
+
+kernels = [exponential_kernel(D=1.0, lam=2.0), oscillating_kernel(D=0.5, lam=1.0, w0=3.0)]
+corr = np.array([[1.0, 0.7],
+                 [0.7, 1.0]])
+t, X = generate(kernels, corr=corr, duration=100.0, dt=0.01, seed=42)
+# X.shape == (2, 10000)
+```
+
+## Visualization
+
+```python
+from random_processes.visualization import plot_realization, plot_correlation
+import matplotlib.pyplot as plt
+
+fig, axes = plt.subplots(2, 1, figsize=(10, 6))
+plot_realization(t, x, ax=axes[0])
+plot_correlation(t, x, k, ax=axes[1])
+plt.tight_layout()
+plt.show()
+```
+
+## Testing
+
+Confidence bands use Fisher z-transform with effective sample size to account for correlation in the data. This is an approximation (exact intervals require Bartlett's formula), but sufficient for validation purposes.
+
+Scalar (with plots / without):
+```bash
+python -c "from random_processes.testing import run_test_suite; run_test_suite()"
+python -c "from random_processes.testing import run_test_suite; run_test_suite(show_plots=False)"
+```
+
+Multivariate (with plots / without):
+```bash
+python -c "from random_processes.testing import run_multi_test_suite; run_multi_test_suite()"
+python -c "from random_processes.testing import run_multi_test_suite; run_multi_test_suite(show_plots=False)"
+```
+
+## Requirements
+
+- Python >= 3.10
+- numpy
+- scipy
+- matplotlib (for visualization)

random_processes-0.1.0/README.md

@@ -0,0 +1,90 @@
+# random-processes
+
+Generate random processes with specified autocorrelation properties.
+
+## Quick start
+
+**Exponential:** `R(tau) = D * exp(-lambda * |tau|)`
+
+```python
+from random_processes import generate, exponential_kernel
+
+k = exponential_kernel(D=1.0, lam=2.0)
+t, x = generate(k, duration=100.0, dt=0.01, seed=42)
+```
+
+**Oscillating:** `R(tau) = D * exp(-lambda * |tau|) * cos(w0 * tau)`
+
+```python
+from random_processes import generate, oscillating_kernel
+
+k = oscillating_kernel(D=2.0, lam=0.5, w0=10.0)
+t, x = generate(k, duration=200.0, dt=0.005, seed=42)
+```
+
+**Custom kernel:**
+
+```python
+import numpy as np
+from random_processes import generate, AutocorrKernel
+
+k = AutocorrKernel(func=lambda tau: np.exp(-tau**2), name="gaussian")
+t, x = generate(k, duration=50.0, dt=0.01, seed=7)
+```
+
+
+
+![Exponential kernel](figures/exponential.png)
+
+
+
+![Oscillating kernel](figures/oscillating.png)
+
+## Multivariate correlated noise
+
+```python
+import numpy as np
+from random_processes import generate, exponential_kernel, oscillating_kernel
+
+kernels = [exponential_kernel(D=1.0, lam=2.0), oscillating_kernel(D=0.5, lam=1.0, w0=3.0)]
+corr = np.array([[1.0, 0.7],
+                 [0.7, 1.0]])
+t, X = generate(kernels, corr=corr, duration=100.0, dt=0.01, seed=42)
+# X.shape == (2, 10000)
+```
+
+## Visualization
+
+```python
+from random_processes.visualization import plot_realization, plot_correlation
+import matplotlib.pyplot as plt
+
+fig, axes = plt.subplots(2, 1, figsize=(10, 6))
+plot_realization(t, x, ax=axes[0])
+plot_correlation(t, x, k, ax=axes[1])
+plt.tight_layout()
+plt.show()
+```
+
+## Testing
+
+Confidence bands use Fisher z-transform with effective sample size to account for correlation in the data. This is an approximation (exact intervals require Bartlett's formula), but sufficient for validation purposes.
+
+Scalar (with plots / without):
+```bash
+python -c "from random_processes.testing import run_test_suite; run_test_suite()"
+python -c "from random_processes.testing import run_test_suite; run_test_suite(show_plots=False)"
+```
+
+Multivariate (with plots / without):
+```bash
+python -c "from random_processes.testing import run_multi_test_suite; run_multi_test_suite()"
+python -c "from random_processes.testing import run_multi_test_suite; run_multi_test_suite(show_plots=False)"
+```
+
+## Requirements
+
+- Python >= 3.10
+- numpy
+- scipy
+- matplotlib (for visualization)

random_processes-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "random-processes"
+version = "0.1.0"
+description = "Python library for generating random processes with specified autocorrelation properties. Supports custom kernels and multivariate correlated noise."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "Alexander Abramov", email = "extremal.ru@gmail.com"},
+]
+keywords = ["random-process", "colored-noise", "autocorrelation", "stochastic", "signal-processing", "spectral-method"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy",
+    "scipy",
+    "matplotlib",
+]
+
+[project.urls]
+Homepage = "https://github.com/avabr/random-processes"
+Repository = "https://github.com/avabr/random-processes"
+Issues = "https://github.com/avabr/random-processes/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["random_processes*"]

random_processes-0.1.0/random_processes/__init__.py

@@ -0,0 +1,13 @@
+"""random_processes - Generate random processes with specified autocorrelation properties."""
+
+from .kernel import AutocorrKernel, exponential_kernel, oscillating_kernel
+from .generator import generate
+from .multi import generate_multi
+
+__all__ = [
+    "AutocorrKernel",
+    "exponential_kernel",
+    "oscillating_kernel",
+    "generate",
+    "generate_multi",
+]

random_processes-0.1.0/random_processes/generator.py

@@ -0,0 +1,86 @@
+"""Spectral (FFT-based) generation of colored noise with a given autocorrelation kernel."""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+
+from .kernel import AutocorrKernel
+
+
+def generate(
+    kernel: AutocorrKernel | list[AutocorrKernel],
+    duration: float,
+    dt: float,
+    seed: int | None = None,
+    corr: np.ndarray | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate a realization of a stationary random process with the given autocorrelation.
+
+    Uses the spectral method: R(tau) -> S(f) via FFT -> filter white noise in frequency domain.
+
+    If a list of kernels is passed, generates multivariate correlated noise
+    (requires ``corr`` — an N×N correlation matrix).
+
+    Parameters
+    ----------
+    kernel : AutocorrKernel or list of AutocorrKernel
+        Autocorrelation kernel(s). A list activates multivariate mode.
+    duration : float
+        Total time of the realization.
+    dt : float
+        Time step between samples.
+    seed : int, optional
+        Random seed for reproducibility.
+    corr : ndarray, optional
+        Correlation matrix (N×N). Required when kernel is a list.
+
+    Returns
+    -------
+    t : ndarray of shape (n,)
+        Time array.
+    x : ndarray of shape (n,) or (N, n)
+        Process realization(s).
+    """
+    if isinstance(kernel, list):
+        from .multi import generate_multi
+        if corr is None:
+            raise ValueError("corr is required when kernel is a list of kernels.")
+        return generate_multi(kernel, corr, duration, dt, seed)
+
+    rng = np.random.default_rng(seed)
+
+    n = int(duration / dt)
+    # Use power-of-2 length for efficient FFT, with padding to avoid circular correlation artifacts
+    n_fft = 2 * n
+    n_fft = 1 << (n_fft - 1).bit_length()  # next power of 2
+
+    # Build symmetric autocorrelation on the FFT grid
+    tau = np.arange(n_fft) * dt
+    tau[n_fft // 2 + 1:] = tau[n_fft // 2 + 1:] - n_fft * dt  # make symmetric: [..., -2dt, -dt]
+    R = kernel(tau)
+
+    # Power spectral density = FFT of autocorrelation (Wiener-Khinchin)
+    S = np.fft.rfft(R).real
+    neg_fraction = np.sum(S < 0) / len(S)
+    if neg_fraction > 0.01:
+        warnings.warn(
+            f"Kernel may not be positive definite: {neg_fraction:.1%} of spectral "
+            f"density values are negative (min={S.min():.4g}). "
+            f"The output process will have distorted autocorrelation.",
+            stacklevel=2,
+        )
+    S = np.maximum(S, 0.0)
+
+    # Generate white noise in frequency domain and shape it
+    white = rng.standard_normal(n_fft)
+    X_freq = np.fft.rfft(white)
+    X_freq *= np.sqrt(S)
+
+    # Back to time domain
+    x_full = np.fft.irfft(X_freq, n=n_fft)
+    x = x_full[:n]
+
+    t = np.arange(n) * dt
+    return t, x

random_processes-0.1.0/random_processes/kernel.py

@@ -0,0 +1,68 @@
+"""Autocorrelation kernels for colored noise generation."""
+
+from dataclasses import dataclass, field
+from typing import Callable
+
+import numpy as np
+
+
+@dataclass
+class AutocorrKernel:
+    """Autocorrelation kernel R(tau) defining the statistical properties of a random process.
+
+    Parameters
+    ----------
+    func : callable
+        Autocorrelation function R(tau). Must satisfy R(0) > 0 and |R(tau)| <= R(0).
+    name : str
+        Human-readable name for display purposes.
+    params : dict
+        Kernel parameters (for introspection and display).
+    """
+
+    func: Callable[[np.ndarray], np.ndarray]
+    name: str = ""
+    params: dict = field(default_factory=dict)
+
+    def __call__(self, tau: np.ndarray) -> np.ndarray:
+        return self.func(tau)
+
+    @property
+    def variance(self) -> float:
+        return float(self.func(np.array([0.0]))[0])
+
+
+def exponential_kernel(D: float, lam: float) -> AutocorrKernel:
+    """R(tau) = D * exp(-lambda * |tau|)
+
+    Parameters
+    ----------
+    D : float
+        Variance (dispersion) of the process.
+    lam : float
+        Decay rate (lambda). Larger values = faster decorrelation.
+    """
+    return AutocorrKernel(
+        func=lambda tau, D=D, lam=lam: D * np.exp(-lam * np.abs(tau)),
+        name="exponential",
+        params={"D": D, "lambda": lam},
+    )
+
+
+def oscillating_kernel(D: float, lam: float, w0: float) -> AutocorrKernel:
+    """R(tau) = D * exp(-lambda * |tau|) * cos(w0 * tau)
+
+    Parameters
+    ----------
+    D : float
+        Variance (dispersion) of the process.
+    lam : float
+        Decay rate (lambda).
+    w0 : float
+        Oscillation frequency (rad/s).
+    """
+    return AutocorrKernel(
+        func=lambda tau, D=D, lam=lam, w0=w0: D * np.exp(-lam * np.abs(tau)) * np.cos(w0 * tau),
+        name="oscillating",
+        params={"D": D, "lambda": lam, "w0": w0},
+    )

random_processes-0.1.0/random_processes/multi.py

@@ -0,0 +1,98 @@
+"""Multivariate correlated noise generation."""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+
+from .kernel import AutocorrKernel
+
+
+def generate_multi(
+    kernels: list[AutocorrKernel],
+    corr: np.ndarray,
+    duration: float,
+    dt: float,
+    seed: int | None = None,
+) -> tuple[np.ndarray, np.ndarray]:
+    """Generate N correlated random processes with given marginal autocorrelations.
+
+    Cross-spectral density is built as S_ij(f) = corr_ij * sqrt(S_i(f) * S_j(f)).
+
+    Parameters
+    ----------
+    kernels : list of AutocorrKernel
+        One kernel per channel (marginal autocorrelation).
+    corr : ndarray of shape (N, N)
+        Correlation matrix between channels. Must be positive definite.
+    duration : float
+        Total time of the realization.
+    dt : float
+        Time step between samples.
+    seed : int, optional
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    t : ndarray of shape (n,)
+        Time array.
+    X : ndarray of shape (N, n)
+        Process realizations, one row per channel.
+    """
+    rng = np.random.default_rng(seed)
+    corr = np.asarray(corr, dtype=float)
+    n_ch = len(kernels)
+
+    # Validate correlation matrix
+    try:
+        np.linalg.cholesky(corr)
+    except np.linalg.LinAlgError:
+        raise ValueError("Correlation matrix is not positive definite.")
+
+    n = int(duration / dt)
+    n_fft = 2 * n
+    n_fft = 1 << (n_fft - 1).bit_length()
+    n_freq = n_fft // 2 + 1
+
+    # Build symmetric tau grid
+    tau = np.arange(n_fft) * dt
+    tau[n_fft // 2 + 1:] = tau[n_fft // 2 + 1:] - n_fft * dt
+
+    # Compute marginal PSDs
+    S = np.empty((n_ch, n_freq))
+    for i, kernel in enumerate(kernels):
+        R = kernel(tau)
+        S_i = np.fft.rfft(R).real
+        neg_fraction = np.sum(S_i < 0) / len(S_i)
+        if neg_fraction > 0.01:
+            warnings.warn(
+                f"Kernel '{kernel.name}' (channel {i}) may not be positive definite: "
+                f"{neg_fraction:.1%} of spectral density values are negative.",
+                stacklevel=2,
+            )
+        S[i] = np.maximum(S_i, 0.0)
+
+    # Build cross-spectral matrix and Cholesky at each frequency
+    # S_cross[i,j,f] = corr[i,j] * sqrt(S[i,f] * S[j,f])
+    sqrt_S = np.sqrt(S)  # (n_ch, n_freq)
+    S_cross = corr[:, :, None] * (sqrt_S[:, None, :] * sqrt_S[None, :, :])  # (n_ch, n_ch, n_freq)
+
+    # Cholesky decomposition at each frequency: transpose to (n_freq, n_ch, n_ch)
+    S_cross = S_cross.transpose(2, 0, 1)  # (n_freq, n_ch, n_ch)
+    # Add small diagonal for numerical stability
+    S_cross += np.eye(n_ch)[None, :, :] * 1e-30
+    L = np.linalg.cholesky(S_cross)  # (n_freq, n_ch, n_ch)
+
+    # Generate N independent white noises in frequency domain
+    white = rng.standard_normal((n_ch, n_fft))
+    W = np.array([np.fft.rfft(white[i]) for i in range(n_ch)])  # (n_ch, n_freq)
+
+    # Mix channels: X_freq[i,f] = sum_j L[f,i,j] * W[j,f]
+    X_freq = np.einsum("fij,jf->if", L, W)
+
+    # Back to time domain
+    X = np.array([np.fft.irfft(X_freq[i], n=n_fft)[:n] for i in range(n_ch)])
+
+    t = np.arange(n) * dt
+    return t, X

random_processes-0.1.0/random_processes/testing.py

@@ -0,0 +1,328 @@
+"""Statistical testing of generated processes against their theoretical kernels."""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy import stats
+
+from .kernel import AutocorrKernel, exponential_kernel, oscillating_kernel
+from .generator import generate
+from .visualization import plot_realization, plot_correlation
+
+
+def _effective_sample_size(n: int, dt: float, kernel: AutocorrKernel) -> float:
+    """Estimate effective sample size for correlated data.
+
+    n_eff = n * dt / (2 * correlation_time), where correlation_time = integral_0^inf |R(tau)/R(0)| dtau,
+    estimated numerically.
+    """
+    R0 = kernel.variance
+    tau_max = 1000 * dt
+    tau_grid = np.linspace(0, tau_max, 10000)
+    r_norm = np.abs(kernel(tau_grid)) / R0
+    corr_time = np.trapz(r_norm, tau_grid)
+    n_eff = max(n * dt / (2 * corr_time), 10.0)
+    return n_eff
+
+
+def correlation_test(
+    t: np.ndarray,
+    x: np.ndarray,
+    kernel: AutocorrKernel,
+    confidence: float = 0.95,
+    max_lag_fraction: float = 0.1,
+) -> dict:
+    """Test whether empirical autocorrelation fits theoretical within confidence band.
+
+    Uses Fisher z-transform with effective sample size to account for correlation.
+
+    Returns
+    -------
+    dict with keys:
+        passed : bool
+        hit_rate : float — fraction of lags within the confidence interval
+        variance_ok : bool — whether empirical variance is within confidence interval
+        empirical_variance : float
+        theoretical_variance : float
+        n_eff : float — effective sample size used
+    """
+    n = len(x)
+    dt = t[1] - t[0]
+    max_lag = int(n * max_lag_fraction)
+
+    x_centered = x - x.mean()
+    var_emp = np.mean(x_centered**2)
+    var_theory = kernel.variance
+
+    lags = np.arange(1, max_lag)
+    r_emp = np.array([np.mean(x_centered[:n - k] * x_centered[k:]) / var_emp for k in lags])
+
+    tau = lags * dt
+    r_theory = kernel(tau) / var_theory
+
+    # Fisher z-transform test with effective sample size
+    n_eff = _effective_sample_size(n, dt, kernel)
+    z_alpha = stats.norm.ppf((1 + confidence) / 2)
+    z_theory = np.arctanh(np.clip(r_theory, -0.999, 0.999))
+    se = 1.0 / np.sqrt(max(n_eff - 3, 4))
+    r_upper = np.tanh(z_theory + z_alpha * se)
+    r_lower = np.tanh(z_theory - z_alpha * se)
+
+    hits = np.sum((r_emp >= r_lower) & (r_emp <= r_upper))
+    hit_rate = hits / len(lags)
+
+    # Variance confidence interval (chi-squared with effective df)
+    df_eff = max(n_eff - 1, 2)
+    chi2_lo = stats.chi2.ppf((1 - confidence) / 2, df_eff)
+    chi2_hi = stats.chi2.ppf((1 + confidence) / 2, df_eff)
+    var_lo = df_eff * var_emp / chi2_hi
+    var_hi = df_eff * var_emp / chi2_lo
+    variance_ok = var_lo <= var_theory <= var_hi
+
+    return {
+        "passed": hit_rate >= confidence and variance_ok,
+        "hit_rate": float(hit_rate),
+        "variance_ok": variance_ok,
+        "empirical_variance": float(var_emp),
+        "theoretical_variance": float(var_theory),
+        "n_eff": float(n_eff),
+    }
+
+
+def run_test_suite(show_plots: bool = True):
+    """Run tests for predefined kernels and optionally visualize results."""
+    import matplotlib.pyplot as plt
+
+    test_cases = [
+        # Exponential: varying decay and variance
+        {
+            "kernel": exponential_kernel(D=1.0, lam=2.0),
+            "duration": 100.0,
+            "dt": 0.01,
+            "seed": 42,
+        },
+        {
+            "kernel": exponential_kernel(D=0.5, lam=0.5),
+            "duration": 200.0,
+            "dt": 0.02,
+            "seed": 123,
+        },
+        {
+            "kernel": exponential_kernel(D=3.0, lam=10.0),
+            "duration": 50.0,
+            "dt": 0.005,
+            "seed": 11,
+        },
+        {
+            "kernel": exponential_kernel(D=0.1, lam=0.1),
+            "duration": 500.0,
+            "dt": 0.05,
+            "seed": 55,
+        },
+        # Oscillating: varying frequency and decay
+        {
+            "kernel": oscillating_kernel(D=1.0, lam=1.0, w0=5.0),
+            "duration": 100.0,
+            "dt": 0.01,
+            "seed": 77,
+        },
+        {
+            "kernel": oscillating_kernel(D=2.0, lam=0.5, w0=10.0),
+            "duration": 200.0,
+            "dt": 0.005,
+            "seed": 99,
+        },
+        {
+            "kernel": oscillating_kernel(D=1.0, lam=3.0, w0=20.0),
+            "duration": 50.0,
+            "dt": 0.002,
+            "seed": 33,
+        },
+        {
+            "kernel": oscillating_kernel(D=0.5, lam=0.2, w0=2.0),
+            "duration": 300.0,
+            "dt": 0.02,
+            "seed": 7,
+        },
+    ]
+
+    for i, case in enumerate(test_cases):
+        kernel = case["kernel"]
+        t, x = generate(kernel, case["duration"], case["dt"], seed=case["seed"])
+        result = correlation_test(t, x, kernel)
+
+        status = "PASSED" if result["passed"] else "FAILED"
+        print(
+            f"[{status}] {kernel.name} {kernel.params} | "
+            f"hit_rate={result['hit_rate']:.2%} "
+            f"var={result['empirical_variance']:.4f} (theory={result['theoretical_variance']:.4f}) "
+            f"var_ok={result['variance_ok']} n_eff={result['n_eff']:.0f}"
+        )
+
+        if show_plots:
+            fig, axes = plt.subplots(2, 1, figsize=(10, 6))
+            plot_realization(t, x, title=f"{kernel.name} {kernel.params}", ax=axes[0])
+            plot_correlation(t, x, kernel, ax=axes[1])
+            fig.tight_layout()
+
+    if show_plots:
+        plt.show()
+
+
+def cross_correlation_test(
+    t: np.ndarray,
+    X: np.ndarray,
+    kernels: list[AutocorrKernel],
+    corr: np.ndarray,
+    confidence: float = 0.95,
+) -> dict:
+    """Test whether empirical cross-correlations match the specified correlation matrix.
+
+    Uses Fisher z-transform with effective sample size.
+
+    Returns
+    -------
+    dict with keys:
+        passed : bool
+        results : list of dicts, one per channel pair (i, j) where i < j
+            Each contains: i, j, rho_theory, rho_empirical, ci_lower, ci_upper, ok
+        n_eff : float
+    """
+    n_ch, n = X.shape
+    dt = t[1] - t[0]
+
+    # Compute marginal PSDs for theoretical cross-correlation calculation
+    n_fft = 2 * n
+    n_fft = 1 << (n_fft - 1).bit_length()
+    tau = np.arange(n_fft) * dt
+    tau[n_fft // 2 + 1:] = tau[n_fft // 2 + 1:] - n_fft * dt
+    S_all = []
+    for k in kernels:
+        S_k = np.maximum(np.fft.rfft(k(tau)).real, 0.0)
+        S_all.append(S_k)
+
+    # Effective sample size: use the slowest-decorrelating kernel
+    n_effs = [_effective_sample_size(n, dt, k) for k in kernels]
+    n_eff = min(n_effs)
+
+    z_alpha = stats.norm.ppf((1 + confidence) / 2)
+    se = 1.0 / np.sqrt(max(n_eff - 3, 4))
+
+    pair_results = []
+    for i in range(n_ch):
+        for j in range(i + 1, n_ch):
+            # True instantaneous correlation accounts for spectral shape mismatch:
+            # rho_actual = corr_ij * sum(sqrt(S_i * S_j)) / sqrt(sum(S_i) * sum(S_j))
+            cross_sum = np.sum(np.sqrt(S_all[i] * S_all[j]))
+            auto_prod = np.sqrt(np.sum(S_all[i]) * np.sum(S_all[j]))
+            rho_theory = float(corr[i, j] * cross_sum / auto_prod)
+            rho_emp = float(np.corrcoef(X[i], X[j])[0, 1])
+
+            z_theory = np.arctanh(np.clip(rho_theory, -0.999, 0.999))
+            ci_lower = float(np.tanh(z_theory - z_alpha * se))
+            ci_upper = float(np.tanh(z_theory + z_alpha * se))
+            ok = ci_lower <= rho_emp <= ci_upper
+
+            pair_results.append({
+                "i": i, "j": j,
+                "rho_theory": rho_theory,
+                "rho_empirical": rho_emp,
+                "ci_lower": ci_lower,
+                "ci_upper": ci_upper,
+                "ok": ok,
+            })
+
+    all_ok = all(r["ok"] for r in pair_results)
+
+    # Also test each channel's autocorrelation
+    autocorr_ok = True
+    for i in range(n_ch):
+        res = correlation_test(t, X[i], kernels[i], confidence=confidence)
+        if not res["passed"]:
+            autocorr_ok = False
+
+    return {
+        "passed": all_ok and autocorr_ok,
+        "cross_correlation_ok": all_ok,
+        "autocorrelation_ok": autocorr_ok,
+        "pairs": pair_results,
+        "n_eff": float(n_eff),
+    }
+
+
+def run_multi_test_suite(show_plots: bool = True):
+    """Run tests for multivariate correlated noise generation."""
+    import matplotlib.pyplot as plt
+
+    multi_cases = [
+        {
+            "kernels": [exponential_kernel(D=1.0, lam=2.0), exponential_kernel(D=1.0, lam=2.0)],
+            "corr": np.array([[1.0, 0.8], [0.8, 1.0]]),
+            "duration": 200.0,
+            "dt": 0.01,
+            "seed": 42,
+        },
+        {
+            "kernels": [exponential_kernel(D=1.0, lam=2.0), oscillating_kernel(D=0.5, lam=1.0, w0=5.0)],
+            "corr": np.array([[1.0, 0.5], [0.5, 1.0]]),
+            "duration": 200.0,
+            "dt": 0.01,
+            "seed": 77,
+        },
+        {
+            "kernels": [exponential_kernel(D=1.0, lam=1.0), exponential_kernel(D=2.0, lam=0.5)],
+            "corr": np.array([[1.0, -0.6], [-0.6, 1.0]]),
+            "duration": 300.0,
+            "dt": 0.01,
+            "seed": 11,
+        },
+        {
+            "kernels": [
+                exponential_kernel(D=1.0, lam=2.0),
+                exponential_kernel(D=0.5, lam=1.0),
+                oscillating_kernel(D=1.0, lam=1.0, w0=3.0),
+            ],
+            "corr": np.array([
+                [1.0, 0.7, 0.3],
+                [0.7, 1.0, 0.5],
+                [0.3, 0.5, 1.0],
+            ]),
+            "duration": 500.0,
+            "dt": 0.01,
+            "seed": 99,
+        },
+    ]
+
+    for case in multi_cases:
+        kernels = case["kernels"]
+        corr_matrix = case["corr"]
+        n_ch = len(kernels)
+
+        t, X = generate(kernels, corr=corr_matrix, duration=case["duration"], dt=case["dt"], seed=case["seed"])
+        result = cross_correlation_test(t, X, kernels, corr_matrix)
+
+        status = "PASSED" if result["passed"] else "FAILED"
+        names = "+".join(k.name for k in kernels)
+        print(f"[{status}] {n_ch}ch {names} | autocorr={result['autocorrelation_ok']} n_eff={result['n_eff']:.0f}")
+        for p in result["pairs"]:
+            ok_str = "ok" if p["ok"] else "MISS"
+            print(
+                f"  ch{p['i']}-ch{p['j']}: "
+                f"rho={p['rho_empirical']:+.4f} (theory={p['rho_theory']:+.2f}) "
+                f"CI=[{p['ci_lower']:+.4f}, {p['ci_upper']:+.4f}] [{ok_str}]"
+            )
+
+        if show_plots:
+            fig, axes = plt.subplots(n_ch, 1, figsize=(10, 3 * n_ch))
+            if n_ch == 1:
+                axes = [axes]
+            for i in range(n_ch):
+                plot_realization(t, X[i], title=f"ch{i}: {kernels[i].name} {kernels[i].params}", ax=axes[i])
+            fig.tight_layout()
+
+    if show_plots:
+        plt.show()
+
+
+if __name__ == "__main__":
+    run_test_suite()

random_processes-0.1.0/random_processes/visualization.py

@@ -0,0 +1,80 @@
+"""Visualization utilities for colored noise analysis."""
+
+import numpy as np
+import matplotlib.pyplot as plt
+
+from .kernel import AutocorrKernel
+
+
+def plot_realization(t: np.ndarray, x: np.ndarray, title: str = "", ax=None):
+    """Plot a single realization of the random process."""
+    if ax is None:
+        _, ax = plt.subplots(figsize=(10, 3))
+    ax.plot(t, x, linewidth=0.5)
+    ax.set_xlabel("t")
+    ax.set_ylabel("x(t)")
+    ax.set_title(title or "Realization")
+    ax.grid(True, alpha=0.3)
+    return ax
+
+
+def plot_correlation(
+    t: np.ndarray,
+    x: np.ndarray,
+    kernel: AutocorrKernel,
+    max_lag_fraction: float = 0.1,
+    confidence: float = 0.95,
+    ax=None,
+):
+    """Plot empirical vs theoretical normalized autocorrelation with confidence band.
+
+    Parameters
+    ----------
+    t, x : ndarray
+        Time and process arrays.
+    kernel : AutocorrKernel
+        Theoretical autocorrelation kernel.
+    max_lag_fraction : float
+        Fraction of total samples to use as max lag.
+    confidence : float
+        Confidence level for Fisher z-transform interval.
+    """
+    from scipy import stats
+    from .testing import _effective_sample_size
+
+    if ax is None:
+        _, ax = plt.subplots(figsize=(10, 4))
+
+    n = len(x)
+    max_lag = int(n * max_lag_fraction)
+    dt = t[1] - t[0]
+
+    # Empirical normalized autocorrelation
+    x_centered = x - x.mean()
+    var = np.mean(x_centered**2)
+    lags = np.arange(max_lag)
+    r_emp = np.array([np.mean(x_centered[:n - k] * x_centered[k:]) / var for k in lags])
+
+    tau = lags * dt
+    r_theory = kernel(tau) / kernel(np.array([0.0]))[0]
+
+    # Fisher z-transform confidence interval with effective sample size
+    n_eff = _effective_sample_size(n, dt, kernel)
+    z_alpha = stats.norm.ppf((1 + confidence) / 2)
+    z_theory = np.arctanh(np.clip(r_theory[1:], -0.999, 0.999))
+    se = 1.0 / np.sqrt(max(n_eff - 3, 4))
+    r_upper = np.tanh(z_theory + z_alpha * se)
+    r_lower = np.tanh(z_theory - z_alpha * se)
+
+    ax.plot(tau, r_emp, label="empirical", linewidth=1)
+    ax.plot(tau, r_theory, "--", label="theoretical", linewidth=1)
+    ax.fill_between(
+        tau[1:], r_lower, r_upper, alpha=0.2, color="orange",
+        label=f"{confidence:.0%} confidence",
+    )
+    ax.set_xlabel("tau")
+    ax.set_ylabel("R(tau) / R(0)")
+    ax.set_title(f"Autocorrelation — {kernel.name}")
+    ax.legend()
+    ax.grid(True, alpha=0.3)
+    return ax

random_processes-0.1.0/random_processes.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.1
+Name: random-processes
+Version: 0.1.0
+Summary: Python library for generating random processes with specified autocorrelation properties. Supports custom kernels and multivariate correlated noise.
+Author-email: Alexander Abramov <extremal.ru@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/avabr/random-processes
+Project-URL: Repository, https://github.com/avabr/random-processes
+Project-URL: Issues, https://github.com/avabr/random-processes/issues
+Keywords: random-process,colored-noise,autocorrelation,stochastic,signal-processing,spectral-method
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: matplotlib
+
+# random-processes
+
+Generate random processes with specified autocorrelation properties.
+
+## Quick start
+
+**Exponential:** `R(tau) = D * exp(-lambda * |tau|)`
+
+```python
+from random_processes import generate, exponential_kernel
+
+k = exponential_kernel(D=1.0, lam=2.0)
+t, x = generate(k, duration=100.0, dt=0.01, seed=42)
+```
+
+**Oscillating:** `R(tau) = D * exp(-lambda * |tau|) * cos(w0 * tau)`
+
+```python
+from random_processes import generate, oscillating_kernel
+
+k = oscillating_kernel(D=2.0, lam=0.5, w0=10.0)
+t, x = generate(k, duration=200.0, dt=0.005, seed=42)
+```
+
+**Custom kernel:**
+
+```python
+import numpy as np
+from random_processes import generate, AutocorrKernel
+
+k = AutocorrKernel(func=lambda tau: np.exp(-tau**2), name="gaussian")
+t, x = generate(k, duration=50.0, dt=0.01, seed=7)
+```
+
+
+
+![Exponential kernel](figures/exponential.png)
+
+
+
+![Oscillating kernel](figures/oscillating.png)
+
+## Multivariate correlated noise
+
+```python
+import numpy as np
+from random_processes import generate, exponential_kernel, oscillating_kernel
+
+kernels = [exponential_kernel(D=1.0, lam=2.0), oscillating_kernel(D=0.5, lam=1.0, w0=3.0)]
+corr = np.array([[1.0, 0.7],
+                 [0.7, 1.0]])
+t, X = generate(kernels, corr=corr, duration=100.0, dt=0.01, seed=42)
+# X.shape == (2, 10000)
+```
+
+## Visualization
+
+```python
+from random_processes.visualization import plot_realization, plot_correlation
+import matplotlib.pyplot as plt
+
+fig, axes = plt.subplots(2, 1, figsize=(10, 6))
+plot_realization(t, x, ax=axes[0])
+plot_correlation(t, x, k, ax=axes[1])
+plt.tight_layout()
+plt.show()
+```
+
+## Testing
+
+Confidence bands use Fisher z-transform with effective sample size to account for correlation in the data. This is an approximation (exact intervals require Bartlett's formula), but sufficient for validation purposes.
+
+Scalar (with plots / without):
+```bash
+python -c "from random_processes.testing import run_test_suite; run_test_suite()"
+python -c "from random_processes.testing import run_test_suite; run_test_suite(show_plots=False)"
+```
+
+Multivariate (with plots / without):
+```bash
+python -c "from random_processes.testing import run_multi_test_suite; run_multi_test_suite()"
+python -c "from random_processes.testing import run_multi_test_suite; run_multi_test_suite(show_plots=False)"
+```
+
+## Requirements
+
+- Python >= 3.10
+- numpy
+- scipy
+- matplotlib (for visualization)

random_processes-0.1.0/random_processes.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+random_processes/__init__.py
+random_processes/generator.py
+random_processes/kernel.py
+random_processes/multi.py
+random_processes/testing.py
+random_processes/visualization.py
+random_processes.egg-info/PKG-INFO
+random_processes.egg-info/SOURCES.txt
+random_processes.egg-info/dependency_links.txt
+random_processes.egg-info/requires.txt
+random_processes.egg-info/top_level.txt

random_processes-0.1.0/random_processes.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

random_processes-0.1.0/random_processes.egg-info/requires.txt

@@ -0,0 +1,3 @@
+numpy
+scipy
+matplotlib

random_processes-0.1.0/random_processes.egg-info/top_level.txt

@@ -0,0 +1 @@
+random_processes

random_processes-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+