Metadata-Version: 2.3
Name: neutrinobt
Version: 0.1.0
Summary: High-performance Python backtesting engine powered by Numba JIT, with indicators, optimization, walk-forward validation, and reporting
Keywords: backtesting,algorithmic-trading,quantitative-finance,numba,pine-script,trading-strategy,technical-analysis
Author: KlaBuasom
Author-email: KlaBuasom <kla.buasom@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering
Requires-Dist: numba>=0.63.1
Requires-Dist: numpy>=2.3.5
Requires-Dist: pandas>=3.0.0
Requires-Dist: polars>=1.37.1
Requires-Dist: matplotlib>=3.9.0
Requires-Dist: jinja2>=3.1
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: ccxt>=4.4.96 ; extra == 'all'
Requires-Dist: quantstats>=0.0.62 ; extra == 'all'
Requires-Dist: pyarrow>=16.0.0 ; extra == 'all'
Requires-Dist: quantstats>=0.0.62 ; extra == 'analytics'
Requires-Dist: ccxt>=4.4.96 ; extra == 'data'
Requires-Dist: pyarrow>=16.0.0 ; extra == 'wfo'
Requires-Python: >=3.12
Project-URL: Homepage, https://github.com/KlaBuasom/NeutrinoBT
Project-URL: Repository, https://github.com/KlaBuasom/NeutrinoBT
Project-URL: Issues, https://github.com/KlaBuasom/NeutrinoBT/issues
Project-URL: Documentation, https://github.com/KlaBuasom/NeutrinoBT#readme
Provides-Extra: all
Provides-Extra: analytics
Provides-Extra: data
Provides-Extra: wfo
Description-Content-Type: text/markdown

# NeutrinoBT

