intensify 0.2.0__py3-none-any.whl

intensify/__init__.py

@@ -0,0 +1,96 @@
+"""
+Intensify — A modern library for point process modeling with Hawkes specialization.
+"""
+
+__version__ = "0.2.0"
+
+from .backends import get_backend, get_backend_name, set_backend
+
+# Core abstractions
+# Config API
+from ._config import config_get, config_reset, config_set
+from .core.base import PointProcess
+from .core.inference import (
+    BayesianInference,
+    FitResult,
+    MLEInference,
+    OnlineInference,
+    get_inference_engine,
+)
+from .core.kernels import (
+    ApproxPowerLawKernel,
+    ExponentialKernel,
+    Kernel,
+    NonparametricKernel,
+    PowerLawKernel,
+    SumExponentialKernel,
+)
+from .core.regularizers import ElasticNet, L1
+from .core.processes import (
+    Hawkes,  # alias to UnivariateHawkes
+    HomogeneousPoisson,
+    InhomogeneousPoisson,
+    LogGaussianCoxProcess,
+    MarkedHawkes,
+    MultivariateHawkes,
+    MultivariateNonlinearHawkes,
+    NonlinearHawkes,
+    Poisson,  # alias to HomogeneousPoisson
+    ShotNoiseCoxProcess,
+    UnivariateHawkes,
+)
+from .visualization import (
+    plot_connectivity,
+    plot_event_aligned_histogram,
+    plot_intensity,
+    plot_inter_event_intervals,
+    plot_kernel,
+)
+
+__all__ = [
+    # Metadata
+    "__version__",
+    # Backend
+    "get_backend",
+    "set_backend",
+    "get_backend_name",
+    # Kernels
+    "Kernel",
+    "ExponentialKernel",
+    "SumExponentialKernel",
+    "PowerLawKernel",
+    "ApproxPowerLawKernel",
+    "NonparametricKernel",
+    # Processes
+    "PointProcess",
+    "HomogeneousPoisson",
+    "InhomogeneousPoisson",
+    "Poisson",
+    "UnivariateHawkes",
+    "Hawkes",
+    "MultivariateHawkes",
+    "MarkedHawkes",
+    "NonlinearHawkes",
+    "MultivariateNonlinearHawkes",
+    "LogGaussianCoxProcess",
+    "ShotNoiseCoxProcess",
+    # Regularizers
+    "L1",
+    "ElasticNet",
+    # Inference
+    "FitResult",
+    "get_inference_engine",
+    "MLEInference",
+    "OnlineInference",
+    "BayesianInference",
+    # Visualization
+    "plot_intensity",
+    "plot_kernel",
+    "plot_connectivity",
+    "plot_inter_event_intervals",
+    "plot_event_aligned_histogram",
+    # Config
+    "config_get",
+    "config_set",
+    "config_reset",
+]

intensify/_config.py

@@ -0,0 +1,41 @@
+"""Global configuration for intensify."""
+
+
+# Configuration defaults
+_DEFAULTS = {
+    "recursive_warning_threshold": 50_000,  # warn if N > 50k and using O(N^2) kernel
+    "float64_auto_enable": True,  # automatically enable x64 for float64 inputs
+    "warn_on_nonstationary": True,
+    "performance_warning": True,
+}
+
+# Current config (mutable)
+_CONFIG: dict[str, object] = _DEFAULTS.copy()
+
+
+def get(key: str):
+    """Get configuration value."""
+    return _CONFIG.get(key, _DEFAULTS.get(key))
+
+
+# Public aliases for package exports
+config_get = get
+
+
+def set_config(key: str, value: object) -> None:
+    """Set configuration value."""
+    if key not in _DEFAULTS:
+        raise KeyError(f"Unknown config key '{key}'. Valid keys: {list(_DEFAULTS.keys())}")
+    _CONFIG[key] = value
+
+
+config_set = set_config
+
+
+def reset() -> None:
+    """Reset configuration to defaults."""
+    _CONFIG.clear()
+    _CONFIG.update(_DEFAULTS)
+
+
+config_reset = reset

intensify/backends/__init__.py

@@ -0,0 +1,10 @@
+"""
+Backend abstraction layer.
+
+All numerical operations in the library should import from here
+to remain backend-agnostic (JAX vs NumPy).
+"""
+
+from ._backend import _active_backend, get_backend, get_backend_name, set_backend
+
+__all__ = ["get_backend", "get_backend_name", "set_backend", "_active_backend"]

