FinStoch 0.0.0__py3-none-any.whl

FinStoch/__init__.py

@@ -0,0 +1,35 @@
+"""FinStoch — A Python library for simulating stochastic processes in finance."""
+
+try:
+    from importlib.metadata import version, PackageNotFoundError
+
+    __version__ = version("FinStoch")
+except PackageNotFoundError:
+    try:
+        from FinStoch._version import version as __version__  # type: ignore[no-redef]
+    except ImportError:
+        __version__ = "0.0.0-unknown"
+
+__author__ = "Yosri Ben Halima"
+__email__ = "yosri.benhalima@ept.ucar.tn"
+__license__ = "MIT"
+
+from FinStoch.processes import (
+    StochasticProcess,
+    GeometricBrownianMotion,
+    MertonJumpDiffusion,
+    OrnsteinUhlenbeck,
+    CoxIngersollRoss,
+    HestonModel,
+    ConstantElasticityOfVariance,
+)
+
+__all__ = [
+    "StochasticProcess",
+    "GeometricBrownianMotion",
+    "MertonJumpDiffusion",
+    "OrnsteinUhlenbeck",
+    "CoxIngersollRoss",
+    "HestonModel",
+    "ConstantElasticityOfVariance",
+]

FinStoch/processes/__init__.py

@@ -0,0 +1,19 @@
+"""Stochastic process simulators."""
+
+from .base import StochasticProcess
+from .gbm import GeometricBrownianMotion
+from .merton import MertonJumpDiffusion
+from .ou import OrnsteinUhlenbeck
+from .cir import CoxIngersollRoss
+from .heston import HestonModel
+from .cev import ConstantElasticityOfVariance
+
+__all__ = [
+    "StochasticProcess",
+    "GeometricBrownianMotion",
+    "MertonJumpDiffusion",
+    "OrnsteinUhlenbeck",
+    "CoxIngersollRoss",
+    "HestonModel",
+    "ConstantElasticityOfVariance",
+]

FinStoch/processes/base.py

