jump-diffusion-estimation 0.2.0__py3-none-any.whl

jump_diffusion/models/__init__.py

@@ -0,0 +1,14 @@
+"""
+Jump-Diffusion Model Definitions
+
+This module contains the mathematical models for various types of
+jump-diffusion processes.
+"""
+
+from .jump_diffusion import JumpDiffusionModel
+from .base_model import BaseStochasticModel
+
+__all__ = [
+    "JumpDiffusionModel",
+    "BaseStochasticModel",
+]

jump_diffusion/models/base_model.py

@@ -0,0 +1,93 @@
+"""
+Base classes for stochastic process models.
+
+This module provides abstract base classes that define the interface
+for all stochastic process models in the library.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+import numpy as np
+
+
+class BaseStochasticModel(ABC):
+    """
+    Abstract base class for all stochastic process models.
+
+    This class defines the common interface that all models must implement,
+    ensuring consistency and extensibility across different model types.
+    """
+
+    def __init__(self, **kwargs):
+        """Initialize the model with parameters."""
+        self.parameters = kwargs
+        self.fitted = False
+
+    @abstractmethod
+    def simulate(
+        self,
+        T: float,
+        n_steps: int,
+        x0: float = 1.0,
+        seed: Optional[int] = None,
+    ) -> tuple:
+        """
+        Simulate a path from the stochastic process.
+
+        Parameters:
+        -----------
+        T : float
+            Total time horizon
+        n_steps : int
+            Number of time steps
+        x0 : float
+            Initial value
+        seed : int, optional
+            Random seed for reproducibility
+
+        Returns:
+        --------
+        tuple
+            (times, path) or (times, path, additional_info)
+        """
+        pass
+
+    @abstractmethod
+    def log_likelihood(self, data: np.ndarray, dt: float) -> float:
+        """
+        Calculate the log-likelihood of observed data.
+
+        Parameters:
+        -----------
+        data : np.ndarray
+            Observed increments
+        dt : float
+            Time step size
+
+        Returns:
+        --------
+        float
+            Log-likelihood value
+        """
+        pass
+
+    @abstractmethod
+    def get_parameter_bounds(self) -> list:
+        """
+        Get parameter bounds for optimization.
+
+        Returns:
+        --------
+        list
+            List of (lower, upper) tuples for each parameter
+        """
+        pass
+
+    def update_parameters(self, **kwargs):
+        """Update model parameters."""
+        self.parameters.update(kwargs)
+        self.fitted = False
+
+    def get_parameters(self) -> Dict[str, Any]:
+        """Get current model parameters."""
+        return self.parameters.copy()

jump_diffusion/models/jump_diffusion.py

@@ -0,0 +1,168 @@
+"""
+Jump-Diffusion Model Implementation
+
+This module implements the jump-diffusion model with a pluggable jump-size
+distribution.
+"""
+
+import numpy as np
+from scipy.stats import norm
+from typing import Dict, Optional, Tuple
+from .base_model import BaseStochasticModel
+from ..distributions import JumpDistribution, SkewNormalJump
+
+
+class JumpDiffusionModel(BaseStochasticModel):
+    """
+    Jump-diffusion model with a pluggable jump-size distribution.
+
+    The model follows the SDE:
+    dX_t = μ dt + σ dW_t + J_t dN_t
+
+    Where J_t follows the distribution given by ``jump_distribution``
+    (skew-normal by default) and N_t is a Poisson process approximated by
+    Bernoulli trials.
+    """
+
+    def __init__(
+        self,
+        mu: float = 0.05,
+        sigma: float = 0.2,
+        jump_prob: float = 0.1,
+        jump_distribution: Optional[JumpDistribution] = None,
+        **jump_params: float,
+    ):
+        r"""
+        Initialize the jump-diffusion model.
+
+        Parameters:
+        -----------
+        mu : float
+            Drift parameter
+        sigma : float
+            Diffusion volatility
+        jump_prob : float
+            Probability of jump per time step
+        jump_distribution : JumpDistribution, optional
+            Distribution used for the jump sizes. Defaults to
+            :class:`SkewNormalJump`.
+        \*\*jump_params : float
+            Values for ``jump_distribution.param_names``. Any name not
+            supplied falls back to ``jump_distribution.default_params()``.
+        """
+        self.jump_distribution = jump_distribution or SkewNormalJump()
+
+        resolved_jump_params = self.jump_distribution.default_params()
+        resolved_jump_params.update(jump_params)
+
+        super().__init__(
+            mu=mu,
+            sigma=sigma,
+            jump_prob=jump_prob,
+            **resolved_jump_params,
+        )
+
+    def _jump_params(self) -> Dict[str, float]:
+        """Extract this model's jump-distribution parameter values."""
+        return {
+            name: self.parameters[name] for name in self.jump_distribution.param_names
+        }
+
+    def simulate(
+        self,
+        T: float,
+        n_steps: int,
+        x0: float = 1.0,
+        seed: Optional[int] = None,
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Simulate a jump-diffusion path.
+
+        Returns:
+        --------
+        tuple
+            (times, path, jumps) where jumps contains the jump component
+        """
+        if seed is not None:
+            np.random.seed(seed)
+
+        dt = T / n_steps
+        times = np.linspace(0, T, n_steps + 1)
+        path = np.zeros(n_steps + 1)
+        path[0] = x0
+
+        # Generate innovations
+        brownian_innovations = np.random.normal(0, 1, n_steps)
+        jump_indicators = np.random.binomial(
+            1,
+            self.parameters["jump_prob"],
+            n_steps,
+        )
+        jump_sizes = self.jump_distribution.rvs(self._jump_params(), size=n_steps)
+
+        # Construct path
+        for i in range(n_steps):
+            drift = self.parameters["mu"] * dt
+            sigma_term = self.parameters["sigma"] * np.sqrt(dt)
+            diffusion = sigma_term * brownian_innovations[i]
+            jump = jump_indicators[i] * jump_sizes[i]
+
+            path[i + 1] = path[i] + drift + diffusion + jump
+
+        jump_components = jump_indicators * jump_sizes
+
+        return times, path, jump_components
+
+    def log_likelihood(self, data: np.ndarray, dt: float) -> float:
+        """
+        Calculate log-likelihood of observed increments.
+        """
+        increments = data if data.ndim == 1 else np.diff(data)
+
+        # Calculate mixture densities
+        densities = self._mixture_density(increments, dt)
+        densities = np.maximum(densities, 1e-300)  # Numerical stability
+
+        return np.sum(np.log(densities))
+
+    def _mixture_density(self, x: np.ndarray, dt: float) -> np.ndarray:
+        """
+        Calculate mixture density for each increment.
+        """
+        mu = self.parameters["mu"]
+        sigma = self.parameters["sigma"]
+        p = self.parameters["jump_prob"]
+
+        # Pure diffusion component
+        diffusion_mean = mu * dt
+        diffusion_std = sigma * np.sqrt(dt)
+        diffusion_density = norm.pdf(
+            x,
+            loc=diffusion_mean,
+            scale=diffusion_std,
+        )
+
+        # Jump + diffusion component: use a closed form if the jump
+        # distribution has one, otherwise fall back to FFT convolution.
+        jump_params = self._jump_params()
+        jump_diffusion_density = self.jump_distribution.diffusion_convolved_pdf(
+            x, jump_params, diffusion_mean, diffusion_std
+        )
+        if jump_diffusion_density is None:
+            jump_diffusion_density = self.jump_distribution.fft_convolved_pdf(
+                x, jump_params, diffusion_mean, diffusion_std
+            )
+
+        # Mixture
+        return (1 - p) * diffusion_density + p * jump_diffusion_density
+
+    def get_parameter_bounds(self) -> list:
+        """Get parameter bounds for optimization."""
+        bounds = [
+            (None, None),  # mu
+            (1e-6, None),  # sigma > 0
+            (1e-6, 1 - 1e-6),  # 0 < jump_prob < 1
+        ]
+        jump_bounds = self.jump_distribution.param_bounds()
+        bounds += [jump_bounds[name] for name in self.jump_distribution.param_names]
+        return bounds

jump_diffusion/scripts/__init__.py

@@ -0,0 +1,3 @@
+"""Console scripts for jump-diffusion-estimation."""
+
+__all__ = ["validate", "benchmark"]

jump_diffusion/scripts/benchmark.py

@@ -0,0 +1,10 @@
+"""Placeholder benchmark script."""
+
+
+def main() -> None:
+    """Entry point for future benchmarking utilities."""
+    print("Benchmark functionality is not yet implemented.")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

jump_diffusion/scripts/validate.py

@@ -0,0 +1,74 @@
+"""Run validation experiments from the command line."""
+
+import argparse
+import json
+
+from ..validation import ValidationExperiment
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Run jump-diffusion validation experiment"
+    )
+    parser.add_argument(
+        "--n_sims",
+        type=int,
+        default=10,
+        help="Number of simulations",
+    )
+    parser.add_argument("--T", type=float, default=1.0, help="Time horizon")
+    parser.add_argument(
+        "--n_steps",
+        type=int,
+        default=252,
+        help="Number of time steps",
+    )
+    parser.add_argument("--output", type=str, help="Output file for results")
+    parser.add_argument("--seed", type=int, default=42, help="Random seed")
+
+    args = parser.parse_args()
+
+    true_params = {
+        "mu": 0.05,
+        "sigma": 0.2,
+        "jump_prob": 0.1,
+        "jump_scale": 0.15,
+        "jump_skew": 2.0,
+    }
+
+    print(f"Running validation with {args.n_sims} simulations...")
+    experiment = ValidationExperiment(true_params)
+    results_df = experiment.run_experiment(
+        n_simulations=args.n_sims,
+        T=args.T,
+        n_steps=args.n_steps,
+        seed_base=args.seed,
+    )
+
+    if len(results_df) == 0:
+        print("Validation experiment failed.")
+        raise SystemExit(1)
+
+    analysis = experiment.analyze_results()
+
+    if args.output:
+        output_data = {
+            "true_parameters": true_params,
+            "experiment_settings": {
+                "n_simulations": args.n_sims,
+                "T": args.T,
+                "n_steps": args.n_steps,
+                "seed": args.seed,
+            },
+            "results": results_df.to_dict("records"),
+            "analysis": analysis,
+        }
+        with open(args.output, "w") as f:
+            json.dump(output_data, f, indent=2, default=str)
+        print(f"Results saved to {args.output}")
+
+    experiment.plot_results()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

jump_diffusion/simulation/__init__.py

@@ -0,0 +1,14 @@
+"""
+Simulation Tools for Jump-Diffusion Processes
+
+This module provides tools for simulating various jump-diffusion processes
+with different jump distributions and arrival mechanisms.
+"""
+
+from .jump_diffusion_simulator import JumpDiffusionSimulator
+from .base_simulator import BaseSimulator
+
+__all__ = [
+    "JumpDiffusionSimulator",
+    "BaseSimulator",
+]

jump_diffusion/simulation/base_simulator.py

@@ -0,0 +1,51 @@
+"""
+Base simulator class for stochastic processes.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional, Tuple
+import numpy as np
+
+
+class BaseSimulator(ABC):
+    """
+    Abstract base class for all simulators.
+    """
+
+    def __init__(self, **kwargs):
+        """Initialize simulator with model parameters."""
+        self.parameters = kwargs
+
+    @abstractmethod
+    def simulate_path(
+        self,
+        T: float,
+        n_steps: int,
+        x0: float = 1.0,
+        seed: Optional[int] = None,
+    ) -> Tuple[np.ndarray, ...]:
+        """
+        Simulate a single path.
+
+        Parameters:
+        -----------
+        T : float
+            Time horizon
+        n_steps : int
+            Number of time steps
+        x0 : float
+            Initial value
+        seed : int, optional
+            Random seed
+
+        Returns:
+        --------
+        tuple
+            Simulation results
+        """
+        pass
+
+    @abstractmethod
+    def plot_simulation(self, *args, **kwargs):
+        """Plot simulation results."""
+        pass

jump_diffusion/simulation/jump_diffusion_simulator.py

@@ -0,0 +1,264 @@
+"""
+Jump-Diffusion Simulator Implementation
+
+This module contains JumpDiffusionSimulator, which builds on the path
+and likelihood math implemented in :class:`JumpDiffusionModel` and adds
+state-tracking and visualisation on top of it.
+"""
+
+import numpy as np
+import matplotlib.pyplot as plt
+from typing import Optional, Tuple
+from .base_simulator import BaseSimulator
+from ..models.jump_diffusion import JumpDiffusionModel
+from ..distributions import JumpDistribution
+
+
+class JumpDiffusionSimulator(BaseSimulator, JumpDiffusionModel):
+    """
+    Simulator for jump-diffusion processes with asymmetric jumps.
+
+    Inherits path generation from :class:`JumpDiffusionModel` and adds
+    state-tracking (for repeated plotting) and visualisation on top.
+    """
+
+    def __init__(
+        self,
+        mu: float = 0.05,
+        sigma: float = 0.2,
+        jump_prob: float = 0.1,
+        jump_distribution: Optional[JumpDistribution] = None,
+        **jump_params: float,
+    ):
+        r"""
+        Initialize the jump-diffusion simulator.
+
+        Parameters:
+        -----------
+        mu : float
+            Drift parameter
+        sigma : float
+            Diffusion volatility
+        jump_prob : float
+            Probability of jump per period
+        jump_distribution : JumpDistribution, optional
+            Distribution used for the jump sizes. Defaults to
+            :class:`SkewNormalJump`.
+        \*\*jump_params : float
+            Values for ``jump_distribution.param_names``, e.g.
+            ``jump_scale``/``jump_skew`` for the default skew-normal
+            distribution. Any name not supplied falls back to
+            ``jump_distribution.default_params()``.
+        """
+        JumpDiffusionModel.__init__(
+            self,
+            mu=mu,
+            sigma=sigma,
+            jump_prob=jump_prob,
+            jump_distribution=jump_distribution,
+            **jump_params,
+        )
+
+        # Store last simulation results
+        self.last_path: Optional[np.ndarray] = None
+        self.last_jumps: Optional[np.ndarray] = None
+        self.last_jump_times: Optional[np.ndarray] = None
+
+    def simulate_path(
+        self,
+        T: float = 1.0,
+        n_steps: int = 252,
+        x0: float = 1.0,
+        seed: Optional[int] = None,
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """
+        Simulate a complete jump-diffusion path.
+
+        Parameters:
+        -----------
+        T : float
+            Total simulation time
+        n_steps : int
+            Number of time steps
+        x0 : float
+            Initial value
+        seed : int, optional
+            Random seed for reproducibility
+
+        Returns:
+        --------
+        tuple
+            (times, path, jumps)
+        """
+        times, path, jump_components = self.simulate(
+            T=T, n_steps=n_steps, x0=x0, seed=seed
+        )
+        jump_times = np.where(jump_components != 0)[0]
+
+        # Store for plotting
+        self.last_path = path
+        self.last_jumps = jump_components
+        self.last_jump_times = jump_times
+
+        return times, path, jump_components
+
+    def plot_simulation(
+        self,
+        times=None,
+        path=None,
+        jumps=None,
+        figsize=(12, 8),
+        show_theoretical=True,
+    ):
+        """
+        Plot simulation results with comprehensive diagnostics.
+
+        Parameters
+        ----------
+        times : array-like, optional
+            Time grid for the plotted path. When ``None``, the time points from
+            the most recent call to :meth:`simulate_path` (uniformly spaced
+            between 0 and 1) are used.
+        path : array-like, optional
+            Simulated trajectory to visualise. Defaults to the last simulated
+            path stored by the simulator.
+        jumps : array-like, optional
+            Jump magnitudes for each step. Required to display jump-related
+            diagnostics. If ``None``, the jump component from the last
+            simulation is used.
+        figsize : tuple, optional
+            Figure size passed to :func:`matplotlib.pyplot.subplots`.
+        show_theoretical : bool, optional
+            When ``True`` (default) and at least one jump was realized,
+            overlay the jump distribution's theoretical ``pdf`` (evaluated at
+            ``self.jump_distribution`` / ``self._jump_params()``) on top of
+            the empirical jump-size histogram, so the plot doubles as a
+            visual check that simulated jumps match the selected
+            distribution's shape.
+
+        Returns
+        -------
+        matplotlib.figure.Figure
+            The created figure, e.g. for further customization or testing.
+
+        Notes
+        -----
+        The method creates a 2×2 grid of plots showing the trajectory with jump
+        markers, a stem plot of jump magnitudes, the distribution of increments,
+        and the distribution of jump sizes. If no arrays are provided and a
+        simulation has been run previously, these plots display the stored
+        results. Supplying ``times``, ``path`` and ``jumps`` overrides the stored
+        data and visualises the provided arrays instead.
+        """
+        if times is None or path is None:
+            if self.last_path is None:
+                raise ValueError(
+                    "No simulation data available. Run simulate_path() first."
+                )
+            times = np.linspace(0, 1, len(self.last_path))
+            path = self.last_path
+            jumps = self.last_jumps
+            jump_times = self.last_jump_times
+        else:
+            jump_times = (
+                np.where(jumps != 0)[0]
+                if jumps is not None
+                else np.array([], dtype=int)
+            )
+
+        fig, axes = plt.subplots(2, 2, figsize=figsize)
+
+        # Main trajectory plot
+        axes[0, 0].plot(times, path, "b-", linewidth=1.5, alpha=0.8)
+        if len(jump_times) > 0:
+            axes[0, 0].scatter(
+                times[1:][jump_times],
+                path[1:][jump_times],
+                color="red",
+                s=30,
+                alpha=0.7,
+                zorder=5,
+            )
+        axes[0, 0].set_title("Jump-Diffusion Path")
+        axes[0, 0].set_xlabel("Time")
+        axes[0, 0].set_ylabel("X(t)")
+        axes[0, 0].grid(True, alpha=0.3)
+
+        # Jump magnitudes
+        if len(jump_times) > 0 and jumps is not None:
+            jump_magnitudes = jumps[jump_times]
+            axes[0, 1].stem(jump_times, jump_magnitudes, basefmt=" ")
+            axes[0, 1].set_title(
+                f"Detected Jumps (Total: {len(jump_times)})",
+            )
+        else:
+            axes[0, 1].text(
+                0.5,
+                0.5,
+                "No jumps detected",
+                ha="center",
+                va="center",
+                transform=axes[0, 1].transAxes,
+            )
+            axes[0, 1].set_title("Detected Jumps (Total: 0)")
+        axes[0, 1].set_xlabel("Time Index")
+        axes[0, 1].set_ylabel("Jump Magnitude")
+        axes[0, 1].grid(True, alpha=0.3)
+
+        # Increment distribution
+        increments = np.diff(path)
+        axes[1, 0].hist(
+            increments,
+            bins=50,
+            density=True,
+            alpha=0.7,
+            color="skyblue",
+            edgecolor="black",
+        )
+        axes[1, 0].set_title("Distribution of Increments")
+        axes[1, 0].set_xlabel("ΔX")
+        axes[1, 0].set_ylabel("Density")
+        axes[1, 0].grid(True, alpha=0.3)
+
+        # Jump size distribution
+        if len(jump_times) > 0 and jumps is not None:
+            actual_jumps = jumps[jumps != 0]
+            axes[1, 1].hist(
+                actual_jumps,
+                bins=20,
+                density=True,
+                alpha=0.7,
+                color="orange",
+                edgecolor="black",
+                label="Simulated",
+            )
+            if show_theoretical:
+                x_grid = np.linspace(actual_jumps.min(), actual_jumps.max(), 200)
+                theoretical_density = self.jump_distribution.pdf(
+                    x_grid, self._jump_params()
+                )
+                axes[1, 1].plot(
+                    x_grid,
+                    theoretical_density,
+                    color="darkred",
+                    linewidth=2,
+                    label="Theoretical pdf",
+                )
+                axes[1, 1].legend()
+            axes[1, 1].set_title("Jump Size Distribution")
+        else:
+            axes[1, 1].text(
+                0.5,
+                0.5,
+                "No jumps to analyze",
+                ha="center",
+                va="center",
+                transform=axes[1, 1].transAxes,
+            )
+        axes[1, 1].set_xlabel("Jump Size")
+        axes[1, 1].set_ylabel("Density")
+        axes[1, 1].grid(True, alpha=0.3)
+
+        plt.tight_layout()
+
+        return fig