intensify/backends/_backend.py

@@ -0,0 +1,90 @@
+"""Backend selection and dispatch."""
+
+import warnings
+
+from . import jax_backend, numpy_backend
+
+_active_backend: object | None = None
+_backend_name: str = "jax"  # default
+
+
+class _BackendProxy:
+    """Thin wrapper that always delegates to the currently active backend.
+
+    Lets modules cache ``bt = get_backend()`` at import time while still
+    picking up later ``set_backend()`` switches — every attribute access
+    resolves through ``_resolve_backend()`` on demand.
+    """
+
+    __slots__ = ()
+
+    def __getattr__(self, name: str):
+        return getattr(_resolve_backend(), name)
+
+    def __repr__(self) -> str:
+        return f"<BackendProxy active={_backend_name}>"
+
+
+_PROXY = _BackendProxy()
+
+
+def _resolve_backend() -> object:
+    """Return the concrete backend module, initializing on first call."""
+    global _active_backend, _backend_name
+    if _active_backend is None:
+        if jax_backend.is_available():
+            jax_backend.enable_x64()
+            _active_backend = jax_backend.backend
+            _backend_name = "jax"
+        elif numpy_backend.is_available():
+            _active_backend = numpy_backend.backend
+            _backend_name = "numpy"
+        else:
+            raise RuntimeError(
+                "Neither JAX nor NumPy is available. Please install one of them."
+            )
+    return _active_backend
+
+
+def set_backend(name: str) -> None:
+    """Set the active backend: 'jax' or 'numpy'."""
+    global _active_backend, _backend_name
+    name = name.lower()
+    if name == "jax":
+        if not jax_backend.is_available():
+            warnings.warn(
+                "JAX backend requested but JAX is not available. Falling back to NumPy.",
+                RuntimeWarning,
+            )
+            _active_backend = numpy_backend.backend
+            _backend_name = "numpy"
+        else:
+            jax_backend.enable_x64()
+            _active_backend = jax_backend.backend
+            _backend_name = "jax"
+    elif name == "numpy":
+        _active_backend = numpy_backend.backend
+        _backend_name = "numpy"
+    else:
+        raise ValueError(f"Unknown backend '{name}'. Use 'jax' or 'numpy'.")
+
+
+def get_backend() -> object:
+    """Return a proxy to the active backend.
+
+    The returned proxy delegates every attribute access to the concrete
+    backend at the moment of access, so ``bt = get_backend()`` cached in
+    module scope stays valid across later ``set_backend()`` calls.
+    """
+    _resolve_backend()
+    return _PROXY
+
+
+def get_backend_name() -> str:
+    """Return the name of the active backend ('jax' or 'numpy')."""
+    get_backend()  # Ensure initialized
+    return _backend_name
+
+
+# Expose the active backend's namespace at module level for convenience
+# All functions/tools will be accessed via get_backend()

intensify/backends/jax_backend.py