@@ -0,0 +1,202 @@
+"""Base class for all stochastic process simulators."""
+
+from abc import ABC, abstractmethod
+from typing import Union
+
+import numpy as np
+from pandas import DatetimeIndex
+
+from FinStoch.utils.plotting import plot_simulated_paths
+from FinStoch.utils.timesteps import (
+    generate_date_range_with_granularity,
+    date_range_duration,
+)
+
+
+class StochasticProcess(ABC):
+    """Abstract base class for stochastic process simulators.
+
+    Provides shared initialization, time grid management, and plotting
+    for all Euler-Maruyama discretized stochastic processes.
+
+    Parameters
+    ----------
+    S0 : float
+        The initial value of the process.
+    mu : float
+        The drift coefficient.
+    sigma : float
+        The volatility coefficient.
+    num_paths : int
+        The number of paths to simulate.
+    start_date : str
+        The start date for the simulation (e.g., '2023-09-01').
+    end_date : str
+        The end date for the simulation (e.g., '2023-12-31').
+    granularity : str
+        The time granularity for each step (e.g., 'D', 'H', '10T').
+    business_days : bool, optional
+        If True, use business days instead of calendar days when
+        granularity is 'D'. Default is False.
+    """
+
+    def __init__(
+        self,
+        S0: float,
+        mu: float,
+        sigma: float,
+        num_paths: int,
+        start_date: str,
+        end_date: str,
+        granularity: str,
+        business_days: bool = False,
+    ) -> None:
+        self._S0 = S0
+        self._mu = mu
+        self._sigma = sigma
+        self._num_paths = num_paths
+        self._start_date = start_date
+        self._end_date = end_date
+        self._granularity = granularity
+        self._business_days = business_days
+        self._recalculate_time_grid()
+
+    def _recalculate_time_grid(self) -> None:
+        """Recompute time grid attributes from date range and granularity."""
+        self._t = generate_date_range_with_granularity(
+            self._start_date, self._end_date, self._granularity, self._business_days
+        )
+        self._T = date_range_duration(self._t)
+        self._num_steps = len(self._t)
+        self._dt = self._T / self._num_steps
+
+    @abstractmethod
+    def simulate(self) -> Union[np.ndarray, tuple[np.ndarray, np.ndarray]]:
+        """Simulate paths of the stochastic process.
+
+        Returns
+        -------
+        np.ndarray or tuple[np.ndarray, np.ndarray]
+            A 2D array of shape (num_paths, num_steps), or a tuple of two
+            such arrays for models with multiple outputs (e.g., Heston).
+        """
+        ...
+
+    def plot(
+        self,
+        paths: np.ndarray | None = None,
+        title: str = "Simulated Paths",
+        ylabel: str = "Value",
+        fig_size: tuple | None = None,
+        **kwargs: object,
+    ) -> None:
+        """Plot simulated paths.
+
+        Parameters
+        ----------
+        paths : np.ndarray, optional
+            Pre-computed paths to plot. If None, calls simulate().
+        title : str
+            Plot title.
+        ylabel : str
+            Y-axis label.
+        fig_size : tuple, optional
+            Figure size in inches.
+        **kwargs
+            Additional keyword arguments passed to plot_simulated_paths.
+        """
+        plot_simulated_paths(
+            self._t,
+            self.simulate,
+            paths,
+            title=title,
+            ylabel=ylabel,
+            fig_size=fig_size,
+            grid=kwargs.get("grid", True),
+        )
+
+    # --- Shared properties ---
+
+    @property
+    def S0(self) -> float:
+        return self._S0
+
+    @S0.setter
+    def S0(self, value: float) -> None:
+        self._S0 = value
+
+    @property
+    def mu(self) -> float:
+        return self._mu
+
+    @mu.setter
+    def mu(self, value: float) -> None:
+        self._mu = value
+
+    @property
+    def sigma(self) -> float:
+        return self._sigma
+
+    @sigma.setter
+    def sigma(self, value: float) -> None:
+        self._sigma = value
+
+    @property
+    def T(self) -> float:
+        return self._T
+
+    @property
+    def num_steps(self) -> int:
+        return self._num_steps
+
+    @property
+    def num_paths(self) -> int:
+        return self._num_paths
+
+    @num_paths.setter
+    def num_paths(self, value: int) -> None:
+        self._num_paths = value
+
+    @property
+    def dt(self) -> float:
+        return self._dt
+
+    @property
+    def t(self) -> DatetimeIndex:
+        return self._t
+
+    @property
+    def start_date(self) -> str:
+        return self._start_date
+
+    @start_date.setter
+    def start_date(self, value: str) -> None:
+        self._start_date = value
+        self._recalculate_time_grid()
+
+    @property
+    def end_date(self) -> str:
+        return self._end_date
+
+    @end_date.setter
+    def end_date(self, value: str) -> None:
+        self._end_date = value
+        self._recalculate_time_grid()
+
+    @property
+    def granularity(self) -> str:
+        return self._granularity
+
+    @granularity.setter
+    def granularity(self, value: str) -> None:
+        self._granularity = value
+        self._recalculate_time_grid()
+
+    @property
+    def business_days(self) -> bool:
+        return self._business_days
+
+    @business_days.setter
+    def business_days(self, value: bool) -> None:
+        self._business_days = value
+        self._recalculate_time_grid()

FinStoch/processes/cev.py

