Metadata-Version: 2.4
Name: pystochastic
Version: 0.2.0
Summary: A Python library for probability, stochastic calculus and modelling, stochastic differential equations, and Monte Carlo simulation
Author: Bastien Velcin
License: MIT License
        
        Copyright (c) 2026 Bastien Velcin
        
        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.
        
        
Project-URL: Homepage, https://github.com/BastienVelcin/PyStochastic
Project-URL: Repository, https://github.com/BastienVelcin/PyStochastic
Project-URL: Issues, https://github.com/BastienVelcin/PyStochastic/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: plotly
Requires-Dist: sympy
Dynamic: license-file

# PyStochastic

PyStochastic is a Python library for probability, stochastic calculus and stochastic modelling, Monte Carlo methods and numerical methods for
stochastic differential equations.

The project aims to provide a simple and consistent interface for
simulating, analysing and visualising stochastic models.

---

## ✨ Features

PyStochastic currently provides tools for:

- Probability distributions
  - Continuous distributions
  - Discrete distributions
- Random number generation
- Stochastic processes
- Numerical SDE solvers
  - Euler-Maruyama
  - Milstein
- Monte Carlo analysis
  - Estimation
  - Moments
  - Variance and standard error
  - Confidence intervals
  - Quantiles
  - Histograms
  - Empirical cumulative distribution functions
  - Confidence curves
- Vectorised simulations
- Plotting and visualisation

---

## 📦 Installation

Clone the repository:

```bash
git clone https://github.com/BastienVelcin/PyStochastic.git
cd PyStochastic
```

Then install the package:

```bash
pip install .
```

---

## 🚀 Quick start

### Probability distributions

PyStochastic provides a common interface for probability distributions.

For example:

```python
from pystochastic.dist import Normal

distribution = Normal(mu=0, sigma=1)

samples = distribution.sample(10000)

mean = distribution.mean()
variance = distribution.variance()
```

Probability distributions also provide functions such as `pdf` and
`cdf` when appropriate.

---

### Discrete distributions

Discrete probability distributions use the `DiscreteDistribution`
interface and provide a `pmf` method.

For example:

```python
from pystochastic.dist import Bernoulli

distribution = Bernoulli(p=0.3)

samples = distribution.sample(10000)

probability = distribution.pmf(1)
```

---

## 🎲 Random number generation

PyStochastic provides random number generators for both continuous
and discrete distributions through the `pyrandom` module.

```python
from pystochastic.pyrandom import crandom

samples = crandom.normal(
    mu=0,
    sigma=1,
    size=10000,
)
```

A global seed can also be configured for reproducible simulations.

```python
from pystochastic.pyrandom.setseed import seed

seed(42)
```

---

# 📈 Stochastic processes

PyStochastic provides several classical stochastic processes, including:

- Brownian motion
- Poisson process
- Geometric Brownian motion
- Ornstein-Uhlenbeck process
- Vasicek model
- Cox-Ingersoll-Ross model

For example:

```python
from pystochastic.processes import Brownian

process = Brownian(
    t_0=0,
    t_n=1,
    n_steps=1000,
    n_simulations=10,
)

process.simulate()
```

The simulated paths can then be analysed and visualised.

---

# 🧮 Stochastic differential equations

PyStochastic provides numerical solvers for stochastic differential
equations.

Currently implemented methods include:

- Euler-Maruyama
- Milstein

These solvers support vectorised simulations and can be applied to
multidimensional stochastic systems.

For example:

```python
from pystochastic.sde import EulerMaruyama

solver = EulerMaruyama(
    drift=drift,
    diffusion=diffusion,
    x_0=x_0,
    t_0=0,
    t_n=1,
    n_steps=1000,
)

solution = solver.solve()
```

---

# 🎯 Monte Carlo

The `MonteCarlo` class provides statistical tools for analysing
collections of simulated samples.

For example:

```python
from pystochastic.montecarlo import MonteCarlo

mc = MonteCarlo(samples)

estimate = mc.estimate()
variance = mc.variance()
standard_error = mc.standard_error()
```

Confidence intervals can also be computed:

```python
lower, upper = mc.confidence_interval(
    confidence=0.95,
    type="student",
)
```

PyStochastic also provides tools for statistical visualisation,
including histograms, empirical CDFs and confidence curves.

```python
mc.histogram()

mc.ecdf()

mc.confidence_curve()
```

---

# 📊 Vectorisation

A major focus of PyStochastic is efficient simulation.

Whenever possible, simulations are vectorised using NumPy rather than
performing independent Python-level loops.

This is particularly useful when a large number of Monte Carlo
simulations is required.

---

# 🧪 Testing

PyStochastic uses `pytest` for its test suite.

Run all tests with:

```bash
pytest
```

The project currently contains tests covering:

- Probability distributions
- Discrete distributions
- Random number generators
- Stochastic processes
- SDE solvers
- Monte Carlo methods
- Public APIs

The test suite also includes mathematical consistency and statistical
tests.

---

# ⚡ Benchmarks

Performance benchmarks are included to compare different simulation
approaches and evaluate the benefit of vectorisation.

For example, vectorised simulations can provide substantial speedups
compared with sequential matrix-based implementations for large
numbers of simulations.

---

# 📚 Project structure

```text
pystochastic/
├── dist/
│   ├── dist.py
│   └── ...
│
├── montecarlo/
│   ├── montecarlo.py
│   └── ...
│
├── processes/
│   ├── brownian.py
│   ├── poisson.py
│   ├── GeometricBrownianMotion.py
│   ├── OrnsteinUhlenbeck.py
│   ├── vasicek.py
│   └── CIR.py
│
├── pyrandom/
│   ├── crandom.py
│   ├── drandom.py
│   └── setseed.py
│
└── sde/
    ├── eulermaruyama.py
    └── milstein.py
```

---

# 🛠️ Development

Clone the repository and install the project in editable mode:

```bash
git clone https://github.com/BastienVelcin/PyStochastic.git
cd PyStochastic

pip install -e .
```

Install the development dependencies and run the tests:

```bash
pytest
```

---

# 🗺️ Roadmap

Possible future developments include:

- Additional probability distributions
- Additional stochastic processes
- Additional SDE numerical schemes
- Improved documentation
- Additional performance optimisations
- More statistical analysis tools
- Expanded benchmarking
- Improved visualisation capabilities

---

# 🤝 Contributing

Contributions, suggestions and bug reports are welcome.

If you find a bug or have an idea for a new feature, please open an
issue on GitHub.

Pull requests are also welcome.

---

# 📄 License

PyStochastic is released under the MIT License.

See the `LICENSE` file for more information.