@@ -0,0 +1,132 @@
+"""JAX backend implementation."""
+
+from types import SimpleNamespace
+
+# Attempt to import JAX
+try:
+    import jax
+    import jax.lax
+    import jax.numpy as jnp
+    import jax.random as random
+    from jax import config as jax_config
+    from jax import grad, jit, pmap, value_and_grad, vmap
+    HAS_JAX = True
+except ImportError as e:  # pragma: no cover
+    HAS_JAX = False
+    jnp = None
+    jax = None
+    jax_config = None
+    grad = None
+    jit = None
+    random = None
+    vmap = None
+    pmap = None
+    IMPORT_ERROR = e
+
+
+def enable_x64():
+    """Enable 64-bit precision in JAX."""
+    if HAS_JAX:
+        jax_config.update("jax_enable_x64", True)
+
+
+def is_available():
+    return HAS_JAX
+
+
+backend = SimpleNamespace(
+    # Array types and constructors
+    array=lambda *args, **kwargs: jnp.array(*args, **kwargs) if HAS_JAX else None,
+    asarray=lambda *args, **kwargs: jnp.asarray(*args, **kwargs) if HAS_JAX else None,
+    zeros=lambda *args, **kwargs: jnp.zeros(*args, **kwargs) if HAS_JAX else None,
+    ones=lambda *args, **kwargs: jnp.ones(*args, **kwargs) if HAS_JAX else None,
+    zeros_like=lambda *args, **kwargs: jnp.zeros_like(*args, **kwargs) if HAS_JAX else None,
+    ones_like=lambda *args, **kwargs: jnp.ones_like(*args, **kwargs) if HAS_JAX else None,
+    full=lambda *args, **kwargs: jnp.full(*args, **kwargs) if HAS_JAX else None,
+    arange=lambda *args, **kwargs: jnp.arange(*args, **kwargs) if HAS_JAX else None,
+    linspace=lambda *args, **kwargs: jnp.linspace(*args, **kwargs) if HAS_JAX else None,
+    # Basic math ops
+    exp=jnp.exp if HAS_JAX else None,
+    log=jnp.log if HAS_JAX else None,
+    log1p=jnp.log1p if HAS_JAX else None,
+    sqrt=jnp.sqrt if HAS_JAX else None,
+    square=jnp.square if HAS_JAX else None,
+    power=jnp.power if HAS_JAX else None,
+    abs=jnp.abs if HAS_JAX else None,
+    sign=jnp.sign if HAS_JAX else None,
+    sin=jnp.sin if HAS_JAX else None,
+    cos=jnp.cos if HAS_JAX else None,
+    tan=jnp.tan if HAS_JAX else None,
+    # Reduction ops
+    sum=jnp.sum if HAS_JAX else None,
+    mean=jnp.mean if HAS_JAX else None,
+    max=jnp.max if HAS_JAX else None,
+    min=jnp.min if HAS_JAX else None,
+    std=jnp.std if HAS_JAX else None,
+    var=jnp.var if HAS_JAX else None,
+    prod=jnp.prod if HAS_JAX else None,
+    any=jnp.any if HAS_JAX else None,
+    all=jnp.all if HAS_JAX else None,
+    # Array manipulation
+    concatenate=jnp.concatenate if HAS_JAX else None,
+    stack=jnp.stack if HAS_JAX else None,
+    reshape=jnp.reshape if HAS_JAX else None,
+    transpose=jnp.transpose if HAS_JAX else None,
+    swapaxes=jnp.swapaxes if HAS_JAX else None,
+    squeeze=jnp.squeeze if HAS_JAX else None,
+    expand_dims=jnp.expand_dims if HAS_JAX else None,
+    split=jnp.split if HAS_JAX else None,
+    roll=jnp.roll if HAS_JAX else None,
+    repeat=jnp.repeat if HAS_JAX else None,
+    tile=jnp.tile if HAS_JAX else None,
+    # Indexing and slicing
+    take=jnp.take if HAS_JAX else None,
+    where=jnp.where if HAS_JAX else None,
+    select=jnp.select if HAS_JAX else None,
+    # Linear algebra
+    dot=jnp.dot if HAS_JAX else None,
+    matmul=jnp.matmul if HAS_JAX else None,
+    inner=jnp.inner if HAS_JAX else None,
+    outer=jnp.outer if HAS_JAX else None,
+    cross=jnp.cross if HAS_JAX else None,
+    linalg=jax.numpy.linalg if HAS_JAX else None,
+    # Statistics
+    median=jnp.median if HAS_JAX else None,
+    quantile=jnp.quantile if HAS_JAX else None,
+    # Array operations
+    diff=jnp.diff if HAS_JAX else None,
+    cumsum=jnp.cumsum if HAS_JAX else None,
+    # Random
+    random=random if HAS_JAX else None,
+    PRNGKey=jax.random.PRNGKey if HAS_JAX else None,
+    # Control flow and transformations
+    lax=jax.lax if HAS_JAX else None,
+    jit=jit if HAS_JAX else None,
+    grad=grad if HAS_JAX else None,
+    value_and_grad=value_and_grad if HAS_JAX else None,
+    vmap=vmap if HAS_JAX else None,
+    pmap=pmap if HAS_JAX else None,
+    cond=jax.lax.cond if HAS_JAX else None,
+    scan=jax.lax.scan if HAS_JAX else None,
+    # Utility functions
+    dtype=jnp.dtype if HAS_JAX else None,
+    finfo=jnp.finfo if HAS_JAX else None,
+    iinfo=jnp.iinfo if HAS_JAX else None,
+    isfinite=jnp.isfinite if HAS_JAX else None,
+    isnan=jnp.isnan if HAS_JAX else None,
+    isinf=jnp.isinf if HAS_JAX else None,
+    allclose=jnp.allclose if HAS_JAX else None,
+    array_equal=jnp.array_equal if HAS_JAX else None,
+    # Configuration
+    config=jax_config if HAS_JAX else None,
+    enable_x64=enable_x64,
+    is_available=is_available,
+    scipy_optimize=None,
+)
+
+__all__ = [
+    "backend",
+    "enable_x64",
+    "is_available",
+    "HAS_JAX",
+]