[![CI](https://github.com/KlaBuasom/NeutrinoBT/actions/workflows/ci.yml/badge.svg)](https://github.com/KlaBuasom/NeutrinoBT/actions/workflows/ci.yml)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**A high-performance Python backtesting library powered by Numba JIT.**

NeutrinoBT runs your trading strategies fast — the core engine is compiled to machine code via Numba so that even large parameter sweeps complete in seconds. The API is modeled after Pine Script, so moving from TradingView concepts to Python is straightforward.

---

## Features

### Core Engine
- **Numba JIT backtesting** — `@njit(cache=True)` compiled execution loop; orders, stops, and equity curves computed at native speed
- **Two signal modes** — vectorized (NumPy arrays) for simple strategies; Pine Script-style order API (`order()`, `exit()`, `cancel()`) for complex logic
- **Multiple positions** — FIFO, LIFO, or BY_ID close selection; configurable `max_positions`
- **Stops & exits** — per-trade stop loss, take profit, and trailing stops (activation by price or points)
- **Leverage & liquidation** — configurable leverage with automatic liquidation price calculation
- **Entry on bar close** — optional `entry_on_bar_close=True` fills at next bar open (matches Pine Script `strategy.entry` behaviour)
- **Commission & slippage** — applied separately to entries and stops

### Indicators (`self.I` / `nt.*`)
25+ built-in indicators, all Numba-accelerated, organized into five categories:

| Category | Indicators |
|----------|-----------|
| Moving Averages | EMA, SMA, RMA, WMA, DEMA, TEMA, HMA, VWMA |
| Momentum | RSI, MACD, Stoch, StochRSI, CCI, Williams %R, ADX, MFI |
| Volatility | ATR, STDEV, SuperTrend, Bollinger Bands, Keltner Channel, Donchian Channel |
| Trend | Parabolic SAR, Ichimoku Cloud, Linear Regression |
| Volume | OBV, VWAP |

All indicators support a `timeframe=` parameter for multi-timeframe analysis without look-ahead bias.

### Optimization
- **Grid search** — exhaustive sweep over all parameter combinations
- **Random search** — sampled trials with reproducible seeds
- **Parallel workers** — `n_jobs=` via `multiprocessing.Pool` (Windows-safe)
- **Built-in objectives** — `net_profit`, `sharpe`, `profit_factor`, `gt_score`, `negative_max_drawdown`; or pass any callable

### Statistics
Professional-grade metrics in the style of TradingView's Strategy Tester:
Net Profit, Gross Profit/Loss, Profit Factor, Sharpe, Sortino, Calmar, Max Drawdown, PROM, GT-Score, Win Rate, Avg Win/Loss, Avg Bars in Trade, CAGR, T-Test — all broken down by **All / Long / Short**.

### Jupyter / In-Notebook Visualization
- **`plot_equity`** — equity curve chart from mark-to-market or trade-step fallback
- **`plot_drawdown`** — underwater / drawdown chart (% from running peak)
- **`plot_price_with_trades`** — close price overlaid with long/short entry & exit markers
- **`display_statistics_summary`** — styled statistics table rendered inline in Jupyter
- **QuantStats export** — `quantstats_returns()` converts the equity curve to per-bar decimal returns compatible with the [QuantStats](https://github.com/ranaroussi/quantstats) tear-sheet library (optional install)

### Dashboard & Export
- **HTML dashboard** — self-contained interactive report with TradingView price chart, equity curve, drawdown, returns heatmap, MFE/MAE scatter, and paginated trade log
- **Pine Script export** — generate a Pine Script indicator from your strategy's signals
- **CSV export** — statistics table and full trade list

---

## Performance

Benchmark: EMA(12/26) crossover strategy, **8,640 rows** of BTCUSDT 30 m data, measured at 10 / 100 / 1,000 repeated runs (Numba JIT pre-warmed).

| Engine | Avg time / run | × NeutrinoBT | × backtrader |
|--------|---------------|-------------|-------------|
| Hardcoded (raw NumPy) | ~1 ms | 22× faster | 1,090× faster |
| **NeutrinoBT** | **~22 ms** | — | **~50× faster** |
| backtesting.py | ~77 ms | 3.5× slower | 14× faster |
| backtrader | ~1,090 ms | 50× slower | — |

NeutrinoBT is only ~22× behind a raw NumPy loop (the theoretical floor) while delivering a production-grade framework: stops, leverage, multi-position, full statistics, and HTML export. At 1,000-parameter-sweep scale, backtrader takes **~18 min** total vs **~22 s** for NeutrinoBT.

> Source: [`backtesting-showcase.ipynb`](backtesting-showcase.ipynb) in the repo root. Results vary by CPU; the first per-session run includes Numba JIT compilation (~1–2 s one-time cost).

---

## Installation

```bash
# Using uv (recommended)
uv pip install neutrinobt

# Or with pip
pip install neutrinobt
```

**Requirements:** Python 3.12+, NumPy, Numba, Pandas, Polars, Jinja2, Matplotlib

**Optional extras:**

```bash
# Development tools from a source checkout (JupyterLab, pytest, ruff)
uv sync --group dev

# Binance / CCXT data downloader helpers
pip install "neutrinobt[data]"

# QuantStats tear sheets (pulls scipy, seaborn, yfinance)
pip install "neutrinobt[analytics]"

# Parquet-backed WFO trade stores
pip install "neutrinobt[wfo]"

# Everything optional
pip install "neutrinobt[all]"
```

---

## Quick Start

```python
import numpy as np
from neutrinobt.data.loader import CSVLoader
from neutrinobt.strategy.base import Strategy
from neutrinobt.core.reactor import Reactor
import neutrinobt.indicators as nt

# 1. Load OHLCV data
loader = CSVLoader("sampledata/BTCUSDTUSDT/1h.csv")
bars = loader.load({
    "time": "timestamp", "open": "open", "high": "high",
    "low": "low", "close": "close", "volume": "volume",
})

# 2. Define a strategy
class EMACrossover(Strategy):
    def init(self):
        self.ema_fast = self.I.EMA(20)
        self.ema_slow = self.I.EMA(50)

    def generate_signals(self):
        valid = ~(np.isnan(self.ema_fast) | np.isnan(self.ema_slow))
        self.buy_cond(nt.crossover(self.ema_fast, self.ema_slow) & valid)
        self.sell_cond(nt.crossunder(self.ema_fast, self.ema_slow) & valid)

    def create_reactor(self):
        return Reactor(bars, initial_balance=10_000.0, commission_rate=0.001)

# 3. Run
results = EMACrossover(bars).run(show_summary=True)
print(f"Final equity: ${results['final_equity']:,.2f}")
```

### Jupyter Plotting

```python
# Pass export_timeseries=True to record bar-by-bar equity
results = EMACrossover(bars).run(export_timeseries=True, show_summary=False)

from neutrinobt.notebook.plots import plot_equity, plot_drawdown, display_statistics_summary
from neutrinobt.notebook.quantstats_export import quantstats_returns

plot_equity(bars, equity_curve=results["equity_curve"])
plot_drawdown(bars, equity_curve=results["equity_curve"])
display_statistics_summary(results["statistics"])

# Export per-bar decimal returns ready for QuantStats
qs = quantstats_returns(bars=bars, equity_curve=results["equity_curve"])
# import quantstats; quantstats.reports.basic(qs.strategy, benchmark=qs.benchmark)
```

See [`examples/notebooks/09_jupyter_plotting.ipynb`](examples/notebooks/09_jupyter_plotting.ipynb) for a full walkthrough.

---

## Tutorials

The `examples/` folder is a step-by-step curriculum. Scripts `01`–`08` cover the core engine; the `notebooks/` subfolder has interactive Jupyter examples.

**Scripts** — run from the project root:

| File | Topic | What you learn |
|------|-------|----------------|
| `01_getting_started.py` | First backtest | Load data, validate, define a strategy, read results |
| `02_strategy_basics.py` | Strategy class | `init()`, `generate_signals()`, `create_reactor()`, statistics keys |
| `03_indicators.py` | All 25+ indicators | Every indicator category, standalone use, multi-timeframe |
| `04_risk_management.py` | Risk controls | Fixed/ATR stop loss & take profit, trailing stops, leverage, sizing |
| `05_advanced_orders.py` | Order-based API | `order()`, `exit()`, `cancel()`, limit/stop entries, multiple positions |
| `06_optimization.py` | Parameter search | `Optimizer.run()`, grid vs random, built-in objectives, parallel |
| `07_dashboard_report.py` | HTML report | `export_html=True`, `generate_report()`, all dashboard sections |
| `08_real_world_strategy.py` | Full strategy | Date range, warmup, production backtest, trade analysis |

```bash
python examples/01_getting_started.py
```

**Notebooks** — open in JupyterLab (`uv sync --group dev && uv run jupyter lab`):

| Notebook | Topic | What you learn |
|----------|-------|----------------|
| `notebooks/09_jupyter_plotting.ipynb` | In-notebook visualization | Equity curve, drawdown, trade markers, statistics table, QuantStats export |

---

## Architecture

```
neutrinobt/
├── core/
│   ├── reactor_core.py   # Numba @njit compiled engine (the hot loop)
│   ├── reactor.py        # Python wrapper — validation, results, statistics
│   └── statistics.py     # ~30 performance metrics
├── strategy/
│   └── base.py           # Strategy base class + IndicatorFactory (self.I)
├── indicators/           # 25+ @njit indicators
├── notebook/             # Jupyter helpers (no mandatory new deps)
│   ├── plots.py          # plot_equity, plot_drawdown, plot_price_with_trades, display_statistics_summary
│   └── quantstats_export.py  # quantstats_returns, export_quantstats_returns_csv
├── optimization/         # Optimizer — grid/random search
├── dashboard/            # HTML report generator (Jinja2 + ECharts)
├── export/               # Pine Script exporter
└── data/                 # CSVLoader, Resampler, validation
```

**Execution flow:**
1. `Strategy.init()` — indicators computed, warmup tracked
2. `Strategy.generate_signals()` — boolean arrays or Pine-style orders
3. `Reactor.run()` — Numba JIT loop processes every bar: pending fills, trailing updates, liquidations, SL/TP, exits, entries
4. Results — `TradeList`, `Statistics`, optional HTML report

---

## Sample Data

CSV bars live under ``sampledata/<BASE>USDTUSDT/<timeframe>.csv``. That directory is **gitignored**
— fetch Binance USDT‑M perpetual OHLCV with CCXT:

```bash
uv sync --group data

# Default list: BTC, XRP, ETH, HYPE, BNB, DOGE — timeframes 30m, 1h, 2h
uv run --group data python scripts/fetch_binance_usdt_perp_ohlcv.py --output-dir sampledata

# Tests and ``research_pipeline/configs/datasets.json`` also expect daily BTC / XRP files:
uv run --group data python scripts/fetch_binance_usdt_perp_ohlcv.py --output-dir sampledata \
  --bases BTC XRP --timeframes 1d
```

See the script docstring for the exact default symbol/timeframe lists.

---

## License

MIT — see [LICENSE](LICENSE) for details.
