Black‑Scholes Options P&L Simulator

Interactive, from‑scratch implementation of the Black‑Scholes model with full Greeks, P&L scenarios and a live Plotly dashboard. No external pricing libraries (QuantLib, etc.) are used – all formulas are coded manually for pedagogical clarity.

---

🚀 Overview

The repository demonstrates the complete workflow of a quantitative research project:

• Core engine – analytical Black‑Scholes pricing and Greeks (black_scholes.py).
• Verification suite – finite‑difference sanity checks and put‑call parity (verify.py).
• Interactive dashboard – sliders for spot, strike, volatility, time‑to‑expiry and risk‑free rate; live price cards, payoff chart and greek‑vs‑spot plot (greeks_dashboard.py).
• P&L scenario generator – tables for long calls/puts and covered‑call strategies (pnl_scenarios.py).
• Research‑grade visualisations – heat‑maps of Greeks over a σ‑T grid and a polished PDF report (visualizations/).

The project is organized as a pure‑Python package (options_simulator/) that can be imported or run directly from a Jupyter notebook.

---

📚 Technical Highlights

Feature	Description
Analytical formulas	All BS equations (d1, d2, Call, Put, Δ, Γ, Θ, Vega, ρ) are implemented from first principles using numpy and scipy.stats.norm.
Finite‑difference verification	Numerical approximations for each Greek are computed and compared; relative errors are plotted (see ).
Put‑Call parity check	Automated assertion that C - P = S - K·e^{-rT} holds for every test case.
Interactive UI	Built with ipywidgets and Plotly – five sliders, option‑type toggle, greek selector, live cards, payoff diagram, and greek‑vs‑spot curve.
Heat‑maps	2‑D visualisations of each Greek across volatility (σ) and time‑to‑expiry (T) – great for a research paper (see ).
PDF research report	Automatically generated from markdown + images using ReportLab (visualizations/BlackScholes_Research_Report.pdf).
No external pricers	Pure‑Python, ideal for learning, teaching, and reproducible research.

---

📦 Project Structure

options_simulator/
├─ __init__.py
├─ black_scholes.py          # Core pricing & Greeks class
├─ greeks_dashboard.py      # Interactive Jupyter dashboard
├─ pnl_scenarios.py         # P&L tables for different strategies
├─ verify.py                # Numerical verification + visual output
├─ visualizations/          # Generated PNGs & PDF report
│   ├─ delta_error.png
│   ├─ gamma_error.png
│   ├─ vega_error.png
│   ├─ theta_error.png
│   ├─ rho_error.png
│   ├─ put_call_parity.png
│   ├─ heatmap_delta.png
│   ├─ heatmap_gamma.png
│   ├─ heatmap_vega.png
│   ├─ heatmap_theta.png
│   ├─ heatmap_rho.png
│   └─ BlackScholes_Research_Report.pdf
└─ notebooks/
    └─ demo.ipynb          # Step‑by‑step walkthrough

---

🛠️ Installation

# Clone the repo
git clone https://github.com/your‑username/black‑scholes‑simulator.git
cd black‑scholes‑simulator

# (Optional) create a virtual environment
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

# Install required packages
pip install -r requirements.txt   # (or the list below)

requirements.txt contains:

numpy
scipy
pandas
plotly
ipywidgets
matplotlib
reportlab
kaleido   # for static Plotly PNG export (optional)

Enable the widget extension for Jupyter:

jupyter nbextension enable --py widgetsnbextension --sys-prefix
# For JupyterLab users also run:
# jupyter labextension install @jupyter-widgets/jupyterlab-manager

---

▶️ Quick Start – Running the Dashboard

1. Launch Jupyter

   jupyter notebook   # or jupyter lab

2. Create a new notebook and run the following two cells:

   %run options_simulator/greeks_dashboard.py
   create_dashboard()

   The full interactive dashboard appears inline. Adjust the sliders to see how price, Greeks and payoff change in real time.

   The dashboard also works when the module is imported in a script:

   from options_simulator.greeks_dashboard import create_dashboard
   create_dashboard()   # will open a browser window if run outside Jupyter

---

📊 Verification & Research Visualisations

Running the verification script produces error plots and a parity check:

python -m options_simulator.verify

The PNGs are saved to options_simulator/visualizations/ and automatically incorporated into the PDF report.

To generate the heat‑maps of Greeks over σ‑T space:

python - <<'PY'
import sys, os
sys.path.append('C:/Users/HP/Desktop/agent/quant_1')
from options_simulator.visualizations.extended_visuals import generate_heatmaps
generate_heatmaps()
PY

All heat‑maps will appear in the same folder, ready for inclusion in presentations or papers.

---

📖 Demo Notebook

The notebooks/demo.ipynb notebook walks through:

• Theory behind Black‑Scholes and Greeks.
• Step‑by‑step implementation details.
• Running the verification suite.
• Using the interactive dashboard.
• Exploring P&L scenarios.
• Generating the research PDF.

---

🤝 Contributing

Contributions are welcome! Feel free to open issues or submit pull requests for:

• Additional Greeks or exotic options.
• More sophisticated visualisations (surface plots, interactive 3‑D).
• Tests and CI pipelines.
• Documentation improvements.

Please follow the standard GitHub workflow:

1. Fork the repository.
2. Create a feature branch (git checkout -b my‑feature).
3. Commit your changes and push (git push origin my‑feature).
4. Open a Pull Request.

---

📄 License

This project is licensed under the MIT License – see the LICENSE file for details.

---

🙋‍♀️ Acknowledgements

• The implementation follows the classical Black‑Scholes derivation as presented in Hull’s Options, Futures & Other Derivatives.
• Thanks to the scipy and plotly communities for the powerful scientific and visualisation tools.
• Built and tested with Claude Code – the AI‑powered developer assistant.