intensify/backends/numpy_backend.py

@@ -0,0 +1,144 @@
+"""NumPy backend implementation (fallback when JAX is unavailable)."""
+
+from types import SimpleNamespace
+
+try:
+    import numpy as np
+except ImportError:  # pragma: no cover
+    np = None  # type: ignore[assignment]
+
+try:
+    import scipy.optimize as opt
+except ImportError:  # pragma: no cover
+    opt = None
+
+HAS_NUMPY = np is not None
+
+
+def is_available() -> bool:
+    return HAS_NUMPY
+
+
+def _noop_random(name: str):
+    def _f(*_a, **_k):
+        raise RuntimeError(
+            f"numpy backend random.{name} called but NumPy is not available."
+        )
+
+    return _f
+
+
+if HAS_NUMPY:
+    _random_ns = SimpleNamespace(
+        PRNGKey=lambda seed: None,
+        split=lambda key, num: [None] * num,
+        uniform=lambda key=None, shape=None, low=0.0, high=1.0, size=None, dtype=None: (
+            np.random.uniform(low, high, size if size is not None else shape).astype(dtype)
+            if dtype
+            else np.random.uniform(low, high, size if size is not None else shape)
+        ),
+        normal=lambda key=None, shape=None, loc=0.0, scale=1.0, size=None, dtype=None: (
+            np.random.normal(loc, scale, size if size is not None else shape).astype(dtype)
+            if dtype
+            else np.random.normal(loc, scale, size if size is not None else shape)
+        ),
+        exponential=lambda key=None, shape=None, scale=1.0, size=None, dtype=None: (
+            np.random.exponential(scale, size if size is not None else shape).astype(dtype)
+            if dtype
+            else np.random.exponential(scale, size if size is not None else shape)
+        ),
+        poisson=lambda key=None, lam=1.0, shape=None: np.random.poisson(lam=lam, size=shape),
+    )
+else:  # pragma: no cover
+    _random_ns = SimpleNamespace(
+        PRNGKey=_noop_random("PRNGKey"),
+        split=_noop_random("split"),
+        uniform=_noop_random("uniform"),
+        normal=_noop_random("normal"),
+        exponential=_noop_random("exponential"),
+        poisson=_noop_random("poisson"),
+    )
+
+backend = SimpleNamespace(
+    array=lambda *args, **kwargs: np.array(*args, **kwargs) if HAS_NUMPY else None,
+    asarray=lambda *args, **kwargs: np.asarray(*args, **kwargs) if HAS_NUMPY else None,
+    zeros=lambda *args, **kwargs: np.zeros(*args, **kwargs) if HAS_NUMPY else None,
+    ones=lambda *args, **kwargs: np.ones(*args, **kwargs) if HAS_NUMPY else None,
+    zeros_like=lambda *args, **kwargs: np.zeros_like(*args, **kwargs) if HAS_NUMPY else None,
+    ones_like=lambda *args, **kwargs: np.ones_like(*args, **kwargs) if HAS_NUMPY else None,
+    full=lambda *args, **kwargs: np.full(*args, **kwargs) if HAS_NUMPY else None,
+    arange=lambda *args, **kwargs: np.arange(*args, **kwargs) if HAS_NUMPY else None,
+    linspace=lambda *args, **kwargs: np.linspace(*args, **kwargs) if HAS_NUMPY else None,
+    exp=np.exp if HAS_NUMPY else None,
+    log=np.log if HAS_NUMPY else None,
+    log1p=np.log1p if HAS_NUMPY else None,
+    power=np.power if HAS_NUMPY else None,
+    sqrt=np.sqrt if HAS_NUMPY else None,
+    square=np.square if HAS_NUMPY else None,
+    abs=np.abs if HAS_NUMPY else None,
+    sign=np.sign if HAS_NUMPY else None,
+    sin=np.sin if HAS_NUMPY else None,
+    cos=np.cos if HAS_NUMPY else None,
+    tan=np.tan if HAS_NUMPY else None,
+    sum=np.sum if HAS_NUMPY else None,
+    mean=np.mean if HAS_NUMPY else None,
+    max=np.max if HAS_NUMPY else None,
+    min=np.min if HAS_NUMPY else None,
+    std=np.std if HAS_NUMPY else None,
+    var=np.var if HAS_NUMPY else None,
+    prod=np.prod if HAS_NUMPY else None,
+    any=np.any if HAS_NUMPY else None,
+    all=np.all if HAS_NUMPY else None,
+    concatenate=np.concatenate if HAS_NUMPY else None,
+    stack=np.stack if HAS_NUMPY else None,
+    reshape=np.reshape if HAS_NUMPY else None,
+    transpose=np.transpose if HAS_NUMPY else None,
+    swapaxes=np.swapaxes if HAS_NUMPY else None,
+    squeeze=np.squeeze if HAS_NUMPY else None,
+    expand_dims=np.expand_dims if HAS_NUMPY else None,
+    split=np.split if HAS_NUMPY else None,
+    roll=np.roll if HAS_NUMPY else None,
+    repeat=np.repeat if HAS_NUMPY else None,
+    tile=np.tile if HAS_NUMPY else None,
+    take=np.take if HAS_NUMPY else None,
+    where=np.where if HAS_NUMPY else None,
+    select=np.select if HAS_NUMPY else None,
+    sort=np.sort if HAS_NUMPY else None,
+    dot=np.dot if HAS_NUMPY else None,
+    matmul=np.matmul if HAS_NUMPY else None,
+    inner=np.inner if HAS_NUMPY else None,
+    outer=np.outer if HAS_NUMPY else None,
+    cross=np.cross if HAS_NUMPY else None,
+    linalg=np.linalg if HAS_NUMPY else None,
+    diff=np.diff if HAS_NUMPY else None,
+    cumsum=np.cumsum if HAS_NUMPY else None,
+    median=np.median if HAS_NUMPY else None,
+    quantile=np.quantile if HAS_NUMPY else None,
+    random=_random_ns,
+    lax=SimpleNamespace(
+        cond=lambda pred, true_fun, false_fun, operand: (
+            true_fun(operand) if pred else false_fun(operand)
+        ),
+        scan=lambda f, init, xs, length=None: (init, []),
+    ),
+    jit=lambda f: f,
+    grad=None,
+    value_and_grad=None,
+    vmap=None,
+    pmap=None,
+    dtype=np.dtype if HAS_NUMPY else None,
+    finfo=np.finfo if HAS_NUMPY else None,
+    iinfo=np.iinfo if HAS_NUMPY else None,
+    isfinite=np.isfinite if HAS_NUMPY else None,
+    isnan=np.isnan if HAS_NUMPY else None,
+    isinf=np.isinf if HAS_NUMPY else None,
+    allclose=np.allclose if HAS_NUMPY else None,
+    array_equal=np.array_equal if HAS_NUMPY else None,
+    scipy_optimize=opt,
+    is_available=is_available,
+)
+
+__all__ = [
+    "backend",
+    "is_available",
+]