@@ -0,0 +1,90 @@
+"""Constant Elasticity of Variance process."""
+
+import numpy as np
+
+from FinStoch.processes.base import StochasticProcess
+from FinStoch.utils.random import generate_random_numbers
+
+
+class ConstantElasticityOfVariance(StochasticProcess):
+    """Constant Elasticity of Variance (CEV) process simulator.
+
+    Models an asset price following the SDE:
+        dS = mu * S * dt + sigma * S^gamma * dW
+
+    Parameters
+    ----------
+    S0 : float
+        The initial value of the asset.
+    mu : float
+        The annualized drift coefficient.
+    sigma : float
+        The annualized volatility coefficient.
+    gamma : float
+        The elasticity parameter.
+    num_paths : int
+        The number of paths to simulate.
+    start_date : str
+        The start date for the simulation.
+    end_date : str
+        The end date for the simulation.
+    granularity : str
+        The time granularity for each step.
+    business_days : bool, optional
+        If True, use business days instead of calendar days. Default is False.
+    """
+
+    def __init__(
+        self,
+        S0: float,
+        mu: float,
+        sigma: float,
+        gamma: float,
+        num_paths: int,
+        start_date: str,
+        end_date: str,
+        granularity: str,
+        business_days: bool = False,
+    ) -> None:
+        self._gamma = gamma
+        super().__init__(S0, mu, sigma, num_paths, start_date, end_date, granularity, business_days)
+
+    def simulate(self) -> np.ndarray:
+        """Simulate paths of the CEV model.
+
+        Returns
+        -------
+        np.ndarray
+            A 2D array of shape (num_paths, num_steps).
+        """
+        S = np.zeros((self._num_paths, self._num_steps))
+        S[:, 0] = self._S0
+
+        for t in range(1, self._num_steps):
+            Z = generate_random_numbers("normal", self._num_paths, mean=0, stddev=1)
+            S[:, t] = (
+                S[:, t - 1]
+                + self._mu * S[:, t - 1] * self._dt
+                + self._sigma * (S[:, t - 1] ** self._gamma) * np.sqrt(self._dt) * Z
+            )
+
+        return S
+
+    def plot(
+        self,
+        paths: np.ndarray | None = None,
+        title: str = "Constant Elasticity of Variance",
+        ylabel: str = "Value",
+        fig_size: tuple | None = None,
+        **kwargs: object,
+    ) -> None:
+        """Plot simulated CEV paths."""
+        super().plot(paths, title=title, ylabel=ylabel, fig_size=fig_size, **kwargs)
+
+    @property
+    def gamma(self) -> float:
+        return self._gamma
+
+    @gamma.setter
+    def gamma(self, value: float) -> None:
+        self._gamma = value

FinStoch/processes/cir.py

@@ -0,0 +1,91 @@
+"""Cox-Ingersoll-Ross process."""
+
+import numpy as np
+
+from FinStoch.processes.base import StochasticProcess
+from FinStoch.utils.random import generate_random_numbers
+
+
+class CoxIngersollRoss(StochasticProcess):
+    """Cox-Ingersoll-Ross (CIR) mean-reverting process simulator.
+
+    Models a non-negative process following the SDE:
+        dS = theta * (mu - S) * dt + sigma * sqrt(S) * dW
+
+    Parameters
+    ----------
+    S0 : float
+        Initial value of the process.
+    mu : float
+        Long-term mean to which the process reverts.
+    sigma : float
+        Volatility parameter.
+    theta : float
+        Speed of reversion to the mean.
+    num_paths : int
+        Number of simulation paths to generate.
+    start_date : str
+        Starting date for the simulation.
+    end_date : str
+        Ending date for the simulation.
+    granularity : str
+        Granularity of time steps (e.g., '10T' for 10 minutes, 'H' for hours).
+    business_days : bool, optional
+        If True, use business days instead of calendar days. Default is False.
+    """
+
+    def __init__(
+        self,
+        S0: float,
+        mu: float,
+        sigma: float,
+        theta: float,
+        num_paths: int,
+        start_date: str,
+        end_date: str,
+        granularity: str,
+        business_days: bool = False,
+    ) -> None:
+        self._theta = theta
+        super().__init__(S0, mu, sigma, num_paths, start_date, end_date, granularity, business_days)
+
+    def simulate(self) -> np.ndarray:
+        """Simulate paths of the CIR model.
+
+        Returns
+        -------
+        np.ndarray
+            A 2D array of shape (num_paths, num_steps).
+        """
+        S = np.zeros((self._num_paths, self._num_steps))
+        S[:, 0] = self._S0
+
+        for t in range(1, self._num_steps):
+            Z = generate_random_numbers("normal", self._num_paths, mean=0, stddev=1)
+            drift = self._theta * (self._mu - S[:, t - 1]) * self._dt
+            diffusion = self._sigma * np.sqrt(S[:, t - 1]) * np.sqrt(self._dt) * Z
+            S[:, t] = S[:, t - 1] + drift + diffusion
+
+            # Ensure non-negativity
+            S[:, t] = np.maximum(S[:, t], 0)
+
+        return S
+
+    def plot(
+        self,
+        paths: np.ndarray | None = None,
+        title: str = "Cox-Ingersoll-Ross",
+        ylabel: str = "Value",
+        fig_size: tuple | None = None,
+        **kwargs: object,
+    ) -> None:
+        """Plot simulated CIR paths."""
+        super().plot(paths, title=title, ylabel=ylabel, fig_size=fig_size, **kwargs)
+
+    @property
+    def theta(self) -> float:
+        return self._theta
+
+    @theta.setter
+    def theta(self, value: float) -> None:
+        self._theta = value

