PyIto Documentation

PyIto

High-performance SDE solver with JIT compilation and parallel execution.

PyIto is a Python library for simulating Stochastic Differential Equations (SDEs). Built on the Numba compiler, it translates Python model definitions into optimized machine code (LLVM) and automatically parallelizes Monte Carlo simulations across all available CPU cores.

It is designed for quantitative finance and research applications where execution speed and memory efficiency are critical.

✨ Key Features

🚀 JIT Compilation: Compiles drift and diffusion functions to machine code for C-like performance.
🔥 Auto-Parallelism: Automatically distributes paths across CPU cores using numba.prange.
📉 Zero-RAM Noise Generation: Generates Brownian motion on-the-fly, allowing for millions of paths without memory overhead.
🧠 Derivative-Free Milstein: Achieves Strong Order 1.0 accuracy without requiring manual calculation of diffusion derivatives.
📊 Flexible Memory Management: Choose to store full path histories or only terminal states to optimize RAM usage.

🛠️ Installation

pip install pyito

Requirements: numpy, numba*

⚡ Quick Start

Here is a minimal example simulating a mean-reverting Ornstein-Uhlenbeck process: $$ dX_t = \theta(\mu - X_t)dt + \sigma dW_t $$

import numpy as np
from numba import njit
from pyito import SDE, integrate

# 1. Define Physics (Must be JIT-compatible)
@njit
def drift(t, x, args):
    theta, mu, sigma = args
    return theta * (mu - x)

@njit
def diffusion(t, x, args):
    theta, mu, sigma = args
    return sigma  # Constant volatility

# 2. Setup Model
# Params: theta=0.7, mu=1.5, sigma=0.3
sde = SDE(drift, diffusion, args=(0.7, 1.5, 0.3))

# 3. Run Simulation
# Simulates 100,000 paths in parallel
# Returns only the final state (at t=1.0) to save memory
results = integrate(sde, y0=0.0, tspan=(0, 1.0), dt=0.01, n_paths=100_000)

print(f"Mean: {np.mean(results):.4f}")
print(f"Std:  {np.std(results):.4f}")

🧮 Supported Algorithms

PyIto supports the following solvers via the method argument:

Method	Strong Order	Description
`euler_maruyama`	0.5	The standard, efficient default solver.
`milstein`	1.0	Higher accuracy for multiplicative noise. Requires providing `diffusion_deriv`.
`df_milstein`	1.0	Derivative-Free Milstein. Approximates derivatives numerically. Recommended for high accuracy without the math overhead.

📚 Advanced Usage

1. Derivative-Free Milstein

To get higher accuracy without calculating manually, use the derivative-free solver. It uses a finite-difference approximation inside the kernel.

results = integrate(sde, ..., method='df_milstein')

2. Correlated Noise (Multi-Dimensional)

PyIto natively handles correlated noise for systems like the Heston model. If your diffusion function returns a matrix, the solver infers a correlated structure.

Scalar Output: Single-factor noise.
Vector Output: Independent diagonal noise.
Matrix Output: Correlated noise (Diffusion Matrix such that ).

3. Memory Optimization

For large-scale Monte Carlo (e.g., 10 million paths), storing the full history is impossible. PyIto allows you to control output verbosity:

# Returns array of shape (Steps, Paths, Dims) - RAM Heavy
history = integrate(..., output='all')

# Returns array of shape (Paths, Dims) - RAM Efficient
terminal_values = integrate(..., output='final')

⚠️ Performance Note

PyIto is optimized to saturate your CPU.

Laptop Users: Ensure your OS power plan is set to “Best Performance”. In “Power Saver” mode, operating systems often park high-performance cores, significantly throttling the parallel speedup.
Warm-up: The first call to integrate will take an extra 1-2 seconds while Numba compiles your functions. Subsequent runs will be instant.

📚 References & Mathematical Foundation

PyIto implements algorithms established in the following primary sources:

Kloeden, P. E., & Platen, E. (1992). Numerical Solution of Stochastic Differential Equations. Springer-Verlag.
Glasserman, P. (2003). Monte Carlo Methods in Financial Engineering. Springer.
Higham, D. J. (2001). “An Algorithmic Introduction to Numerical Simulation of Stochastic Differential Equations.” SIAM Review.
Maruyama, G. (1955). “Continuous Markov processes and stochastic equations.”
Milstein, G. N. (1974). “Approximate integration of stochastic differential equations.”

🤝 Contributing

Contributions are welcome!

Fork the repository.
Create your feature branch.
Install dev dependencies: pip install -e .[dev]
Run tests: pytest tests/

📄 License

Distributed under the MIT License. See LICENSE for more information.

API Reference

Core Modules