intensify/core/__init__.py

@@ -0,0 +1,57 @@
+"""Core abstractions and implementations."""
+
+from .base import PointProcess, PointProcessBase
+from .diagnostics import *
+from .inference import *
+from .kernels import *
+from .processes import *
+from .regularizers import L1, ElasticNet, Regularizer
+from .simulation import *
+
+__all__ = [
+    "PointProcess",
+    "PointProcessBase",
+    # Kernel subclasses
+    "Kernel",
+    "ExponentialKernel",
+    "SumExponentialKernel",
+    "PowerLawKernel",
+    "ApproxPowerLawKernel",
+    "NonparametricKernel",
+    # Process models
+    "HomogeneousPoisson",
+    "InhomogeneousPoisson",
+    "Hawkes",
+    "MultivariateHawkes",
+    "MarkedHawkes",
+    "NonlinearHawkes",
+    "MultivariateNonlinearHawkes",
+    "LogGaussianCoxProcess",
+    "ShotNoiseCoxProcess",
+    # Inference
+    "InferenceEngine",
+    "FitResult",
+    "MLEInference",
+    "EMInference",
+    "OnlineInference",
+    "BayesianInference",
+    "get_inference_engine",
+    "register_engine",
+    # Simulation
+    "ogata_thinning",
+    "ogata_thinning_multivariate",
+    "branching_simulation",
+    "branching_simulation_multivariate",
+    # Diagnostics
+    "time_rescaling_test",
+    "qq_plot",
+    "residual_intensity_plot",
+    "raw_residuals",
+    "pearson_residuals",
+    "compute_information_criteria",
+    "branching_ratio",
+    "endogeneity_index",
+    "L1",
+    "ElasticNet",
+    "Regularizer",
+]