FinStoch/processes/gbm.py

@@ -0,0 +1,59 @@
+"""Geometric Brownian Motion process."""
+
+import numpy as np
+
+from FinStoch.processes.base import StochasticProcess
+from FinStoch.utils.random import generate_random_numbers
+
+
+class GeometricBrownianMotion(StochasticProcess):
+    """Geometric Brownian Motion (GBM) process simulator.
+
+    Models an asset price following the SDE:
+        dS = mu * S * dt + sigma * S * dW
+
+    Parameters
+    ----------
+    S0 : float
+        The initial value of the asset.
+    mu : float
+        The annualized drift coefficient.
+    sigma : float
+        The annualized volatility coefficient.
+    num_paths : int
+        The number of paths to simulate.
+    start_date : str
+        The start date for the simulation (e.g., '2023-09-01').
+    end_date : str
+        The end date for the simulation (e.g., '2023-12-31').
+    granularity : str
+        The time granularity for each step (e.g., '10T' for 10 minutes, 'H' for hours).
+    """
+
+    def simulate(self) -> np.ndarray:
+        """Simulate paths of the GBM model.
+
+        Returns
+        -------
+        np.ndarray
+            A 2D array of shape (num_paths, num_steps).
+        """
+        S = np.zeros((self._num_paths, self._num_steps))
+        S[:, 0] = self._S0
+
+        for t in range(1, self._num_steps):
+            Z = generate_random_numbers("normal", self._num_paths, mean=0, stddev=1)
+            S[:, t] = S[:, t - 1] * np.exp((self._mu - 0.5 * self._sigma**2) * self._dt + self._sigma * np.sqrt(self._dt) * Z)
+
+        return S
+
+    def plot(
+        self,
+        paths: np.ndarray | None = None,
+        title: str = "Geometric Brownian Motion",
+        ylabel: str = "Value",
+        fig_size: tuple | None = None,
+        **kwargs: object,
+    ) -> None:
+        """Plot simulated GBM paths."""
+        super().plot(paths, title=title, ylabel=ylabel, fig_size=fig_size, **kwargs)

FinStoch/processes/heston.py

