FinStoch 0.0.0__tar.gz

finstoch-0.0.0/.github/workflows/cd.yml

@@ -0,0 +1,40 @@
+name: CD
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for setuptools-scm to read git tags
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

finstoch-0.0.0/.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - name: Check formatting
+        run: ruff format --check .
+      - name: Lint (critical errors)
+        run: flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+      - name: Lint (warnings)
+        run: flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+      - name: Type check
+        run: mypy . --exclude venv --exclude build --exclude dist --ignore-missing-imports
+
+  test:
+    needs: lint
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - name: Run tests
+        run: python -m unittest discover -s tests -p "*_test.py" -v

finstoch-0.0.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+**/__pycache__/
+*.pyc
+*.pyo
+
+# Build & distribution
+dist/
+build/
+*.egg-info/
+
+# Virtual environments
+venv/
+.venv/
+
+# IDE
+.vscode/
+
+# Testing & linting caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Generated version file
+FinStoch/_version.py
+
+# Claude Code (local only)
+.claude/
+
+# Project-specific
+dependencies.txt
+dependencies.json
+*.ipynb
+notes.txt
+CLAUDE.md

finstoch-0.0.0/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-0.0.0/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-0.0.0/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-0.0.0/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-0.0.0/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-0.0.0/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)