intensify/core/base.py

@@ -0,0 +1,122 @@
+"""Abstract base classes for point process models."""
+
+from abc import ABC, abstractmethod
+from typing import Protocol, runtime_checkable
+
+from ..backends import get_backend
+
+bt = get_backend()
+
+
+@runtime_checkable
+class PointProcess(Protocol):
+    """Protocol defining the interface for point process models."""
+
+    @abstractmethod
+    def simulate(self, T: float, seed: int = None) -> bt.array:
+        """Generate event times on interval [0, T].
+
+        Parameters
+        ----------
+        T : float
+            End of observation window.
+        seed : int, optional
+            Random seed for reproducibility.
+
+        Returns
+        -------
+        events : jnp.ndarray or np.ndarray
+            Sorted array of event timestamps in [0, T].
+        """
+        pass
+
+    @abstractmethod
+    def intensity(self, t: float, history: bt.array) -> float:
+        """Evaluate conditional intensity function λ(t | history).
+
+        Parameters
+        ----------
+        t : float
+            Time at which to evaluate intensity.
+        history : jnp.ndarray or np.ndarray
+            Past event times before t.
+
+        Returns
+        -------
+        intensity : float
+            Conditional intensity value at time t.
+        """
+        pass
+
+    @abstractmethod
+    def log_likelihood(self, events: bt.array, T: float) -> float:
+        """Compute log-likelihood of observed event sequence.
+
+        Parameters
+        ----------
+        events : jnp.ndarray or np.ndarray
+            Event timestamps on [0, T].
+        T : float
+            End of observation window.
+
+        Returns
+        -------
+        ll : float
+            Log-likelihood value.
+        """
+        pass
+
+    def fit(self, events, T: float = None, method: str = "mle", **kwargs):
+        """Fit process parameters to observed event data.
+
+        Parameters
+        ----------
+        events : array-like or domain-specific data object
+            Event timestamps. May also accept domain objects (SpikeTrainData, OrderBookStream).
+        T : float, optional
+            Observation window end time. Inferred from events if not provided.
+        method : str
+            Inference method: 'mle', 'em', 'bayesian' (bayesian not yet implemented).
+
+        Returns
+        -------
+        result : FitResult
+            Standardized container with fitted parameters and diagnostics.
+        """
+        from .inference import get_inference_engine
+
+        # Infer T if not provided
+        if T is None:
+            import warnings
+            warnings.warn(
+                "T not specified; inferring T = max(events). "
+                "This may be incorrect if the observation window extends past the last event.",
+                UserWarning,
+            )
+            events_array = bt.asarray(events)
+            T = float(events_array.max())
+
+        engine = get_inference_engine(method)
+        return engine.fit(self, events, T, **kwargs)
+
+    def get_params(self) -> dict:
+        """Return model parameters as a dict (for optimization)."""
+        raise NotImplementedError
+
+    def set_params(self, params: dict) -> None:
+        """Set model parameters from a dict."""
+        raise NotImplementedError
+
+    def project_params(self) -> None:
+        """Project parameters onto feasible set (e.g., enforce stationarity)."""
+        pass  # default: nothing to project
+
+
+class PointProcessBase(ABC, PointProcess):
+    """Convenience base class that implements get/set_params stubs and other helpers."""
+
+    def get_params(self) -> dict:
+        raise NotImplementedError
+
+    def set_params(self, params: dict) -> None:
+        raise NotImplementedError