@@ -0,0 +1,169 @@
+"""Heston stochastic volatility model."""
+
+import numpy as np
+
+from FinStoch.processes.base import StochasticProcess
+from FinStoch.utils.plotting import plot_simulated_paths
+from FinStoch.utils.random import generate_random_numbers
+
+
+class HestonModel(StochasticProcess):
+    """Heston stochastic volatility model simulator.
+
+    Models an asset price with stochastic variance:
+        dS = mu * S * dt + sqrt(v) * S * dW_s
+        dv = kappa * (theta - v) * dt + sigma * sqrt(v) * dW_v
+        corr(dW_s, dW_v) = rho
+
+    Parameters
+    ----------
+    S0 : float
+        The initial value of the asset.
+    v0 : float
+        The initial variance.
+    mu : float
+        The drift rate of the asset.
+    sigma : float
+        The volatility of the variance (vol of vol).
+    theta : float
+        The long-term mean of the variance process.
+    kappa : float
+        The rate of mean reversion for the variance.
+    rho : float
+        The correlation between asset and variance Brownian motions.
+    num_paths : int
+        The number of paths to simulate.
+    start_date : str
+        The start date for the simulation.
+    end_date : str
+        The end date for the simulation.
+    granularity : str
+        The time granularity for each step.
+    business_days : bool, optional
+        If True, use business days instead of calendar days. Default is False.
+    """
+
+    def __init__(
+        self,
+        S0: float,
+        v0: float,
+        mu: float,
+        sigma: float,
+        theta: float,
+        kappa: float,
+        rho: float,
+        num_paths: int,
+        start_date: str,
+        end_date: str,
+        granularity: str,
+        business_days: bool = False,
+    ) -> None:
+        self._v0 = v0
+        self._theta = theta
+        self._kappa = kappa
+        self._rho = rho
+        super().__init__(S0, mu, sigma, num_paths, start_date, end_date, granularity, business_days)
+
+    def simulate(self) -> tuple[np.ndarray, np.ndarray]:
+        """Simulate paths of the Heston model.
+
+        Returns
+        -------
+        tuple[np.ndarray, np.ndarray]
+            A tuple (S, v) of 2D arrays of shape (num_paths, num_steps)
+            for asset prices and variance paths respectively.
+        """
+        S = np.zeros((self._num_paths, self._num_steps))
+        S[:, 0] = self._S0
+
+        v = np.zeros((self._num_paths, self._num_steps))
+        v[:, 0] = self._v0
+
+        for t in range(1, self._num_steps):
+            Xs, Xv = (
+                generate_random_numbers("normal", self._num_paths, mean=0, stddev=1),
+                generate_random_numbers("normal", self._num_paths, mean=0, stddev=1),
+            )
+            L = np.array([[1, 0], [self._rho, np.sqrt(1 - self._rho**2)]])
+
+            X = np.dot(L, np.array([Xs, Xv]))
+            Ws = X[0]
+            Wv = X[1]
+
+            v[:, t] = np.maximum(
+                v[:, t - 1]
+                + self._kappa * (self._theta - v[:, t - 1]) * self._dt
+                + self._sigma * np.sqrt(v[:, t - 1]) * np.sqrt(self._dt) * Wv,
+                0,
+            )
+            S[:, t] = S[:, t - 1] * np.exp(
+                (self._mu - 0.5 * v[:, t - 1]) * self._dt + np.sqrt(v[:, t - 1]) * np.sqrt(self._dt) * Ws
+            )
+
+        return S, v
+
+    def plot(
+        self,
+        paths: np.ndarray | None = None,
+        title: str = "Heston Model",
+        ylabel: str = "Value",
+        fig_size: tuple | None = None,
+        **kwargs: object,
+    ) -> None:
+        """Plot simulated Heston paths.
+
+        Parameters
+        ----------
+        paths : np.ndarray, optional
+            Pre-computed paths to plot.
+        title : str
+            Plot title.
+        ylabel : str
+            Y-axis label.
+        fig_size : tuple, optional
+            Figure size in inches.
+        **kwargs
+            Additional keyword arguments. Pass ``variance=True`` to plot
+            variance paths instead of asset prices.
+        """
+        plot_simulated_paths(
+            self._t,
+            self.simulate,
+            paths,
+            title=title,
+            ylabel=ylabel,
+            fig_size=fig_size,
+            **kwargs,
+        )
+
+    @property
+    def v0(self) -> float:
+        return self._v0
+
+    @v0.setter
+    def v0(self, value: float) -> None:
+        self._v0 = value
+
+    @property
+    def theta(self) -> float:
+        return self._theta
+
+    @theta.setter
+    def theta(self, value: float) -> None:
+        self._theta = value
+
+    @property
+    def kappa(self) -> float:
+        return self._kappa
+
+    @kappa.setter
+    def kappa(self, value: float) -> None:
+        self._kappa = value
+
+    @property
+    def rho(self) -> float:
+        return self._rho
+
+    @rho.setter
+    def rho(self, value: float) -> None:
+        self._rho = value