[
{
"path": ".github/workflows/ci.yml",
"content": "name: Test\n\non: [push, pull_request]\n\njobs:\n test:\n runs-on: ubuntu-latest\n\n steps:\n - uses: actions/checkout@v4\n - uses: cachix/install-nix-action@v30\n - name: Download data\n run: nix develop --command python data/fetch_data.py all --symbols SPY --force\n - name: Run tests\n run: nix develop --command python -m pytest -v tests/ --ignore=tests/bench --ignore=tests/compat\n - name: Type check\n run: nix develop --command python -m mypy options_portfolio_backtester --ignore-missing-imports\n"
},
{
"path": ".gitignore",
"content": "# Byte-compiled / optimized / DLL files\n__pycache__/\n*.py[cod]\n*$py.class\n\n# C extensions\n*.so\n\n# Distribution / packaging\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\n\n# PyInstaller\n# Usually these files are written by a python script from a template\n# before PyInstaller builds the exe, so as to inject date/other infos into it.\n*.manifest\n*.spec\n\n# Installer logs\npip-log.txt\npip-delete-this-directory.txt\n\n# Unit test / coverage reports\nhtmlcov/\n.tox/\n.coverage\n.coverage.*\n.cache\nnosetests.xml\ncoverage.xml\n*.cover\n.hypothesis/\n.pytest_cache/\n\n# Translations\n*.mo\n*.pot\n\n# Django stuff:\n*.log\nlocal_settings.py\ndb.sqlite3\n\n# Flask stuff:\ninstance/\n.webassets-cache\n\n# Scrapy stuff:\n.scrapy\n\n# Sphinx documentation\ndocs/_build/\n\n# PyBuilder\ntarget/\n\n# Jupyter Notebook\n.ipynb_checkpoints\n\n# celery beat schedule file\ncelerybeat-schedule\n\n# SageMath parsed files\n*.sage.py\n\n# Environments\n.env\n.venv\n.venv-bt/\nenv/\nvenv/\nENV/\nenv.bak/\nvenv.bak/\n\n# Spyder project settings\n.spyderproject\n.spyproject\n\n# Rope project settings\n.ropeproject\n\n# mkdocs documentation\n/site\n\n# mypy\n.mypy_cache/\n\n# Generated charts/plots\n*.png\n\n# Mac OS-specific storage files\n.DS_Store\n\n# VS Code\n.vscode/\n_ob_rust.so\nmutants/\n\n# Large regenerable test data (from tests/bench/extract_prod_slices.py)\ntests/data/*.csv\n\n# exclude data from source control by default\ndata/*\n!data/README.md\n!data/fetch_data.py\n!data/fetch_signals.py\n!data/convert_optionsdx.py\n!data/raw/\ndata/raw/*\n!data/raw/.gitkeep\n!data/processed/\ndata/processed/*\n!data/processed/.gitkeep\n!data/processed/signals.csv\n"
},
{
"path": ".python-version",
"content": "3.12\n\n"
},
{
"path": "CONTRIBUTING.md",
"content": "Contributing\n============\n\nContributions are welcome and very much appreciated. Credit will be appropriately given.\n\n## License\n\nBy contributing, you agree that your contributions will be licensed under its MIT License.\n\n## Code contributions\n\nTo begin contributing to the project, please follow these steps.\n\n1. [Fork](https://help.github.com/en/articles/fork-a-repo) the repo.\n2. Clone your fork locally:\n\n```shell\n$ git clone git@github.com:your_username/backtester_options.git\n```\n\n3. Create the environment and install dependencies:\n\n```shell\n$ make init\n```\n\n4. Create your development branch from `master`\n\n```shell\n$ git checkout -b your_branch master\n```\n\n5. Start coding your contribution (Thanks!)\n\n6. Make sure your code passes all tests, lints and is formatted correctly (`TODO`: Add linting, code formatting to Travis.)\n\n6. Submit a pull request with a brief explanation of your work.\n\n## Types of Contributions\n\n### Bug reports\n\nMake sure to follow the setup steps detailed in the [readme](README.md). If you find a bug, please create an issue with the label `bug` and provide the following information:\n\n- Operating System and version.\n- Steps taken to replicate the bug.\n- What was the expected output and what actually happend.\n- Any details of your local environment that might be helpful for troubleshooting.\n\n### Bug fixes\n\nIf you find a bug issue you want to fix, follow the steps outlined [above](#code-contributions) and submit a pull request with a link to the original issue.\n\n### Proposing Features\n\nCreate an issue detailing what functionality you'd like to see implemented. If you can, provide general advice as to how the proposed feature could be done.\n\n### Implementing Features\n\nFind an issue with the label `help wanted` or `improvement` and [start coding](#code-contributions). \nWhen you are done, submit a pull request with a link to the original issue and some code samples showing how the code works. Tests are expected when adding new functionality.\n\n\n### Documentation\n\nWe encourage users to improve our project documentation, either via docstrings, markdown documents to be added to the [project wiki](https://github.com/lambdaclass/backtester_options/wiki) or writing blog posts. \nLet us know via issues labeled `docs` and we'll credit you appropriately.\n"
},
{
"path": "LICENSE",
"content": "MIT License\n\nCopyright (c) 2019 Federico Carrone\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "Makefile",
"content": "NIX_CMD := XDG_CACHE_HOME=$(CURDIR)/.cache nix --extra-experimental-features 'nix-command flakes' develop --command\nRUNCMD := $(NIX_CMD)\nPYTHON := python\n\n.PHONY: test test-bench lint typecheck notebooks rust-build rust-test rust-bench bench install-dev compare-bt benchmark-matrix walk-forward-report parity-gate bench-rust-vs-python help\n.DEFAULT_GOAL := help\n\ntest: ## Run all tests\n\t$(RUNCMD) $(PYTHON) -m pytest -v tests\n\ntest-bench: ## Run benchmark/property tests\n\t$(RUNCMD) $(PYTHON) -m pytest -v -m bench tests/bench\n\nlint: ## Run ruff linter\n\t$(RUNCMD) $(PYTHON) -m ruff check options_portfolio_backtester\n\ntypecheck: ## Run mypy type checker\n\t$(RUNCMD) $(PYTHON) -m mypy options_portfolio_backtester --ignore-missing-imports\n\nnotebooks: ## Execute all notebooks\n\t@for nb in notebooks/*.ipynb; do \\\n\t\techo \"Running $$nb...\"; \\\n\t\t$(RUNCMD) $(PYTHON) -m jupyter nbconvert --to notebook --execute \"$$nb\" \\\n\t\t\t--output \"$$(basename $$nb)\" --ExecutePreprocessor.timeout=600 || true; \\\n\tdone\n\nrust-build: ## Build Rust extension with maturin (release)\n\t$(RUNCMD) bash -c 'cd rust && maturin develop --manifest-path ob_python/Cargo.toml --release'\n\nrust-test: ## Run Rust unit tests\n\t$(RUNCMD) bash -c 'cd rust && cargo test'\n\nrust-bench: ## Run Rust benchmarks (criterion)\n\t$(RUNCMD) bash -c 'cd rust && cargo bench'\n\nbench: rust-build ## Run Python benchmarks (requires Rust build)\n\t$(RUNCMD) $(PYTHON) -m pytest tests/bench/ -v -m bench --benchmark-only 2>/dev/null || \\\n\t\techo \"Install pytest-benchmark for Python benchmarks\"\n\ninstall-dev: ## Install local dev deps into active nix dev environment\n\t$(PYTHON) -m pip install -e '.[dev,charts,notebooks,rust]'\n\ncompare-bt: ## Compare stock-only monthly rebalance vs bt library\n\t$(RUNCMD) $(PYTHON) scripts/compare_with_bt.py\n\nbenchmark-matrix: ## Run standardized runtime/accuracy matrix vs bt\n\t$(RUNCMD) $(PYTHON) scripts/benchmark_matrix.py\n\nwalk-forward-report: ## Run walk-forward/OOS harness and save report\n\t$(RUNCMD) $(PYTHON) scripts/walk_forward_report.py\n\nbench-rust-vs-python: ## Benchmark Rust vs Python vs bt (options + stock-only)\n\t$(RUNCMD) $(PYTHON) scripts/benchmark_rust_vs_python.py --stock-only\n\nparity-gate: ## Run bt overlap parity CI gate (bench marker)\n\t$(RUNCMD) $(PYTHON) -m pytest -v tests/compat/test_bt_overlap_gate.py -m bench\n\nhelp:\n\t@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) |\\\n\tawk 'BEGIN {FS = \":.*?## \"}; {printf \"\\033[36m%-30s\\033[0m %s\\n\", $$1, $$2}'\n"
},
{
"path": "README.md",
"content": "Options Portfolio Backtester\n============================\n\nBacktest options strategies with realistic execution, Greeks-aware risk management, and contract-level inventory. Also handles equities and multi-asset portfolios. Optional Rust core for speed.\n\n## Get started\n\n### Install\n\nWith Nix:\n```shell\nnix develop\n```\n\nWithout Nix (Python >= 3.12):\n```shell\npython -m venv .venv && source .venv/bin/activate\nmake install-dev\n```\n\n### Get data\n\n```shell\npython data/fetch_data.py all --symbols SPY\n```\n\nDownloads SPY stock prices and options chains to `data/processed/`. Supports 104+ symbols. See [`data/README.md`](data/README.md) for details.\n\n### Run your first backtest\n\n```python\nfrom options_portfolio_backtester import (\n BacktestEngine, Stock, Type, Direction,\n HistoricalOptionsData, TiingoData,\n Strategy, StrategyLeg,\n NearestDelta, PerContractCommission,\n RiskManager, MaxDelta, MaxDrawdown,\n)\n\n# Load data\noptions_data = HistoricalOptionsData(\"data/processed/options.csv\")\nstocks_data = TiingoData(\"data/processed/stocks.csv\")\nschema = options_data.schema\n\n# Define strategy: buy OTM puts on SPY, exit when DTE drops below 30\nstrategy = Strategy(schema)\nleg = StrategyLeg(\"leg_1\", schema, option_type=Type.PUT, direction=Direction.BUY)\nleg.entry_filter = (\n (schema.underlying == \"SPY\")\n & (schema.dte >= 60) & (schema.dte <= 120)\n & (schema.delta >= -0.25) & (schema.delta <= -0.10)\n)\nleg.exit_filter = schema.dte <= 30\nstrategy.add_leg(leg)\n\n# Run backtest: 97% stocks, 3% options\nengine = BacktestEngine(\n allocation={\"stocks\": 0.97, \"options\": 0.03, \"cash\": 0.0},\n initial_capital=1_000_000,\n cost_model=PerContractCommission(rate=0.65),\n signal_selector=NearestDelta(target_delta=-0.20),\n risk_manager=RiskManager([MaxDelta(100.0), MaxDrawdown(0.20)]),\n)\nengine.stocks = [Stock(\"SPY\", 1.0)]\nengine.stocks_data = stocks_data\nengine.options_data = options_data\nengine.options_strategy = strategy\nengine.run(rebalance_freq=1)\n\n# Results\nprint(engine.balance[\"total capital\"].iloc[-1]) # final capital\nprint(len(engine.trade_log)) # number of trades\n```\n\n### Strategy presets\n\nInstead of building legs manually:\n\n```python\nfrom options_portfolio_backtester import Strangle\n\nstrangle = Strangle(schema, \"short\", \"SPY\",\n dte_entry_range=(30, 60), dte_exit=7,\n otm_pct=5, pct_tolerance=1,\n exit_thresholds=(0.2, 0.2))\n```\n\nAvailable presets: `Strangle`, `IronCondor`, `CoveredCall`, `CashSecuredPut`, `Collar`, `Butterfly`.\n\n### Stock-only backtest with algo pipeline\n\nFor equity portfolios without options, use the pipeline API:\n\n```python\nfrom options_portfolio_backtester.engine.pipeline import (\n AlgoPipelineBacktester,\n RunMonthly, SelectAll, WeighInvVol, LimitWeights, Rebalance,\n)\nimport pandas as pd\n\nprices = pd.read_csv(\"data/processed/stocks.csv\", parse_dates=[\"date\"])\nprices = prices.pivot(index=\"date\", columns=\"symbol\", values=\"adjClose\")\n\nbt = AlgoPipelineBacktester(\n prices=prices,\n initial_capital=1_000_000,\n algos=[\n RunMonthly(),\n SelectAll(),\n WeighInvVol(lookback=252),\n LimitWeights(limit=0.25),\n Rebalance(),\n ],\n)\nbt.run()\n```\n\n## Execution models\n\nEvery component is swappable. Pass them to `BacktestEngine(...)` or override per-leg.\n\n**Signal selectors** — which contract to pick from candidates:\n`FirstMatch()`, `NearestDelta(target)`, `MaxOpenInterest()`\n\n**Cost models** — commissions and fees:\n`NoCosts()`, `PerContractCommission(rate)`, `TieredCommission(tiers)`, `SpreadSlippage(pct)`\n\n**Fill models** — execution price:\n`MarketAtBidAsk()`, `MidPrice()`, `VolumeAwareFill(threshold)`\n\n**Position sizers** — how many contracts:\n`CapitalBased()`, `FixedQuantity(qty)`, `FixedDollar(amount)`, `PercentOfPortfolio(pct)`\n\n**Risk constraints** — pre-trade gating:\n`MaxDelta(limit)`, `MaxVega(limit)`, `MaxDrawdown(max_dd_pct)`\n\n## Rebalancing model\n\nAt each rebalance date, the engine follows a **full liquidation** approach:\n\n1. **Liquidate all options** — every open option position is sold at current market price (bid for long, ask for short)\n2. **Compute total capital** — cash + stock value (options are zero after liquidation)\n3. **Rebalance stocks** — sell all stocks, buy fresh at target allocation (e.g. 97%)\n4. **Buy new options** — use the full options allocation (e.g. 3%) to purchase contracts matching entry criteria (DTE, delta, etc.)\n\nThis ensures:\n- **Clean accounting** — no stale option value carried across rebalances, no money creation\n- **Fresh positions** — every rebalance picks the best available contracts for current market conditions\n- **Simple math** — `total_capital = cash + stocks` at the point of redeployment, no complex delta tracking\n\nBetween rebalance dates, positions are held (mark-to-market for balance tracking). If `check_exits_daily=True`, exit filters run daily but no new entries are made until the next rebalance.\n\nFor the **Spitznagel leverage** model (`options_budget` parameter), options are funded separately from the stock allocation so `{stocks: 1.0, options: 0.005}` means 100% equity + 0.5% put budget on top.\n\n## Rust acceleration\n\nOptional. Falls back to Python when not installed.\n\n```shell\nmake rust-build\n```\n\n| Benchmark | Python | Rust |\n|-----------|--------|------|\n| Full options backtest (24.7M rows) | 10.0s | **4.2s** |\n| Stock-only monthly rebalance | 3.7s | **0.6s** |\n| Parallel grid sweep (100 configs) | — | **5-8x** faster (Rayon, bypasses GIL) |\n\n## Data\n\n```shell\n# SPY stock + options data\npython data/fetch_data.py all --symbols SPY\n\n# Multiple symbols\npython data/fetch_data.py all --symbols SPY IWM QQQ --start 2020-01-01 --end 2023-01-01\n\n# FRED macro signals (VIX, GDP, Buffett Indicator, etc.)\npython data/fetch_signals.py\n\n# Convert OptionsDX format\npython data/convert_optionsdx.py data/raw/spx_eod_2020.csv --output data/processed/spx_options.csv\n```\n\nYou can also bring your own CSVs. Required columns:\n- **Stocks**: `date`, `symbol`, `adjClose`\n- **Options**: `quotedate`, `underlying`, `type`, `strike`, `expiration`, `dte`, `bid`, `ask`, `volume`, `openinterest`, `delta`\n\n## Tests\n\n```shell\nmake test # all tests (1300+)\nmake test-regression # regression snapshots (locked golden values)\nmake test-chaos # fault injection (corrupted/adversarial data)\nmake muttest # mutation testing on core modules\nmake lint # ruff\nmake typecheck # mypy\nmake rust-test # Rust unit tests\n```\n\n## Architecture\n\n```\noptions_portfolio_backtester/\n├── core/ # Types: Direction, OptionType, Greeks, Fill, Order\n├── data/ # Schema DSL, CSV providers\n├── strategy/ # Strategy, StrategyLeg, presets\n├── execution/ # CostModel, FillModel, Sizer, SignalSelector\n├── portfolio/ # Portfolio, OptionPosition, RiskManager\n├── engine/ # BacktestEngine, AlgoPipelineBacktester, StrategyTreeEngine\n└── analytics/ # BacktestStats, TradeLog, TearsheetReport, charts\n\nrust/\n├── ob_core/ # Backtest loop, stats, execution models, filter parser\n└── ob_python/ # PyO3 bindings, parallel sweep, Arrow bridge\n```\n\n## Pipeline algos\n\n40+ composable algos for the `AlgoPipelineBacktester`. All follow `__call__(ctx) -> StepDecision`.\n\n**Scheduling**: `RunDaily`, `RunWeekly`, `RunMonthly`, `RunQuarterly`, `RunYearly`, `RunOnce`, `RunOnDate`, `RunAfterDate`, `RunAfterDays`, `RunEveryNPeriods`, `RunIfOutOfBounds`, `Or`, `Not`, `Require`\n\n**Selection**: `SelectAll`, `SelectThese`, `SelectHasData`, `SelectN`, `SelectMomentum`, `SelectWhere`, `SelectRandomly`, `SelectActive`, `SelectRegex`\n\n**Weighting**: `WeighEqually`, `WeighSpecified`, `WeighTarget`, `WeighInvVol`, `WeighMeanVar`, `WeighERC`, `TargetVol`, `WeighRandomly`\n\n**Risk & rebalancing**: `LimitWeights`, `LimitDeltas`, `ScaleWeights`, `HedgeRisks`, `Margin`, `MaxDrawdownGuard`, `Rebalance`, `RebalanceOverTime`, `CapitalFlow`, `CloseDead`, `ClosePositionsAfterDates`, `ReplayTransactions`, `CouponPayingPosition`\n\n## Research\n\nResearch notebooks and analysis: [finance_research](https://github.com/unbalancedparentheses/finance_research).\n"
},
{
"path": "benchmarks/benchmark_large_pipeline.py",
"content": "\"\"\"Large-scale performance benchmark: Rust vs Python on production data.\n\nRuns the same strategy through Rust full-loop and Python BacktestEngine on\nthe full SPY options dataset (24.7M rows, 4500+ trading days) with frequent\nrebalancing to produce thousands of trades.\n\nUsage:\n python scripts/benchmark_large_pipeline.py\n python scripts/benchmark_large_pipeline.py --rebalance-freq 2 --runs 3\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport gc\nimport os\nimport sys\nimport time\nfrom dataclasses import dataclass, field\nfrom pathlib import Path\n\nimport numpy as np\nimport pandas as pd\n\nREPO_ROOT = Path(__file__).resolve().parents[1]\n\nfrom options_portfolio_backtester import BacktestEngine as LegacyBacktest\nfrom options_portfolio_backtester.data.providers import HistoricalOptionsData, TiingoData\nfrom options_portfolio_backtester.core.types import Direction, Stock, OptionType as Type\nfrom options_portfolio_backtester.strategy.strategy import Strategy\nfrom options_portfolio_backtester.strategy.strategy_leg import StrategyLeg\n\nfrom options_portfolio_backtester.engine.engine import BacktestEngine\nfrom options_portfolio_backtester.engine._dispatch import use_rust\nfrom options_portfolio_backtester.engine import _dispatch as _rust_dispatch\nfrom options_portfolio_backtester.execution.cost_model import NoCosts\n\n\nSTOCKS_FILE = os.path.join(REPO_ROOT, \"data\", \"processed\", \"stocks.csv\")\nOPTIONS_FILE = os.path.join(REPO_ROOT, \"data\", \"processed\", \"options.csv\")\n\n\n@dataclass\nclass BenchResult:\n name: str\n runtime_s: float\n final_capital: float\n total_return_pct: float\n n_trades: int\n n_balance_rows: int\n dispatch_mode: str\n peak_mem_mb: float = 0.0\n per_run_times: list[float] = field(default_factory=list)\n\n\ndef parse_args() -> argparse.Namespace:\n p = argparse.ArgumentParser(description=\"Large-scale Rust vs Python benchmark.\")\n p.add_argument(\"--runs\", type=int, default=3,\n help=\"Number of timing runs (default: 3).\")\n p.add_argument(\"--rebalance-freq\", type=int, default=1,\n help=\"Rebalance frequency in business months (1=monthly).\")\n p.add_argument(\"--dte-min\", type=int, default=20,\n help=\"Min DTE for entry filter.\")\n p.add_argument(\"--dte-max\", type=int, default=60,\n help=\"Max DTE for entry filter.\")\n p.add_argument(\"--dte-exit\", type=int, default=10,\n help=\"DTE threshold for exit.\")\n p.add_argument(\"--initial-capital\", type=int, default=1_000_000,\n help=\"Initial capital.\")\n p.add_argument(\"--options-pct\", type=float, default=0.10,\n help=\"Options allocation pct (0.10 = 10%%).\")\n return p.parse_args()\n\n\ndef _load_data():\n print(\"Loading data...\")\n t0 = time.perf_counter()\n stocks_data = TiingoData(STOCKS_FILE)\n options_data = HistoricalOptionsData(OPTIONS_FILE)\n load_time = time.perf_counter() - t0\n n_opt = len(options_data._data)\n n_stk = len(stocks_data._data)\n n_dates = options_data._data[\"quotedate\"].nunique()\n print(f\" Loaded in {load_time:.2f}s\")\n print(f\" Options: {n_opt:,} rows, {n_dates:,} trading days\")\n print(f\" Stocks: {n_stk:,} rows\")\n return stocks_data, options_data\n\n\ndef _strategy(schema, dte_min, dte_max, dte_exit):\n strat = Strategy(schema)\n leg = StrategyLeg(\"leg_1\", schema, option_type=Type.PUT, direction=Direction.BUY)\n leg.entry_filter = (\n (schema.underlying == \"SPY\")\n & (schema.dte >= dte_min)\n & (schema.dte <= dte_max)\n )\n leg.exit_filter = schema.dte <= dte_exit\n strat.add_legs([leg])\n return strat\n\n\ndef _copy_data(stocks_data, options_data):\n \"\"\"Deep-copy data handlers to avoid cross-run contamination.\"\"\"\n sd = TiingoData.__new__(TiingoData)\n sd.__dict__.update(stocks_data.__dict__)\n sd._data = stocks_data._data.copy()\n\n od = HistoricalOptionsData.__new__(HistoricalOptionsData)\n od.__dict__.update(options_data.__dict__)\n od._data = options_data._data.copy()\n return sd, od\n\n\ndef run_engine(\n stocks_data, options_data, args, runs, force_python=False,\n) -> BenchResult:\n \"\"\"Run BacktestEngine. If force_python, temporarily disable Rust dispatch.\"\"\"\n label = \"Python BacktestEngine\" if force_python else \"Rust BacktestEngine\"\n times = []\n engine = None\n\n for i in range(runs):\n sd, od = _copy_data(stocks_data, options_data)\n engine = BacktestEngine(\n {\"stocks\": 1.0 - args.options_pct, \"options\": args.options_pct, \"cash\": 0.0},\n cost_model=NoCosts(),\n initial_capital=args.initial_capital,\n )\n engine.stocks = [Stock(\"SPY\", 1.0)]\n engine.stocks_data = sd\n engine.options_data = od\n engine.options_strategy = _strategy(od.schema, args.dte_min, args.dte_max, args.dte_exit)\n\n gc.collect()\n saved_rust = _rust_dispatch.RUST_AVAILABLE\n if force_python:\n _rust_dispatch.RUST_AVAILABLE = False\n try:\n t0 = time.perf_counter()\n engine.run(rebalance_freq=args.rebalance_freq)\n elapsed = time.perf_counter() - t0\n finally:\n _rust_dispatch.RUST_AVAILABLE = saved_rust\n times.append(elapsed)\n print(f\" {label} run {i+1}/{runs}: {elapsed:.3f}s\")\n\n assert engine is not None\n mode = engine.run_metadata.get(\"dispatch_mode\", \"unknown\")\n final = float(engine.balance[\"total capital\"].iloc[-1])\n n_trades = len(engine.trade_log) if not engine.trade_log.empty else 0\n total_ret = (final / args.initial_capital - 1.0) * 100.0\n return BenchResult(\n name=label,\n runtime_s=float(np.mean(times)),\n final_capital=final,\n total_return_pct=total_ret,\n n_trades=n_trades,\n n_balance_rows=len(engine.balance),\n dispatch_mode=mode,\n per_run_times=times,\n )\n\n\ndef run_legacy(stocks_data, options_data, args, runs) -> BenchResult:\n \"\"\"Run legacy Backtest class.\"\"\"\n times = []\n bt = None\n\n for i in range(runs):\n sd, od = _copy_data(stocks_data, options_data)\n bt = LegacyBacktest(\n {\"stocks\": 1.0 - args.options_pct, \"options\": args.options_pct, \"cash\": 0.0},\n initial_capital=args.initial_capital,\n )\n bt.stocks = [Stock(\"SPY\", 1.0)]\n bt.stocks_data = sd\n bt.options_data = od\n bt.options_strategy = _strategy(od.schema, args.dte_min, args.dte_max, args.dte_exit)\n\n gc.collect()\n t0 = time.perf_counter()\n bt.run(rebalance_freq=args.rebalance_freq)\n elapsed = time.perf_counter() - t0\n times.append(elapsed)\n print(f\" Legacy Python run {i+1}/{runs}: {elapsed:.3f}s\")\n\n assert bt is not None\n final = float(bt.balance[\"total capital\"].iloc[-1])\n n_trades = len(bt.trade_log) if not bt.trade_log.empty else 0\n total_ret = (final / bt.initial_capital - 1.0) * 100.0\n return BenchResult(\n name=\"Legacy Python Backtest\",\n runtime_s=float(np.mean(times)),\n final_capital=final,\n total_return_pct=total_ret,\n n_trades=n_trades,\n n_balance_rows=len(bt.balance),\n dispatch_mode=\"python-legacy\",\n per_run_times=times,\n )\n\n\ndef print_result(r: BenchResult, indent: str = \" \") -> None:\n print(f\"{indent}{r.name}\")\n print(f\"{indent} dispatch: {r.dispatch_mode}\")\n print(f\"{indent} avg runtime: {r.runtime_s:.3f}s\")\n print(f\"{indent} per-run times: [{', '.join(f'{t:.3f}s' for t in r.per_run_times)}]\")\n print(f\"{indent} final capital: ${r.final_capital:,.2f}\")\n print(f\"{indent} total return: {r.total_return_pct:.4f}%\")\n print(f\"{indent} trades: {r.n_trades:,}\")\n print(f\"{indent} balance rows: {r.n_balance_rows:,}\")\n\n\ndef print_comparison(a: BenchResult, b: BenchResult) -> None:\n if a.runtime_s > 0:\n speedup = b.runtime_s / a.runtime_s\n else:\n speedup = float(\"nan\")\n cap_delta = abs(a.final_capital - b.final_capital)\n ret_delta = a.total_return_pct - b.total_return_pct\n cap_pct = (cap_delta / max(a.final_capital, 1)) * 100\n print(f\" {a.name} vs {b.name}:\")\n print(f\" speedup: {speedup:.2f}x ({a.name} is {'faster' if speedup > 1 else 'slower'})\")\n print(f\" capital delta: ${cap_delta:,.2f} ({cap_pct:.4f}%)\")\n print(f\" return delta: {ret_delta:+.4f} pct-pts\")\n if a.n_trades > 0 and b.n_trades > 0:\n print(f\" trade count: {a.n_trades:,} vs {b.n_trades:,} ({'match' if a.n_trades == b.n_trades else 'MISMATCH'})\")\n\n\ndef main() -> None:\n args = parse_args()\n\n for f in (STOCKS_FILE, OPTIONS_FILE):\n if not Path(f).exists():\n print(f\"ERROR: Missing data file: {f}\")\n print(\"Run this benchmark from the repo root with production data in data/processed/\")\n sys.exit(1)\n\n print(f\"\\n{'='*65}\")\n print(\"Large-Scale Performance Benchmark: Rust vs Python\")\n print(f\"{'='*65}\")\n print(f\" Rust available: {use_rust()}\")\n print(f\" runs per backend: {args.runs}\")\n print(f\" rebalance freq: {args.rebalance_freq} BMS\")\n print(f\" strategy: BUY PUT, DTE {args.dte_min}-{args.dte_max}, exit DTE <= {args.dte_exit}\")\n print(f\" allocation: {(1-args.options_pct)*100:.0f}% stocks / {args.options_pct*100:.0f}% options\")\n print(f\" initial capital: ${args.initial_capital:,}\")\n print()\n\n stocks_data, options_data = _load_data()\n print()\n\n # -- Run all backends --\n results = []\n\n if use_rust():\n print(\"Running Rust BacktestEngine...\")\n rust_result = run_engine(stocks_data, options_data, args, args.runs, force_python=False)\n results.append(rust_result)\n print()\n\n print(\"Running Python BacktestEngine...\")\n python_result = run_engine(stocks_data, options_data, args, args.runs, force_python=True)\n results.append(python_result)\n print()\n\n print(\"Running Legacy Python Backtest...\")\n legacy_result = run_legacy(stocks_data, options_data, args, args.runs)\n results.append(legacy_result)\n print()\n\n # -- Report --\n print(f\"{'='*65}\")\n print(\"Results\")\n print(f\"{'='*65}\")\n for r in results:\n print_result(r)\n print()\n\n print(f\"{'='*65}\")\n print(\"Comparisons\")\n print(f\"{'='*65}\")\n if use_rust():\n print_comparison(rust_result, python_result)\n print()\n print_comparison(rust_result, legacy_result)\n print()\n print_comparison(python_result, legacy_result)\n print()\n\n # -- Summary table --\n print(f\"{'='*65}\")\n print(\"Summary Table\")\n print(f\"{'='*65}\")\n rows = []\n for r in results:\n rows.append({\n \"Backend\": r.name,\n \"Dispatch\": r.dispatch_mode,\n \"Avg Time (s)\": f\"{r.runtime_s:.3f}\",\n \"Trades\": f\"{r.n_trades:,}\",\n \"Final Capital\": f\"${r.final_capital:,.0f}\",\n \"Return %\": f\"{r.total_return_pct:.2f}\",\n })\n df = pd.DataFrame(rows)\n print(df.to_string(index=False))\n\n if use_rust() and rust_result.runtime_s > 0:\n print(f\"\\n Rust speedup over Python Engine: {python_result.runtime_s / rust_result.runtime_s:.2f}x\")\n print(f\" Rust speedup over Legacy: {legacy_result.runtime_s / rust_result.runtime_s:.2f}x\")\n\n print(\"\\nDone.\")\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "benchmarks/benchmark_matrix.py",
"content": "\"\"\"Standardized benchmark matrix for options_portfolio_backtester vs bt.\n\nRuns multiple scenarios over date ranges/rebalance frequencies and writes\na CSV scorecard with runtime and parity metrics.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport sys\nimport time\nfrom dataclasses import dataclass\nfrom pathlib import Path\n\nimport numpy as np\nimport pandas as pd\n\nREPO_ROOT = Path(__file__).resolve().parents[1]\n\nfrom options_portfolio_backtester import BacktestEngine as Backtest\nfrom options_portfolio_backtester.data.providers import TiingoData\nfrom options_portfolio_backtester.core.types import Stock\n\n\n@dataclass(frozen=True)\nclass Scenario:\n label: str\n start: pd.Timestamp\n end: pd.Timestamp\n rebalance_months: int\n initial_capital: float\n\n\ndef parse_args() -> argparse.Namespace:\n p = argparse.ArgumentParser(description=\"Benchmark matrix vs bt.\")\n p.add_argument(\"--stocks-file\", default=\"data/processed/stocks.csv\")\n p.add_argument(\"--symbols\", default=\"SPY\")\n p.add_argument(\"--weights\", default=None)\n p.add_argument(\"--date-ranges\", default=\"2008-01-01:2025-12-12,2016-01-01:2025-12-12\")\n p.add_argument(\"--rebalance-months\", default=\"1,3\")\n p.add_argument(\"--initial-capitals\", default=\"1000000\")\n p.add_argument(\"--runs\", type=int, default=3)\n p.add_argument(\"--output\", default=\"data/processed/benchmark_matrix.csv\")\n return p.parse_args()\n\n\ndef parse_csv_list(s: str, cast):\n return [cast(x.strip()) for x in s.split(\",\") if x.strip()]\n\n\ndef normalize_weights(symbols: list[str], raw_weights: str | None) -> list[float]:\n if raw_weights is None:\n return [1.0 / len(symbols)] * len(symbols)\n vals = [float(x) for x in raw_weights.split(\",\")]\n if len(vals) != len(symbols):\n raise ValueError(\"--weights length must match --symbols length\")\n total = float(sum(vals))\n if total <= 0:\n raise ValueError(\"--weights must sum to > 0\")\n return [v / total for v in vals]\n\n\ndef compute_metrics(total_capital: pd.Series) -> tuple[float, float, float, float, float]:\n total_capital = total_capital.dropna()\n if total_capital.empty:\n return 0.0, 0.0, 0.0, 0.0, 0.0\n rets = total_capital.pct_change().dropna()\n total_return = total_capital.iloc[-1] / total_capital.iloc[0] - 1.0\n n_years = len(total_capital) / 252.0\n cagr = (total_capital.iloc[-1] / total_capital.iloc[0]) ** (1.0 / n_years) - 1.0 if n_years > 0 else 0.0\n peak = total_capital.cummax()\n dd = total_capital / peak - 1.0\n max_dd = float(dd.min()) if not dd.empty else 0.0\n vol = float(rets.std(ddof=1) * np.sqrt(252)) if len(rets) > 1 else 0.0\n sharpe = float((rets.mean() / rets.std(ddof=1)) * np.sqrt(252)) if len(rets) > 1 and rets.std(ddof=1) > 0 else 0.0\n return total_return, cagr, max_dd, vol, sharpe\n\n\ndef slice_stocks_data(stocks_file: str, start: pd.Timestamp, end: pd.Timestamp) -> TiingoData:\n d = TiingoData(stocks_file)\n m = (d._data[\"date\"] >= start) & (d._data[\"date\"] <= end)\n d._data = d._data.loc[m].copy()\n d.start_date = d._data[\"date\"].min()\n d.end_date = d._data[\"date\"].max()\n return d\n\n\ndef run_options_portfolio_backtester(\n stocks_file: str,\n symbols: list[str],\n weights: list[float],\n scenario: Scenario,\n runs: int,\n) -> tuple[dict[str, float], pd.Series]:\n stocks = [Stock(sym, w) for sym, w in zip(symbols, weights)]\n runtimes = []\n last_eq = pd.Series(dtype=float)\n for _ in range(runs):\n stocks_data = slice_stocks_data(stocks_file, scenario.start, scenario.end)\n bt = Backtest({\"stocks\": 1.0, \"options\": 0.0, \"cash\": 0.0}, initial_capital=int(scenario.initial_capital))\n bt.stocks = stocks\n bt.stocks_data = stocks_data\n t0 = time.perf_counter()\n bt.run(rebalance_freq=scenario.rebalance_months, rebalance_unit=\"BMS\")\n runtimes.append(time.perf_counter() - t0)\n last_eq = bt.balance[\"total capital\"].dropna()\n tr, cagr, mdd, vol, sharpe = compute_metrics(last_eq)\n return ({\n \"ob_runtime_s\": float(np.mean(runtimes)),\n \"ob_total_return_pct\": tr * 100.0,\n \"ob_cagr_pct\": cagr * 100.0,\n \"ob_max_drawdown_pct\": mdd * 100.0,\n \"ob_vol_annual_pct\": vol * 100.0,\n \"ob_sharpe\": sharpe,\n \"ob_rows\": float(len(last_eq)),\n }, last_eq)\n\n\ndef run_bt(\n stocks_file: str,\n symbols: list[str],\n weights: list[float],\n scenario: Scenario,\n runs: int,\n) -> tuple[dict[str, float], pd.Series | None]:\n try:\n import bt # type: ignore\n except Exception:\n return ({\"bt_available\": 0.0}, None)\n\n prices = pd.read_csv(stocks_file, parse_dates=[\"date\"])\n m = (prices[\"date\"] >= scenario.start) & (prices[\"date\"] <= scenario.end) & (prices[\"symbol\"].isin(symbols))\n prices = prices.loc[m].copy()\n px = prices.pivot(index=\"date\", columns=\"symbol\", values=\"adjClose\").sort_index().dropna()\n px = px[symbols]\n\n runtimes = []\n last_eq = None\n for _ in range(runs):\n algos = [\n bt.algos.RunMonthly(),\n bt.algos.SelectThese(symbols),\n bt.algos.WeighSpecified(**{s: w for s, w in zip(symbols, weights)}),\n bt.algos.Rebalance(),\n ]\n test = bt.Backtest(bt.Strategy(\"bench_matrix\", algos), px, initial_capital=scenario.initial_capital)\n t0 = time.perf_counter()\n res = bt.run(test)\n runtimes.append(time.perf_counter() - t0)\n last_eq = res.prices.iloc[:, 0]\n\n assert last_eq is not None\n tr, cagr, mdd, vol, sharpe = compute_metrics(last_eq)\n return ({\n \"bt_available\": 1.0,\n \"bt_runtime_s\": float(np.mean(runtimes)),\n \"bt_total_return_pct\": tr * 100.0,\n \"bt_cagr_pct\": cagr * 100.0,\n \"bt_max_drawdown_pct\": mdd * 100.0,\n \"bt_vol_annual_pct\": vol * 100.0,\n \"bt_sharpe\": sharpe,\n \"bt_rows\": float(len(last_eq)),\n }, last_eq)\n\n\ndef overlap_parity(ob_eq: pd.Series, bt_eq: pd.Series | None) -> dict[str, float]:\n if bt_eq is None:\n return {\"overlap_rows\": 0.0, \"overlap_end_delta\": np.nan, \"overlap_max_abs_delta\": np.nan}\n common = ob_eq.index.intersection(bt_eq.index)\n if len(common) == 0:\n return {\"overlap_rows\": 0.0, \"overlap_end_delta\": np.nan, \"overlap_max_abs_delta\": np.nan}\n ob_n = ob_eq.loc[common] / ob_eq.loc[common].iloc[0]\n bt_n = bt_eq.loc[common] / bt_eq.loc[common].iloc[0]\n d = ob_n - bt_n\n return {\n \"overlap_rows\": float(len(common)),\n \"overlap_end_delta\": float(d.iloc[-1]),\n \"overlap_max_abs_delta\": float(d.abs().max()),\n }\n\n\ndef build_scenarios(args: argparse.Namespace) -> list[Scenario]:\n date_ranges = []\n for chunk in args.date_ranges.split(\",\"):\n chunk = chunk.strip()\n if not chunk:\n continue\n s, e = chunk.split(\":\")\n date_ranges.append((pd.Timestamp(s), pd.Timestamp(e)))\n rebal = parse_csv_list(args.rebalance_months, int)\n capitals = parse_csv_list(args.initial_capitals, float)\n\n scenarios = []\n idx = 1\n for s, e in date_ranges:\n for r in rebal:\n for c in capitals:\n scenarios.append(Scenario(\n label=f\"S{idx}\",\n start=s,\n end=e,\n rebalance_months=r,\n initial_capital=c,\n ))\n idx += 1\n return scenarios\n\n\ndef main() -> None:\n args = parse_args()\n symbols = [s.strip().upper() for s in args.symbols.split(\",\") if s.strip()]\n if not symbols:\n raise ValueError(\"No symbols provided\")\n weights = normalize_weights(symbols, args.weights)\n scenarios = build_scenarios(args)\n\n rows = []\n for sc in scenarios:\n ob_stats, ob_eq = run_options_portfolio_backtester(\n stocks_file=args.stocks_file,\n symbols=symbols,\n weights=weights,\n scenario=sc,\n runs=args.runs,\n )\n bt_stats, bt_eq = run_bt(\n stocks_file=args.stocks_file,\n symbols=symbols,\n weights=weights,\n scenario=sc,\n runs=args.runs,\n )\n parity = overlap_parity(ob_eq, bt_eq)\n row = {\n \"scenario\": sc.label,\n \"start\": sc.start.date().isoformat(),\n \"end\": sc.end.date().isoformat(),\n \"rebalance_months\": sc.rebalance_months,\n \"initial_capital\": sc.initial_capital,\n \"symbols\": \",\".join(symbols),\n \"weights\": \",\".join(f\"{w:.6f}\" for w in weights),\n **ob_stats,\n **bt_stats,\n **parity,\n }\n if bt_stats.get(\"bt_available\", 0.0) == 1.0:\n row[\"speed_ratio_bt_over_ob\"] = row[\"bt_runtime_s\"] / row[\"ob_runtime_s\"] if row[\"ob_runtime_s\"] > 0 else np.nan\n row[\"return_delta_pct_pts\"] = row[\"ob_total_return_pct\"] - row[\"bt_total_return_pct\"]\n row[\"maxdd_delta_pct_pts\"] = row[\"ob_max_drawdown_pct\"] - row[\"bt_max_drawdown_pct\"]\n else:\n row[\"speed_ratio_bt_over_ob\"] = np.nan\n row[\"return_delta_pct_pts\"] = np.nan\n row[\"maxdd_delta_pct_pts\"] = np.nan\n rows.append(row)\n\n out = pd.DataFrame(rows).sort_values([\"start\", \"rebalance_months\", \"initial_capital\"])\n out_path = Path(args.output)\n out_path.parent.mkdir(parents=True, exist_ok=True)\n out.to_csv(out_path, index=False)\n\n print(\"\\n=== Benchmark Matrix Summary ===\")\n print(f\"scenarios: {len(out)}\")\n print(f\"output: {out_path}\")\n cols = [\n \"scenario\", \"start\", \"end\", \"rebalance_months\",\n \"ob_runtime_s\", \"bt_runtime_s\", \"speed_ratio_bt_over_ob\",\n \"return_delta_pct_pts\", \"maxdd_delta_pct_pts\", \"overlap_max_abs_delta\",\n ]\n print(out[cols].to_string(index=False))\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "benchmarks/benchmark_rust_vs_python.py",
"content": "\"\"\"Benchmark: Rust full-loop vs Python BacktestEngine vs legacy Backtest vs bt.\n\nRuns options backtest (with options data) through Rust and Python paths, plus\na stock-only comparison against bt if installed.\n\nUsage:\n python scripts/benchmark_rust_vs_python.py\n python scripts/benchmark_rust_vs_python.py --runs 5 --stock-only\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport os\nimport sys\nimport time\nfrom dataclasses import dataclass\nfrom pathlib import Path\n\nimport numpy as np\nimport pandas as pd\n\nREPO_ROOT = Path(__file__).resolve().parents[1]\n\nfrom options_portfolio_backtester import BacktestEngine as LegacyBacktest\nfrom options_portfolio_backtester.data.providers import HistoricalOptionsData, TiingoData\nfrom options_portfolio_backtester.core.types import Direction, Stock, OptionType as Type\nfrom options_portfolio_backtester.strategy.strategy import Strategy\nfrom options_portfolio_backtester.strategy.strategy_leg import StrategyLeg\n\nfrom options_portfolio_backtester.engine.engine import BacktestEngine\nfrom options_portfolio_backtester.engine._dispatch import use_rust\nfrom options_portfolio_backtester.engine import _dispatch as _rust_dispatch\nfrom options_portfolio_backtester.execution.cost_model import NoCosts\nfrom options_portfolio_backtester.execution.fill_model import MarketAtBidAsk\nfrom options_portfolio_backtester.execution.signal_selector import FirstMatch\n\nTEST_DIR = os.path.join(REPO_ROOT, \"backtester\", \"test\")\nSTOCKS_FILE = os.path.join(TEST_DIR, \"test_data\", \"ivy_5assets_data.csv\")\nOPTIONS_FILE = os.path.join(TEST_DIR, \"test_data\", \"options_data.csv\")\nPROD_STOCKS_FILE = os.path.join(REPO_ROOT, \"data\", \"processed\", \"stocks.csv\")\nPROD_OPTIONS_FILE = os.path.join(REPO_ROOT, \"data\", \"processed\", \"options.csv\")\n\n\n@dataclass\nclass BenchResult:\n name: str\n runtime_s: float\n final_capital: float\n total_return_pct: float\n n_trades: int\n dispatch_mode: str\n\n\ndef parse_args() -> argparse.Namespace:\n p = argparse.ArgumentParser(description=\"Benchmark Rust vs Python backtest paths.\")\n p.add_argument(\"--runs\", type=int, default=3, help=\"Timing averaging repeats.\")\n p.add_argument(\"--stock-only\", action=\"store_true\", help=\"Also run stock-only comparison vs bt.\")\n p.add_argument(\"--use-prod-data\", action=\"store_true\", help=\"Use production data files if available.\")\n p.add_argument(\"--rebalance-freq\", type=int, default=1, help=\"Rebalance frequency.\")\n return p.parse_args()\n\n\ndef _stocks(use_prod: bool = False):\n if use_prod:\n return [Stock(\"SPY\", 1.0)]\n return [Stock(\"VTI\", 0.2), Stock(\"VEU\", 0.2), Stock(\"BND\", 0.2),\n Stock(\"VNQ\", 0.2), Stock(\"DBC\", 0.2)]\n\n\ndef _load_data(use_prod: bool):\n if use_prod and Path(PROD_STOCKS_FILE).exists() and Path(PROD_OPTIONS_FILE).exists():\n stocks_file, options_file = PROD_STOCKS_FILE, PROD_OPTIONS_FILE\n else:\n stocks_file, options_file = STOCKS_FILE, OPTIONS_FILE\n\n stocks_data = TiingoData(stocks_file)\n options_data = HistoricalOptionsData(options_file)\n\n if stocks_file == STOCKS_FILE:\n stocks_data._data[\"adjClose\"] = 10\n options_data._data.at[2, \"ask\"] = 1\n options_data._data.at[2, \"bid\"] = 0.5\n options_data._data.at[51, \"ask\"] = 1.5\n options_data._data.at[50, \"bid\"] = 0.5\n options_data._data.at[130, \"bid\"] = 0.5\n options_data._data.at[131, \"bid\"] = 1.5\n options_data._data.at[206, \"bid\"] = 0.5\n options_data._data.at[207, \"bid\"] = 1.5\n\n return stocks_data, options_data, stocks_file\n\n\ndef _buy_strategy(schema):\n strat = Strategy(schema)\n leg = StrategyLeg(\"leg_1\", schema, option_type=Type.PUT, direction=Direction.BUY)\n leg.entry_filter = (schema.underlying == \"SPX\") & (schema.dte >= 60)\n leg.exit_filter = schema.dte <= 30\n strat.add_legs([leg])\n return strat\n\n\n# ---------------------------------------------------------------------------\n# Runners\n# ---------------------------------------------------------------------------\n\ndef run_engine_python(stocks_data, options_data, stocks, rebalance_freq, runs) -> BenchResult:\n \"\"\"Force Python path by temporarily disabling Rust dispatch.\"\"\"\n times = []\n engine = None\n for _ in range(runs):\n sd = TiingoData.__new__(TiingoData)\n sd.__dict__.update(stocks_data.__dict__)\n sd._data = stocks_data._data.copy()\n\n od = HistoricalOptionsData.__new__(HistoricalOptionsData)\n od.__dict__.update(options_data.__dict__)\n od._data = options_data._data.copy()\n\n engine = BacktestEngine(\n {\"stocks\": 0.97, \"options\": 0.03, \"cash\": 0},\n cost_model=NoCosts(),\n )\n engine.stocks = stocks\n engine.stocks_data = sd\n engine.options_data = od\n engine.options_strategy = _buy_strategy(od.schema)\n\n saved_rust = _rust_dispatch.RUST_AVAILABLE\n _rust_dispatch.RUST_AVAILABLE = False\n try:\n t0 = time.perf_counter()\n engine.run(rebalance_freq=rebalance_freq)\n times.append(time.perf_counter() - t0)\n finally:\n _rust_dispatch.RUST_AVAILABLE = saved_rust\n\n assert engine is not None\n final = float(engine.balance[\"total capital\"].iloc[-1])\n n_trades = len(engine.trade_log) if not engine.trade_log.empty else 0\n total_ret = (final / engine.initial_capital - 1) * 100\n return BenchResult(\n name=\"Python BacktestEngine\",\n runtime_s=float(np.mean(times)),\n final_capital=final,\n total_return_pct=total_ret,\n n_trades=n_trades,\n dispatch_mode=\"python\",\n )\n\n\ndef run_engine_rust(stocks_data, options_data, stocks, rebalance_freq, runs) -> BenchResult | None:\n \"\"\"Let Rust dispatch happen naturally (default path).\"\"\"\n if not use_rust():\n return None\n\n times = []\n engine = None\n for _ in range(runs):\n sd = TiingoData.__new__(TiingoData)\n sd.__dict__.update(stocks_data.__dict__)\n sd._data = stocks_data._data.copy()\n\n od = HistoricalOptionsData.__new__(HistoricalOptionsData)\n od.__dict__.update(options_data.__dict__)\n od._data = options_data._data.copy()\n\n engine = BacktestEngine(\n {\"stocks\": 0.97, \"options\": 0.03, \"cash\": 0},\n cost_model=NoCosts(),\n )\n engine.stocks = stocks\n engine.stocks_data = sd\n engine.options_data = od\n engine.options_strategy = _buy_strategy(od.schema)\n\n t0 = time.perf_counter()\n engine.run(rebalance_freq=rebalance_freq)\n times.append(time.perf_counter() - t0)\n\n assert engine is not None\n mode = engine.run_metadata.get(\"dispatch_mode\", \"unknown\")\n final = float(engine.balance[\"total capital\"].iloc[-1])\n n_trades = len(engine.trade_log) if not engine.trade_log.empty else 0\n total_ret = (final / engine.initial_capital - 1) * 100\n return BenchResult(\n name=\"Rust BacktestEngine\",\n runtime_s=float(np.mean(times)),\n final_capital=final,\n total_return_pct=total_ret,\n n_trades=n_trades,\n dispatch_mode=mode,\n )\n\n\ndef run_legacy_python(stocks_data, options_data, stocks, rebalance_freq, runs) -> BenchResult:\n \"\"\"Legacy Backtest class.\"\"\"\n times = []\n bt = None\n for _ in range(runs):\n sd = TiingoData.__new__(TiingoData)\n sd.__dict__.update(stocks_data.__dict__)\n sd._data = stocks_data._data.copy()\n\n od = HistoricalOptionsData.__new__(HistoricalOptionsData)\n od.__dict__.update(options_data.__dict__)\n od._data = options_data._data.copy()\n\n bt = LegacyBacktest({\"stocks\": 0.97, \"options\": 0.03, \"cash\": 0})\n bt.stocks = stocks\n bt.stocks_data = sd\n bt.options_data = od\n bt.options_strategy = _buy_strategy(od.schema)\n\n t0 = time.perf_counter()\n bt.run(rebalance_freq=rebalance_freq)\n times.append(time.perf_counter() - t0)\n\n assert bt is not None\n final = float(bt.balance[\"total capital\"].iloc[-1])\n n_trades = len(bt.trade_log) if not bt.trade_log.empty else 0\n total_ret = (final / bt.initial_capital - 1) * 100\n return BenchResult(\n name=\"Legacy Python Backtest\",\n runtime_s=float(np.mean(times)),\n final_capital=final,\n total_return_pct=total_ret,\n n_trades=n_trades,\n dispatch_mode=\"python-legacy\",\n )\n\n\ndef run_bt_stock_only(stocks_file, symbols, weights, initial_capital, runs) -> BenchResult | None:\n \"\"\"bt library stock-only benchmark.\"\"\"\n try:\n import bt\n except Exception:\n return None\n\n prices = pd.read_csv(stocks_file, parse_dates=[\"date\"])\n prices = prices[prices[\"symbol\"].isin(symbols)].copy()\n px = prices.pivot(index=\"date\", columns=\"symbol\", values=\"adjClose\").sort_index().dropna()\n px = px[symbols]\n\n times = []\n last_res = None\n for _ in range(runs):\n algos = [\n bt.algos.RunMonthly(),\n bt.algos.SelectThese(symbols),\n bt.algos.WeighSpecified(**dict(zip(symbols, weights))),\n bt.algos.Rebalance(),\n ]\n strat = bt.Strategy(\"bench\", algos)\n test = bt.Backtest(strat, px, initial_capital=initial_capital)\n t0 = time.perf_counter()\n last_res = bt.run(test)\n times.append(time.perf_counter() - t0)\n\n assert last_res is not None\n series = last_res.prices.iloc[:, 0]\n # bt normalizes NAV to start at initial_capital\n final = float(series.iloc[-1])\n start = float(series.iloc[0])\n total_ret = (final / start - 1) * 100\n return BenchResult(\n name=\"bt library\",\n runtime_s=float(np.mean(times)),\n final_capital=final,\n total_return_pct=total_ret,\n n_trades=0,\n dispatch_mode=\"bt\",\n )\n\n\ndef run_ob_stock_only(stocks_file, symbols, weights, initial_capital, runs) -> BenchResult:\n \"\"\"options_portfolio_backtester stock-only benchmark.\"\"\"\n stocks = [Stock(sym, w) for sym, w in zip(symbols, weights)]\n times = []\n bt_obj = None\n for _ in range(runs):\n stocks_data = TiingoData(stocks_file)\n bt_obj = LegacyBacktest({\"stocks\": 1.0, \"options\": 0.0, \"cash\": 0.0},\n initial_capital=int(initial_capital))\n bt_obj.stocks = stocks\n bt_obj.stocks_data = stocks_data\n t0 = time.perf_counter()\n bt_obj.run(rebalance_freq=1, rebalance_unit=\"BMS\")\n times.append(time.perf_counter() - t0)\n\n assert bt_obj is not None\n bal = bt_obj.balance[\"total capital\"].dropna()\n final = float(bal.iloc[-1])\n total_ret = (final / initial_capital - 1) * 100\n return BenchResult(\n name=\"options_portfolio_backtester (stock-only)\",\n runtime_s=float(np.mean(times)),\n final_capital=final,\n total_return_pct=total_ret,\n n_trades=0,\n dispatch_mode=\"python-legacy-stock-only\",\n )\n\n\n# ---------------------------------------------------------------------------\n# Display\n# ---------------------------------------------------------------------------\n\ndef print_result(r: BenchResult) -> None:\n print(f\" {r.name}\")\n print(f\" dispatch: {r.dispatch_mode}\")\n print(f\" runtime: {r.runtime_s:.4f}s\")\n print(f\" final_capital: {r.final_capital:,.2f}\")\n print(f\" total_return: {r.total_return_pct:.4f}%\")\n print(f\" n_trades: {r.n_trades}\")\n\n\ndef print_comparison(a: BenchResult, b: BenchResult) -> None:\n speedup = b.runtime_s / a.runtime_s if a.runtime_s > 0 else float(\"nan\")\n cap_delta = abs(a.final_capital - b.final_capital)\n ret_delta = a.total_return_pct - b.total_return_pct\n print(f\" {a.name} vs {b.name}:\")\n print(f\" speedup: {speedup:.2f}x ({a.name} is {'faster' if speedup > 1 else 'slower'})\")\n print(f\" capital delta: ${cap_delta:,.2f}\")\n print(f\" return delta: {ret_delta:+.4f} pct-pts\")\n if a.n_trades > 0 and b.n_trades > 0:\n print(f\" trades match: {a.n_trades == b.n_trades} ({a.n_trades} vs {b.n_trades})\")\n\n\ndef main() -> None:\n args = parse_args()\n stocks_data, options_data, stocks_file = _load_data(args.use_prod_data)\n stocks = _stocks(use_prod=args.use_prod_data)\n\n print(f\"\\n{'='*60}\")\n print(\"Benchmark: Rust vs Python vs Legacy\")\n print(f\"{'='*60}\")\n print(f\" Rust available: {use_rust()}\")\n print(f\" runs per backend: {args.runs}\")\n print(f\" rebalance_freq: {args.rebalance_freq}\")\n print(f\" data: {'production' if args.use_prod_data else 'test'}\")\n print()\n\n # -- Options backtest benchmarks --\n print(\"--- Options Backtest (with options data) ---\")\n results = []\n\n legacy = run_legacy_python(stocks_data, options_data, stocks, args.rebalance_freq, args.runs)\n results.append(legacy)\n print_result(legacy)\n\n python_engine = run_engine_python(stocks_data, options_data, stocks, args.rebalance_freq, args.runs)\n results.append(python_engine)\n print_result(python_engine)\n\n rust_engine = run_engine_rust(stocks_data, options_data, stocks, args.rebalance_freq, args.runs)\n if rust_engine:\n results.append(rust_engine)\n print_result(rust_engine)\n else:\n print(\" Rust BacktestEngine: SKIPPED (Rust not available)\")\n\n print()\n print(\"--- Comparisons ---\")\n if rust_engine:\n print_comparison(rust_engine, python_engine)\n print_comparison(rust_engine, legacy)\n print_comparison(python_engine, legacy)\n\n # -- Stock-only benchmarks --\n if args.stock_only and Path(PROD_STOCKS_FILE).exists():\n print()\n print(\"--- Stock-Only Monthly Rebalance (vs bt) ---\")\n symbols = [\"SPY\"]\n weights = [1.0]\n capital = 1_000_000.0\n\n ob_stock = run_ob_stock_only(PROD_STOCKS_FILE, symbols, weights, capital, args.runs)\n print_result(ob_stock)\n\n bt_res = run_bt_stock_only(PROD_STOCKS_FILE, symbols, weights, capital, args.runs)\n if bt_res:\n print_result(bt_res)\n print()\n print_comparison(ob_stock, bt_res)\n else:\n print(\" bt: SKIPPED (not installed)\")\n\n print()\n print(\"Done.\")\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "benchmarks/benchmark_sweep.py",
"content": "\"\"\"Benchmark: Rust parallel_sweep vs Python sequential grid search.\n\nThis is the PRIMARY benchmark for justifying the Rust backend.\nSingle backtests have Pandas<->Polars conversion overhead, but\nparallel_sweep amortizes that cost over N grid points and runs\nall backtests on Rayon threads (no GIL, no pickle, zero-copy data).\n\nUsage:\n python scripts/benchmark_sweep.py\n python scripts/benchmark_sweep.py --grid-sizes 10 50 100 --runs 3\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport gc\nimport math\nimport os\nimport sys\nimport time\nfrom pathlib import Path\n\nimport numpy as np\nimport pandas as pd\nimport polars as pl\n\nREPO_ROOT = Path(__file__).resolve().parents[1]\n\nfrom options_portfolio_backtester.data.providers import HistoricalOptionsData, TiingoData\nfrom options_portfolio_backtester.core.types import Direction, Stock, OptionType as Type\nfrom options_portfolio_backtester.strategy.strategy import Strategy\nfrom options_portfolio_backtester.strategy.strategy_leg import StrategyLeg\n\nfrom options_portfolio_backtester.engine.engine import BacktestEngine\nfrom options_portfolio_backtester.engine._dispatch import use_rust, rust\nfrom options_portfolio_backtester.engine import _dispatch as _rust_dispatch\nfrom options_portfolio_backtester.execution.cost_model import NoCosts\n\nTEST_DIR = os.path.join(REPO_ROOT, \"backtester\", \"test\")\nSTOCKS_FILE = os.path.join(TEST_DIR, \"test_data\", \"ivy_5assets_data.csv\")\nOPTIONS_FILE = os.path.join(TEST_DIR, \"test_data\", \"options_data.csv\")\nPROD_STOCKS_FILE = os.path.join(REPO_ROOT, \"data\", \"processed\", \"stocks.csv\")\nPROD_OPTIONS_FILE = os.path.join(REPO_ROOT, \"data\", \"processed\", \"options.csv\")\n\n\ndef parse_args():\n p = argparse.ArgumentParser(description=\"Benchmark Rust parallel_sweep vs Python sequential\")\n p.add_argument(\"--grid-sizes\", nargs=\"+\", type=int, default=[5, 10, 25, 50],\n help=\"Grid sizes to test (number of parameter combos)\")\n p.add_argument(\"--runs\", type=int, default=2, help=\"Timing runs per grid size\")\n p.add_argument(\"--use-prod-data\", action=\"store_true\", help=\"Use production data\")\n return p.parse_args()\n\n\ndef _load_data(use_prod: bool):\n if use_prod and Path(PROD_STOCKS_FILE).exists() and Path(PROD_OPTIONS_FILE).exists():\n sf, of = PROD_STOCKS_FILE, PROD_OPTIONS_FILE\n else:\n sf, of = STOCKS_FILE, OPTIONS_FILE\n\n stocks_data = TiingoData(sf)\n options_data = HistoricalOptionsData(of)\n\n if sf == STOCKS_FILE:\n stocks_data._data[\"adjClose\"] = 10\n options_data._data.at[2, \"ask\"] = 1\n options_data._data.at[2, \"bid\"] = 0.5\n options_data._data.at[51, \"ask\"] = 1.5\n options_data._data.at[50, \"bid\"] = 0.5\n options_data._data.at[130, \"bid\"] = 0.5\n options_data._data.at[131, \"bid\"] = 1.5\n options_data._data.at[206, \"bid\"] = 0.5\n options_data._data.at[207, \"bid\"] = 1.5\n\n return stocks_data, options_data, sf\n\n\ndef _build_param_grid(n: int, underlying: str = \"SPX\") -> list[dict]:\n \"\"\"Generate n parameter override dicts varying DTE thresholds.\n\n Returns list of dicts with both Rust filter strings AND raw dte values\n so both the Rust and Python paths can use the same grid.\n \"\"\"\n dte_mins = np.linspace(20, 90, max(int(n**0.5), 2)).astype(int)\n dte_exits = np.linspace(5, 45, max(int(n / len(dte_mins)) + 1, 2)).astype(int)\n grid = []\n for dmin in dte_mins:\n for dex in dte_exits:\n if len(grid) >= n:\n break\n grid.append({\n \"label\": f\"dte_min={dmin}_exit={dex}\",\n \"leg_entry_filters\": [\n f\"(underlying == '{underlying}') & (dte >= {dmin})\",\n ],\n \"leg_exit_filters\": [\n f\"dte <= {dex}\",\n ],\n # Raw params for Python path\n \"_dte_min\": int(dmin),\n \"_dte_exit\": int(dex),\n \"_underlying\": underlying,\n })\n if len(grid) >= n:\n break\n return grid[:n]\n\n\ndef _build_rust_config(stocks_data, options_data, stocks, underlying=\"SPX\"):\n \"\"\"Build the config dict for rust.parallel_sweep.\"\"\"\n schema = options_data.schema\n strat = Strategy(schema)\n leg = StrategyLeg(\"leg_1\", schema, option_type=Type.PUT, direction=Direction.BUY)\n leg.entry_filter = (schema.underlying == underlying) & (schema.dte >= 60)\n leg.exit_filter = schema.dte <= 30\n strat.add_legs([leg])\n\n date_fmt = \"%Y-%m-%d %H:%M:%S\"\n dates_df = (\n pd.DataFrame(options_data._data[[\"quotedate\", \"volume\"]])\n .drop_duplicates(\"quotedate\")\n .set_index(\"quotedate\")\n )\n rebalancing_days = pd.to_datetime(\n dates_df.groupby(pd.Grouper(freq=\"1BMS\"))\n .apply(lambda x: x.index.min())\n .values\n )\n rb_dates = [d.strftime(date_fmt) for d in rebalancing_days]\n\n config = {\n \"allocation\": {\"stocks\": 0.97, \"options\": 0.03, \"cash\": 0.0},\n \"initial_capital\": 1_000_000.0,\n \"shares_per_contract\": 100,\n \"rebalance_dates\": rb_dates,\n \"legs\": [{\n \"name\": leg.name,\n \"entry_filter\": leg.entry_filter.query,\n \"exit_filter\": leg.exit_filter.query,\n \"direction\": leg.direction.value,\n \"type\": leg.type.value,\n \"entry_sort_col\": None,\n \"entry_sort_asc\": True,\n }],\n \"profit_pct\": None,\n \"loss_pct\": None,\n \"stocks\": [(s.symbol, s.percentage) for s in stocks],\n }\n\n stocks_schema = stocks_data.schema\n opts_schema = options_data.schema\n schema_mapping = {\n \"contract\": opts_schema[\"contract\"],\n \"date\": opts_schema[\"date\"],\n \"stocks_date\": stocks_schema[\"date\"],\n \"stocks_symbol\": stocks_schema[\"symbol\"],\n \"stocks_price\": stocks_schema[\"adjClose\"],\n \"underlying\": opts_schema[\"underlying\"],\n \"expiration\": opts_schema[\"expiration\"],\n \"type\": opts_schema[\"type\"],\n \"strike\": opts_schema[\"strike\"],\n }\n\n # Convert datetime columns\n opts_copy = options_data._data.copy()\n for c in [opts_schema[\"date\"], opts_schema[\"expiration\"]]:\n if c in opts_copy.columns and pd.api.types.is_datetime64_any_dtype(opts_copy[c]):\n opts_copy[c] = opts_copy[c].dt.strftime(date_fmt)\n\n stocks_copy = stocks_data._data.copy()\n sc = stocks_schema[\"date\"]\n if sc in stocks_copy.columns and pd.api.types.is_datetime64_any_dtype(stocks_copy[sc]):\n stocks_copy[sc] = stocks_copy[sc].dt.strftime(date_fmt)\n\n opts_pl = pl.from_pandas(opts_copy)\n stocks_pl = pl.from_pandas(stocks_copy)\n\n return config, schema_mapping, opts_pl, stocks_pl, strat\n\n\ndef run_rust_sweep(opts_pl, stocks_pl, config, schema_mapping, param_grid, runs):\n \"\"\"Run Rust parallel_sweep.\"\"\"\n times = []\n last_results = None\n for _ in range(runs):\n gc.collect()\n t0 = time.perf_counter()\n results = rust.parallel_sweep(\n opts_pl, stocks_pl, config, schema_mapping, param_grid, None,\n )\n elapsed = time.perf_counter() - t0\n times.append(elapsed)\n last_results = results\n return times, last_results\n\n\ndef run_python_sequential(stocks_data, options_data, stocks, param_grid, runs, underlying=\"SPX\"):\n \"\"\"Run sequential Python backtests for same grid.\"\"\"\n times = []\n last_results = None\n for _ in range(runs):\n gc.collect()\n t0 = time.perf_counter()\n results = []\n for params in param_grid:\n sd = TiingoData.__new__(TiingoData)\n sd.__dict__.update(stocks_data.__dict__)\n sd._data = stocks_data._data.copy()\n\n od = HistoricalOptionsData.__new__(HistoricalOptionsData)\n od.__dict__.update(options_data.__dict__)\n od._data = options_data._data.copy()\n\n schema = od.schema\n strat = Strategy(schema)\n leg = StrategyLeg(\"leg_1\", schema, option_type=Type.PUT, direction=Direction.BUY)\n\n # Construct filters from raw DTE params\n dte_min = params.get(\"_dte_min\", 60)\n dte_exit = params.get(\"_dte_exit\", 30)\n und = params.get(\"_underlying\", underlying)\n leg.entry_filter = (schema.underlying == und) & (schema.dte >= dte_min)\n leg.exit_filter = schema.dte <= dte_exit\n strat.add_legs([leg])\n\n engine = BacktestEngine(\n {\"stocks\": 0.97, \"options\": 0.03, \"cash\": 0},\n cost_model=NoCosts(),\n )\n engine.stocks = stocks\n engine.stocks_data = sd\n engine.options_data = od\n engine.options_strategy = strat\n\n saved = _rust_dispatch.RUST_AVAILABLE\n _rust_dispatch.RUST_AVAILABLE = False\n try:\n engine.run(rebalance_freq=1)\n finally:\n _rust_dispatch.RUST_AVAILABLE = saved\n\n final = float(engine.balance[\"total capital\"].iloc[-1])\n n_trades = len(engine.trade_log) if not engine.trade_log.empty else 0\n results.append({\n \"label\": params.get(\"label\", \"\"),\n \"final_capital\": final,\n \"total_trades\": n_trades,\n })\n\n elapsed = time.perf_counter() - t0\n times.append(elapsed)\n last_results = results\n return times, last_results\n\n\ndef run_rust_single(opts_pl, stocks_pl, config, schema_mapping, runs):\n \"\"\"Run a single Rust backtest (for overhead measurement).\"\"\"\n times = []\n for _ in range(runs):\n gc.collect()\n t0 = time.perf_counter()\n rust.run_backtest_py(opts_pl, stocks_pl, config, schema_mapping)\n elapsed = time.perf_counter() - t0\n times.append(elapsed)\n return times\n\n\ndef run_python_single(stocks_data, options_data, stocks, runs, underlying=\"SPX\"):\n \"\"\"Run a single Python backtest.\"\"\"\n times = []\n for _ in range(runs):\n sd = TiingoData.__new__(TiingoData)\n sd.__dict__.update(stocks_data.__dict__)\n sd._data = stocks_data._data.copy()\n\n od = HistoricalOptionsData.__new__(HistoricalOptionsData)\n od.__dict__.update(options_data.__dict__)\n od._data = options_data._data.copy()\n\n engine = BacktestEngine(\n {\"stocks\": 0.97, \"options\": 0.03, \"cash\": 0},\n cost_model=NoCosts(),\n )\n engine.stocks = stocks\n engine.stocks_data = sd\n engine.options_data = od\n schema = od.schema\n strat = Strategy(schema)\n leg = StrategyLeg(\"leg_1\", schema, option_type=Type.PUT, direction=Direction.BUY)\n leg.entry_filter = (schema.underlying == underlying) & (schema.dte >= 60)\n leg.exit_filter = schema.dte <= 30\n strat.add_legs([leg])\n engine.options_strategy = strat\n\n saved = _rust_dispatch.RUST_AVAILABLE\n _rust_dispatch.RUST_AVAILABLE = False\n try:\n gc.collect()\n t0 = time.perf_counter()\n engine.run(rebalance_freq=1)\n elapsed = time.perf_counter() - t0\n finally:\n _rust_dispatch.RUST_AVAILABLE = saved\n times.append(elapsed)\n return times\n\n\ndef main():\n args = parse_args()\n\n if not use_rust():\n print(\"ERROR: Rust extension not available. Build with: make rust-build\")\n sys.exit(1)\n\n stocks_data, options_data, sf = _load_data(args.use_prod_data)\n if args.use_prod_data and Path(PROD_STOCKS_FILE).exists():\n stocks = [Stock(\"SPY\", 1.0)]\n else:\n stocks = [Stock(\"VTI\", 0.2), Stock(\"VEU\", 0.2), Stock(\"BND\", 0.2),\n Stock(\"VNQ\", 0.2), Stock(\"DBC\", 0.2)]\n underlying = \"SPY\" if args.use_prod_data else \"SPX\"\n n_rows = len(options_data._data)\n n_dates = options_data._data[\"quotedate\"].nunique()\n\n print(f\"\\n{'='*65}\")\n print(\"Benchmark: Rust parallel_sweep vs Python sequential\")\n print(f\"{'='*65}\")\n print(f\" Data: {'production' if args.use_prod_data else 'test'} ({n_rows:,} options rows, {n_dates} dates)\")\n print(f\" Underlying: {underlying}\")\n print(f\" Grid sizes: {args.grid_sizes}\")\n print(f\" Runs per test: {args.runs}\")\n print(f\" CPU cores: {os.cpu_count()}\")\n print()\n\n # Build Rust config once (amortized over all grid sizes)\n config, schema_mapping, opts_pl, stocks_pl, strat = _build_rust_config(\n stocks_data, options_data, stocks, underlying=underlying\n )\n\n # -- Single backtest comparison --\n print(\"--- Single Backtest (1 run) ---\")\n rust_single = run_rust_single(opts_pl, stocks_pl, config, schema_mapping, args.runs)\n python_single = run_python_single(stocks_data, options_data, stocks, args.runs, underlying=underlying)\n rust_avg = np.mean(rust_single)\n py_avg = np.mean(python_single)\n print(f\" Rust single: {rust_avg:.4f}s (per-run: [{', '.join(f'{t:.4f}s' for t in rust_single)}])\")\n print(f\" Python single: {py_avg:.4f}s (per-run: [{', '.join(f'{t:.4f}s' for t in python_single)}])\")\n print(f\" Speedup: {py_avg/rust_avg:.2f}x {'(Rust faster)' if rust_avg < py_avg else '(Python faster)'}\")\n print()\n\n # -- Grid sweep comparison --\n print(\"--- Grid Sweep (N parallel Rust vs N sequential Python) ---\")\n rows = []\n for grid_size in args.grid_sizes:\n param_grid = _build_param_grid(grid_size, underlying=underlying)\n\n print(f\"\\n Grid size: {grid_size}\")\n\n # Rust parallel_sweep\n rust_times, rust_results = run_rust_sweep(\n opts_pl, stocks_pl, config, schema_mapping, param_grid, args.runs\n )\n rust_avg = np.mean(rust_times)\n print(f\" Rust parallel: {rust_avg:.4f}s (per-run: [{', '.join(f'{t:.4f}s' for t in rust_times)}])\")\n\n # Python sequential\n python_times, python_results = run_python_sequential(\n stocks_data, options_data, stocks, param_grid, args.runs, underlying=underlying\n )\n py_avg = np.mean(python_times)\n print(f\" Python seq: {py_avg:.4f}s (per-run: [{', '.join(f'{t:.4f}s' for t in python_times)}])\")\n\n speedup = py_avg / rust_avg if rust_avg > 0 else float(\"nan\")\n throughput_rust = grid_size / rust_avg if rust_avg > 0 else 0\n throughput_py = grid_size / py_avg if py_avg > 0 else 0\n print(f\" Speedup: {speedup:.2f}x {'(Rust faster)' if speedup > 1 else '(Python faster)'}\")\n print(f\" Throughput: Rust={throughput_rust:.1f}/s, Python={throughput_py:.1f}/s\")\n\n rows.append({\n \"Grid\": grid_size,\n \"Rust (s)\": f\"{rust_avg:.4f}\",\n \"Python (s)\": f\"{py_avg:.4f}\",\n \"Speedup\": f\"{speedup:.2f}x\",\n \"Rust runs/s\": f\"{throughput_rust:.1f}\",\n \"Python runs/s\": f\"{throughput_py:.1f}\",\n })\n\n # -- Summary Table --\n print(f\"\\n{'='*65}\")\n print(\"Summary\")\n print(f\"{'='*65}\")\n df = pd.DataFrame(rows)\n print(df.to_string(index=False))\n\n print(f\"\\n{'='*65}\")\n print(\"Conclusion\")\n print(f\"{'='*65}\")\n if rows:\n final_speedup = float(rows[-1][\"Speedup\"].replace(\"x\", \"\"))\n if final_speedup > 1:\n print(f\" Rust parallel_sweep is {final_speedup:.1f}x faster for {args.grid_sizes[-1]} grid points.\")\n print(f\" For optimization/grid search, Rust + Rayon provides real value.\")\n else:\n print(f\" Rust is {1/final_speedup:.1f}x slower even for parallel sweep.\")\n print(f\" The Pandas<->Polars conversion overhead dominates.\")\n\n single_speedup = np.mean(python_single) / np.mean(rust_single)\n if single_speedup < 1:\n print(f\" Single backtest: Rust is {1/single_speedup:.1f}x SLOWER (conversion overhead).\")\n else:\n print(f\" Single backtest: Rust is {single_speedup:.1f}x faster.\")\n\n print(\"\\nDone.\")\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "benchmarks/compare_with_bt.py",
"content": "\"\"\"Head-to-head comparison: options_portfolio_backtester stock-only mode vs bt.\n\nThis harness runs the same monthly stock-rebalance policy in both frameworks:\n- options_portfolio_backtester (legacy Backtest with options allocation = 0)\n- bt (if installed)\n\nOutputs a small scorecard with performance and runtime metrics.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport argparse\nimport sys\nimport time\nfrom dataclasses import dataclass\nfrom pathlib import Path\n\nimport numpy as np\nimport pandas as pd\n\nREPO_ROOT = Path(__file__).resolve().parents[1]\n\nfrom options_portfolio_backtester import BacktestEngine as Backtest\nfrom options_portfolio_backtester.data.providers import TiingoData\nfrom options_portfolio_backtester.core.types import Stock\n\n\n@dataclass\nclass RunResult:\n name: str\n total_return_pct: float\n cagr_pct: float\n max_drawdown_pct: float\n vol_annual_pct: float\n sharpe: float\n runtime_s: float\n start_date: str\n end_date: str\n n_days: int\n equity: pd.Series\n\n\ndef parse_args() -> argparse.Namespace:\n parser = argparse.ArgumentParser(description=\"Compare options_portfolio_backtester vs bt on stock-only allocation.\")\n parser.add_argument(\"--stocks-file\", default=\"data/processed/stocks.csv\")\n parser.add_argument(\"--options-file\", default=\"data/processed/options.csv\")\n parser.add_argument(\"--symbols\", default=\"SPY\", help=\"Comma-separated symbols. Example: SPY or SPY,TLT,GLD\")\n parser.add_argument(\"--weights\", default=None, help=\"Comma-separated weights matching symbols. Defaults equal.\")\n parser.add_argument(\"--initial-capital\", type=float, default=1_000_000.0)\n parser.add_argument(\"--rebalance-months\", type=int, default=1, help=\"Business-month-start rebalance frequency.\")\n parser.add_argument(\"--runs\", type=int, default=3, help=\"Runtime averaging repeats.\")\n return parser.parse_args()\n\n\ndef normalize_weights(symbols: list[str], raw_weights: str | None) -> list[float]:\n if raw_weights is None:\n return [1.0 / len(symbols)] * len(symbols)\n vals = [float(x) for x in raw_weights.split(\",\")]\n if len(vals) != len(symbols):\n raise ValueError(\"--weights length must match --symbols length\")\n total = float(sum(vals))\n if total <= 0:\n raise ValueError(\"--weights must sum to > 0\")\n return [v / total for v in vals]\n\n\ndef compute_metrics(total_capital: pd.Series) -> tuple[float, float, float, float, float]:\n total_capital = total_capital.dropna()\n if total_capital.empty:\n return 0.0, 0.0, 0.0, 0.0, 0.0\n\n rets = total_capital.pct_change().dropna()\n total_return = total_capital.iloc[-1] / total_capital.iloc[0] - 1.0\n n_years = len(total_capital) / 252.0\n cagr = (total_capital.iloc[-1] / total_capital.iloc[0]) ** (1.0 / n_years) - 1.0 if n_years > 0 else 0.0\n\n peak = total_capital.cummax()\n dd = total_capital / peak - 1.0\n max_dd = float(dd.min()) if not dd.empty else 0.0\n\n vol = float(rets.std(ddof=1) * np.sqrt(252)) if len(rets) > 1 else 0.0\n sharpe = float((rets.mean() / rets.std(ddof=1)) * np.sqrt(252)) if len(rets) > 1 and rets.std(ddof=1) > 0 else 0.0\n return total_return, cagr, max_dd, vol, sharpe\n\n\ndef run_options_portfolio_backtester(\n stocks_file: str,\n symbols: list[str],\n weights: list[float],\n initial_capital: float,\n rebalance_months: int,\n runs: int,\n) -> RunResult:\n stocks_data = TiingoData(stocks_file)\n\n stocks = [Stock(sym, w) for sym, w in zip(symbols, weights)]\n times: list[float] = []\n bt_obj = None\n for _ in range(runs):\n bt = Backtest({\"stocks\": 1.0, \"options\": 0.0, \"cash\": 0.0}, initial_capital=int(initial_capital))\n bt.stocks = stocks\n bt.stocks_data = stocks_data\n\n t0 = time.perf_counter()\n bt.run(rebalance_freq=rebalance_months, rebalance_unit=\"BMS\")\n times.append(time.perf_counter() - t0)\n bt_obj = bt\n\n assert bt_obj is not None\n bal = bt_obj.balance[\"total capital\"].dropna()\n tr, cagr, mdd, vol, sharpe = compute_metrics(bal)\n return RunResult(\n name=\"options_portfolio_backtester\",\n total_return_pct=tr * 100.0,\n cagr_pct=cagr * 100.0,\n max_drawdown_pct=mdd * 100.0,\n vol_annual_pct=vol * 100.0,\n sharpe=sharpe,\n runtime_s=float(np.mean(times)),\n start_date=str(bal.index.min().date()),\n end_date=str(bal.index.max().date()),\n n_days=int(len(bal)),\n equity=bal,\n )\n\n\ndef run_bt(\n stocks_file: str,\n symbols: list[str],\n weights: list[float],\n initial_capital: float,\n runs: int,\n) -> RunResult | None:\n try:\n import bt # type: ignore\n except Exception:\n return None\n\n prices = pd.read_csv(stocks_file, parse_dates=[\"date\"])\n prices = prices[prices[\"symbol\"].isin(symbols)].copy()\n px = prices.pivot(index=\"date\", columns=\"symbol\", values=\"adjClose\").sort_index().dropna()\n px = px[symbols]\n\n times: list[float] = []\n last_res = None\n for _ in range(runs):\n algos = [\n bt.algos.RunMonthly(),\n bt.algos.SelectThese(symbols),\n bt.algos.WeighSpecified(**{s: w for s, w in zip(symbols, weights)}),\n bt.algos.Rebalance(),\n ]\n strat = bt.Strategy(\"bt_monthly_rebal\", algos)\n test = bt.Backtest(strat, px, initial_capital=initial_capital)\n\n t0 = time.perf_counter()\n last_res = bt.run(test)\n times.append(time.perf_counter() - t0)\n\n assert last_res is not None\n series = last_res.prices.iloc[:, 0]\n tr, cagr, mdd, vol, sharpe = compute_metrics(series)\n return RunResult(\n name=\"bt\",\n total_return_pct=tr * 100.0,\n cagr_pct=cagr * 100.0,\n max_drawdown_pct=mdd * 100.0,\n vol_annual_pct=vol * 100.0,\n sharpe=sharpe,\n runtime_s=float(np.mean(times)),\n start_date=str(series.index.min().date()),\n end_date=str(series.index.max().date()),\n n_days=int(len(series)),\n equity=series,\n )\n\n\ndef print_result(r: RunResult) -> None:\n print(f\"{r.name}\")\n print(f\" period: {r.start_date} -> {r.end_date} ({r.n_days} rows)\")\n print(f\" total_return: {r.total_return_pct:8.2f}%\")\n print(f\" cagr: {r.cagr_pct:8.2f}%\")\n print(f\" max_drawdown: {r.max_drawdown_pct:8.2f}%\")\n print(f\" vol_annual: {r.vol_annual_pct:8.2f}%\")\n print(f\" sharpe: {r.sharpe:8.3f}\")\n print(f\" runtime: {r.runtime_s:8.4f}s\")\n\n\ndef print_overlap_parity(a: RunResult, b: RunResult) -> None:\n common = a.equity.index.intersection(b.equity.index)\n if len(common) == 0:\n print(\" overlap: none\")\n return\n\n a_n = a.equity.loc[common] / a.equity.loc[common].iloc[0]\n b_n = b.equity.loc[common] / b.equity.loc[common].iloc[0]\n diff = a_n - b_n\n print(f\" overlap rows: {len(common)}\")\n print(f\" overlap end delta: {float(diff.iloc[-1]):.6e}\")\n print(f\" overlap max abs delta: {float(diff.abs().max()):.6e}\")\n\n\ndef main() -> None:\n args = parse_args()\n symbols = [s.strip().upper() for s in args.symbols.split(\",\") if s.strip()]\n if not symbols:\n raise ValueError(\"No symbols provided\")\n weights = normalize_weights(symbols, args.weights)\n\n for file_path in (args.stocks_file,):\n if not Path(file_path).exists():\n raise FileNotFoundError(f\"Missing file: {file_path}\")\n\n ob = run_options_portfolio_backtester(\n stocks_file=args.stocks_file,\n symbols=symbols,\n weights=weights,\n initial_capital=args.initial_capital,\n rebalance_months=args.rebalance_months,\n runs=args.runs,\n )\n bt_res = run_bt(\n stocks_file=args.stocks_file,\n symbols=symbols,\n weights=weights,\n initial_capital=args.initial_capital,\n runs=args.runs,\n )\n\n print(\"\\n=== Comparison Scorecard ===\")\n print_result(ob)\n if bt_res is None:\n print(\"\\nbt\")\n print(\" not available (module 'bt' is not installed in this environment).\")\n print(\" install in nix shell and rerun:\")\n print(\" pip install bt\")\n else:\n print()\n print_result(bt_res)\n speedup = bt_res.runtime_s / ob.runtime_s if ob.runtime_s > 0 else float(\"nan\")\n print(\"\\nsummary\")\n print(f\" speed ratio (bt / options_portfolio_backtester): {speedup:0.2f}x\")\n print(\n f\" return delta (options_portfolio_backtester - bt): \"\n f\"{(ob.total_return_pct - bt_res.total_return_pct):0.2f} pct-pts\"\n )\n print(\n f\" maxDD delta (options_portfolio_backtester - bt): \"\n f\"{(ob.max_drawdown_pct - bt_res.max_drawdown_pct):0.2f} pct-pts\"\n )\n print(\" overlap parity:\")\n print_overlap_parity(ob, bt_res)\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "data/README.md",
"content": "# Data Scripts\n\nScripts for fetching and converting market data into the formats expected by the backtester.\n\n## Quick Start\n\nFetch both stock and options data for SPY, aligned by date:\n\n```bash\npython data/fetch_data.py all --symbols SPY --start 2020-01-01 --end 2023-01-01\n```\n\nData is first fetched from the [self-hosted GitHub Release](https://github.com/lambdaclass/options_backtester/releases/tag/data-v1), falling back to [philippdubach/options-data](https://github.com/philippdubach/options-data) CDN and yfinance. Outputs:\n- `data/processed/stocks.csv` — Tiingo-format stock data\n- `data/processed/options.csv` — options data with Greeks\n\n## Subcommands\n\n```bash\n# Stocks only (GitHub Release > options-data > yfinance)\npython data/fetch_data.py stocks --symbols SPY --start 2020-01-01 --end 2023-01-01\n\n# Options only\npython data/fetch_data.py options --symbols SPY --start 2020-01-01 --end 2023-01-01\n\n# Both + date alignment (default)\npython data/fetch_data.py all --symbols SPY --start 2020-01-01 --end 2023-01-01\n\n# Multiple symbols\npython data/fetch_data.py all --symbols SPY IWM QQQ --start 2020-01-01 --end 2023-01-01\n\n# Custom output paths\npython data/fetch_data.py all --symbols SPY --start 2020-01-01 --end 2023-01-01 \\\n --stocks-output data/processed/spy_stocks.csv \\\n --options-output data/processed/spy_options.csv\n\n# Force re-download (skip cache)\npython data/fetch_data.py all --symbols SPY --start 2020-01-01 --end 2023-01-01 --force\n```\n\n## OptionsDX Conversion (separate)\n\nFor SPX index options from [optionsdx.com](https://www.optionsdx.com/):\n\n```bash\npython data/convert_optionsdx.py data/raw/spx_eod_2020.csv --output data/processed/spx_options.csv\n```\n\n## Loading Data in the Backtester\n\n```python\nfrom backtester.datahandler import HistoricalOptionsData, TiingoData\n\noptions = HistoricalOptionsData(\"data/processed/options.csv\")\nstocks = TiingoData(\"data/processed/stocks.csv\")\n```\n\nThe `all` subcommand automatically aligns stock and option dates so the backtester's `np.array_equal` assertion passes.\n\n## Directory Structure\n\n- `raw/` — Cached parquet downloads (gitignored)\n- `processed/` — Converted CSV output ready for the backtester (gitignored)\n"
},
{
"path": "data/convert_optionsdx.py",
"content": "#!/usr/bin/env python3\n\"\"\"Convert OptionsDX wide-format CSV to backtester long-format CSV.\n\nOptionsDX provides one row per strike/date/expiry with both call and put data\nin wide format. The backtester expects one row per contract in long format.\n\nUsage:\n python data/convert_optionsdx.py data/raw/spx_eod.csv --output data/processed/spx_options.csv\n\"\"\"\n\nimport argparse\nimport sys\n\nimport pandas as pd\n\n\n# OptionsDX columns we need (they have trailing spaces, stripped on read)\nCALL_COLS = {\n \"C_BID\": \"bid\",\n \"C_ASK\": \"ask\",\n \"C_LAST\": \"last\",\n \"C_VOLUME\": \"volume\",\n \"C_IV\": \"impliedvol\",\n \"C_DELTA\": \"delta\",\n \"C_GAMMA\": \"gamma\",\n \"C_THETA\": \"theta\",\n \"C_VEGA\": \"vega\",\n}\n\nPUT_COLS = {\n \"P_BID\": \"bid\",\n \"P_ASK\": \"ask\",\n \"P_LAST\": \"last\",\n \"P_VOLUME\": \"volume\",\n \"P_IV\": \"impliedvol\",\n \"P_DELTA\": \"delta\",\n \"P_GAMMA\": \"gamma\",\n \"P_THETA\": \"theta\",\n \"P_VEGA\": \"vega\",\n}\n\nOUTPUT_COLUMNS = [\n \"underlying\",\n \"underlying_last\",\n \"optionroot\",\n \"type\",\n \"expiration\",\n \"quotedate\",\n \"strike\",\n \"last\",\n \"bid\",\n \"ask\",\n \"volume\",\n \"openinterest\",\n \"impliedvol\",\n \"delta\",\n \"gamma\",\n \"theta\",\n \"vega\",\n \"optionalias\",\n]\n\n\ndef make_optionroot(expire_dates, option_type, strikes):\n \"\"\"Generate OCC-format option root symbols vectorized.\n\n Format: SPX{YYMMDD}{C|P}{strike*1000:08d}\n Example: SPX170317C00300000\n \"\"\"\n date_str = expire_dates.dt.strftime(\"%y%m%d\")\n type_char = \"C\" if option_type == \"call\" else \"P\"\n strike_str = (strikes * 1000).astype(int).astype(str).str.zfill(8)\n return \"SPX\" + date_str + type_char + strike_str\n\n\ndef convert(input_path, output_path):\n df = pd.read_csv(input_path, parse_dates=[\"QUOTE_DATE\", \"EXPIRE_DATE\"])\n # Strip whitespace from column names (OptionsDX CSVs have trailing spaces)\n df.columns = df.columns.str.strip()\n\n shared = {\n \"underlying\": \"SPX\",\n \"underlying_last\": df[\"UNDERLYING_LAST\"],\n \"expiration\": df[\"EXPIRE_DATE\"],\n \"quotedate\": df[\"QUOTE_DATE\"],\n \"strike\": df[\"STRIKE\"],\n \"openinterest\": 0,\n }\n\n # Build call rows\n calls = pd.DataFrame(shared)\n calls[\"type\"] = \"call\"\n for src, dst in CALL_COLS.items():\n calls[dst] = df[src].values\n calls[\"optionroot\"] = make_optionroot(df[\"EXPIRE_DATE\"], \"call\", df[\"STRIKE\"])\n calls[\"optionalias\"] = calls[\"optionroot\"]\n\n # Build put rows\n puts = pd.DataFrame(shared)\n puts[\"type\"] = \"put\"\n for src, dst in PUT_COLS.items():\n puts[dst] = df[src].values\n puts[\"optionroot\"] = make_optionroot(df[\"EXPIRE_DATE\"], \"put\", df[\"STRIKE\"])\n puts[\"optionalias\"] = puts[\"optionroot\"]\n\n result = pd.concat([calls, puts], ignore_index=True)\n result = result[OUTPUT_COLUMNS]\n result = result.sort_values([\"quotedate\", \"expiration\", \"strike\", \"type\"])\n result.to_csv(output_path, index=False)\n print(f\"Wrote {len(result)} rows to {output_path}\")\n\n\ndef main():\n parser = argparse.ArgumentParser(\n description=\"Convert OptionsDX wide CSV to backtester long CSV\"\n )\n parser.add_argument(\"input\", help=\"Path to OptionsDX CSV file\")\n parser.add_argument(\n \"--output\",\n default=\"data/processed/spx_options.csv\",\n help=\"Output path (default: data/processed/spx_options.csv)\",\n )\n args = parser.parse_args()\n convert(args.input, args.output)\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "data/fetch_data.py",
"content": "#!/usr/bin/env python3\n\"\"\"Unified data fetch script for the options backtester.\n\nDownloads stock and options data, converts to backtester CSV formats,\nand aligns dates between datasets.\n\nDownload priority (for each symbol):\n 1. Self-hosted GitHub Release (lambdaclass/options_backtester data-v1)\n 2. philippdubach/options-data CDN — 104 symbols\n 3. philippdubach/options-dataset-hist — SPY/IWM/QQQ underlying prices\n 4. yfinance (last resort, stocks only)\n\nUsage:\n python data/fetch_data.py all --symbols SPY --start 2020-01-01 --end 2023-01-01\n python data/fetch_data.py stocks --symbols SPY --start 2020-01-01 --end 2023-01-01\n python data/fetch_data.py options --symbols SPY --start 2020-01-01 --end 2023-01-01\n python data/fetch_data.py all --symbols SPY --start 2020-01-01 --end 2023-01-01 --update\n\"\"\"\n\nimport argparse\nimport shutil\nimport sys\nfrom pathlib import Path\nfrom urllib.request import Request, urlopen\n\nimport pandas as pd\n\nBASE_DIR = Path(__file__).resolve().parent\nRAW_DIR = BASE_DIR / \"raw\"\nPROCESSED_DIR = BASE_DIR / \"processed\"\n\n# Self-hosted data on GitHub Releases (primary source)\nRELEASE_URL = \"https://github.com/lambdaclass/options_backtester/releases/download/data-v1\"\n\n# philippdubach/options-data — 104 symbols, options + underlying (underlying empty for some ETFs)\nOPTIONS_DATA_URL = \"https://static.philippdubach.com/data/options\"\n\n# philippdubach/options-dataset-hist — SPY/IWM/QQQ, proper underlying_prices via GitHub LFS\nHIST_REPO_RAW = \"https://github.com/philippdubach/options-dataset-hist/raw/main/data\"\nHIST_SYMBOLS = {\"SPY\", \"IWM\", \"QQQ\"}\n\n\n# ---------------------------------------------------------------------------\n# Download helpers\n# ---------------------------------------------------------------------------\n\ndef _download(url, dest, force=False):\n \"\"\"Download url to dest. Returns dest on success, None on failure.\"\"\"\n dest = Path(dest)\n dest.parent.mkdir(parents=True, exist_ok=True)\n\n if dest.exists() and not force:\n print(f\" Using cached {dest}\")\n return dest\n\n print(f\" Downloading {url} ...\")\n try:\n req = Request(url, headers={\"User-Agent\": \"options-backtester/1.0\"})\n with urlopen(req) as resp, open(dest, \"wb\") as f:\n shutil.copyfileobj(resp, f)\n print(f\" Saved to {dest}\")\n except Exception as e:\n print(f\" Error: {e}\", file=sys.stderr)\n if dest.exists():\n dest.unlink()\n return None\n return dest\n\n\ndef download_options_parquet(symbol, force=False):\n \"\"\"Download options parquet. Priority: GitHub Release > options-data CDN.\"\"\"\n sym = symbol.upper()\n\n # 1. Self-hosted GitHub Release\n dest = RAW_DIR / \"release\" / f\"{sym}_options.parquet\"\n url = f\"{RELEASE_URL}/{sym}_options.parquet\"\n result = _download(url, dest, force)\n if result is not None:\n return result\n\n # 2. options-data CDN\n dest = RAW_DIR / \"options-data\" / sym / \"options.parquet\"\n url = f\"{OPTIONS_DATA_URL}/{sym.lower()}/options.parquet\"\n return _download(url, dest, force)\n\n\ndef download_underlying(symbol, force=False):\n \"\"\"Download underlying prices.\n\n Priority: GitHub Release > options-dataset-hist > options-data > None (caller falls back to yfinance).\n \"\"\"\n sym = symbol.upper()\n\n # 1. Self-hosted GitHub Release\n dest = RAW_DIR / \"release\" / f\"{sym}_underlying.parquet\"\n url = f\"{RELEASE_URL}/{sym}_underlying.parquet\"\n result = _download(url, dest, force)\n if result is not None:\n df = pd.read_parquet(result)\n if not df.empty:\n return result\n print(f\" Warning: release underlying empty for {sym}\")\n\n # 2. options-dataset-hist has proper underlying for SPY/IWM/QQQ\n if sym in HIST_SYMBOLS:\n dest = RAW_DIR / \"options-dataset-hist\" / sym / \"underlying_prices.parquet\"\n url = f\"{HIST_REPO_RAW}/parquet_{sym.lower()}/underlying_prices.parquet\"\n result = _download(url, dest, force)\n if result is not None:\n df = pd.read_parquet(result)\n if not df.empty:\n return result\n print(f\" Warning: options-dataset-hist underlying empty for {sym}\")\n\n # 3. options-data underlying\n dest = RAW_DIR / \"options-data\" / sym / \"underlying.parquet\"\n url = f\"{OPTIONS_DATA_URL}/{sym.lower()}/underlying.parquet\"\n result = _download(url, dest, force)\n if result is not None:\n df = pd.read_parquet(result)\n if not df.empty:\n return result\n print(f\" Warning: options-data underlying empty for {sym}\")\n\n return None\n\n\n# ---------------------------------------------------------------------------\n# Underlying price reading\n# ---------------------------------------------------------------------------\n\ndef read_underlying_prices(symbol, und_path, start, end):\n \"\"\"Read underlying parquet and return (date, close) DataFrame for joining.\"\"\"\n und = pd.read_parquet(und_path)\n und[\"date\"] = pd.to_datetime(und[\"date\"])\n und = und[(und[\"date\"] >= start) & (und[\"date\"] <= end)]\n if und.empty:\n return None\n return und[[\"date\", \"close\"]].rename(columns={\"close\": \"underlying_last\"})\n\n\ndef underlying_to_tiingo(symbol, und_path, start, end):\n \"\"\"Convert an underlying.parquet to Tiingo-format DataFrame.\"\"\"\n und = pd.read_parquet(und_path)\n und[\"date\"] = pd.to_datetime(und[\"date\"])\n und = und[(und[\"date\"] >= start) & (und[\"date\"] <= end)]\n\n if und.empty:\n return pd.DataFrame()\n\n ratio = und[\"adjusted_close\"] / und[\"close\"]\n\n return pd.DataFrame({\n \"symbol\": symbol,\n \"date\": und[\"date\"].values,\n \"close\": und[\"close\"].values,\n \"high\": und[\"high\"].values,\n \"low\": und[\"low\"].values,\n \"open\": und[\"open\"].values,\n \"volume\": und[\"volume\"].values,\n \"adjClose\": und[\"adjusted_close\"].values,\n \"adjHigh\": (und[\"high\"] * ratio).values,\n \"adjLow\": (und[\"low\"] * ratio).values,\n \"adjOpen\": (und[\"open\"] * ratio).values,\n \"adjVolume\": und[\"volume\"].values,\n \"divCash\": und[\"dividend_amount\"].values,\n \"splitFactor\": und[\"split_coefficient\"].values,\n })\n\n\ndef fetch_yfinance(symbol, start, end):\n \"\"\"Fetch one symbol via yfinance (last resort).\"\"\"\n try:\n import yfinance as yf\n except ImportError:\n print(f\" yfinance not installed, cannot fetch {symbol}\", file=sys.stderr)\n return pd.DataFrame()\n\n print(f\" Last resort: fetching {symbol} from yfinance...\")\n ticker = yf.Ticker(symbol)\n df = ticker.history(start=str(start.date()), end=str(end.date()), auto_adjust=False)\n\n if df.empty:\n return pd.DataFrame()\n\n if df.index.tz is not None:\n df.index = df.index.tz_localize(None)\n\n ratio = df[\"Adj Close\"] / df[\"Close\"]\n\n return pd.DataFrame({\n \"symbol\": symbol,\n \"date\": df.index,\n \"close\": df[\"Close\"].values,\n \"high\": df[\"High\"].values,\n \"low\": df[\"Low\"].values,\n \"open\": df[\"Open\"].values,\n \"volume\": df[\"Volume\"].values,\n \"adjClose\": df[\"Adj Close\"].values,\n \"adjHigh\": (df[\"High\"] * ratio).values,\n \"adjLow\": (df[\"Low\"] * ratio).values,\n \"adjOpen\": (df[\"Open\"] * ratio).values,\n \"adjVolume\": df[\"Volume\"].values,\n \"divCash\": 0.0,\n \"splitFactor\": 1.0,\n })\n\n\n# ---------------------------------------------------------------------------\n# Options\n# ---------------------------------------------------------------------------\n\ndef fetch_options(symbols, start, end, output, force=False):\n \"\"\"Download options parquets and convert to backtester CSV format.\"\"\"\n frames = []\n\n for symbol in symbols:\n sym = symbol.upper()\n print(f\"Fetching options for {sym}...\")\n\n opt_path = download_options_parquet(sym, force)\n if opt_path is None:\n print(f\" Skipping {sym} options (download failed)\", file=sys.stderr)\n continue\n\n opts = pd.read_parquet(opt_path)\n opts[\"date\"] = pd.to_datetime(opts[\"date\"])\n opts = opts[(opts[\"date\"] >= start) & (opts[\"date\"] <= end)]\n\n if opts.empty:\n print(f\" No options data for {sym} in [{start}, {end}]\")\n continue\n\n # Get underlying close prices for underlying_last\n und_path = download_underlying(sym, force)\n und_prices = None\n if und_path is not None:\n und_prices = read_underlying_prices(sym, und_path, start, end)\n\n if und_prices is None:\n yf_df = fetch_yfinance(sym, start, end)\n if not yf_df.empty:\n und_prices = pd.DataFrame({\n \"date\": pd.to_datetime(yf_df[\"date\"]),\n \"underlying_last\": yf_df[\"close\"].values,\n })\n\n if und_prices is not None:\n opts = opts.merge(und_prices, on=\"date\", how=\"left\")\n else:\n opts[\"underlying_last\"] = float(\"nan\")\n\n # Last price: use column if present, else mid\n if \"last\" in opts.columns:\n opts[\"_last\"] = opts[\"last\"].fillna((opts[\"bid\"] + opts[\"ask\"]) / 2)\n else:\n opts[\"_last\"] = (opts[\"bid\"] + opts[\"ask\"]) / 2\n\n out = pd.DataFrame({\n \"underlying\": sym,\n \"underlying_last\": opts[\"underlying_last\"].values,\n \"optionroot\": opts[\"contract_id\"].values,\n \"type\": opts[\"type\"].values,\n \"expiration\": pd.to_datetime(opts[\"expiration\"]).values,\n \"quotedate\": opts[\"date\"].values,\n \"strike\": opts[\"strike\"].values,\n \"last\": opts[\"_last\"].values,\n \"bid\": opts[\"bid\"].values,\n \"ask\": opts[\"ask\"].values,\n \"volume\": opts[\"volume\"].values,\n \"openinterest\": opts[\"open_interest\"].values,\n \"impliedvol\": opts[\"implied_volatility\"].values,\n \"delta\": opts[\"delta\"].values,\n \"gamma\": opts[\"gamma\"].values,\n \"theta\": opts[\"theta\"].values,\n \"vega\": opts[\"vega\"].values,\n \"optionalias\": opts[\"contract_id\"].values,\n })\n frames.append(out)\n print(f\" {len(out)} option rows for {sym}\")\n\n if not frames:\n print(\"No options data fetched.\", file=sys.stderr)\n return None\n\n result = pd.concat(frames, ignore_index=True)\n result = result.sort_values([\"quotedate\", \"underlying\", \"expiration\", \"strike\", \"type\"])\n PROCESSED_DIR.mkdir(parents=True, exist_ok=True)\n result.to_csv(output, index=False)\n print(f\"Wrote {len(result)} option rows to {output}\")\n return result\n\n\n# ---------------------------------------------------------------------------\n# Stocks\n# ---------------------------------------------------------------------------\n\ndef fetch_stocks(symbols, start, end, output, force=False):\n \"\"\"Download stock data. Priority: options-dataset-hist > options-data > yfinance.\"\"\"\n frames = []\n\n for symbol in symbols:\n sym = symbol.upper()\n print(f\"Fetching stocks for {sym}...\")\n\n und_path = download_underlying(sym, force)\n if und_path is not None:\n df = underlying_to_tiingo(sym, und_path, start, end)\n if not df.empty:\n source = \"options-dataset-hist\" if \"options-dataset-hist\" in str(und_path) else \"options-data\"\n frames.append(df)\n print(f\" {len(df)} stock rows for {sym} (from {source})\")\n continue\n\n df = fetch_yfinance(sym, start, end)\n if not df.empty:\n frames.append(df)\n print(f\" {len(df)} stock rows for {sym} (from yfinance)\")\n else:\n print(f\" No stock data for {sym}\", file=sys.stderr)\n\n if not frames:\n print(\"No stock data fetched.\", file=sys.stderr)\n return None\n\n result = pd.concat(frames, ignore_index=True)\n PROCESSED_DIR.mkdir(parents=True, exist_ok=True)\n result.to_csv(output, index=False)\n print(f\"Wrote {len(result)} stock rows to {output}\")\n return result\n\n\n# ---------------------------------------------------------------------------\n# Date alignment\n# ---------------------------------------------------------------------------\n\ndef align_dates(stocks_path, options_path):\n \"\"\"Align stock and option dates to their intersection.\"\"\"\n stocks = pd.read_csv(stocks_path, parse_dates=[\"date\"])\n options = pd.read_csv(options_path, parse_dates=[\"quotedate\", \"expiration\"])\n\n stock_dates = set(stocks[\"date\"].dt.normalize())\n option_dates = set(options[\"quotedate\"].dt.normalize())\n shared = stock_dates & option_dates\n\n if not shared:\n print(\"Warning: no overlapping dates between stocks and options!\", file=sys.stderr)\n return\n\n stocks_filtered = stocks[stocks[\"date\"].dt.normalize().isin(shared)]\n options_filtered = options[options[\"quotedate\"].dt.normalize().isin(shared)]\n\n stocks_filtered.to_csv(stocks_path, index=False)\n options_filtered.to_csv(options_path, index=False)\n\n dropped_stock = len(stocks) - len(stocks_filtered)\n dropped_opt = len(options) - len(options_filtered)\n print(f\"Aligned dates: {len(shared)} shared trading days\")\n if dropped_stock:\n print(f\" Dropped {dropped_stock} stock rows without matching option dates\")\n if dropped_opt:\n print(f\" Dropped {dropped_opt} option rows without matching stock dates\")\n\n\n# ---------------------------------------------------------------------------\n# CLI\n# ---------------------------------------------------------------------------\n\ndef main():\n parser = argparse.ArgumentParser(\n description=\"Fetch stock and options data for the backtester\"\n )\n parser.add_argument(\n \"command\", nargs=\"?\", default=\"all\",\n choices=[\"all\", \"stocks\", \"options\"],\n help=\"What to fetch (default: all)\",\n )\n parser.add_argument(\n \"--symbols\", nargs=\"+\", required=True,\n help=\"Ticker symbols (e.g. SPY IWM QQQ AAPL)\",\n )\n parser.add_argument(\"--start\", required=True, help=\"Start date (YYYY-MM-DD)\")\n parser.add_argument(\"--end\", required=True, help=\"End date (YYYY-MM-DD)\")\n parser.add_argument(\n \"--stocks-output\", default=\"data/processed/stocks.csv\",\n help=\"Stock CSV output path\",\n )\n parser.add_argument(\n \"--options-output\", default=\"data/processed/options.csv\",\n help=\"Options CSV output path\",\n )\n parser.add_argument(\n \"--update\", action=\"store_true\",\n help=\"Re-download parquets to get latest data\",\n )\n args = parser.parse_args()\n\n start = pd.Timestamp(args.start)\n end = pd.Timestamp(args.end)\n force = args.update\n\n if args.command in (\"all\", \"options\"):\n fetch_options(args.symbols, start, end, args.options_output, force)\n\n if args.command in (\"all\", \"stocks\"):\n fetch_stocks(args.symbols, start, end, args.stocks_output, force)\n\n if args.command == \"all\":\n if Path(args.stocks_output).exists() and Path(args.options_output).exists():\n print(\"\\nAligning dates...\")\n align_dates(args.stocks_output, args.options_output)\n\n print(\"\\nDone!\")\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "data/fetch_signals.py",
"content": "#!/usr/bin/env python3\n\"\"\"Download macro signal data from FRED for use in backtest signal filters.\n\nDownloads:\n - GDP (quarterly) — for Buffett Indicator proxy\n - VIX (daily) — CBOE Volatility Index\n - High Yield Spread (daily) — credit stress indicator\n - 10Y-2Y Yield Curve (daily) — recession predictor\n - Nonfinancial Corporate Equity Market Value (quarterly) — for Tobin's Q\n - Nonfinancial Corporate Net Worth (quarterly) — for Tobin's Q\n - Dollar Index (daily) — broad trade-weighted USD\n\nOutputs:\n data/processed/signals.csv — daily signal data, forward-filled from quarterly\n\"\"\"\n\nimport io\nimport urllib.request\n\nimport pandas as pd\n\nFRED_SERIES = {\n 'gdp': 'GDP',\n 'vix': 'VIXCLS',\n 'hy_spread': 'BAMLH0A0HYM2',\n 'yield_curve_10y2y': 'T10Y2Y',\n 'nfc_equity_mv': 'NCBEILQ027S',\n 'nfc_net_worth': 'NCBCMDPMVCE',\n 'dollar_index': 'DTWEXBGS',\n}\n\nSTART = '2007-01-01'\nEND = '2025-12-31'\n\n\ndef fetch_fred(series_id: str) -> pd.Series:\n url = (f'https://fred.stlouisfed.org/graph/fredgraph.csv'\n f'?id={series_id}&cosd={START}&coed={END}')\n req = urllib.request.Request(url, headers={'User-Agent': 'Mozilla/5.0'})\n resp = urllib.request.urlopen(req, timeout=30)\n data = resp.read().decode()\n df = pd.read_csv(io.StringIO(data), parse_dates=['observation_date'],\n index_col='observation_date')\n col = df.columns[0]\n s = pd.to_numeric(df[col], errors='coerce')\n s.index.name = 'date'\n return s.dropna()\n\n\ndef main():\n signals = {}\n\n for name, sid in FRED_SERIES.items():\n print(f'Fetching {name} ({sid})...', end=' ', flush=True)\n try:\n s = fetch_fred(sid)\n signals[name] = s\n print(f'{len(s)} obs, {s.index[0].date()} to {s.index[-1].date()}')\n except Exception as e:\n print(f'FAILED: {e}')\n\n if not signals:\n print('No data fetched.')\n return\n\n # Build daily DataFrame\n all_dates = sorted(set().union(*(s.index for s in signals.values())))\n daily = pd.DataFrame(index=pd.DatetimeIndex(all_dates, name='date'))\n\n for name, s in signals.items():\n daily[name] = s.reindex(daily.index)\n\n # Forward-fill quarterly data to daily\n daily = daily.ffill()\n\n # Compute derived signals\n if 'gdp' in daily.columns:\n # Buffett Indicator proxy: we don't have total market cap, but\n # nfc_equity_mv is corporate equity market value (in millions)\n # GDP is in billions. Scale NFC equity to billions to match.\n if 'nfc_equity_mv' in daily.columns:\n daily['buffett_indicator'] = daily['nfc_equity_mv'] / (daily['gdp'] * 1000) * 100\n print(f'Computed buffett_indicator (nfc_equity_mv / GDP)')\n\n if 'nfc_equity_mv' in daily.columns and 'nfc_net_worth' in daily.columns:\n # Tobin's Q proxy: market value / net worth\n # nfc_net_worth is in weird units (ratio), use nfc_equity_mv levels\n # Actually NCBCMDPMVCE is \"market value / cost\" already\n daily['tobin_q'] = daily['nfc_net_worth']\n print(f'Computed tobin_q (NCBCMDPMVCE is already MV/replacement cost)')\n\n daily = daily.dropna(how='all')\n\n out = 'data/processed/signals.csv'\n daily.to_csv(out)\n print(f'\\nSaved {len(daily)} rows to {out}')\n print(f'Columns: {list(daily.columns)}')\n print(f'Date range: {daily.index[0].date()} to {daily.index[-1].date()}')\n print(daily.describe().round(2))\n\n\nif __name__ == '__main__':\n main()\n"
},
{
"path": "flake.nix",
"content": "{\n description = \"Options backtester dev environment\";\n\n inputs = {\n nixpkgs.url = \"github:NixOS/nixpkgs/nixpkgs-unstable\";\n rust-overlay.url = \"github:oxalica/rust-overlay\";\n };\n\n outputs = { self, nixpkgs, rust-overlay }:\n let\n supportedSystems = [ \"x86_64-linux\" \"aarch64-linux\" \"x86_64-darwin\" \"aarch64-darwin\" ];\n forAllSystems = nixpkgs.lib.genAttrs supportedSystems;\n in {\n devShells = forAllSystems (system:\n let\n pkgs = import nixpkgs {\n inherit system;\n overlays = [ rust-overlay.overlays.default ];\n };\n python = pkgs.python312;\n pythonPkgs = python.pkgs;\n rustToolchain = pkgs.rust-bin.stable.latest.default.override {\n extensions = [ \"rust-src\" \"rust-analyzer\" ];\n };\n in {\n default = pkgs.mkShell {\n packages = [\n # Rust\n rustToolchain\n pkgs.maturin\n pkgs.cargo-nextest\n\n (python.withPackages (ps: [\n # Runtime\n ps.pandas\n ps.numpy\n ps.altair\n ps.pyprind\n ps.seaborn\n ps.matplotlib\n ps.pyarrow\n ps.polars\n\n # Notebooks\n ps.jupyter\n ps.nbconvert\n ps.ipykernel\n\n # Testing\n ps.pytest\n ps.hypothesis\n ps.pytest-benchmark\n ps.mypy\n ps.pandas-stubs\n ps.ruff\n\n # Dev tools\n ps.yapf\n\n # Data fetching (optional, for data/ scripts)\n ps.yfinance\n ]))\n ];\n\n shellHook = ''\n export PYO3_PYTHON=${python}/bin/python\n export PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1\n\n # Build Rust extension and symlink for Python import\n if [ -f rust/ob_python/Cargo.toml ]; then\n if [ ! -f rust/target/release/lib_ob_rust.dylib ] && [ ! -f rust/target/release/lib_ob_rust.so ]; then\n echo \"Building Rust extension (first time only)...\"\n cargo build --manifest-path rust/ob_python/Cargo.toml --release 2>&1 | tail -1\n fi\n # Python needs _ob_rust.so, Rust produces lib_ob_rust.dylib/.so\n if [ -f rust/target/release/lib_ob_rust.dylib ] && [ ! -f _ob_rust.so ]; then\n ln -sf rust/target/release/lib_ob_rust.dylib _ob_rust.so\n elif [ -f rust/target/release/lib_ob_rust.so ] && [ ! -f _ob_rust.so ]; then\n ln -sf rust/target/release/lib_ob_rust.so _ob_rust.so\n fi\n fi\n '';\n };\n });\n };\n}\n"
},
{
"path": "options_portfolio_backtester/__init__.py",
"content": "\"\"\"options_portfolio_backtester — the open-source options backtesting framework.\"\"\"\n\n# Core types\nfrom options_portfolio_backtester.core.types import (\n Direction,\n OptionType,\n Type,\n Order,\n Signal,\n Fill,\n Greeks,\n OptionContract,\n StockAllocation,\n Stock,\n get_order,\n)\n\n# Data\nfrom options_portfolio_backtester.data.schema import Schema, Field, Filter\nfrom options_portfolio_backtester.data.providers import (\n CsvOptionsProvider, CsvStocksProvider,\n TiingoData, HistoricalOptionsData,\n)\n\n# Strategy\nfrom options_portfolio_backtester.strategy.strategy import Strategy\nfrom options_portfolio_backtester.strategy.strategy_leg import StrategyLeg\nfrom options_portfolio_backtester.strategy.presets import Strangle\n\n# Execution\nfrom options_portfolio_backtester.execution.cost_model import (\n NoCosts, PerContractCommission, TieredCommission, SpreadSlippage,\n)\nfrom options_portfolio_backtester.execution.fill_model import MarketAtBidAsk, MidPrice, VolumeAwareFill\nfrom options_portfolio_backtester.execution.sizer import (\n CapitalBased, FixedQuantity, FixedDollar, PercentOfPortfolio,\n)\nfrom options_portfolio_backtester.execution.signal_selector import (\n FirstMatch, NearestDelta, MaxOpenInterest,\n)\n\n# Portfolio\nfrom options_portfolio_backtester.portfolio.portfolio import Portfolio\nfrom options_portfolio_backtester.portfolio.position import OptionPosition\nfrom options_portfolio_backtester.portfolio.greeks import aggregate_greeks\nfrom options_portfolio_backtester.portfolio.risk import RiskManager, MaxDelta, MaxVega, MaxDrawdown\n\n# Engine\nfrom options_portfolio_backtester.engine.engine import BacktestEngine\nfrom options_portfolio_backtester.engine.clock import TradingClock\n\n# Analytics\nfrom options_portfolio_backtester.analytics.stats import BacktestStats, PeriodStats, LookbackReturns\nfrom options_portfolio_backtester.analytics.trade_log import TradeLog\nfrom options_portfolio_backtester.analytics.tearsheet import TearsheetReport, build_tearsheet\nfrom options_portfolio_backtester.analytics.summary import summary\n\n__all__ = [\n # Core types\n \"Direction\", \"OptionType\", \"Type\", \"Order\", \"Signal\", \"Fill\", \"Greeks\",\n \"OptionContract\", \"StockAllocation\", \"Stock\", \"get_order\",\n # Data\n \"Schema\", \"Field\", \"Filter\", \"CsvOptionsProvider\", \"CsvStocksProvider\",\n \"TiingoData\", \"HistoricalOptionsData\",\n # Strategy\n \"Strategy\", \"StrategyLeg\", \"Strangle\",\n # Execution\n \"NoCosts\", \"PerContractCommission\", \"TieredCommission\", \"SpreadSlippage\",\n \"MarketAtBidAsk\", \"MidPrice\", \"VolumeAwareFill\",\n \"CapitalBased\", \"FixedQuantity\", \"FixedDollar\", \"PercentOfPortfolio\",\n \"FirstMatch\", \"NearestDelta\", \"MaxOpenInterest\",\n # Portfolio\n \"Portfolio\", \"OptionPosition\", \"aggregate_greeks\",\n \"RiskManager\", \"MaxDelta\", \"MaxVega\", \"MaxDrawdown\",\n # Engine\n \"BacktestEngine\", \"TradingClock\",\n # Analytics\n \"BacktestStats\", \"PeriodStats\", \"LookbackReturns\",\n \"TradeLog\", \"TearsheetReport\", \"build_tearsheet\",\n \"summary\",\n]\n"
},
{
"path": "options_portfolio_backtester/analytics/__init__.py",
"content": ""
},
{
"path": "options_portfolio_backtester/analytics/charts.py",
"content": "\"\"\"Charts — Altair charts + matplotlib additions.\"\"\"\n\nfrom __future__ import annotations\n\nimport altair as alt\nimport pandas as pd\n\n\ndef returns_chart(report: pd.DataFrame) -> alt.VConcatChart:\n # Time interval selector\n time_interval = alt.selection_interval(encodings=['x'])\n\n # Area plot\n areas = alt.Chart().mark_area(opacity=0.7).encode(x='index:T',\n y=alt.Y('accumulated return:Q', axis=alt.Axis(format='%')))\n\n # Nearest point selector\n nearest = alt.selection_point(nearest=True, on='mouseover', fields=['index'])\n\n points = areas.mark_point().encode(opacity=alt.condition(nearest, alt.value(1), alt.value(0)))\n\n # Transparent date selector\n selectors = alt.Chart().mark_point().encode(\n x='index:T',\n opacity=alt.value(0),\n ).add_params(nearest)\n\n text = areas.mark_text(\n align='left', dx=5,\n dy=-5).encode(text=alt.condition(nearest, 'accumulated return:Q', alt.value(' '), format='.2%'))\n\n layered = alt.layer(selectors,\n points,\n text,\n areas.encode(\n alt.X('index:T', axis=alt.Axis(title='date'), scale=alt.Scale(domain=time_interval))),\n width=700,\n height=350,\n title='Returns over time')\n\n lower = areas.properties(width=700, height=70).add_params(time_interval)\n\n return alt.vconcat(layered, lower, data=report.reset_index())\n\n\ndef returns_histogram(report: pd.DataFrame) -> alt.Chart:\n bar = alt.Chart(report).mark_bar().encode(x=alt.X('% change:Q',\n bin=alt.BinParams(maxbins=100),\n axis=alt.Axis(format='%')),\n y='count():Q')\n return bar\n\n\ndef monthly_returns_heatmap(report: pd.DataFrame) -> alt.Chart:\n resample = report.resample('ME')['total capital'].last()\n monthly_returns = resample.pct_change().reset_index()\n monthly_returns.loc[monthly_returns.index[0], 'total capital'] = resample.iloc[0] / report.iloc[0]['total capital'] - 1\n monthly_returns.columns = ['date', 'total capital']\n\n chart = alt.Chart(monthly_returns).mark_rect().encode(\n alt.X('year(date):O', title='Year'), alt.Y('month(date):O', title='Month'),\n alt.Color('mean(total capital)', title='Return', scale=alt.Scale(scheme='redyellowgreen')),\n alt.Tooltip('mean(total capital)', format='.2f')).properties(title='Monthly Returns')\n\n return chart\n\n\ndef weights_chart(balance: pd.DataFrame, figsize: tuple[float, float] = (12, 6)):\n \"\"\"Stacked area chart of portfolio weights over time.\n\n Expects a balance DataFrame with ``{symbol} qty`` columns and a\n ``total capital`` column (as produced by ``AlgoPipelineBacktester``).\n\n Returns ``(fig, ax)`` from matplotlib.\n \"\"\"\n import matplotlib.pyplot as plt\n\n qty_cols = [c for c in balance.columns if c.endswith(\" qty\")]\n if not qty_cols:\n fig, ax = plt.subplots(figsize=figsize)\n ax.set_title(\"Portfolio Weights (no positions found)\")\n return fig, ax\n\n symbols = [c.replace(\" qty\", \"\") for c in qty_cols]\n total = balance[\"total capital\"]\n\n # Compute weights: qty * price / total_capital\n # We don't have price columns directly, but stocks capital is available.\n # Reconstruct per-symbol value: qty * (total - cash) is aggregate,\n # so we estimate from qty shares of total stock value.\n weights = pd.DataFrame(index=balance.index)\n for sym, col in zip(symbols, qty_cols):\n weights[sym] = balance[col].fillna(0)\n\n # Normalize to weights (proportional share of total qty-weighted value)\n row_sums = weights.abs().sum(axis=1)\n row_sums = row_sums.replace(0, 1) # avoid division by zero\n # If we have cash and total capital, use stock fraction\n if \"cash\" in balance.columns:\n stock_fraction = 1.0 - balance[\"cash\"] / total.replace(0, 1)\n for sym in symbols:\n weights[sym] = (weights[sym] / row_sums) * stock_fraction\n else:\n weights = weights.div(row_sums, axis=0)\n\n fig, ax = plt.subplots(figsize=figsize)\n ax.stackplot(weights.index, *[weights[s] for s in symbols], labels=symbols, alpha=0.8)\n ax.set_title(\"Portfolio Weights Over Time\")\n ax.set_ylabel(\"Weight\")\n ax.set_xlabel(\"Date\")\n ax.legend(loc=\"upper left\", fontsize=\"small\")\n ax.set_ylim(0, 1)\n fig.tight_layout()\n return fig, ax\n\n\n__all__ = [\"returns_chart\", \"returns_histogram\", \"monthly_returns_heatmap\", \"weights_chart\"]\n"
},
{
"path": "options_portfolio_backtester/analytics/optimization.py",
"content": "\"\"\"Walk-forward optimization and parameter grid sweep.\"\"\"\n\nfrom __future__ import annotations\n\nimport itertools\nfrom concurrent.futures import ProcessPoolExecutor, as_completed\nfrom dataclasses import dataclass\nfrom typing import Any, Callable\n\nimport pandas as pd\nimport numpy as np\n\nfrom options_portfolio_backtester.analytics.stats import BacktestStats\n\n\n@dataclass\nclass OptimizationResult:\n \"\"\"Result of a single parameter combination.\"\"\"\n params: dict[str, Any]\n stats: BacktestStats\n balance: pd.DataFrame\n\n\ndef grid_sweep(\n run_fn: Callable[..., tuple[BacktestStats, pd.DataFrame]],\n param_grid: dict[str, list[Any]],\n max_workers: int | None = None,\n) -> list[OptimizationResult]:\n \"\"\"Run a parameter grid sweep using parallel execution.\n\n Args:\n run_fn: Function that takes **params and returns (BacktestStats, balance).\n param_grid: Dict mapping parameter names to lists of values.\n max_workers: Number of parallel workers (None = CPU count).\n\n Returns:\n List of OptimizationResult, sorted by Sharpe ratio descending.\n \"\"\"\n keys = list(param_grid.keys())\n combos = list(itertools.product(*param_grid.values()))\n results: list[OptimizationResult] = []\n\n with ProcessPoolExecutor(max_workers=max_workers) as executor:\n futures = {}\n for combo in combos:\n params = dict(zip(keys, combo))\n future = executor.submit(run_fn, **params)\n futures[future] = params\n\n for future in as_completed(futures):\n params = futures[future]\n try:\n stats, balance = future.result()\n results.append(OptimizationResult(\n params=params, stats=stats, balance=balance,\n ))\n except Exception:\n continue\n\n results.sort(key=lambda r: r.stats.sharpe_ratio, reverse=True)\n return results\n\n\ndef walk_forward(\n run_fn: Callable[[pd.Timestamp, pd.Timestamp], tuple[BacktestStats, pd.DataFrame]],\n dates: pd.DatetimeIndex,\n in_sample_pct: float = 0.70,\n n_splits: int = 5,\n) -> list[tuple[OptimizationResult, OptimizationResult]]:\n \"\"\"Walk-forward analysis with rolling in-sample/out-of-sample splits.\n\n Args:\n run_fn: Function that takes (start_date, end_date) and returns (stats, balance).\n dates: Full date range.\n in_sample_pct: Fraction of each window used for in-sample.\n n_splits: Number of walk-forward windows.\n\n Returns:\n List of (in_sample_result, out_of_sample_result) tuples.\n \"\"\"\n total = len(dates)\n window_size = total // n_splits\n results = []\n\n for i in range(n_splits):\n start_idx = i * window_size\n end_idx = min(start_idx + window_size, total)\n split_idx = start_idx + int((end_idx - start_idx) * in_sample_pct)\n\n is_start = dates[start_idx]\n is_end = dates[split_idx - 1]\n oos_start = dates[split_idx]\n oos_end = dates[end_idx - 1]\n\n try:\n is_stats, is_balance = run_fn(is_start, is_end)\n oos_stats, oos_balance = run_fn(oos_start, oos_end)\n results.append((\n OptimizationResult(params={\"split\": i, \"type\": \"in_sample\"},\n stats=is_stats, balance=is_balance),\n OptimizationResult(params={\"split\": i, \"type\": \"out_of_sample\"},\n stats=oos_stats, balance=oos_balance),\n ))\n except Exception:\n continue\n\n return results\n\n\ndef rust_grid_sweep(\n options_data,\n stocks_data,\n base_config: dict,\n schema_mapping: dict,\n param_overrides: list[dict],\n n_workers: int | None = None,\n) -> list[dict]:\n \"\"\"Run a parallel grid sweep using the Rust backtest engine.\n\n Each dict in param_overrides can contain:\n - \"label\": str\n - \"profit_pct\": Optional[float]\n - \"loss_pct\": Optional[float]\n - \"rebalance_dates\": Optional[list[str]]\n - \"leg_entry_filters\": Optional[list[Optional[str]]]\n - \"leg_exit_filters\": Optional[list[Optional[str]]]\n\n Returns list of result dicts sorted by sharpe_ratio descending.\n \"\"\"\n from options_portfolio_backtester._ob_rust import parallel_sweep\n\n results = parallel_sweep(\n options_data, stocks_data,\n base_config, schema_mapping,\n param_overrides, n_workers,\n )\n results.sort(key=lambda r: r.get(\"sharpe_ratio\", 0.0), reverse=True)\n return results\n"
},
{
"path": "options_portfolio_backtester/analytics/stats.py",
"content": "\"\"\"BacktestStats — comprehensive analytics matching and exceeding bt/ffn.\n\nProvides:\n- Trade stats: profit factor, win rate, largest win/loss\n- Return stats: total, annualized, Sharpe, Sortino, Calmar\n- Risk stats: max drawdown, drawdown duration, volatility, tail ratio\n- Period stats: monthly/yearly Sharpe, Sortino, mean, vol, skew, kurtosis\n- Extreme analysis: best/worst day, month, year\n- Lookback returns: MTD, 3M, 6M, YTD, 1Y, 3Y, 5Y, 10Y\n- Portfolio metrics: turnover, Herfindahl concentration index\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom dataclasses import dataclass, field\nfrom typing import Any\n\nimport numpy as np\nimport pandas as pd\n\nfrom options_portfolio_backtester._ob_rust import compute_full_stats\n\n\n@dataclass\nclass PeriodStats:\n \"\"\"Stats for a specific return frequency (daily, monthly, yearly).\"\"\"\n mean: float = 0.0\n vol: float = 0.0\n sharpe: float = 0.0\n sortino: float = 0.0\n skew: float = 0.0\n kurtosis: float = 0.0\n best: float = 0.0\n worst: float = 0.0\n\n\n@dataclass\nclass LookbackReturns:\n \"\"\"Trailing period returns as of the end date.\"\"\"\n mtd: float | None = None\n three_month: float | None = None\n six_month: float | None = None\n ytd: float | None = None\n one_year: float | None = None\n three_year: float | None = None\n five_year: float | None = None\n ten_year: float | None = None\n\n\n@dataclass\nclass BacktestStats:\n \"\"\"Comprehensive backtest statistics.\"\"\"\n\n # Trade stats\n total_trades: int = 0\n wins: int = 0\n losses: int = 0\n win_pct: float = 0.0\n profit_factor: float = 0.0\n largest_win: float = 0.0\n largest_loss: float = 0.0\n avg_win: float = 0.0\n avg_loss: float = 0.0\n avg_trade: float = 0.0\n\n # Return stats\n total_return: float = 0.0\n annualized_return: float = 0.0\n sharpe_ratio: float = 0.0\n sortino_ratio: float = 0.0\n calmar_ratio: float = 0.0\n\n # Risk stats\n max_drawdown: float = 0.0\n max_drawdown_duration: int = 0\n avg_drawdown: float = 0.0\n avg_drawdown_duration: int = 0\n volatility: float = 0.0\n tail_ratio: float = 0.0\n\n # Period stats\n daily: PeriodStats = field(default_factory=PeriodStats)\n monthly: PeriodStats = field(default_factory=PeriodStats)\n yearly: PeriodStats = field(default_factory=PeriodStats)\n\n # Lookback\n lookback: LookbackReturns = field(default_factory=LookbackReturns)\n\n # Portfolio metrics\n turnover: float = 0.0\n herfindahl: float = 0.0\n\n @classmethod\n def from_balance_range(\n cls,\n balance: pd.DataFrame,\n start: str | pd.Timestamp | None = None,\n end: str | pd.Timestamp | None = None,\n **kwargs,\n ) -> \"BacktestStats\":\n \"\"\"Slice balance to [start, end] and recompute all stats.\"\"\"\n if balance.empty:\n return cls()\n b = balance.copy()\n if start:\n b = b.loc[pd.Timestamp(start):]\n if end:\n b = b.loc[:pd.Timestamp(end)]\n if b.empty:\n return cls()\n b[\"% change\"] = b[\"total capital\"].pct_change()\n return cls.from_balance(b, **kwargs)\n\n @classmethod\n def from_balance(\n cls,\n balance: pd.DataFrame,\n trade_pnls: np.ndarray | None = None,\n risk_free_rate: float = 0.0,\n ) -> \"BacktestStats\":\n \"\"\"Compute stats from a balance DataFrame and optional trade P&Ls.\"\"\"\n if balance.empty:\n return cls()\n\n total_capital = balance[\"total capital\"].values.astype(np.float64)\n timestamps_ns = balance.index.values.astype(\"datetime64[ns]\").view(\"int64\").astype(np.int64).tolist()\n pnls = trade_pnls.astype(np.float64).tolist() if trade_pnls is not None else []\n\n # Build stock weight matrix\n stock_cols = [c for c in balance.columns if f\"{c} qty\" in balance.columns]\n if stock_cols:\n total = balance[\"total capital\"].values\n with np.errstate(divide=\"ignore\", invalid=\"ignore\"):\n weights = balance[stock_cols].values / total[:, None]\n weights = np.nan_to_num(weights, 0.0).astype(np.float64)\n flat_weights = weights.ravel().tolist()\n n_stocks = len(stock_cols)\n else:\n flat_weights = []\n n_stocks = 0\n\n d = compute_full_stats(\n total_capital.tolist(),\n timestamps_ns,\n pnls,\n flat_weights,\n n_stocks,\n risk_free_rate,\n )\n\n stats = cls()\n # Scalars\n for attr in (\n \"total_trades\", \"wins\", \"losses\", \"win_pct\", \"profit_factor\",\n \"largest_win\", \"largest_loss\", \"avg_win\", \"avg_loss\", \"avg_trade\",\n \"total_return\", \"annualized_return\", \"sharpe_ratio\", \"sortino_ratio\",\n \"calmar_ratio\", \"max_drawdown\", \"max_drawdown_duration\",\n \"avg_drawdown\", \"avg_drawdown_duration\", \"volatility\", \"tail_ratio\",\n \"turnover\", \"herfindahl\",\n ):\n setattr(stats, attr, d[attr])\n\n # Period stats\n for period_name in (\"daily\", \"monthly\", \"yearly\"):\n pd_dict = d[period_name]\n setattr(stats, period_name, PeriodStats(\n mean=pd_dict[\"mean\"], vol=pd_dict[\"vol\"],\n sharpe=pd_dict[\"sharpe\"], sortino=pd_dict[\"sortino\"],\n skew=pd_dict[\"skew\"], kurtosis=pd_dict[\"kurtosis\"],\n best=pd_dict[\"best\"], worst=pd_dict[\"worst\"],\n ))\n\n # Lookback\n lb = d[\"lookback\"]\n stats.lookback = LookbackReturns(\n mtd=lb[\"mtd\"], three_month=lb[\"three_month\"],\n six_month=lb[\"six_month\"], ytd=lb[\"ytd\"],\n one_year=lb[\"one_year\"], three_year=lb[\"three_year\"],\n five_year=lb[\"five_year\"], ten_year=lb[\"ten_year\"],\n )\n\n return stats\n\n def to_dataframe(self) -> pd.DataFrame:\n \"\"\"Return stats as a styled DataFrame.\"\"\"\n data = {\n \"Total trades\": self.total_trades,\n \"Wins\": self.wins,\n \"Losses\": self.losses,\n \"Win %\": self.win_pct,\n \"Profit factor\": self.profit_factor,\n \"Largest win\": self.largest_win,\n \"Largest loss\": self.largest_loss,\n \"Avg win\": self.avg_win,\n \"Avg loss\": self.avg_loss,\n \"Avg trade\": self.avg_trade,\n \"Total return\": self.total_return,\n \"Annualized return\": self.annualized_return,\n \"Sharpe ratio\": self.sharpe_ratio,\n \"Sortino ratio\": self.sortino_ratio,\n \"Calmar ratio\": self.calmar_ratio,\n \"Max drawdown\": self.max_drawdown,\n \"Max DD duration (days)\": self.max_drawdown_duration,\n \"Avg drawdown\": self.avg_drawdown,\n \"Avg DD duration (days)\": self.avg_drawdown_duration,\n \"Volatility\": self.volatility,\n \"Tail ratio\": self.tail_ratio,\n # Daily\n \"Daily mean\": self.daily.mean,\n \"Daily vol\": self.daily.vol,\n \"Daily Sharpe\": self.daily.sharpe,\n \"Daily Sortino\": self.daily.sortino,\n \"Daily skew\": self.daily.skew,\n \"Daily kurtosis\": self.daily.kurtosis,\n \"Best day\": self.daily.best,\n \"Worst day\": self.daily.worst,\n # Monthly\n \"Monthly mean\": self.monthly.mean,\n \"Monthly vol\": self.monthly.vol,\n \"Monthly Sharpe\": self.monthly.sharpe,\n \"Monthly Sortino\": self.monthly.sortino,\n \"Monthly skew\": self.monthly.skew,\n \"Monthly kurtosis\": self.monthly.kurtosis,\n \"Best month\": self.monthly.best,\n \"Worst month\": self.monthly.worst,\n # Yearly\n \"Yearly mean\": self.yearly.mean,\n \"Yearly vol\": self.yearly.vol,\n \"Yearly Sharpe\": self.yearly.sharpe,\n \"Yearly Sortino\": self.yearly.sortino,\n \"Best year\": self.yearly.best,\n \"Worst year\": self.yearly.worst,\n # Portfolio\n \"Turnover\": self.turnover,\n \"Herfindahl index\": self.herfindahl,\n }\n # Add lookback returns (skip None values)\n lb = self.lookback\n for label, val in [\n (\"MTD\", lb.mtd), (\"3M return\", lb.three_month),\n (\"6M return\", lb.six_month), (\"YTD\", lb.ytd),\n (\"1Y return\", lb.one_year), (\"3Y return\", lb.three_year),\n (\"5Y return\", lb.five_year), (\"10Y return\", lb.ten_year),\n ]:\n if val is not None:\n data[label] = val\n\n return pd.DataFrame(\n list(data.values()), index=list(data.keys()), columns=[\"Value\"]\n )\n\n def summary(self) -> str:\n \"\"\"Return a formatted text summary.\"\"\"\n lines = [\n f\"Total Return: {self.total_return:>10.2%}\",\n f\"Annualized Return: {self.annualized_return:>10.2%}\",\n f\"Sharpe Ratio: {self.sharpe_ratio:>10.2f}\",\n f\"Sortino Ratio: {self.sortino_ratio:>10.2f}\",\n f\"Max Drawdown: {self.max_drawdown:>10.2%}\",\n f\"Max DD Duration: {self.max_drawdown_duration:>10d} days\",\n f\"Calmar Ratio: {self.calmar_ratio:>10.2f}\",\n f\"Profit Factor: {self.profit_factor:>10.2f}\",\n f\"Win Rate: {self.win_pct:>10.1f}%\",\n f\"Total Trades: {self.total_trades:>10d}\",\n ]\n if self.monthly.sharpe != 0:\n lines.append(f\"Monthly Sharpe: {self.monthly.sharpe:>10.2f}\")\n if self.monthly.best != 0:\n lines.append(f\"Best Month: {self.monthly.best:>10.2%}\")\n lines.append(f\"Worst Month: {self.monthly.worst:>10.2%}\")\n if self.turnover != 0:\n lines.append(f\"Turnover: {self.turnover:>10.2%}\")\n return \"\\n\".join(lines)\n\n def lookback_table(self) -> pd.DataFrame:\n \"\"\"Lookback returns as a single-row DataFrame.\"\"\"\n lb = self.lookback\n data = {}\n for label, val in [\n (\"MTD\", lb.mtd), (\"3M\", lb.three_month), (\"6M\", lb.six_month),\n (\"YTD\", lb.ytd), (\"1Y\", lb.one_year), (\"3Y\", lb.three_year),\n (\"5Y\", lb.five_year), (\"10Y\", lb.ten_year),\n ]:\n if val is not None:\n data[label] = val\n if not data:\n return pd.DataFrame()\n return pd.DataFrame([data])\n"
},
{
"path": "options_portfolio_backtester/analytics/summary.py",
"content": "\"\"\"Summary statistics for trade logs.\"\"\"\n\nfrom __future__ import annotations\n\nimport numpy as np\nimport pandas as pd\n\nfrom options_portfolio_backtester.core.types import Order\n\n\ndef summary(trade_log: pd.DataFrame, balance: pd.DataFrame) -> pd.io.formats.style.Styler:\n \"\"\"Returns a table with summary statistics about the trade log\"\"\"\n\n initial_capital: float = balance['total capital'].iloc[0]\n trade_log.loc[:,\n ('totals',\n 'capital')] = (-trade_log['totals']['cost'] * trade_log['totals']['qty']).cumsum() + initial_capital\n\n daily_returns: pd.Series = balance['% change'] * 100\n\n first_leg: str = trade_log.columns.levels[0][0]\n\n ## Not sure of a better way to to this, just doing `Order` or `@Order` inside\n ## the .eval(...) does not seem to work.\n order_bto = Order.BTO\n order_sto = Order.STO\n\n entry_mask: pd.Series = trade_log[first_leg].eval('(order == @order_bto) | (order == @order_sto)')\n entries: pd.DataFrame = trade_log.loc[entry_mask]\n exits: pd.DataFrame = trade_log.loc[~entry_mask]\n\n costs: np.ndarray = np.array([])\n for contract in entries[first_leg]['contract']:\n entry = entries.loc[entries[first_leg]['contract'] == contract]\n exit_ = exits.loc[exits[first_leg]['contract'] == contract]\n try:\n # Here we assume we are entering only once per contract (i.e both entry and exit_ have only one row)\n costs = np.append(costs, (entry['totals']['cost'] * entry['totals']['qty']).values[0] +\n (exit_['totals']['cost'] * exit_['totals']['qty']).values[0])\n except IndexError:\n continue\n\n wins: np.ndarray = costs < 0\n losses: np.ndarray = costs >= 0\n total_trades: int = len(exits)\n win_number: int = int(np.sum(wins))\n loss_number: int = total_trades - win_number\n win_pct: float = (win_number / total_trades) * 100 if total_trades > 0 else 0\n profit_factor: float = np.sum(wins) / np.sum(losses) if np.sum(losses) > 0 else 0\n largest_loss: float = max(0, np.max(costs)) if len(costs) > 0 else 0\n avg_profit: float = np.mean(-costs) if len(costs) > 0 else 0\n avg_pl: float = np.mean(daily_returns)\n total_pl: float = (trade_log['totals']['capital'].iloc[-1] / initial_capital) * 100\n\n data = [total_trades, win_number, loss_number, win_pct, largest_loss, profit_factor, avg_profit, avg_pl, total_pl]\n stats = [\n 'Total trades', 'Number of wins', 'Number of losses', 'Win %', 'Largest loss', 'Profit factor',\n 'Average profit', 'Average P&L %', 'Total P&L %'\n ]\n strat = ['Strategy']\n summary_df = pd.DataFrame(data, stats, strat)\n\n formatters: dict[str, str] = {\n \"Total trades\": \"{:.0f}\",\n \"Number of wins\": \"{:.0f}\",\n \"Number of losses\": \"{:.0f}\",\n \"Win %\": \"{:.2f}%\",\n \"Largest loss\": \"${:.2f}\",\n \"Profit factor\": \"{:.2f}\",\n \"Average profit\": \"${:.2f}\",\n \"Average P&L %\": \"{:.2f}%\",\n \"Total P&L %\": \"{:.2f}%\"\n }\n\n styled = summary_df.style\n for row_label, fmt in formatters.items():\n styled = styled.format(fmt, subset=pd.IndexSlice[row_label, :])\n return styled\n"
},
{
"path": "options_portfolio_backtester/analytics/tearsheet.py",
"content": "\"\"\"Simple tearsheet-style report helpers.\"\"\"\n\nfrom __future__ import annotations\n\nfrom dataclasses import dataclass\nfrom pathlib import Path\n\nimport numpy as np\nimport pandas as pd\n\nfrom options_portfolio_backtester.analytics.stats import BacktestStats\n\n\n@dataclass\nclass TearsheetReport:\n \"\"\"Container for common report artifacts.\"\"\"\n\n stats: BacktestStats\n stats_table: pd.DataFrame\n monthly_returns: pd.DataFrame\n drawdown_series: pd.Series\n\n def to_dict(self) -> dict[str, object]:\n return {\n \"stats\": self.stats,\n \"stats_table\": self.stats_table,\n \"monthly_returns\": self.monthly_returns,\n \"drawdown_series\": self.drawdown_series,\n }\n\n def to_csv(self, directory: str | Path) -> dict[str, Path]:\n out_dir = Path(directory)\n out_dir.mkdir(parents=True, exist_ok=True)\n stats_path = out_dir / \"stats_table.csv\"\n monthly_path = out_dir / \"monthly_returns.csv\"\n drawdown_path = out_dir / \"drawdown_series.csv\"\n self.stats_table.to_csv(stats_path)\n self.monthly_returns.to_csv(monthly_path)\n self.drawdown_series.rename(\"drawdown\").to_frame().to_csv(drawdown_path)\n return {\n \"stats_table\": stats_path,\n \"monthly_returns\": monthly_path,\n \"drawdown_series\": drawdown_path,\n }\n\n def to_markdown(self) -> str:\n lines = [\"# Tearsheet\", \"\", \"## Summary\", \"\"]\n try:\n lines.extend(self.stats_table.to_markdown().splitlines())\n except Exception:\n lines.extend(self.stats_table.to_string().splitlines())\n lines.extend([\"\", \"## Monthly Returns\", \"\"])\n if self.monthly_returns.empty:\n lines.append(\"_No monthly returns available._\")\n else:\n try:\n lines.extend(self.monthly_returns.to_markdown().splitlines())\n except Exception:\n lines.extend(self.monthly_returns.to_string().splitlines())\n return \"\\n\".join(lines)\n\n def to_html(self) -> str:\n summary = self.stats_table.to_html(classes=\"stats-table\")\n monthly = (\n self.monthly_returns.to_html(classes=\"monthly-returns\")\n if not self.monthly_returns.empty\n else \"No monthly returns available.
\"\n )\n return (\n \"Tearsheet\"\n \"Tearsheet
\"\n \"Summary
\"\n f\"{summary}\"\n \"Monthly Returns
\"\n f\"{monthly}\"\n \"\"\n )\n\n\ndef monthly_return_table(balance: pd.DataFrame) -> pd.DataFrame:\n if balance.empty or \"% change\" not in balance.columns:\n return pd.DataFrame()\n rets = balance[\"% change\"].dropna()\n if rets.empty:\n return pd.DataFrame()\n monthly = (1.0 + rets).groupby(pd.Grouper(freq=\"ME\")).prod() - 1.0\n out = monthly.to_frame(name=\"return\")\n out[\"year\"] = out.index.year\n out[\"month\"] = out.index.month\n return out.pivot(index=\"year\", columns=\"month\", values=\"return\").sort_index()\n\n\ndef drawdown_series(balance: pd.DataFrame) -> pd.Series:\n if balance.empty or \"total capital\" not in balance.columns:\n return pd.Series(dtype=float)\n total = balance[\"total capital\"].dropna()\n if total.empty:\n return pd.Series(dtype=float)\n peak = total.cummax()\n return (total - peak) / peak\n\n\ndef build_tearsheet(\n balance: pd.DataFrame,\n trade_pnls=None,\n risk_free_rate: float = 0.0,\n) -> TearsheetReport:\n trade_arr = None if trade_pnls is None else np.asarray(trade_pnls, dtype=float)\n stats = BacktestStats.from_balance(balance, trade_pnls=trade_arr, risk_free_rate=risk_free_rate)\n table = stats.to_dataframe()\n monthly = monthly_return_table(balance)\n dd = drawdown_series(balance)\n return TearsheetReport(\n stats=stats,\n stats_table=table,\n monthly_returns=monthly,\n drawdown_series=dd,\n )\n"
},
{
"path": "options_portfolio_backtester/analytics/trade_log.py",
"content": "\"\"\"Structured trade log — replaces MultiIndex trade log with per-trade P&L.\"\"\"\n\nfrom __future__ import annotations\n\nfrom dataclasses import dataclass, field\nfrom typing import Any\n\nimport pandas as pd\nimport numpy as np\n\nfrom options_portfolio_backtester.core.types import Order\n\n\n@dataclass\nclass Trade:\n \"\"\"A single round-trip trade (entry + exit).\"\"\"\n contract: str\n underlying: str\n option_type: str\n strike: float\n entry_date: Any\n exit_date: Any\n entry_price: float\n exit_price: float\n quantity: int\n shares_per_contract: int\n entry_order: Order\n exit_order: Order\n entry_commission: float = 0.0\n exit_commission: float = 0.0\n\n @property\n def gross_pnl(self) -> float:\n \"\"\"P&L before commissions.\"\"\"\n return (self.exit_price - self.entry_price) * self.quantity * self.shares_per_contract\n\n @property\n def net_pnl(self) -> float:\n \"\"\"P&L after commissions.\"\"\"\n return self.gross_pnl - self.entry_commission - self.exit_commission\n\n @property\n def return_pct(self) -> float:\n \"\"\"Return as percentage of entry cost.\"\"\"\n entry_cost = abs(self.entry_price * self.quantity * self.shares_per_contract)\n if entry_cost == 0:\n return 0.0\n return self.net_pnl / entry_cost\n\n\nclass TradeLog:\n \"\"\"Structured collection of round-trip trades with analysis methods.\"\"\"\n\n def __init__(self) -> None:\n self.trades: list[Trade] = []\n\n def add_trade(self, trade: Trade) -> None:\n self.trades.append(trade)\n\n @classmethod\n def from_legacy_trade_log(cls, trade_log: pd.DataFrame,\n shares_per_contract: int = 100) -> \"TradeLog\":\n \"\"\"Build a TradeLog from the legacy MultiIndex trade_log DataFrame.\"\"\"\n tl = cls()\n if trade_log.empty:\n return tl\n\n first_leg: str = trade_log.columns.levels[0][0]\n\n order_bto = Order.BTO\n order_sto = Order.STO\n entry_mask = trade_log[first_leg].eval(\n \"(order == @order_bto) | (order == @order_sto)\"\n )\n entries = trade_log.loc[entry_mask]\n exits = trade_log.loc[~entry_mask]\n\n for contract in entries[first_leg][\"contract\"]:\n entry = entries.loc[entries[first_leg][\"contract\"] == contract]\n exit_ = exits.loc[exits[first_leg][\"contract\"] == contract]\n if entry.empty or exit_.empty:\n continue\n try:\n e_row = entry.iloc[0]\n x_row = exit_.iloc[0]\n trade = Trade(\n contract=contract,\n underlying=e_row[first_leg][\"underlying\"],\n option_type=e_row[first_leg][\"type\"],\n strike=e_row[first_leg][\"strike\"],\n entry_date=e_row[\"totals\"][\"date\"],\n exit_date=x_row[\"totals\"][\"date\"],\n entry_price=abs(e_row[first_leg][\"cost\"]) / shares_per_contract,\n exit_price=abs(x_row[first_leg][\"cost\"]) / shares_per_contract,\n quantity=int(e_row[\"totals\"][\"qty\"]),\n shares_per_contract=shares_per_contract,\n entry_order=e_row[first_leg][\"order\"],\n exit_order=x_row[first_leg][\"order\"],\n )\n tl.add_trade(trade)\n except (IndexError, KeyError):\n continue\n\n return tl\n\n def to_dataframe(self) -> pd.DataFrame:\n \"\"\"Convert to a flat DataFrame for analysis.\"\"\"\n if not self.trades:\n return pd.DataFrame()\n rows = []\n for t in self.trades:\n rows.append({\n \"contract\": t.contract,\n \"underlying\": t.underlying,\n \"type\": t.option_type,\n \"strike\": t.strike,\n \"entry_date\": t.entry_date,\n \"exit_date\": t.exit_date,\n \"entry_price\": t.entry_price,\n \"exit_price\": t.exit_price,\n \"quantity\": t.quantity,\n \"gross_pnl\": t.gross_pnl,\n \"net_pnl\": t.net_pnl,\n \"return_pct\": t.return_pct,\n \"entry_commission\": t.entry_commission,\n \"exit_commission\": t.exit_commission,\n })\n return pd.DataFrame(rows)\n\n @property\n def net_pnls(self) -> np.ndarray:\n return np.array([t.net_pnl for t in self.trades])\n\n @property\n def winners(self) -> list[Trade]:\n return [t for t in self.trades if t.net_pnl > 0]\n\n @property\n def losers(self) -> list[Trade]:\n return [t for t in self.trades if t.net_pnl <= 0]\n\n def __len__(self) -> int:\n return len(self.trades)\n"
},
{
"path": "options_portfolio_backtester/convexity/__init__.py",
"content": "\"\"\"Convexity scanner: cross-asset tail protection scoring and allocation.\"\"\"\n\nfrom options_portfolio_backtester.convexity.allocator import (\n allocate_equal_weight,\n allocate_inverse_vol,\n pick_cheapest,\n)\nfrom options_portfolio_backtester.convexity.backtest import (\n BacktestResult,\n run_backtest,\n run_unhedged,\n)\nfrom options_portfolio_backtester.convexity.config import (\n BacktestConfig,\n InstrumentConfig,\n default_config,\n)\nfrom options_portfolio_backtester.convexity.scoring import compute_convexity_scores\n\n__all__ = [\n \"InstrumentConfig\",\n \"BacktestConfig\",\n \"default_config\",\n \"compute_convexity_scores\",\n \"BacktestResult\",\n \"run_backtest\",\n \"run_unhedged\",\n \"pick_cheapest\",\n \"allocate_equal_weight\",\n \"allocate_inverse_vol\",\n]\n"
},
{
"path": "options_portfolio_backtester/convexity/_utils.py",
"content": "\"\"\"Shared utilities for the convexity module.\"\"\"\n\nfrom __future__ import annotations\n\nimport numpy as np\nimport pandas as pd\n\n\ndef _to_ns(series: pd.Series) -> np.ndarray:\n \"\"\"Convert a datetime Series to int64 nanosecond timestamps.\"\"\"\n return series.values.astype(\"datetime64[ns]\").view(\"int64\").astype(np.int64)\n"
},
{
"path": "options_portfolio_backtester/convexity/allocator.py",
"content": "\"\"\"Allocation strategies: pick which instrument(s) to hedge.\"\"\"\n\nfrom __future__ import annotations\n\n\ndef pick_cheapest(scores: dict[str, float]) -> str:\n \"\"\"Pick the instrument with the highest convexity ratio.\"\"\"\n if not scores:\n raise ValueError(\"No scores to pick from\")\n return max(scores, key=scores.get)\n\n\ndef allocate_equal_weight(symbols: list[str], budget: float) -> dict[str, float]:\n \"\"\"Split budget equally across all instruments.\"\"\"\n if not symbols:\n return {}\n per_symbol = budget / len(symbols)\n return {s: per_symbol for s in symbols}\n\n\ndef allocate_inverse_vol(vol_map: dict[str, float], budget: float) -> dict[str, float]:\n \"\"\"Allocate more to lower-volatility instruments.\n\n Weight is proportional to 1/vol, normalized to sum to budget.\n \"\"\"\n if not vol_map:\n return {}\n\n inv_vols = {}\n for sym, vol in vol_map.items():\n if vol > 0:\n inv_vols[sym] = 1.0 / vol\n\n if not inv_vols:\n return allocate_equal_weight(list(vol_map.keys()), budget)\n\n total_inv_vol = sum(inv_vols.values())\n return {sym: (iv / total_inv_vol) * budget for sym, iv in inv_vols.items()}\n"
},
{
"path": "options_portfolio_backtester/convexity/backtest.py",
"content": "\"\"\"Backtest: run the monthly rebalance loop via Rust backend.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom dataclasses import dataclass\n\nimport numpy as np\nimport pandas as pd\n\nfrom .config import BacktestConfig\n\nlog = logging.getLogger(__name__)\n\n\ndef _to_ns(series: pd.Series) -> np.ndarray:\n \"\"\"Convert a datetime Series to int64 nanosecond timestamps.\"\"\"\n return series.values.astype(\"datetime64[ns]\").view(\"int64\").astype(np.int64)\n\n\n@dataclass\nclass BacktestResult:\n \"\"\"Results from a single-instrument backtest.\"\"\"\n\n records: pd.DataFrame # monthly rebalance records\n daily_balance: pd.DataFrame # daily portfolio values\n config: BacktestConfig\n\n\ndef run_backtest(\n options_data,\n stocks_data,\n config: BacktestConfig,\n) -> BacktestResult:\n \"\"\"Run the full backtest: monthly put overlay on equity portfolio.\n\n Takes HistoricalOptionsData and TiingoData from options_backtester.\n \"\"\"\n from options_portfolio_backtester._ob_rust import run_convexity_backtest\n\n opt_df = options_data._data\n puts = opt_df[opt_df[\"type\"] == \"put\"].sort_values(\"quotedate\")\n stk_df = stocks_data._data.sort_values(\"date\")\n\n if puts.empty or stk_df.empty:\n empty_records = pd.DataFrame()\n empty_daily = pd.DataFrame()\n return BacktestResult(records=empty_records, daily_balance=empty_daily, config=config)\n\n result = run_convexity_backtest(\n put_dates_ns=_to_ns(puts[\"quotedate\"]),\n put_expirations_ns=_to_ns(puts[\"expiration\"]),\n put_strikes=puts[\"strike\"].values.astype(np.float64),\n put_bids=puts[\"bid\"].values.astype(np.float64),\n put_asks=puts[\"ask\"].values.astype(np.float64),\n put_deltas=puts[\"delta\"].values.astype(np.float64),\n put_underlying=puts[\"underlying_last\"].values.astype(np.float64),\n put_dtes=puts[\"dte\"].values.astype(np.int32),\n put_ivs=puts[\"impliedvol\"].values.astype(np.float64),\n stock_dates_ns=_to_ns(stk_df[\"date\"]),\n stock_prices=stk_df[\"adjClose\"].values.astype(np.float64),\n initial_capital=config.initial_capital,\n budget_pct=config.budget_pct,\n target_delta=config.target_delta,\n dte_min=config.dte_min,\n dte_max=config.dte_max,\n tail_drop=config.tail_drop,\n )\n\n # Build monthly records DataFrame\n rec = result[\"records\"]\n records = pd.DataFrame(\n {\n \"date\": pd.to_datetime(rec[\"dates_ns\"], unit=\"ns\"),\n \"shares\": rec[\"shares\"],\n \"stock_price\": rec[\"stock_prices\"],\n \"equity_value\": rec[\"equity_values\"],\n \"put_cost\": rec[\"put_costs\"],\n \"put_exit_value\": rec[\"put_exit_values\"],\n \"put_pnl\": rec[\"put_pnls\"],\n \"portfolio_value\": rec[\"portfolio_values\"],\n \"convexity_ratio\": rec[\"convexity_ratios\"],\n \"strike\": rec[\"strikes\"],\n \"contracts\": rec[\"contracts\"],\n }\n ).set_index(\"date\")\n\n # Build daily balance DataFrame\n daily = pd.DataFrame(\n {\n \"date\": pd.to_datetime(result[\"daily_dates_ns\"], unit=\"ns\"),\n \"balance\": result[\"daily_balances\"],\n }\n ).set_index(\"date\")\n daily[\"pct_change\"] = daily[\"balance\"].pct_change()\n\n log.info(\n \"Backtest: %d months, final value $%.0f (started $%.0f)\",\n len(records),\n daily[\"balance\"].iloc[-1] if len(daily) > 0 else 0,\n config.initial_capital,\n )\n\n return BacktestResult(records=records, daily_balance=daily, config=config)\n\n\ndef run_unhedged(stocks_data, config: BacktestConfig) -> pd.DataFrame:\n \"\"\"Run unhedged equity-only benchmark. Returns daily balance DataFrame.\"\"\"\n stk_df = stocks_data._data.sort_values(\"date\")\n if stk_df.empty:\n return pd.DataFrame()\n\n prices = stk_df[\"adjClose\"].values.astype(np.float64)\n dates = stk_df[\"date\"]\n\n initial_shares = config.initial_capital / prices[0]\n daily_balance = initial_shares * prices\n\n df = pd.DataFrame({\"date\": dates, \"balance\": daily_balance}).set_index(\"date\")\n df[\"pct_change\"] = df[\"balance\"].pct_change()\n return df\n"
},
{
"path": "options_portfolio_backtester/convexity/config.py",
"content": "\"\"\"Configuration: instrument registry and backtest parameters.\"\"\"\n\nfrom __future__ import annotations\n\nfrom dataclasses import dataclass, field\n\n\n@dataclass(frozen=True)\nclass InstrumentConfig:\n \"\"\"Configuration for a single instrument.\"\"\"\n\n symbol: str\n options_file: str\n stocks_file: str\n target_delta: float = -0.10\n dte_min: int = 14\n dte_max: int = 60\n tail_drop: float = 0.20\n\n\n@dataclass(frozen=True)\nclass BacktestConfig:\n \"\"\"Global backtest parameters.\"\"\"\n\n initial_capital: float = 1_000_000.0\n budget_pct: float = 0.005 # 0.5% of portfolio per month on puts\n target_delta: float = -0.10\n dte_min: int = 14\n dte_max: int = 60\n tail_drop: float = 0.20\n instruments: list[InstrumentConfig] = field(default_factory=list)\n\n\ndef default_config(\n options_file: str = \"data/processed/options.csv\",\n stocks_file: str = \"data/processed/stocks.csv\",\n) -> BacktestConfig:\n \"\"\"Default config with SPY only.\"\"\"\n spy = InstrumentConfig(\n symbol=\"SPY\",\n options_file=options_file,\n stocks_file=stocks_file,\n )\n return BacktestConfig(instruments=[spy])\n"
},
{
"path": "options_portfolio_backtester/convexity/scoring.py",
"content": "\"\"\"Scoring: compute convexity ratios via Rust backend.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\n\nimport numpy as np\nimport pandas as pd\n\nfrom .config import BacktestConfig\n\nlog = logging.getLogger(__name__)\n\n\ndef _to_ns(series: pd.Series) -> np.ndarray:\n \"\"\"Convert a datetime Series to int64 nanosecond timestamps.\"\"\"\n return series.values.astype(\"datetime64[ns]\").view(\"int64\").astype(np.int64)\n\n\ndef compute_convexity_scores(\n options_data,\n config: BacktestConfig,\n) -> pd.DataFrame:\n \"\"\"Compute daily convexity ratio scores for an instrument.\n\n Takes an HistoricalOptionsData object from options_backtester and\n returns a DataFrame indexed by date with convexity_ratio and supporting fields.\n \"\"\"\n from options_portfolio_backtester._ob_rust import compute_daily_scores\n\n df = options_data._data\n puts = df[df[\"type\"] == \"put\"].sort_values(\"quotedate\")\n\n if puts.empty:\n return pd.DataFrame()\n\n result = compute_daily_scores(\n dates_ns=_to_ns(puts[\"quotedate\"]),\n strikes=puts[\"strike\"].values.astype(np.float64),\n bids=puts[\"bid\"].values.astype(np.float64),\n asks=puts[\"ask\"].values.astype(np.float64),\n deltas=puts[\"delta\"].values.astype(np.float64),\n underlying_prices=puts[\"underlying_last\"].values.astype(np.float64),\n dtes=puts[\"dte\"].values.astype(np.int32),\n implied_vols=puts[\"impliedvol\"].values.astype(np.float64),\n target_delta=config.target_delta,\n dte_min=config.dte_min,\n dte_max=config.dte_max,\n tail_drop=config.tail_drop,\n )\n\n scores = pd.DataFrame(\n {\n \"date\": pd.to_datetime(result[\"dates_ns\"], unit=\"ns\"),\n \"convexity_ratio\": result[\"convexity_ratios\"],\n \"strike\": result[\"strikes\"],\n \"ask\": result[\"asks\"],\n \"bid\": result[\"bids\"],\n \"delta\": result[\"deltas\"],\n \"underlying_price\": result[\"underlying_prices\"],\n \"implied_vol\": result[\"implied_vols\"],\n \"dte\": result[\"dtes\"],\n \"annual_cost\": result[\"annual_costs\"],\n \"tail_payoff\": result[\"tail_payoffs\"],\n }\n ).set_index(\"date\")\n\n log.info(\"Computed %d daily scores (%.1f years)\", len(scores), len(scores) / 252)\n\n return scores\n"
},
{
"path": "options_portfolio_backtester/convexity/viz.py",
"content": "\"\"\"Visualization: Altair charts for scores, allocations, and P&L.\"\"\"\n\nfrom __future__ import annotations\n\nimport altair as alt\nimport pandas as pd\n\n\ndef convexity_scores_chart(scores_df: pd.DataFrame) -> alt.Chart:\n \"\"\"Line chart of daily convexity ratios over time.\"\"\"\n data = scores_df.reset_index()\n return (\n alt.Chart(data)\n .mark_line()\n .encode(\n x=alt.X(\"date:T\", title=\"Date\"),\n y=alt.Y(\"convexity_ratio:Q\", title=\"Convexity Ratio\"),\n tooltip=[\"date:T\", \"convexity_ratio:Q\", \"strike:Q\", \"underlying_price:Q\", \"implied_vol:Q\"],\n )\n .properties(title=\"Daily Convexity Ratio\", width=800, height=300)\n )\n\n\ndef monthly_pnl_chart(records: pd.DataFrame) -> alt.Chart:\n \"\"\"Bar chart of monthly put P&L.\"\"\"\n data = records.reset_index()\n return (\n alt.Chart(data)\n .mark_bar()\n .encode(\n x=alt.X(\"date:T\", title=\"Date\"),\n y=alt.Y(\"put_pnl:Q\", title=\"Put P&L ($)\"),\n color=alt.condition(\n alt.datum.put_pnl > 0,\n alt.value(\"steelblue\"),\n alt.value(\"salmon\"),\n ),\n tooltip=[\"date:T\", \"put_pnl:Q\", \"put_cost:Q\", \"put_exit_value:Q\", \"strike:Q\", \"contracts:Q\"],\n )\n .properties(title=\"Monthly Put P&L\", width=800, height=200)\n )\n\n\ndef cumulative_pnl_chart(results: dict[str, pd.DataFrame]) -> alt.Chart:\n \"\"\"Cumulative portfolio value for multiple strategies.\"\"\"\n frames = []\n for name, daily_df in results.items():\n df = daily_df[[\"balance\"]].copy()\n df[\"strategy\"] = name\n frames.append(df.reset_index())\n\n if not frames:\n return alt.Chart(pd.DataFrame()).mark_line()\n\n data = pd.concat(frames, ignore_index=True)\n\n return (\n alt.Chart(data)\n .mark_line()\n .encode(\n x=alt.X(\"date:T\", title=\"Date\"),\n y=alt.Y(\"balance:Q\", title=\"Portfolio Value ($)\", scale=alt.Scale(zero=False)),\n color=alt.Color(\"strategy:N\", title=\"Strategy\"),\n tooltip=[\"date:T\", \"balance:Q\", \"strategy:N\"],\n )\n .properties(title=\"Cumulative Portfolio Value\", width=800, height=400)\n )\n"
},
{
"path": "options_portfolio_backtester/core/__init__.py",
"content": ""
},
{
"path": "options_portfolio_backtester/core/types.py",
"content": "\"\"\"Core domain types for options backtesting.\n\nDirection is decoupled from column names — use Direction.price_column instead of\nDirection.value to get the DataFrame column for pricing.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom collections import namedtuple\nfrom dataclasses import dataclass, field\nfrom enum import Enum\nfrom typing import Any\n\n\n# ---------------------------------------------------------------------------\n# Enums\n# ---------------------------------------------------------------------------\n\nclass OptionType(Enum):\n CALL = \"call\"\n PUT = \"put\"\n\n def __invert__(self) -> OptionType:\n return OptionType.PUT if self == OptionType.CALL else OptionType.CALL\n\n\nclass Direction(Enum):\n \"\"\"Trade direction. price_column gives the DataFrame column name.\"\"\"\n BUY = \"buy\"\n SELL = \"sell\"\n\n @property\n def price_column(self) -> str:\n \"\"\"Column name used for trade execution pricing.\"\"\"\n return \"ask\" if self == Direction.BUY else \"bid\"\n\n def __invert__(self) -> Direction:\n return Direction.SELL if self == Direction.BUY else Direction.BUY\n\n\nclass Signal(Enum):\n ENTRY = \"entry\"\n EXIT = \"exit\"\n\n\nclass Order(Enum):\n BTO = \"BTO\" # Buy to Open\n BTC = \"BTC\" # Buy to Close\n STO = \"STO\" # Sell to Open\n STC = \"STC\" # Sell to Close\n\n def __invert__(self) -> Order:\n _inv = {Order.BTO: Order.STC, Order.STC: Order.BTO,\n Order.STO: Order.BTC, Order.BTC: Order.STO}\n return _inv[self]\n\n\ndef get_order(direction: Direction, signal: Signal) -> Order:\n \"\"\"Map (direction, signal) to the appropriate Order type.\"\"\"\n if direction == Direction.BUY:\n return Order.BTO if signal == Signal.ENTRY else Order.STC\n return Order.STO if signal == Signal.ENTRY else Order.BTC\n\n\n# ---------------------------------------------------------------------------\n# Value objects\n# ---------------------------------------------------------------------------\n\n@dataclass(frozen=True, slots=True)\nclass Greeks:\n \"\"\"Option Greeks for a single contract or aggregated position.\n\n Supports addition (aggregation) and scalar multiplication (scaling by qty).\n \"\"\"\n delta: float = 0.0\n gamma: float = 0.0\n theta: float = 0.0\n vega: float = 0.0\n\n def __add__(self, other: Greeks) -> Greeks:\n return Greeks(\n delta=self.delta + other.delta,\n gamma=self.gamma + other.gamma,\n theta=self.theta + other.theta,\n vega=self.vega + other.vega,\n )\n\n def __mul__(self, scalar: float) -> Greeks:\n return Greeks(\n delta=self.delta * scalar,\n gamma=self.gamma * scalar,\n theta=self.theta * scalar,\n vega=self.vega * scalar,\n )\n\n def __rmul__(self, scalar: float) -> Greeks:\n return self.__mul__(scalar)\n\n def __neg__(self) -> Greeks:\n return self * -1.0\n\n @property\n def as_dict(self) -> dict[str, float]:\n return {\"delta\": self.delta, \"gamma\": self.gamma,\n \"theta\": self.theta, \"vega\": self.vega}\n\n\n@dataclass(frozen=True, slots=True)\nclass Fill:\n \"\"\"A single execution fill.\n\n Captures price, quantity, commission, slippage, and computes notional.\n \"\"\"\n price: float\n quantity: int\n direction: Direction\n shares_per_contract: int = 100\n commission: float = 0.0\n slippage: float = 0.0\n\n @property\n def direction_sign(self) -> int:\n return -1 if self.direction == Direction.BUY else 1\n\n @property\n def notional(self) -> float:\n \"\"\"Net cash impact: direction_sign * (price * qty * spc) - commission - slippage.\"\"\"\n raw = self.direction_sign * self.price * self.quantity * self.shares_per_contract\n return raw - self.commission - self.slippage\n\n\n@dataclass(frozen=True, slots=True)\nclass OptionContract:\n \"\"\"Identifies a specific option contract.\"\"\"\n contract_id: str\n underlying: str\n expiration: Any # pd.Timestamp or str\n option_type: OptionType\n strike: float\n\n\n# Re-use namedtuple for backward compatibility\nStockAllocation = namedtuple(\"StockAllocation\", \"symbol percentage\")\n\n# Backward-compatible aliases\nStock = StockAllocation\nType = OptionType\n"
},
{
"path": "options_portfolio_backtester/data/__init__.py",
"content": "\"\"\"Data module — schema and providers.\"\"\"\n"
},
{
"path": "options_portfolio_backtester/data/providers.py",
"content": "\"\"\"Data providers — ABCs, CSV implementations, and data loaders.\"\"\"\n\nfrom __future__ import annotations\n\nimport os\nfrom abc import ABC, abstractmethod\nfrom typing import Any, Union\n\nimport pandas as pd\n\nfrom .schema import Schema, Filter\n\n\nclass TiingoData:\n \"\"\"Tiingo (stocks & indeces) Data container class.\"\"\"\n def __init__(self, file: str, schema: Schema | None = None, **params: Any) -> None:\n if schema is None:\n self.schema = TiingoData.default_schema()\n\n file_extension = os.path.splitext(file)[1]\n\n if file_extension == '.h5':\n self._data: pd.DataFrame = pd.read_hdf(file, **params)\n elif file_extension == '.csv':\n params['parse_dates'] = [self.schema.date.mapping]\n self._data = pd.read_csv(file, **params)\n\n columns = self._data.columns\n assert all((col in columns for _key, col in self.schema))\n\n date_col = self.schema['date']\n\n self.start_date: pd.Timestamp = self._data[date_col].min()\n self.end_date: pd.Timestamp = self._data[date_col].max()\n\n def apply_filter(self, f: Filter) -> pd.DataFrame:\n \"\"\"Apply Filter `f` to the data. Returns a `pd.DataFrame` with the filtered rows.\"\"\"\n return self._data.query(f.query)\n\n def iter_dates(self) -> pd.core.groupby.DataFrameGroupBy:\n \"\"\"Returns `pd.DataFrameGroupBy` that groups stocks by date\"\"\"\n return self._data.groupby(self.schema['date'])\n\n def iter_months(self) -> pd.core.groupby.DataFrameGroupBy:\n \"\"\"Returns `pd.DataFrameGroupBy` that groups stocks by month\"\"\"\n date_col = self.schema['date']\n first_date_per_month = (\n self._data.groupby(self._data[date_col].dt.to_period('M'))[date_col]\n .min()\n )\n mask = self._data[date_col].isin(first_date_per_month.values)\n return self._data[mask].groupby(date_col)\n\n def __getattr__(self, attr: str) -> Any:\n \"\"\"Pass method invocation to `self._data`\"\"\"\n\n method = getattr(self._data, attr)\n if hasattr(method, '__call__'):\n\n def df_method(*args: Any, **kwargs: Any) -> Any:\n return method(*args, **kwargs)\n\n return df_method\n else:\n return method\n\n def __getitem__(self, item: Union[str, pd.Series]) -> Union[pd.DataFrame, pd.Series]:\n if isinstance(item, pd.Series):\n return self._data[item]\n else:\n key = self.schema[item]\n return self._data[key]\n\n def __setitem__(self, key: str, value: Any) -> None:\n self._data[key] = value\n if key not in self.schema:\n self.schema.update({key: key})\n\n def __len__(self) -> int:\n return len(self._data)\n\n def __repr__(self) -> str:\n return self._data.__repr__()\n\n @staticmethod\n def default_schema() -> Schema:\n \"\"\"Returns default schema for Tiingo Data\"\"\"\n return Schema.stocks()\n\n def sma(self, periods: int) -> None:\n sma = self._data.groupby('symbol', as_index=False).rolling(periods)['adjClose'].mean()\n sma = sma.fillna(0)\n sma.index = [index[1] for index in sma.index]\n self._data['sma'] = sma\n self.schema.update({'sma': 'sma'})\n\n\nclass HistoricalOptionsData:\n \"\"\"Historical Options Data container class.\"\"\"\n def __init__(self, file: str, schema: Schema | None = None, **params: Any) -> None:\n if schema is None:\n self.schema = HistoricalOptionsData.default_schema()\n\n file_extension = os.path.splitext(file)[1]\n\n if file_extension == '.h5':\n self._data: pd.DataFrame = pd.read_hdf(file, **params)\n elif file_extension == '.csv':\n params['parse_dates'] = [self.schema.expiration.mapping, self.schema.date.mapping]\n self._data = pd.read_csv(file, **params)\n\n columns = self._data.columns\n assert all((col in columns for _key, col in self.schema))\n\n date_col = self.schema['date']\n expiration_col = self.schema['expiration']\n\n self._data['dte'] = (self._data[expiration_col] - self._data[date_col]).dt.days\n self.schema.update({'dte': 'dte'})\n\n self.start_date: pd.Timestamp = self._data[date_col].min()\n self.end_date: pd.Timestamp = self._data[date_col].max()\n\n def apply_filter(self, f: Filter) -> pd.DataFrame:\n \"\"\"Apply Filter `f` to the data. Returns a `pd.DataFrame` with the filtered rows.\"\"\"\n return self._data.query(f.query)\n\n def iter_dates(self) -> pd.core.groupby.DataFrameGroupBy:\n \"\"\"Returns `pd.DataFrameGroupBy` that groups contracts by date\"\"\"\n return self._data.groupby(self.schema['date'])\n\n def iter_months(self) -> pd.core.groupby.DataFrameGroupBy:\n \"\"\"Returns `pd.DataFrameGroupBy` that groups contracts by month\"\"\"\n date_col = self.schema['date']\n first_date_per_month = (\n self._data.groupby(self._data[date_col].dt.to_period('M'))[date_col]\n .min()\n )\n mask = self._data[date_col].isin(first_date_per_month.values)\n return self._data[mask].groupby(date_col)\n\n def __getattr__(self, attr: str) -> Any:\n \"\"\"Pass method invocation to `self._data`\"\"\"\n\n method = getattr(self._data, attr)\n if hasattr(method, '__call__'):\n\n def df_method(*args: Any, **kwargs: Any) -> Any:\n return method(*args, **kwargs)\n\n return df_method\n else:\n return method\n\n def __getitem__(self, item: Union[str, pd.Series]) -> Union[pd.DataFrame, pd.Series]:\n if isinstance(item, pd.Series):\n return self._data[item]\n else:\n key = self.schema[item]\n return self._data[key]\n\n def __setitem__(self, key: str, value: Any) -> None:\n self._data[key] = value\n if key not in self.schema:\n self.schema.update({key: key})\n\n def __len__(self) -> int:\n return len(self._data)\n\n def __repr__(self) -> str:\n return self._data.__repr__()\n\n @staticmethod\n def default_schema() -> Schema:\n \"\"\"Returns default schema for Historical Options Data\"\"\"\n schema = Schema.options()\n schema.update({\n 'contract': 'optionroot',\n 'date': 'quotedate',\n 'last': 'last',\n 'open_interest': 'openinterest',\n 'impliedvol': 'impliedvol',\n 'delta': 'delta',\n 'gamma': 'gamma',\n 'theta': 'theta',\n 'vega': 'vega'\n })\n return schema\n\n\n# ---------------------------------------------------------------------------\n# Abstract base classes\n# ---------------------------------------------------------------------------\n\nclass DataProvider(ABC):\n \"\"\"Base interface for all data providers.\"\"\"\n\n @property\n @abstractmethod\n def schema(self) -> Schema:\n ...\n\n @property\n @abstractmethod\n def data(self) -> pd.DataFrame:\n ...\n\n @property\n @abstractmethod\n def start_date(self) -> pd.Timestamp:\n ...\n\n @property\n @abstractmethod\n def end_date(self) -> pd.Timestamp:\n ...\n\n @abstractmethod\n def apply_filter(self, f: Filter) -> pd.DataFrame:\n ...\n\n @abstractmethod\n def iter_dates(self) -> Any:\n ...\n\n @abstractmethod\n def iter_months(self) -> Any:\n ...\n\n\nclass OptionsDataProvider(DataProvider):\n \"\"\"Options-specific data provider interface.\"\"\"\n pass\n\n\nclass StocksDataProvider(DataProvider):\n \"\"\"Stocks-specific data provider interface.\"\"\"\n\n @abstractmethod\n def sma(self, periods: int) -> None:\n ...\n\n\n# ---------------------------------------------------------------------------\n# CSV implementations (wrap existing loaders)\n# ---------------------------------------------------------------------------\n\nclass CsvOptionsProvider(OptionsDataProvider):\n \"\"\"Load options data from CSV files using the existing HistoricalOptionsData loader.\"\"\"\n\n def __init__(self, file: str, schema: Schema | None = None, **params: Any) -> None:\n self._loader = HistoricalOptionsData(file, schema=schema, **params)\n\n @property\n def schema(self) -> Schema:\n return self._loader.schema\n\n @property\n def data(self) -> pd.DataFrame:\n return self._loader._data\n\n @property\n def start_date(self) -> pd.Timestamp:\n return self._loader.start_date\n\n @property\n def end_date(self) -> pd.Timestamp:\n return self._loader.end_date\n\n def apply_filter(self, f: Filter) -> pd.DataFrame:\n return self._loader.apply_filter(f)\n\n def iter_dates(self) -> Any:\n return self._loader.iter_dates()\n\n def iter_months(self) -> Any:\n return self._loader.iter_months()\n\n def __getitem__(self, item: Any) -> Any:\n return self._loader[item]\n\n def __setitem__(self, key: str, value: Any) -> None:\n self._loader[key] = value\n\n def __len__(self) -> int:\n return len(self._loader)\n\n @property\n def _data(self) -> pd.DataFrame:\n \"\"\"Access to underlying DataFrame.\"\"\"\n return self._loader._data\n\n\nclass CsvStocksProvider(StocksDataProvider):\n \"\"\"Load stock data from CSV files using the existing TiingoData loader.\"\"\"\n\n def __init__(self, file: str, schema: Schema | None = None, **params: Any) -> None:\n self._loader = TiingoData(file, schema=schema, **params)\n\n @property\n def schema(self) -> Schema:\n return self._loader.schema\n\n @property\n def data(self) -> pd.DataFrame:\n return self._loader._data\n\n @property\n def start_date(self) -> pd.Timestamp:\n return self._loader.start_date\n\n @property\n def end_date(self) -> pd.Timestamp:\n return self._loader.end_date\n\n def apply_filter(self, f: Filter) -> pd.DataFrame:\n return self._loader.apply_filter(f)\n\n def iter_dates(self) -> Any:\n return self._loader.iter_dates()\n\n def iter_months(self) -> Any:\n return self._loader.iter_months()\n\n def sma(self, periods: int) -> None:\n self._loader.sma(periods)\n\n def __getitem__(self, item: Any) -> Any:\n return self._loader[item]\n\n def __setitem__(self, key: str, value: Any) -> None:\n self._loader[key] = value\n\n def __len__(self) -> int:\n return len(self._loader)\n\n @property\n def _data(self) -> pd.DataFrame:\n \"\"\"Access to underlying DataFrame.\"\"\"\n return self._loader._data\n"
},
{
"path": "options_portfolio_backtester/data/schema.py",
"content": "\"\"\"Filter DSL — Schema, Field, and Filter for building query expressions.\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import Any, Iterator, Union\n\n\nclass Schema:\n \"\"\"Data schema class.\n Used provide uniform access to fields in the data set.\n \"\"\"\n\n stock_columns = [\n \"symbol\", \"date\", \"open\", \"close\", \"high\", \"low\", \"volume\", \"adjClose\", \"adjHigh\", \"adjLow\", \"adjOpen\",\n \"adjVolume\", \"divCash\", \"splitFactor\"\n ]\n\n option_columns = [\n \"underlying\", \"underlying_last\", \"date\", \"contract\", \"type\", \"expiration\", \"strike\", \"bid\", \"ask\", \"volume\",\n \"open_interest\"\n ]\n\n @staticmethod\n def stocks() -> Schema:\n \"\"\"Builder method that returns a `Schema` with default mappings for stocks\"\"\"\n mappings = {key: key for key in Schema.stock_columns}\n return Schema(mappings)\n\n @staticmethod\n def options() -> Schema:\n \"\"\"Builder method that returns a `Schema` with default mappings for options\"\"\"\n mappings = {key: key for key in Schema.option_columns}\n return Schema(mappings)\n\n def __init__(self, mappings: dict[str, str]) -> None:\n assert all((key in mappings for key in Schema.stock_columns)) or all(\n (key in mappings for key in Schema.option_columns))\n\n self._mappings: dict[str, str] = mappings\n\n def update(self, mappings: dict[str, str]) -> Schema:\n \"\"\"Update schema according to given `mappings`\"\"\"\n self._mappings.update(mappings)\n return self\n\n def __contains__(self, key: str) -> bool:\n \"\"\"Returns True if key is in schema\"\"\"\n return key in self._mappings.keys()\n\n def __getattr__(self, key: str) -> Field:\n \"\"\"Returns Field object used to build Filters\"\"\"\n return Field(key, self._mappings[key])\n\n def __setitem__(self, key: str, value: str) -> None:\n self._mappings[key] = value\n\n def __getitem__(self, key: str) -> str:\n \"\"\"Returns mapping of given `key`\"\"\"\n return self._mappings[key]\n\n def __iter__(self) -> Iterator[tuple[str, str]]:\n return iter(self._mappings.items())\n\n def __repr__(self) -> str:\n return \"Schema({})\".format([Field(k, m) for k, m in self._mappings.items()])\n\n def __eq__(self, other: object) -> bool:\n if not isinstance(other, Schema):\n return NotImplemented\n return self._mappings == other._mappings\n\n\nclass Field:\n \"\"\"Encapsulates data fields to build filters used by strategies\"\"\"\n\n __slots__ = (\"name\", \"mapping\")\n\n def __init__(self, name: str, mapping: str) -> None:\n self.name = name\n self.mapping = mapping\n\n def _create_filter(self, op: str, other: Union[Field, Any]) -> Filter:\n if isinstance(other, Field):\n\n query = Field._format_query(self.mapping, op, other.mapping)\n else:\n query = Field._format_query(self.mapping, op, other)\n return Filter(query)\n\n def _combine_fields(self, op: str, other: Union[Field, int, float], invert: bool = False) -> Field:\n if isinstance(other, Field):\n name = Field._format_query(self.name, op, other.name, invert)\n mapping = Field._format_query(self.mapping, op, other.mapping, invert)\n elif isinstance(other, (int, float)):\n name = Field._format_query(self.name, op, other, invert)\n mapping = Field._format_query(self.mapping, op, other, invert)\n else:\n raise TypeError\n\n return Field(name, mapping)\n\n @staticmethod\n def _format_query(left: Any, op: str, right: Any, invert: bool = False) -> str:\n if invert:\n left, right = right, left\n query = \"{left} {op} {right}\".format(left=left, op=op, right=right)\n return query\n\n def __add__(self, value: Union[Field, int, float]) -> Field:\n return self._combine_fields(\"+\", value)\n\n def __radd__(self, value: Union[Field, int, float]) -> Field:\n return self._combine_fields(\"+\", value, invert=True)\n\n def __sub__(self, value: Union[Field, int, float]) -> Field:\n return self._combine_fields(\"-\", value)\n\n def __rsub__(self, value: Union[Field, int, float]) -> Field:\n return self._combine_fields(\"-\", value, invert=True)\n\n def __mul__(self, value: Union[Field, int, float]) -> Field:\n return self._combine_fields(\"*\", value)\n\n def __rmul__(self, value: Union[Field, int, float]) -> Field:\n return self._combine_fields(\"*\", value, invert=True)\n\n def __truediv__(self, value: Union[Field, int, float]) -> Field:\n return self._combine_fields(\"/\", value)\n\n def __rtruediv__(self, value: Union[Field, int, float]) -> Field:\n return self._combine_fields(\"/\", value, invert=True)\n\n def __lt__(self, value: Union[Field, Any]) -> Filter:\n return self._create_filter(\"<\", value)\n\n def __le__(self, value: Union[Field, Any]) -> Filter:\n return self._create_filter(\"<=\", value)\n\n def __gt__(self, value: Union[Field, Any]) -> Filter:\n return self._create_filter(\">\", value)\n\n def __ge__(self, value: Union[Field, Any]) -> Filter:\n return self._create_filter(\">=\", value)\n\n def __eq__(self, value: Union[Field, Any]) -> Filter: # type: ignore[override]\n if isinstance(value, str):\n value = \"'{}'\".format(value)\n return self._create_filter(\"==\", value)\n\n def __ne__(self, value: Union[Field, Any]) -> Filter: # type: ignore[override]\n return self._create_filter(\"!=\", value)\n\n def __repr__(self) -> str:\n return \"Field(name='{}', mapping='{}')\".format(self.name, self.mapping)\n\n\nclass Filter:\n \"\"\"This class determines entry/exit conditions for strategies\"\"\"\n\n __slots__ = (\"query\")\n\n def __init__(self, query: str) -> None:\n self.query = query\n\n def __and__(self, other: Filter) -> Filter:\n \"\"\"Returns logical *and* between `self` and `other`\"\"\"\n assert isinstance(other, Filter)\n new_query = \"({}) & ({})\".format(self.query, other.query)\n return Filter(query=new_query)\n\n def __or__(self, other: Filter) -> Filter:\n \"\"\"Returns logical *or* between `self` and `other`\"\"\"\n assert isinstance(other, Filter)\n new_query = \"(({}) | ({}))\".format(self.query, other.query)\n return Filter(query=new_query)\n\n def __invert__(self) -> Filter:\n \"\"\"Negates filter\"\"\"\n return Filter(\"!({})\".format(self.query))\n\n def __call__(self, data: 'pd.DataFrame') -> 'pd.Series':\n \"\"\"Returns dataframe of filtered data\"\"\"\n return data.eval(self.query)\n\n def __repr__(self) -> str:\n return \"Filter(query='{}')\".format(self.query)\n\n\n__all__ = [\"Schema\", \"Field\", \"Filter\"]\n"
},
{
"path": "options_portfolio_backtester/engine/__init__.py",
"content": ""
},
{
"path": "options_portfolio_backtester/engine/algo_adapters.py",
"content": "\"\"\"Algo adapter layer to drive BacktestEngine with bt-style pipeline blocks.\"\"\"\n\nfrom __future__ import annotations\n\nimport math\nfrom dataclasses import dataclass, field\nfrom typing import Literal, Protocol\n\nimport pandas as pd\n\nfrom options_portfolio_backtester.core.types import Greeks\n\n\nStepStatus = Literal[\"continue\", \"skip_day\", \"stop\"]\n\n\n@dataclass(frozen=True)\nclass EngineStepDecision:\n \"\"\"Decision emitted by one engine-algo step.\"\"\"\n\n status: StepStatus = \"continue\"\n message: str = \"\"\n\n\n@dataclass\nclass EnginePipelineContext:\n \"\"\"Mutable run context shared by all engine algo steps for one rebalance date.\"\"\"\n\n date: pd.Timestamp\n stocks: pd.DataFrame\n options: pd.DataFrame\n total_capital: float\n current_cash: float\n current_greeks: Greeks\n options_allocation: float\n entry_filters: list = field(default_factory=list)\n exit_threshold_override: tuple[float, float] | None = None\n\n\nclass EngineAlgo(Protocol):\n def __call__(self, ctx: EnginePipelineContext) -> EngineStepDecision:\n ...\n\n\nclass EngineRunMonthly:\n \"\"\"Allow rebalances only on first rebalance day per month.\"\"\"\n\n def __init__(self) -> None:\n self._last_month: tuple[int, int] | None = None\n\n def reset(self) -> None:\n self._last_month = None\n\n def __call__(self, ctx: EnginePipelineContext) -> EngineStepDecision:\n key = (ctx.date.year, ctx.date.month)\n if self._last_month == key:\n return EngineStepDecision(status=\"skip_day\", message=\"not month-start\")\n self._last_month = key\n return EngineStepDecision()\n\n\nclass BudgetPercent:\n \"\"\"Set options allocation budget as percent of current total capital.\"\"\"\n\n def __init__(self, pct: float) -> None:\n self.pct = float(pct)\n\n def __call__(self, ctx: EnginePipelineContext) -> EngineStepDecision:\n ctx.options_allocation = max(0.0, float(ctx.total_capital) * self.pct)\n return EngineStepDecision()\n\n\nclass RangeFilter:\n \"\"\"Keep contracts where *column* falls within [min_val, max_val].\n\n Generic building block — use directly or via the convenience aliases\n ``SelectByDelta``, ``SelectByDTE``, ``IVRankFilter``.\n \"\"\"\n\n def __init__(self, column: str, min_val: float, max_val: float) -> None:\n self.column = column\n self.min_val = float(min_val)\n self.max_val = float(max_val)\n\n def __call__(self, ctx: EnginePipelineContext) -> EngineStepDecision:\n lo, hi, col = self.min_val, self.max_val, self.column\n\n def _flt(df: pd.DataFrame) -> pd.Series:\n if col not in df.columns:\n return pd.Series(True, index=df.index)\n v = df[col]\n return (v >= lo) & (v <= hi)\n\n ctx.entry_filters.append(_flt)\n return EngineStepDecision()\n\n\ndef SelectByDelta(min_delta: float = -1.0, max_delta: float = 1.0, column: str = \"delta\") -> RangeFilter:\n \"\"\"Keep contracts with delta within [min_delta, max_delta].\"\"\"\n return RangeFilter(column=column, min_val=min_delta, max_val=max_delta)\n\n\ndef SelectByDTE(min_dte: int = 0, max_dte: int = 10_000, column: str = \"dte\") -> RangeFilter:\n \"\"\"Keep contracts with DTE within [min_dte, max_dte].\"\"\"\n return RangeFilter(column=column, min_val=float(min_dte), max_val=float(max_dte))\n\n\ndef IVRankFilter(min_rank: float = 0.0, max_rank: float = 1.0, column: str = \"iv_rank\") -> RangeFilter:\n \"\"\"Keep contracts with IV rank within [min_rank, max_rank].\"\"\"\n return RangeFilter(column=column, min_val=min_rank, max_val=max_rank)\n\n\nclass MaxGreekExposure:\n \"\"\"Skip new entries when current absolute greek exposure exceeds limits.\"\"\"\n\n def __init__(\n self,\n max_abs_delta: float | None = None,\n max_abs_vega: float | None = None,\n ) -> None:\n self.max_abs_delta = float(max_abs_delta) if max_abs_delta is not None else None\n self.max_abs_vega = float(max_abs_vega) if max_abs_vega is not None else None\n\n def __call__(self, ctx: EnginePipelineContext) -> EngineStepDecision:\n if self.max_abs_delta is not None and abs(float(ctx.current_greeks.delta)) > self.max_abs_delta:\n return EngineStepDecision(\n status=\"skip_day\",\n message=f\"|delta|>{self.max_abs_delta}\",\n )\n if self.max_abs_vega is not None and abs(float(ctx.current_greeks.vega)) > self.max_abs_vega:\n return EngineStepDecision(\n status=\"skip_day\",\n message=f\"|vega|>{self.max_abs_vega}\",\n )\n return EngineStepDecision()\n\n\nclass ExitOnThreshold:\n \"\"\"Override strategy exit profit/loss thresholds for this run.\n\n At least one of *profit_pct* or *loss_pct* must be finite, otherwise the\n algo is a no-op and likely a caller mistake.\n \"\"\"\n\n def __init__(self, profit_pct: float = float(\"inf\"), loss_pct: float = float(\"inf\")) -> None:\n self.profit_pct = float(profit_pct)\n self.loss_pct = float(loss_pct)\n if math.isinf(self.profit_pct) and math.isinf(self.loss_pct):\n import warnings\n warnings.warn(\n \"ExitOnThreshold created with both thresholds infinite — \"\n \"exit overrides will have no effect\",\n stacklevel=2,\n )\n\n def __call__(self, ctx: EnginePipelineContext) -> EngineStepDecision:\n ctx.exit_threshold_override = (self.profit_pct, self.loss_pct)\n return EngineStepDecision()\n"
},
{
"path": "options_portfolio_backtester/engine/clock.py",
"content": "\"\"\"Trading clock — date iteration and rebalance scheduling.\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import Generator\n\nimport pandas as pd\n\n\nclass TradingClock:\n \"\"\"Generates (date, stocks_df, options_df) tuples for the backtest loop.\n\n Handles daily/monthly iteration and rebalance scheduling.\n \"\"\"\n\n def __init__(\n self,\n stocks_data: pd.DataFrame,\n options_data: pd.DataFrame,\n stocks_date_col: str = \"date\",\n options_date_col: str = \"quotedate\",\n monthly: bool = False,\n ) -> None:\n self.stocks_data = stocks_data\n self.options_data = options_data\n self.stocks_date_col = stocks_date_col\n self.options_date_col = options_date_col\n self.monthly = monthly\n\n def iter_dates(self) -> Generator[tuple[pd.Timestamp, pd.DataFrame, pd.DataFrame], None, None]:\n \"\"\"Iterate over trading dates, yielding (date, stocks, options) per step.\"\"\"\n if self.monthly:\n stocks_iter = self._monthly_iter(self.stocks_data, self.stocks_date_col)\n options_iter = self._monthly_iter(self.options_data, self.options_date_col)\n else:\n stocks_iter = self.stocks_data.groupby(self.stocks_date_col)\n options_iter = self.options_data.groupby(self.options_date_col)\n\n for (date, stocks), (_, options) in zip(stocks_iter, options_iter):\n yield date, stocks, options\n\n def rebalance_dates(self, freq: int) -> pd.DatetimeIndex:\n \"\"\"Compute rebalance dates using business-month-start frequency.\n\n Args:\n freq: Number of business months between rebalances.\n\n Returns:\n DatetimeIndex of rebalance dates present in the data.\n \"\"\"\n if freq <= 0:\n return pd.DatetimeIndex([])\n\n dates = pd.DataFrame(\n self.options_data[[self.options_date_col, \"volume\"]]\n ).drop_duplicates(self.options_date_col).set_index(self.options_date_col)\n\n return pd.to_datetime(\n dates.groupby(pd.Grouper(freq=f\"{freq}BMS\"))\n .apply(lambda x: x.index.min())\n .values\n )\n\n @staticmethod\n def _monthly_iter(data: pd.DataFrame, date_col: str):\n first_date_per_month = (\n data.groupby(data[date_col].dt.to_period('M'))[date_col]\n .min()\n )\n mask = data[date_col].isin(first_date_per_month.values)\n return data[mask].groupby(date_col)\n\n @property\n def all_dates(self) -> pd.DatetimeIndex:\n return pd.DatetimeIndex(self.options_data[self.options_date_col].unique())\n"
},
{
"path": "options_portfolio_backtester/engine/engine.py",
"content": "\"\"\"BacktestEngine — thin orchestrator composing all framework components.\n\nReplaces the monolithic Backtest class with a clean composition of:\n- Data providers (stocks, options)\n- Strategy (legs, filters, thresholds)\n- Execution (cost model, fill model, sizer, signal selector)\n- Portfolio (positions, cash, holdings)\n- Risk management (constraints)\n- Analytics (trade log, balance sheet)\n\"\"\"\n\nfrom __future__ import annotations\n\nimport hashlib\nimport json\nimport logging\nimport subprocess\nfrom dataclasses import dataclass, field\nfrom datetime import datetime, timezone\nfrom pathlib import Path\nfrom typing import Any\n\nimport numpy as np\nimport pandas as pd\n\nfrom options_portfolio_backtester.core.types import (\n Direction, OptionType, Order, Signal, Greeks, Stock, StockAllocation,\n get_order,\n)\nfrom options_portfolio_backtester.execution.cost_model import TransactionCostModel, NoCosts\nfrom options_portfolio_backtester.execution.fill_model import FillModel, MarketAtBidAsk\nfrom options_portfolio_backtester.execution.sizer import PositionSizer, CapitalBased\nfrom options_portfolio_backtester.execution.signal_selector import SignalSelector, FirstMatch\nfrom options_portfolio_backtester.portfolio.risk import RiskManager\nfrom options_portfolio_backtester.portfolio.portfolio import Portfolio\nfrom options_portfolio_backtester import _ob_rust\nfrom options_portfolio_backtester.engine.algo_adapters import (\n EngineAlgo,\n EnginePipelineContext,\n)\n\nfrom options_portfolio_backtester.data.providers import HistoricalOptionsData, TiingoData\nfrom options_portfolio_backtester.data.schema import Schema\nfrom options_portfolio_backtester.strategy.strategy import Strategy\nfrom options_portfolio_backtester.strategy.strategy_leg import StrategyLeg\n\nlogger = logging.getLogger(__name__)\n\n\ndef _intrinsic_value(option_type: str, strike: float, underlying_price: float) -> float:\n \"\"\"Compute intrinsic value of an option given spot price.\n\n For puts: max(0, strike - spot)\n For calls: max(0, spot - strike)\n \"\"\"\n if option_type == OptionType.CALL.value:\n return max(0.0, underlying_price - strike)\n return max(0.0, strike - underlying_price)\n\n\n@dataclass\nclass _StrategySlot:\n \"\"\"Configuration and runtime state for one strategy within a multi-strategy engine.\"\"\"\n strategy: Strategy\n weight: float\n rebalance_freq: int\n rebalance_unit: str = 'BMS'\n check_exits_daily: bool = False\n name: str = \"\"\n inventory: pd.DataFrame = field(default=None, repr=False)\n rebalance_dates: pd.DatetimeIndex = field(default=None, repr=False)\n\n\nclass BacktestEngine:\n \"\"\"Orchestrates backtest with pluggable execution components.\n\n Composes data providers, strategy legs, cost/fill/sizer/selector models,\n and risk constraints into a single backtest loop. Dispatches to Rust\n for all supported configurations.\n \"\"\"\n\n def __init__(\n self,\n allocation: dict[str, float],\n initial_capital: int = 1_000_000,\n shares_per_contract: int = 100,\n cost_model: TransactionCostModel | None = None,\n fill_model: FillModel | None = None,\n sizer: PositionSizer | None = None,\n signal_selector: SignalSelector | None = None,\n risk_manager: RiskManager | None = None,\n algos: list[EngineAlgo] | None = None,\n stop_if_broke: bool = False,\n max_notional_pct: float | None = None,\n ) -> None:\n assets = (\"stocks\", \"options\", \"cash\")\n self._raw_allocation = {a: allocation.get(a, 0.0) for a in assets}\n total_allocation = sum(self._raw_allocation.values())\n\n self.allocation: dict[str, float] = {}\n for asset in assets:\n self.allocation[asset] = self._raw_allocation[asset] / total_allocation\n\n self.initial_capital = initial_capital\n self.shares_per_contract = shares_per_contract\n self.cost_model = cost_model or NoCosts()\n self.fill_model = fill_model or MarketAtBidAsk()\n self.sizer = sizer or CapitalBased()\n self.signal_selector = signal_selector or FirstMatch()\n self.risk_manager = risk_manager or RiskManager()\n self.algos = list(algos or [])\n self.stop_if_broke = stop_if_broke\n self.max_notional_pct = max_notional_pct\n\n self.options_budget_pct: float | None = None\n self.options_budget_annual_pct: float | None = None\n self._stocks: list[Stock] = []\n self._options_strategy: Strategy | None = None\n self._stocks_data: TiingoData | None = None\n self._options_data: HistoricalOptionsData | None = None\n self.run_metadata: dict[str, Any] = {}\n self._event_log_rows: list[dict[str, Any]] = []\n\n # -- Properties (same API as original Backtest) --\n\n @property\n def stocks(self) -> list[Stock]:\n return self._stocks\n\n @stocks.setter\n def stocks(self, stocks: list[Stock]) -> None:\n assert np.isclose(sum(s.percentage for s in stocks), 1.0, atol=1e-6)\n self._stocks = list(stocks)\n\n @property\n def options_strategy(self) -> Strategy | None:\n return self._options_strategy\n\n @options_strategy.setter\n def options_strategy(self, strat: Strategy) -> None:\n self._options_strategy = strat\n\n @property\n def stocks_data(self) -> TiingoData | None:\n return self._stocks_data\n\n @stocks_data.setter\n def stocks_data(self, data: TiingoData) -> None:\n self._stocks_schema = data.schema\n self._stocks_data = data\n\n @property\n def options_data(self) -> HistoricalOptionsData | None:\n return self._options_data\n\n @options_data.setter\n def options_data(self, data: HistoricalOptionsData) -> None:\n self._options_schema = data.schema\n self._options_data = data\n\n # -- Multi-strategy API --\n\n def add_strategy(\n self,\n strategy: Strategy,\n weight: float,\n rebalance_freq: int,\n rebalance_unit: str = 'BMS',\n check_exits_daily: bool = False,\n name: str | None = None,\n ) -> None:\n \"\"\"Register a strategy slot for multi-strategy mode.\n\n Args:\n strategy: The Strategy object (legs + exit thresholds).\n weight: Fraction of options allocation for this strategy.\n rebalance_freq: Rebalance every N periods.\n rebalance_unit: Pandas offset alias (default 'BMS').\n check_exits_daily: Check exits on non-rebalance days.\n name: Human-readable name (auto-generated if omitted).\n \"\"\"\n if not hasattr(self, '_strategy_slots'):\n self._strategy_slots: list[_StrategySlot] = []\n slot_name = name or f\"strategy_{len(self._strategy_slots)}\"\n self._strategy_slots.append(_StrategySlot(\n strategy=strategy,\n weight=weight,\n rebalance_freq=rebalance_freq,\n rebalance_unit=rebalance_unit,\n check_exits_daily=check_exits_daily,\n name=slot_name,\n ))\n\n @property\n def _is_multi_strategy(self) -> bool:\n return hasattr(self, '_strategy_slots') and len(self._strategy_slots) > 0\n\n # -- Main entry point --\n\n def run(self, rebalance_freq: int = 0, monthly: bool = False,\n sma_days: int | None = None,\n rebalance_unit: str = 'BMS',\n check_exits_daily: bool = False) -> pd.DataFrame:\n \"\"\"Run the backtest. Returns the trade log DataFrame.\n\n Args:\n check_exits_daily: When True, evaluate exit filters on every trading\n day (not just rebalancing days). Positions that match the exit\n filter are closed and cash is updated, but no new entries or\n stock reallocation occurs outside rebalancing days.\n \"\"\"\n self._event_log_rows = []\n for algo in self.algos:\n if hasattr(algo, \"reset\"):\n algo.reset()\n assert self._stocks_data, \"Stock data not set\"\n assert all(\n stock.symbol in self._stocks_data[\"symbol\"].values\n for stock in self._stocks\n ), \"Ensure all stocks in portfolio are present in the data\"\n assert self._options_data, \"Options data not set\"\n\n # Multi-strategy mode\n if self._is_multi_strategy:\n total_weight = sum(s.weight for s in self._strategy_slots)\n assert abs(total_weight - 1.0) < 1e-6, (\n f\"Strategy weights must sum to 1.0, got {total_weight}\"\n )\n for slot in self._strategy_slots:\n assert self._options_data.schema == slot.strategy.schema\n return self._run_rust_multi(\n monthly=monthly, sma_days=sma_days,\n check_exits_daily=check_exits_daily,\n )\n\n assert self._options_strategy, \"Options Strategy not set\"\n assert self._options_data.schema == self._options_strategy.schema\n\n option_dates = self._options_data[\"date\"].unique()\n stock_dates = self.stocks_data[\"date\"].unique()\n assert np.array_equal(stock_dates, option_dates)\n\n # Translate algos to Rust-compatible config fields before dispatch.\n if self.algos:\n self._translate_algos_to_config()\n\n return self._run_rust(\n rebalance_freq,\n monthly=monthly,\n sma_days=sma_days,\n rebalance_unit=rebalance_unit,\n check_exits_daily=check_exits_daily,\n )\n\n def events_dataframe(self) -> pd.DataFrame:\n \"\"\"Structured execution event log for debugging and audit.\n\n The ``data`` dict from each event is flattened into top-level columns\n so that the result can be filtered directly (e.g.\n ``df[df[\"cash\"] > 0]``).\n \"\"\"\n if not self._event_log_rows:\n return pd.DataFrame(columns=[\"date\", \"event\", \"status\"])\n flat = []\n for row in self._event_log_rows:\n entry = {\"date\": row[\"date\"], \"event\": row[\"event\"], \"status\": row[\"status\"]}\n entry.update(row.get(\"data\", {}))\n flat.append(entry)\n return pd.DataFrame(flat)\n\n def _translate_algos_to_config(self) -> None:\n \"\"\"Translate algo pipeline into Rust-compatible engine config fields.\n\n Each algo type maps to an existing Rust feature:\n - EngineRunMonthly → rebalance_unit='BMS' + rebalance_freq=1 (already handled)\n - BudgetPercent → options_budget_pct\n - RangeFilter/SelectByDelta/SelectByDTE/IVRankFilter → entry filter conjunction\n - MaxGreekExposure → risk_constraints (MaxDelta/MaxVega)\n - ExitOnThreshold → profit_pct/loss_pct on strategy\n\n After translation, self.algos is cleared so the Rust gate passes.\n \"\"\"\n from options_portfolio_backtester.engine.algo_adapters import (\n EngineRunMonthly, BudgetPercent, RangeFilter,\n MaxGreekExposure, ExitOnThreshold,\n )\n from options_portfolio_backtester.portfolio.risk import RiskManager\n\n for algo in self.algos:\n if isinstance(algo, EngineRunMonthly):\n # Already handled by rebalance_unit='BMS' + rebalance_freq=1.\n # If user set algos=[EngineRunMonthly()], it's a no-op for Rust.\n pass\n elif isinstance(algo, BudgetPercent):\n self.options_budget_pct = algo.pct\n elif isinstance(algo, RangeFilter):\n # Append range condition to each leg's entry filter as conjunction.\n col, lo, hi = algo.column, algo.min_val, algo.max_val\n clause = f\"({col} >= {lo}) & ({col} <= {hi})\"\n for leg in self._options_strategy.legs:\n existing = leg.entry_filter.query\n if existing:\n leg.entry_filter.query = f\"({existing}) & ({clause})\"\n else:\n leg.entry_filter.query = clause\n elif isinstance(algo, MaxGreekExposure):\n if algo.max_abs_delta is not None:\n self.risk_manager.add_constraint(\n type(\"MaxDelta\", (), {\n \"to_rust_config\": lambda self_: {\"type\": \"MaxDelta\", \"limit\": algo.max_abs_delta},\n \"is_allowed\": lambda self_, cg, pg, pv, pk: (\n abs(cg.delta + pg.delta) <= algo.max_abs_delta, \"\"\n ),\n })()\n )\n if algo.max_abs_vega is not None:\n self.risk_manager.add_constraint(\n type(\"MaxVega\", (), {\n \"to_rust_config\": lambda self_: {\"type\": \"MaxVega\", \"limit\": algo.max_abs_vega},\n \"is_allowed\": lambda self_, cg, pg, pv, pk: (\n abs(cg.vega + pg.vega) <= algo.max_abs_vega, \"\"\n ),\n })()\n )\n elif isinstance(algo, ExitOnThreshold):\n import math\n if not math.isinf(algo.profit_pct):\n self._options_strategy.add_exit_thresholds(\n profit_pct=algo.profit_pct,\n loss_pct=self._options_strategy.exit_thresholds[1],\n )\n if not math.isinf(algo.loss_pct):\n self._options_strategy.add_exit_thresholds(\n profit_pct=self._options_strategy.exit_thresholds[0],\n loss_pct=algo.loss_pct,\n )\n else:\n raise ValueError(\n f\"Unsupported algo type for Rust dispatch: {type(algo).__name__}. \"\n f\"All execution runs through Rust; translate to config fields.\"\n )\n self.algos.clear()\n\n def _run_rust(\n self,\n rebalance_freq: int,\n monthly: bool,\n sma_days: int | None,\n rebalance_unit: str = 'BMS',\n check_exits_daily: bool = False,\n ) -> pd.DataFrame:\n \"\"\"Run the backtest using the Rust full-loop implementation.\"\"\"\n import math\n import pyarrow as pa\n import polars as pl\n\n strategy = self._options_strategy\n\n # Compute rebalance dates for the Rust backtest loop.\n dates_df = (\n pd.DataFrame(self.options_data._data[[\"quotedate\", \"volume\"]])\n .drop_duplicates(\"quotedate\")\n .set_index(\"quotedate\")\n )\n if rebalance_freq:\n rebalancing_days = pd.to_datetime(\n dates_df.groupby(pd.Grouper(freq=f\"{rebalance_freq}{rebalance_unit}\"))\n .apply(lambda x: x.index.min())\n .values\n )\n # Pass rebalance dates as i64 nanoseconds (matching Polars Datetime(ns))\n rb_date_ns = [int(d.value) for d in rebalancing_days if not pd.isna(d)]\n else:\n rb_date_ns = []\n\n opts_date_col = self._options_schema[\"date\"]\n stocks_date_col = self._stocks_schema[\"date\"]\n exp_col = self._options_schema[\"expiration\"]\n\n # Drop columns Rust never accesses to reduce Arrow conversion cost.\n _drop_cols = {\"underlying_last\", \"last\", \"optionalias\", \"impliedvol\"}\n # Also drop openinterest unless MaxOpenInterest selector is in use\n if not (hasattr(self.signal_selector, '__class__')\n and self.signal_selector.__class__.__name__ == 'MaxOpenInterest'):\n _drop_cols.add(\"openinterest\")\n opts_df = self._options_data._data\n to_drop = [c for c in _drop_cols if c in opts_df.columns]\n opts_src = opts_df.drop(columns=to_drop) if to_drop else opts_df\n\n # Convert pandas → PyArrow → Polars (avoids intermediate copies).\n opts_pl = pl.from_arrow(pa.Table.from_pandas(opts_src, preserve_index=False))\n stocks_pl = pl.from_arrow(\n pa.Table.from_pandas(self._stocks_data._data, preserve_index=False)\n )\n\n leg_configs = []\n for leg in strategy.legs:\n lc = {\n \"name\": leg.name,\n \"entry_filter\": leg.entry_filter.query,\n \"exit_filter\": leg.exit_filter.query,\n \"direction\": leg.direction.price_column,\n \"type\": leg.type.value,\n \"entry_sort_col\": leg.entry_sort[0] if leg.entry_sort else None,\n \"entry_sort_asc\": leg.entry_sort[1] if leg.entry_sort else True,\n }\n # Per-leg overrides\n leg_sel = getattr(leg, 'signal_selector', None)\n if leg_sel is not None and hasattr(leg_sel, 'to_rust_config'):\n lc[\"signal_selector\"] = leg_sel.to_rust_config()\n leg_fill = getattr(leg, 'fill_model', None)\n if leg_fill is not None and hasattr(leg_fill, 'to_rust_config'):\n lc[\"fill_model\"] = leg_fill.to_rust_config()\n leg_configs.append(lc)\n\n config = {\n \"allocation\": self.allocation,\n \"initial_capital\": float(self.initial_capital),\n \"shares_per_contract\": self.shares_per_contract,\n \"rebalance_dates\": rb_date_ns,\n \"legs\": leg_configs,\n \"profit_pct\": (\n strategy.exit_thresholds[0]\n if strategy.exit_thresholds[0] != math.inf else None\n ),\n \"loss_pct\": (\n strategy.exit_thresholds[1]\n if strategy.exit_thresholds[1] != math.inf else None\n ),\n \"stocks\": [(s.symbol, s.percentage) for s in self._stocks],\n \"cost_model\": self.cost_model.to_rust_config(),\n \"fill_model\": self.fill_model.to_rust_config(),\n \"signal_selector\": self.signal_selector.to_rust_config(),\n \"risk_constraints\": [c.to_rust_config() for c in self.risk_manager.constraints],\n \"sma_days\": sma_days,\n \"options_budget_pct\": self.options_budget_pct,\n \"options_budget_annual_pct\": self.options_budget_annual_pct,\n \"stop_if_broke\": self.stop_if_broke,\n \"max_notional_pct\": self.max_notional_pct,\n \"check_exits_daily\": check_exits_daily,\n }\n\n schema_mapping = {\n \"contract\": self._options_schema[\"contract\"],\n \"date\": opts_date_col,\n \"stocks_date\": stocks_date_col,\n \"stocks_symbol\": self._stocks_schema[\"symbol\"],\n \"stocks_price\": self._stocks_schema[\"adjClose\"],\n \"underlying\": self._options_schema[\"underlying\"],\n \"expiration\": self._options_schema[\"expiration\"],\n \"type\": self._options_schema[\"type\"],\n \"strike\": self._options_schema[\"strike\"],\n }\n\n balance_pl, trade_log_pl, stats = _ob_rust.run_backtest_py(\n opts_pl, stocks_pl, config, schema_mapping,\n )\n\n # Convert trade log from flat columns to MultiIndex\n trade_log_pd = trade_log_pl.to_pandas()\n self.trade_log = self._flat_trade_log_to_multiindex(trade_log_pd)\n\n # Convert balance\n self.balance = balance_pl.to_pandas()\n if \"date\" in self.balance.columns:\n self.balance[\"date\"] = pd.to_datetime(self.balance[\"date\"])\n self.balance.set_index(\"date\", inplace=True)\n\n # Add initial balance row (day before first rebalance) — matches Python\n initial_date = self.stocks_data.start_date - pd.Timedelta(1, unit=\"day\")\n initial_row = pd.DataFrame(\n {\"total capital\": self.initial_capital, \"cash\": float(self.initial_capital)},\n index=[initial_date],\n )\n self.balance = pd.concat([initial_row, self.balance], sort=False)\n for col_name in self.balance.columns:\n self.balance[col_name] = pd.to_numeric(self.balance[col_name], errors=\"coerce\")\n\n # Ensure per-stock columns exist (match Python's balance format)\n for stock in self._stocks:\n sym = stock.symbol\n if sym not in self.balance.columns:\n self.balance[sym] = 0.0\n if f\"{sym} qty\" not in self.balance.columns:\n self.balance[f\"{sym} qty\"] = 0.0\n for col_name in [\"options qty\", \"stocks qty\", \"calls capital\", \"puts capital\"]:\n if col_name not in self.balance.columns:\n self.balance[col_name] = 0.0\n\n # Add derived columns matching Python output\n self.balance[\"options capital\"] = (\n self.balance[\"calls capital\"] + self.balance[\"puts capital\"]\n ).fillna(0)\n stock_cols = [s.symbol for s in self._stocks]\n self.balance[\"stocks capital\"] = sum(\n self.balance.get(c, 0) for c in stock_cols\n )\n first_idx = self.balance.index[0]\n self.balance.loc[first_idx, \"stocks capital\"] = 0\n self.balance.loc[first_idx, \"options capital\"] = 0\n self.balance[\"total capital\"] = (\n self.balance[\"cash\"]\n + self.balance[\"stocks capital\"]\n + self.balance[\"options capital\"]\n )\n self.balance[\"% change\"] = self.balance[\"total capital\"].pct_change()\n self.balance[\"accumulated return\"] = (1.0 + self.balance[\"% change\"]).cumprod()\n\n # Set current_cash to match Python loop's final state after rebalancing\n # (after the loop, all capital is allocated to stocks/options/cash per allocation)\n final_total = self.balance[\"total capital\"].iloc[-1]\n self.current_cash = self.allocation[\"cash\"] * final_total\n self._initialize_inventories()\n self._portfolio = Portfolio(initial_cash=self.current_cash)\n self._attach_run_metadata(\n rebalance_freq=rebalance_freq,\n monthly=monthly,\n sma_days=sma_days,\n )\n\n return self.trade_log\n\n def _run_rust_multi(\n self,\n monthly: bool = False,\n sma_days: int | None = None,\n check_exits_daily: bool = False,\n ) -> pd.DataFrame:\n \"\"\"Run multi-strategy backtest using Rust backend.\"\"\"\n import math\n import pyarrow as pa\n import polars as pl\n\n opts_date_col = self._options_schema[\"date\"]\n stocks_date_col = self._stocks_schema[\"date\"]\n\n # Drop unused columns for Arrow conversion speed\n _drop_cols = {\"underlying_last\", \"last\", \"optionalias\", \"impliedvol\"}\n opts_df = self._options_data._data\n to_drop = [c for c in _drop_cols if c in opts_df.columns]\n opts_src = opts_df.drop(columns=to_drop) if to_drop else opts_df\n\n opts_pl = pl.from_arrow(pa.Table.from_pandas(opts_src, preserve_index=False))\n stocks_pl = pl.from_arrow(\n pa.Table.from_pandas(self._stocks_data._data, preserve_index=False)\n )\n\n # Compute per-slot rebalance dates\n dates_df = (\n pd.DataFrame(self.options_data._data[[\"quotedate\", \"volume\"]])\n .drop_duplicates(\"quotedate\")\n .set_index(\"quotedate\")\n )\n\n slot_configs = []\n for slot in self._strategy_slots:\n if slot.rebalance_freq:\n rb_dates = pd.to_datetime(\n dates_df.groupby(\n pd.Grouper(freq=f\"{slot.rebalance_freq}{slot.rebalance_unit}\")\n ).apply(lambda x: x.index.min()).values\n )\n rb_date_ns = [int(d.value) for d in rb_dates if not pd.isna(d)]\n else:\n rb_date_ns = []\n\n leg_configs = []\n for leg in slot.strategy.legs:\n lc = {\n \"name\": leg.name,\n \"entry_filter\": leg.entry_filter.query,\n \"exit_filter\": leg.exit_filter.query,\n \"direction\": leg.direction.price_column,\n \"type\": leg.type.value,\n \"entry_sort_col\": leg.entry_sort[0] if leg.entry_sort else None,\n \"entry_sort_asc\": leg.entry_sort[1] if leg.entry_sort else True,\n }\n leg_sel = getattr(leg, 'signal_selector', None)\n if leg_sel is not None and hasattr(leg_sel, 'to_rust_config'):\n lc[\"signal_selector\"] = leg_sel.to_rust_config()\n leg_fill = getattr(leg, 'fill_model', None)\n if leg_fill is not None and hasattr(leg_fill, 'to_rust_config'):\n lc[\"fill_model\"] = leg_fill.to_rust_config()\n leg_configs.append(lc)\n\n slot_configs.append({\n \"name\": slot.name,\n \"legs\": leg_configs,\n \"weight\": slot.weight,\n \"rebalance_dates\": rb_date_ns,\n \"profit_pct\": (\n slot.strategy.exit_thresholds[0]\n if slot.strategy.exit_thresholds[0] != math.inf else None\n ),\n \"loss_pct\": (\n slot.strategy.exit_thresholds[1]\n if slot.strategy.exit_thresholds[1] != math.inf else None\n ),\n \"check_exits_daily\": slot.check_exits_daily,\n })\n\n config = {\n \"allocation\": self.allocation,\n \"initial_capital\": float(self.initial_capital),\n \"shares_per_contract\": self.shares_per_contract,\n \"rebalance_dates\": [], # Not used for multi-strategy; per-slot instead\n \"legs\": [], # Not used for multi-strategy; per-slot instead\n \"stocks\": [(s.symbol, s.percentage) for s in self._stocks],\n \"cost_model\": self.cost_model.to_rust_config(),\n \"fill_model\": self.fill_model.to_rust_config(),\n \"signal_selector\": self.signal_selector.to_rust_config(),\n \"risk_constraints\": [c.to_rust_config() for c in self.risk_manager.constraints],\n \"sma_days\": sma_days,\n \"options_budget_pct\": self.options_budget_pct,\n \"options_budget_annual_pct\": self.options_budget_annual_pct,\n \"stop_if_broke\": self.stop_if_broke,\n \"max_notional_pct\": self.max_notional_pct,\n \"check_exits_daily\": check_exits_daily,\n }\n\n schema_mapping = {\n \"contract\": self._options_schema[\"contract\"],\n \"date\": opts_date_col,\n \"stocks_date\": stocks_date_col,\n \"stocks_symbol\": self._stocks_schema[\"symbol\"],\n \"stocks_price\": self._stocks_schema[\"adjClose\"],\n \"underlying\": self._options_schema[\"underlying\"],\n \"expiration\": self._options_schema[\"expiration\"],\n \"type\": self._options_schema[\"type\"],\n \"strike\": self._options_schema[\"strike\"],\n }\n\n balance_pl, trade_log_pl, stats = _ob_rust.run_multi_strategy_py(\n opts_pl, stocks_pl, config, schema_mapping, slot_configs,\n )\n\n # Convert trade log\n trade_log_pd = trade_log_pl.to_pandas()\n self.trade_log = self._flat_trade_log_to_multiindex(trade_log_pd)\n\n # Convert balance\n self.balance = balance_pl.to_pandas()\n if \"date\" in self.balance.columns:\n self.balance[\"date\"] = pd.to_datetime(self.balance[\"date\"])\n self.balance.set_index(\"date\", inplace=True)\n\n # Add initial balance row\n initial_date = self.stocks_data.start_date - pd.Timedelta(1, unit=\"day\")\n initial_row = pd.DataFrame(\n {\"total capital\": self.initial_capital, \"cash\": float(self.initial_capital)},\n index=[initial_date],\n )\n self.balance = pd.concat([initial_row, self.balance], sort=False)\n for col_name in self.balance.columns:\n self.balance[col_name] = pd.to_numeric(self.balance[col_name], errors=\"coerce\")\n\n # Ensure per-stock columns exist\n for stock in self._stocks:\n sym = stock.symbol\n if sym not in self.balance.columns:\n self.balance[sym] = 0.0\n if f\"{sym} qty\" not in self.balance.columns:\n self.balance[f\"{sym} qty\"] = 0.0\n for col_name in [\"options qty\", \"stocks qty\", \"calls capital\", \"puts capital\"]:\n if col_name not in self.balance.columns:\n self.balance[col_name] = 0.0\n\n # Add derived columns\n self.balance[\"options capital\"] = (\n self.balance[\"calls capital\"] + self.balance[\"puts capital\"]\n ).fillna(0)\n stock_cols = [s.symbol for s in self._stocks]\n self.balance[\"stocks capital\"] = sum(\n self.balance.get(c, 0) for c in stock_cols\n )\n first_idx = self.balance.index[0]\n self.balance.loc[first_idx, \"stocks capital\"] = 0\n self.balance.loc[first_idx, \"options capital\"] = 0\n self.balance[\"total capital\"] = (\n self.balance[\"cash\"]\n + self.balance[\"stocks capital\"]\n + self.balance[\"options capital\"]\n )\n self.balance[\"% change\"] = self.balance[\"total capital\"].pct_change()\n self.balance[\"accumulated return\"] = (1.0 + self.balance[\"% change\"]).cumprod()\n\n final_total = self.balance[\"total capital\"].iloc[-1]\n self.current_cash = self.allocation[\"cash\"] * final_total\n self._attach_run_metadata(\n rebalance_freq=0,\n monthly=monthly,\n sma_days=sma_days,\n )\n\n return self.trade_log\n\n def _attach_run_metadata(\n self,\n rebalance_freq: int,\n monthly: bool,\n sma_days: int | None,\n ) -> None:\n metadata = self._build_run_metadata(\n rebalance_freq=rebalance_freq,\n monthly=monthly,\n sma_days=sma_days,\n )\n self.run_metadata = metadata\n self.balance.attrs[\"run_metadata\"] = metadata\n self.trade_log.attrs[\"run_metadata\"] = metadata\n\n def _build_run_metadata(\n self,\n rebalance_freq: int,\n monthly: bool,\n sma_days: int | None,\n ) -> dict[str, Any]:\n stocks = [\n {\"symbol\": stock.symbol, \"percentage\": float(stock.percentage)}\n for stock in self._stocks\n ]\n run_config = {\n \"allocation\": {k: float(v) for k, v in self.allocation.items()},\n \"initial_capital\": float(self.initial_capital),\n \"shares_per_contract\": int(self.shares_per_contract),\n \"rebalance_freq\": int(rebalance_freq),\n \"monthly\": bool(monthly),\n \"sma_days\": int(sma_days) if sma_days is not None else None,\n \"stocks\": stocks,\n }\n data_snapshot = self._data_snapshot()\n return {\n \"framework\": \"options_portfolio_backtester.engine.BacktestEngine\",\n \"git_sha\": self._git_sha(),\n \"run_at_utc\": datetime.now(timezone.utc).isoformat(),\n \"config_hash\": self._sha256_json(run_config),\n \"data_snapshot_hash\": self._sha256_json(data_snapshot),\n \"data_snapshot\": data_snapshot,\n }\n\n def _data_snapshot(self) -> dict[str, Any]:\n options_dates = self._options_data[\"date\"]\n stocks_dates = self._stocks_data[\"date\"]\n return {\n \"options_rows\": int(len(self._options_data._data)),\n \"stocks_rows\": int(len(self._stocks_data._data)),\n \"options_date_start\": pd.Timestamp(options_dates.min()).isoformat(),\n \"options_date_end\": pd.Timestamp(options_dates.max()).isoformat(),\n \"stocks_date_start\": pd.Timestamp(stocks_dates.min()).isoformat(),\n \"stocks_date_end\": pd.Timestamp(stocks_dates.max()).isoformat(),\n \"options_columns\": list(self._options_data._data.columns),\n \"stocks_columns\": list(self._stocks_data._data.columns),\n }\n\n @staticmethod\n def _sha256_json(payload: dict[str, Any]) -> str:\n blob = json.dumps(payload, sort_keys=True, separators=(\",\", \":\"), default=str)\n return hashlib.sha256(blob.encode(\"utf-8\")).hexdigest()\n\n @staticmethod\n def _git_sha() -> str:\n repo_root = Path(__file__).resolve().parents[2]\n try:\n proc = subprocess.run(\n [\"git\", \"rev-parse\", \"HEAD\"],\n cwd=repo_root,\n check=True,\n capture_output=True,\n text=True,\n )\n return proc.stdout.strip()\n except Exception:\n return \"unknown\"\n\n def _flat_trade_log_to_multiindex(self, flat_df: pd.DataFrame) -> pd.DataFrame:\n \"\"\"Convert flat 'leg__field' columns from Rust to MultiIndex DataFrame.\"\"\"\n if flat_df.empty:\n return pd.DataFrame()\n tuples = []\n for c in flat_df.columns:\n if \"__\" in c:\n parts = c.split(\"__\", 1)\n tuples.append((parts[0], parts[1]))\n else:\n tuples.append((\"\", c))\n flat_df.columns = pd.MultiIndex.from_tuples(tuples)\n return flat_df\n\n # -- Internals (same logic as original, with pluggable components) --\n\n def _initialize_inventories(self) -> None:\n columns = pd.MultiIndex.from_product(\n [\n [leg.name for leg in self._options_strategy.legs],\n [\"contract\", \"underlying\", \"expiration\", \"type\", \"strike\", \"cost\", \"order\"],\n ]\n )\n totals = pd.MultiIndex.from_product([[\"totals\"], [\"cost\", \"qty\", \"date\"]])\n self._options_inventory: pd.DataFrame = pd.DataFrame(\n columns=pd.Index(columns.tolist() + totals.tolist())\n )\n self._stocks_inventory: pd.DataFrame = pd.DataFrame(\n columns=[\"symbol\", \"price\", \"qty\"]\n )\n # Portfolio dataclass — dual-write alongside legacy DataFrames\n self._portfolio = Portfolio(initial_cash=0.0)\n\n def _current_options_capital(self, options, stocks):\n options_value = self._get_current_option_quotes(options)\n values_by_row: Any = [0] * len(options_value[0])\n if len(options_value[0]) != 0:\n sym_col = self._stocks_schema[\"symbol\"]\n # Use unadjusted close for intrinsic value — strikes are raw prices\n _close_col = self._stocks_schema[\"close\"] if \"close\" in self._stocks_schema else None\n price_col = _close_col if (_close_col and _close_col in stocks.columns) else self._stocks_schema[\"adjClose\"]\n for i, leg in enumerate(self._options_strategy.legs):\n cost_series = options_value[i][\"cost\"].copy()\n # Replace NaN (missing contracts) with intrinsic value\n if cost_series.isna().any():\n inv_leg = self._options_inventory[leg.name]\n for idx in cost_series.index[cost_series.isna()]:\n opt_type = inv_leg.at[idx, \"type\"]\n strike = inv_leg.at[idx, \"strike\"]\n underlying = inv_leg.at[idx, \"underlying\"]\n spot_match = stocks.loc[stocks[sym_col] == underlying, price_col]\n spot = spot_match.iloc[0] if len(spot_match) > 0 else 0.0\n iv = _intrinsic_value(opt_type, float(strike), float(spot))\n cash_sign = -1.0 if ~leg.direction == Direction.SELL else 1.0\n cost_series.at[idx] = cash_sign * iv * self.shares_per_contract\n values_by_row += cost_series.values\n total: float = -sum(values_by_row * self._options_inventory[\"totals\"][\"qty\"].values)\n else:\n total = 0\n return total\n\n def _get_current_option_quotes(self, options):\n current_options_quotes: list[pd.DataFrame] = []\n for leg in self._options_strategy.legs:\n inventory_leg = self._options_inventory[leg.name]\n leg_options = inventory_leg[[\"contract\"]].merge(\n options, how=\"left\",\n left_on=\"contract\", right_on=leg.schema[\"contract\"],\n )\n leg_options.index = self._options_inventory.index\n leg_options[\"order\"] = get_order(leg.direction, Signal.EXIT)\n leg_options[\"cost\"] = leg_options[self._options_schema[(~leg.direction).price_column]]\n\n if ~leg.direction == Direction.SELL:\n leg_options[\"cost\"] = -leg_options[\"cost\"]\n leg_options[\"cost\"] *= self.shares_per_contract\n current_options_quotes.append(leg_options)\n return current_options_quotes\n\n def __repr__(self) -> str:\n return (\n f\"BacktestEngine(capital={self.initial_capital}, \"\n f\"allocation={self.allocation}, \"\n f\"cost_model={self.cost_model.__class__.__name__})\"\n )\n\n"
},
{
"path": "options_portfolio_backtester/engine/multi_strategy.py",
"content": "\"\"\"Multi-strategy engine — run N strategies with shared capital and risk budget.\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import Any\n\nimport pandas as pd\n\nfrom options_portfolio_backtester.engine.engine import BacktestEngine\nfrom options_portfolio_backtester.execution.cost_model import TransactionCostModel, NoCosts\nfrom options_portfolio_backtester.portfolio.risk import RiskManager\n\nfrom options_portfolio_backtester.core.types import Stock\n\n\nclass StrategyAllocation:\n \"\"\"Configuration for one strategy within a multi-strategy engine.\"\"\"\n\n def __init__(\n self,\n name: str,\n engine: BacktestEngine,\n weight: float = 1.0,\n ) -> None:\n self.name = name\n self.engine = engine\n self.weight = weight\n\n\nclass MultiStrategyEngine:\n \"\"\"Run multiple strategies with shared capital allocation.\n\n Each strategy gets a fraction of total capital proportional to its weight.\n Results are combined into a single balance sheet.\n \"\"\"\n\n def __init__(\n self,\n strategies: list[StrategyAllocation],\n initial_capital: int = 1_000_000,\n ) -> None:\n self.strategies = strategies\n self.initial_capital = initial_capital\n total_weight = sum(s.weight for s in strategies)\n self._weights = {s.name: s.weight / total_weight for s in strategies}\n\n def run(self, rebalance_freq: int = 0, monthly: bool = False,\n sma_days: int | None = None) -> dict[str, pd.DataFrame]:\n \"\"\"Run all strategies and return per-strategy trade logs.\n\n Returns:\n Dict mapping strategy name to its trade log DataFrame.\n \"\"\"\n results: dict[str, pd.DataFrame] = {}\n\n for sa in self.strategies:\n capital_share = int(self.initial_capital * self._weights[sa.name])\n # Override the engine's initial capital with its share\n sa.engine.initial_capital = capital_share\n trade_log = sa.engine.run(\n rebalance_freq=rebalance_freq,\n monthly=monthly,\n sma_days=sma_days,\n )\n results[sa.name] = trade_log\n\n # Build combined balance\n self._build_combined_balance()\n return results\n\n def _build_combined_balance(self) -> None:\n \"\"\"Combine balance sheets from all strategies.\"\"\"\n balances = []\n for sa in self.strategies:\n if hasattr(sa.engine, \"balance\"):\n b = sa.engine.balance[[\"total capital\", \"% change\"]].copy()\n b.columns = [f\"{sa.name}_capital\", f\"{sa.name}_pct_change\"]\n balances.append(b)\n\n if balances:\n self.balance = pd.concat(balances, axis=1)\n capital_cols = [f\"{sa.name}_capital\" for sa in self.strategies]\n self.balance[\"total capital\"] = self.balance[capital_cols].sum(axis=1)\n self.balance[\"% change\"] = self.balance[\"total capital\"].pct_change()\n self.balance[\"accumulated return\"] = (\n 1.0 + self.balance[\"% change\"]\n ).cumprod()\n else:\n self.balance = pd.DataFrame()\n"
},
{
"path": "options_portfolio_backtester/engine/pipeline.py",
"content": "\"\"\"Composable algo pipeline for stock portfolio workflows.\n\nProvides bt-compatible scheduling, selection, weighting, and rebalancing algos.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport re as _re\nimport random as _random\nfrom dataclasses import dataclass, field\nfrom typing import Callable, Literal, Protocol, Sequence\n\nimport numpy as np\nimport pandas as pd\n\n\nStepStatus = Literal[\"continue\", \"skip_day\", \"stop\"]\n\n\n@dataclass(frozen=True)\nclass StepDecision:\n \"\"\"Outcome returned by a pipeline step.\"\"\"\n\n status: StepStatus = \"continue\"\n message: str = \"\"\n\n\n@dataclass\nclass PipelineContext:\n \"\"\"Mutable state shared across pipeline steps for one date.\"\"\"\n\n date: pd.Timestamp\n prices: pd.Series\n total_capital: float\n cash: float\n positions: dict[str, float]\n selected_symbols: list[str] = field(default_factory=list)\n target_weights: dict[str, float] = field(default_factory=dict)\n # Price history up to current date (set by AlgoPipelineBacktester).\n price_history: pd.DataFrame | None = None\n\n\n@dataclass(frozen=True)\nclass PipelineLogRow:\n date: pd.Timestamp\n step: str\n status: StepStatus\n message: str\n\n\nclass Algo(Protocol):\n \"\"\"Protocol for a pipeline step.\"\"\"\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n ...\n\n\n# ---------------------------------------------------------------------------\n# Scheduling algos\n# ---------------------------------------------------------------------------\n\nclass RunMonthly:\n \"\"\"Gate pipeline execution to month starts.\"\"\"\n\n def __init__(self) -> None:\n self._last_month: tuple[int, int] | None = None\n\n def reset(self) -> None:\n self._last_month = None\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n key = (ctx.date.year, ctx.date.month)\n if self._last_month == key:\n return StepDecision(status=\"skip_day\", message=\"not month-start\")\n self._last_month = key\n return StepDecision()\n\n\nclass RunWeekly:\n \"\"\"Gate pipeline execution to week starts (Monday).\"\"\"\n\n def __init__(self) -> None:\n self._last_week: tuple[int, int] | None = None\n\n def reset(self) -> None:\n self._last_week = None\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n key = (ctx.date.isocalendar()[0], ctx.date.isocalendar()[1])\n if self._last_week == key:\n return StepDecision(status=\"skip_day\", message=\"not week-start\")\n self._last_week = key\n return StepDecision()\n\n\nclass RunQuarterly:\n \"\"\"Gate pipeline execution to quarter starts.\"\"\"\n\n def __init__(self) -> None:\n self._last_quarter: tuple[int, int] | None = None\n\n def reset(self) -> None:\n self._last_quarter = None\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n key = (ctx.date.year, (ctx.date.month - 1) // 3)\n if self._last_quarter == key:\n return StepDecision(status=\"skip_day\", message=\"not quarter-start\")\n self._last_quarter = key\n return StepDecision()\n\n\nclass RunYearly:\n \"\"\"Gate pipeline execution to year starts.\"\"\"\n\n def __init__(self) -> None:\n self._last_year: int | None = None\n\n def reset(self) -> None:\n self._last_year = None\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if self._last_year == ctx.date.year:\n return StepDecision(status=\"skip_day\", message=\"not year-start\")\n self._last_year = ctx.date.year\n return StepDecision()\n\n\nclass RunDaily:\n \"\"\"Allow pipeline execution on every date (no gating).\"\"\"\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n return StepDecision()\n\n\nclass RunOnce:\n \"\"\"Execute pipeline only on the first date, skip all subsequent dates.\"\"\"\n\n def __init__(self) -> None:\n self._ran = False\n\n def reset(self) -> None:\n self._ran = False\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if self._ran:\n return StepDecision(status=\"skip_day\", message=\"already ran\")\n self._ran = True\n return StepDecision()\n\n\nclass RunOnDate:\n \"\"\"Execute pipeline only on specific dates.\"\"\"\n\n def __init__(self, dates: Sequence[str | pd.Timestamp]) -> None:\n self._dates = {pd.Timestamp(d).normalize() for d in dates}\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if ctx.date.normalize() not in self._dates:\n return StepDecision(status=\"skip_day\", message=\"not a target date\")\n return StepDecision()\n\n\nclass RunAfterDate:\n \"\"\"Execute pipeline only after a specific date (inclusive).\"\"\"\n\n def __init__(self, date: str | pd.Timestamp) -> None:\n self._date = pd.Timestamp(date).normalize()\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if ctx.date.normalize() < self._date:\n return StepDecision(status=\"skip_day\", message=\"before start date\")\n return StepDecision()\n\n\nclass RunEveryNPeriods:\n \"\"\"Execute pipeline every N trading days.\"\"\"\n\n def __init__(self, n: int) -> None:\n self._n = int(n)\n self._count = 0\n\n def reset(self) -> None:\n self._count = 0\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n self._count += 1\n if self._count % self._n != 1 and self._count != 1:\n return StepDecision(status=\"skip_day\", message=f\"period {self._count}, not every {self._n}\")\n return StepDecision()\n\n\nclass RunAfterDays:\n \"\"\"Warmup gate: skip the first *n* trading days.\"\"\"\n\n def __init__(self, n: int) -> None:\n self._n = int(n)\n self._count = 0\n\n def reset(self) -> None:\n self._count = 0\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n self._count += 1\n if self._count <= self._n:\n return StepDecision(status=\"skip_day\", message=f\"warmup day {self._count}/{self._n}\")\n return StepDecision()\n\n\nclass RunIfOutOfBounds:\n \"\"\"Trigger rebalance when any position drifts beyond *tolerance* from target.\n\n Typically used with ``Or``: ``Or(RunQuarterly(), RunIfOutOfBounds(0.05))``.\n Requires ``target_weights`` to have been set by a prior weighting algo\n on the *previous* rebalance (stored internally).\n \"\"\"\n\n def __init__(self, tolerance: float = 0.05) -> None:\n self._tolerance = float(tolerance)\n self._last_target: dict[str, float] = {}\n\n def reset(self) -> None:\n self._last_target = {}\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not self._last_target:\n # No previous target — let downstream algos set it, then remember\n return StepDecision(status=\"skip_day\", message=\"no prior target weights\")\n\n total = float(ctx.total_capital)\n if total <= 0:\n return StepDecision(status=\"skip_day\", message=\"no capital\")\n\n for sym, target_w in self._last_target.items():\n qty = ctx.positions.get(sym, 0.0)\n if sym in ctx.prices.index and pd.notna(ctx.prices[sym]):\n actual_w = float(qty) * float(ctx.prices[sym]) / total\n else:\n actual_w = 0.0\n if abs(actual_w - target_w) > self._tolerance:\n return StepDecision() # out of bounds → allow rebalance\n\n return StepDecision(status=\"skip_day\", message=\"all weights within bounds\")\n\n def update_target(self, weights: dict[str, float]) -> None:\n \"\"\"Call after a successful rebalance to remember the new target.\"\"\"\n self._last_target = dict(weights)\n\n\nclass Or:\n \"\"\"Logical OR combinator: pass if any child algo passes.\"\"\"\n\n def __init__(self, *algos: Algo) -> None:\n self._algos = algos\n\n def reset(self) -> None:\n for algo in self._algos:\n if hasattr(algo, \"reset\"):\n algo.reset()\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n for algo in self._algos:\n decision = algo(ctx)\n if decision.status == \"continue\":\n return StepDecision()\n return StepDecision(status=\"skip_day\", message=\"all sub-algos skipped\")\n\n\nclass Not:\n \"\"\"Logical NOT combinator: invert the child algo's decision.\"\"\"\n\n def __init__(self, algo: Algo) -> None:\n self._algo = algo\n\n def reset(self) -> None:\n if hasattr(self._algo, \"reset\"):\n self._algo.reset()\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n decision = self._algo(ctx)\n if decision.status == \"skip_day\":\n return StepDecision()\n return StepDecision(status=\"skip_day\", message=\"inverted\")\n\n\n# ---------------------------------------------------------------------------\n# Selection algos\n# ---------------------------------------------------------------------------\n\nclass SelectThese:\n \"\"\"Select a fixed list of symbols if priced on current date.\"\"\"\n\n def __init__(self, symbols: list[str]) -> None:\n self.symbols = [s.upper() for s in symbols]\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n available = [s for s in self.symbols if s in ctx.prices.index and pd.notna(ctx.prices[s])]\n ctx.selected_symbols = available\n if not available:\n return StepDecision(status=\"skip_day\", message=\"no selected symbols with valid prices\")\n return StepDecision()\n\n\nclass SelectAll:\n \"\"\"Select all symbols with valid prices on current date.\"\"\"\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n available = [s for s in ctx.prices.index if pd.notna(ctx.prices[s]) and float(ctx.prices[s]) > 0]\n ctx.selected_symbols = sorted(available)\n if not available:\n return StepDecision(status=\"skip_day\", message=\"no symbols with valid prices\")\n return StepDecision()\n\n\nclass SelectHasData:\n \"\"\"Select symbols that have at least *min_days* of price history.\"\"\"\n\n def __init__(self, min_days: int = 1) -> None:\n self._min_days = int(min_days)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if ctx.price_history is None or ctx.price_history.empty:\n return StepDecision(status=\"skip_day\", message=\"no price history\")\n keep = []\n for s in ctx.selected_symbols or list(ctx.prices.index):\n if s in ctx.price_history.columns:\n valid = ctx.price_history[s].dropna()\n if len(valid) >= self._min_days:\n keep.append(s)\n ctx.selected_symbols = keep\n if not keep:\n return StepDecision(status=\"skip_day\", message=f\"no symbols with {self._min_days}+ days\")\n return StepDecision()\n\n\nclass SelectMomentum:\n \"\"\"Select top *n* symbols by trailing momentum (total return over *lookback* days).\"\"\"\n\n def __init__(self, n: int, lookback: int = 252, sort_descending: bool = True) -> None:\n self._n = int(n)\n self._lookback = int(lookback)\n self._sort_desc = sort_descending\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if ctx.price_history is None or ctx.price_history.empty:\n return StepDecision(status=\"skip_day\", message=\"no price history for momentum\")\n candidates = ctx.selected_symbols or [\n s for s in ctx.prices.index if pd.notna(ctx.prices[s])\n ]\n scores: dict[str, float] = {}\n for s in candidates:\n if s not in ctx.price_history.columns:\n continue\n series = ctx.price_history[s].dropna()\n if len(series) < 2:\n continue\n window = series.iloc[-self._lookback:]\n if len(window) < 2 or float(window.iloc[0]) <= 0:\n continue\n scores[s] = float(window.iloc[-1] / window.iloc[0] - 1)\n ranked = sorted(scores, key=scores.get, reverse=self._sort_desc) # type: ignore[arg-type]\n ctx.selected_symbols = ranked[: self._n]\n if not ctx.selected_symbols:\n return StepDecision(status=\"skip_day\", message=\"no symbols with enough momentum data\")\n return StepDecision()\n\n\nclass SelectN:\n \"\"\"Keep the first *n* symbols from current selection (stable order).\"\"\"\n\n def __init__(self, n: int) -> None:\n self._n = int(n)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n ctx.selected_symbols = ctx.selected_symbols[: self._n]\n if not ctx.selected_symbols:\n return StepDecision(status=\"skip_day\", message=\"no symbols after SelectN\")\n return StepDecision()\n\n\nclass SelectRandomly:\n \"\"\"Select *n* symbols at random from the current selection.\"\"\"\n\n def __init__(self, n: int, seed: int | None = None) -> None:\n self._n = int(n)\n self._rng = _random.Random(seed)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n candidates = ctx.selected_symbols or [\n s for s in ctx.prices.index if pd.notna(ctx.prices[s])\n ]\n if not candidates:\n return StepDecision(status=\"skip_day\", message=\"no candidates for random selection\")\n k = min(self._n, len(candidates))\n ctx.selected_symbols = sorted(self._rng.sample(candidates, k))\n return StepDecision()\n\n\nclass SelectActive:\n \"\"\"Filter out symbols whose price is zero or NaN (dead/expired).\"\"\"\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n candidates = ctx.selected_symbols or list(ctx.prices.index)\n active = [\n s for s in candidates\n if s in ctx.prices.index and pd.notna(ctx.prices[s]) and float(ctx.prices[s]) > 0\n ]\n ctx.selected_symbols = active\n if not active:\n return StepDecision(status=\"skip_day\", message=\"no active symbols\")\n return StepDecision()\n\n\nclass SelectRegex:\n \"\"\"Select symbols whose name matches a regex pattern.\"\"\"\n\n def __init__(self, pattern: str) -> None:\n self._pattern = _re.compile(pattern)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n candidates = ctx.selected_symbols or list(ctx.prices.index)\n matched = [s for s in candidates if self._pattern.search(s)]\n ctx.selected_symbols = matched\n if not matched:\n return StepDecision(status=\"skip_day\", message=f\"no symbols match {self._pattern.pattern!r}\")\n return StepDecision()\n\n\nclass SelectWhere:\n \"\"\"Select symbols where a user-defined function returns True.\"\"\"\n\n def __init__(self, fn: Callable[[str, PipelineContext], bool]) -> None:\n self._fn = fn\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n candidates = ctx.selected_symbols or [\n s for s in ctx.prices.index if pd.notna(ctx.prices[s])\n ]\n ctx.selected_symbols = [s for s in candidates if self._fn(s, ctx)]\n if not ctx.selected_symbols:\n return StepDecision(status=\"skip_day\", message=\"no symbols passed filter\")\n return StepDecision()\n\n\n# ---------------------------------------------------------------------------\n# Weighting algos\n# ---------------------------------------------------------------------------\n\nclass WeighSpecified:\n \"\"\"Set fixed target weights, normalized over selected symbols.\"\"\"\n\n def __init__(self, weights: dict[str, float]) -> None:\n self.weights = {k.upper(): float(v) for k, v in weights.items()}\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.selected_symbols:\n return StepDecision(status=\"skip_day\", message=\"no selected symbols\")\n raw = {s: self.weights.get(s, 0.0) for s in ctx.selected_symbols}\n total = float(sum(raw.values()))\n if total <= 0:\n return StepDecision(status=\"skip_day\", message=\"target weights sum to zero\")\n ctx.target_weights = {s: w / total for s, w in raw.items()}\n return StepDecision()\n\n\nclass WeighEqually:\n \"\"\"Equal-weight all selected symbols.\"\"\"\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.selected_symbols:\n return StepDecision(status=\"skip_day\", message=\"no selected symbols\")\n w = 1.0 / len(ctx.selected_symbols)\n ctx.target_weights = {s: w for s in ctx.selected_symbols}\n return StepDecision()\n\n\nclass WeighRandomly:\n \"\"\"Assign random weights to selected symbols (normalized to sum to 1).\n\n Useful for constructing random benchmark strategies.\n \"\"\"\n\n def __init__(self, seed: int | None = None) -> None:\n self._rng = np.random.RandomState(seed)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.selected_symbols:\n return StepDecision(status=\"skip_day\", message=\"no selected symbols\")\n raw = self._rng.dirichlet(np.ones(len(ctx.selected_symbols)))\n ctx.target_weights = {s: float(w) for s, w in zip(ctx.selected_symbols, raw)}\n return StepDecision()\n\n\nclass WeighTarget:\n \"\"\"Read target weights from a pre-computed DataFrame indexed by date.\n\n *weights_df* should have dates as index and symbol names as columns.\n On each date, looks up the closest prior row.\n \"\"\"\n\n def __init__(self, weights_df: pd.DataFrame) -> None:\n self._weights = weights_df.sort_index()\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.selected_symbols:\n return StepDecision(status=\"skip_day\", message=\"no selected symbols\")\n # Find the most recent row <= current date\n mask = self._weights.index <= ctx.date\n if not mask.any():\n return StepDecision(status=\"skip_day\", message=\"no weight data for this date\")\n row = self._weights.loc[mask].iloc[-1]\n weights = {}\n for s in ctx.selected_symbols:\n if s in row.index and pd.notna(row[s]):\n weights[s] = float(row[s])\n if not weights:\n return StepDecision(status=\"skip_day\", message=\"no matching weights\")\n total = sum(weights.values())\n if total <= 0:\n return StepDecision(status=\"skip_day\", message=\"weights sum to zero\")\n ctx.target_weights = {s: w / total for s, w in weights.items()}\n return StepDecision()\n\n\nclass WeighInvVol:\n \"\"\"Inverse-volatility weighting (risk parity lite).\n\n Weight_i = (1/vol_i) / sum(1/vol_j).\n Uses trailing *lookback*-day returns standard deviation.\n \"\"\"\n\n def __init__(self, lookback: int = 252) -> None:\n self._lookback = int(lookback)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.selected_symbols:\n return StepDecision(status=\"skip_day\", message=\"no selected symbols\")\n if ctx.price_history is None or ctx.price_history.empty:\n return StepDecision(status=\"skip_day\", message=\"no price history for inv-vol\")\n inv_vols: dict[str, float] = {}\n for s in ctx.selected_symbols:\n if s not in ctx.price_history.columns:\n continue\n series = ctx.price_history[s].dropna()\n window = series.iloc[-self._lookback:]\n if len(window) < 3:\n continue\n rets = window.pct_change().dropna()\n vol = float(rets.std())\n if vol > 0:\n inv_vols[s] = 1.0 / vol\n if not inv_vols:\n return StepDecision(status=\"skip_day\", message=\"no valid vol data\")\n total = sum(inv_vols.values())\n ctx.target_weights = {s: v / total for s, v in inv_vols.items()}\n return StepDecision()\n\n\nclass WeighMeanVar:\n \"\"\"Mean-variance optimization (max Sharpe ratio portfolio).\n\n Uses trailing *lookback*-day returns. Falls back to equal weight\n if optimization fails (singular covariance, etc.).\n \"\"\"\n\n def __init__(self, lookback: int = 252, risk_free_rate: float = 0.0) -> None:\n self._lookback = int(lookback)\n self._rf = float(risk_free_rate)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.selected_symbols:\n return StepDecision(status=\"skip_day\", message=\"no selected symbols\")\n if ctx.price_history is None or ctx.price_history.empty:\n return StepDecision(status=\"skip_day\", message=\"no price history for mean-var\")\n syms = [s for s in ctx.selected_symbols if s in ctx.price_history.columns]\n if len(syms) < 1:\n return StepDecision(status=\"skip_day\", message=\"no price history columns match\")\n prices = ctx.price_history[syms].dropna()\n if len(prices) < 3:\n return StepDecision(status=\"skip_day\", message=\"insufficient data for mean-var\")\n rets = prices.iloc[-self._lookback:].pct_change().dropna()\n if len(rets) < 3:\n return StepDecision(status=\"skip_day\", message=\"insufficient returns for mean-var\")\n mu = rets.mean().values\n cov = rets.cov().values\n n = len(syms)\n try:\n cov_inv = np.linalg.inv(cov)\n except np.linalg.LinAlgError:\n # Singular covariance — fall back to equal weight\n w = 1.0 / n\n ctx.target_weights = {s: w for s in syms}\n return StepDecision()\n excess = mu - self._rf / 252\n raw_w = cov_inv @ excess\n # Normalize to sum to 1, allow short positions only if naturally arising\n total = float(np.sum(np.abs(raw_w)))\n if total <= 0:\n w = 1.0 / n\n ctx.target_weights = {s: w for s in syms}\n return StepDecision()\n # Long-only: clip negatives, renormalize\n clipped = np.maximum(raw_w, 0.0)\n clip_sum = float(np.sum(clipped))\n if clip_sum <= 0:\n w = 1.0 / n\n ctx.target_weights = {s: w for s in syms}\n return StepDecision()\n weights = clipped / clip_sum\n ctx.target_weights = {s: float(weights[i]) for i, s in enumerate(syms)}\n return StepDecision()\n\n\nclass WeighERC:\n \"\"\"Equal Risk Contribution weighting.\n\n Each asset contributes equally to portfolio risk.\n Uses iterative bisection approximation.\n \"\"\"\n\n def __init__(self, lookback: int = 252, max_iter: int = 100) -> None:\n self._lookback = int(lookback)\n self._max_iter = int(max_iter)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.selected_symbols:\n return StepDecision(status=\"skip_day\", message=\"no selected symbols\")\n if ctx.price_history is None or ctx.price_history.empty:\n return StepDecision(status=\"skip_day\", message=\"no price history for ERC\")\n syms = [s for s in ctx.selected_symbols if s in ctx.price_history.columns]\n if len(syms) < 1:\n return StepDecision(status=\"skip_day\", message=\"no matching columns\")\n prices = ctx.price_history[syms].dropna()\n rets = prices.iloc[-self._lookback:].pct_change().dropna()\n if len(rets) < 3:\n return StepDecision(status=\"skip_day\", message=\"insufficient data for ERC\")\n cov = rets.cov().values\n n = len(syms)\n # Start with equal weights\n w = np.ones(n) / n\n for _ in range(self._max_iter):\n sigma = np.sqrt(float(w @ cov @ w))\n if sigma <= 0:\n break\n mrc = (cov @ w) / sigma # marginal risk contribution\n rc = w * mrc # risk contribution\n target_rc = sigma / n\n # Adjust: increase weight of under-contributing, decrease over-contributing\n adj = target_rc / np.maximum(rc, 1e-12)\n w = w * adj\n w = np.maximum(w, 0.0)\n w_sum = float(np.sum(w))\n if w_sum > 0:\n w = w / w_sum\n ctx.target_weights = {s: float(w[i]) for i, s in enumerate(syms)}\n return StepDecision()\n\n\nclass TargetVol:\n \"\"\"Scale weights to target a specific annualized portfolio volatility.\n\n Scales the existing target_weights by (target_vol / realized_vol).\n Excess weight goes to cash.\n \"\"\"\n\n def __init__(self, target: float = 0.10, lookback: int = 252) -> None:\n self._target = float(target)\n self._lookback = int(lookback)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.target_weights:\n return StepDecision(status=\"skip_day\", message=\"no target weights to scale\")\n if ctx.price_history is None or ctx.price_history.empty:\n return StepDecision(status=\"skip_day\", message=\"no price history for vol scaling\")\n syms = list(ctx.target_weights.keys())\n available = [s for s in syms if s in ctx.price_history.columns]\n if not available:\n return StepDecision(status=\"skip_day\", message=\"no price data for vol scaling\")\n prices = ctx.price_history[available].dropna()\n rets = prices.iloc[-self._lookback:].pct_change().dropna()\n if len(rets) < 3:\n return StepDecision() # not enough data, pass through unchanged\n weights_arr = np.array([ctx.target_weights.get(s, 0.0) for s in available])\n port_rets = rets.values @ weights_arr\n realized_vol = float(np.std(port_rets) * np.sqrt(252))\n if realized_vol <= 0:\n return StepDecision()\n scale = min(self._target / realized_vol, 1.0) # never lever above 1.0\n ctx.target_weights = {s: w * scale for s, w in ctx.target_weights.items()}\n return StepDecision()\n\n\n# ---------------------------------------------------------------------------\n# Weight limits\n# ---------------------------------------------------------------------------\n\nclass LimitWeights:\n \"\"\"Cap individual position weights and renormalize.\"\"\"\n\n def __init__(self, limit: float = 0.25) -> None:\n self._limit = float(limit)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.target_weights:\n return StepDecision()\n # Iteratively clip and renormalize (may need multiple passes)\n weights = dict(ctx.target_weights)\n for _ in range(10):\n over = {s: w for s, w in weights.items() if w > self._limit}\n if not over:\n break\n under = {s: w for s, w in weights.items() if w <= self._limit}\n for s in over:\n weights[s] = self._limit\n under_sum = sum(under.values())\n over_excess = sum(w - self._limit for w in over.values())\n if under_sum > 0:\n scale = 1.0 + over_excess / under_sum\n for s in under:\n weights[s] = weights[s] * scale\n ctx.target_weights = weights\n return StepDecision()\n\n\nclass LimitDeltas:\n \"\"\"Cap how much any single weight can change between rebalances.\n\n On each call, computes the current portfolio weights from positions and\n clips ``target_weights`` so no weight moves more than *limit* from its\n current value. Excess is redistributed proportionally.\n \"\"\"\n\n def __init__(self, limit: float = 0.10) -> None:\n self._limit = float(limit)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.target_weights:\n return StepDecision()\n total = float(ctx.total_capital)\n if total <= 0:\n return StepDecision()\n\n # Compute current weights from positions\n current: dict[str, float] = {}\n for sym in ctx.target_weights:\n qty = ctx.positions.get(sym, 0.0)\n if sym in ctx.prices.index and pd.notna(ctx.prices[sym]):\n current[sym] = float(qty) * float(ctx.prices[sym]) / total\n else:\n current[sym] = 0.0\n\n # Clip deltas\n clipped: dict[str, float] = {}\n for sym, target_w in ctx.target_weights.items():\n cur_w = current.get(sym, 0.0)\n delta = target_w - cur_w\n clamped = max(-self._limit, min(self._limit, delta))\n clipped[sym] = cur_w + clamped\n\n # Renormalize to sum to original target sum\n orig_sum = sum(ctx.target_weights.values())\n clip_sum = sum(clipped.values())\n if clip_sum > 0 and orig_sum > 0:\n scale = orig_sum / clip_sum\n clipped = {s: w * scale for s, w in clipped.items()}\n\n ctx.target_weights = clipped\n return StepDecision()\n\n\nclass ScaleWeights:\n \"\"\"Multiply all target weights by a scalar.\n\n Useful for leverage (scale > 1) or de-leverage (scale < 1).\n Excess weight goes to cash.\n \"\"\"\n\n def __init__(self, scale: float) -> None:\n self._scale = float(scale)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.target_weights:\n return StepDecision()\n ctx.target_weights = {s: w * self._scale for s, w in ctx.target_weights.items()}\n return StepDecision()\n\n\n# ---------------------------------------------------------------------------\n# Capital flows\n# ---------------------------------------------------------------------------\n\nclass CapitalFlow:\n \"\"\"Model periodic capital additions (+) or withdrawals (-).\n\n *flows* is a dict mapping dates to amounts, or a callable\n ``(date: pd.Timestamp) -> float`` returning the flow amount.\n \"\"\"\n\n def __init__(self, flows: dict[str | pd.Timestamp, float] | Callable[[pd.Timestamp], float]) -> None:\n if callable(flows):\n self._fn = flows\n else:\n mapping = {pd.Timestamp(k).normalize(): float(v) for k, v in flows.items()}\n self._fn = lambda d: mapping.get(d.normalize(), 0.0)\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n amount = self._fn(ctx.date)\n if amount != 0.0:\n ctx.cash = float(ctx.cash + amount)\n ctx.total_capital = float(ctx.total_capital + amount)\n return StepDecision()\n\n\n# ---------------------------------------------------------------------------\n# Risk guards\n# ---------------------------------------------------------------------------\n\nclass MaxDrawdownGuard:\n \"\"\"Block new rebalances while drawdown exceeds threshold.\"\"\"\n\n def __init__(self, max_drawdown_pct: float) -> None:\n self.max_drawdown_pct = float(max_drawdown_pct)\n self._peak = 0.0\n\n def reset(self) -> None:\n self._peak = 0.0\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n self._peak = max(self._peak, float(ctx.total_capital))\n if self._peak <= 0:\n return StepDecision()\n dd = (self._peak - float(ctx.total_capital)) / self._peak\n if dd > self.max_drawdown_pct:\n return StepDecision(status=\"skip_day\", message=f\"drawdown {dd:.2%} > {self.max_drawdown_pct:.2%}\")\n return StepDecision()\n\n\nclass HedgeRisks:\n \"\"\"Adjust target weights to hedge portfolio Greeks toward targets.\n\n Uses a Jacobian-based approach: for each hedge instrument, compute\n partial derivatives (delta/vega per unit weight), then solve the\n linear system to find weight adjustments that bring portfolio Greeks\n closest to targets.\n\n Expects ``ctx.prices`` to contain columns for hedge instruments and\n ``ctx.price_history`` to be available for estimating betas (used as\n a proxy for delta when true Greeks are unavailable).\n \"\"\"\n\n def __init__(\n self,\n target_delta: float = 0.0,\n target_vega: float = 0.0,\n hedge_symbols: list[str] | None = None,\n ) -> None:\n self.target_delta = float(target_delta)\n self.target_vega = float(target_vega)\n self.hedge_symbols = hedge_symbols\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.target_weights:\n return StepDecision(status=\"skip_day\", message=\"no target weights to hedge\")\n\n # Determine hedge instruments\n hedgers = self.hedge_symbols or ctx.selected_symbols\n if not hedgers:\n return StepDecision(status=\"skip_day\", message=\"no hedge symbols\")\n\n hedgers = [s for s in hedgers if s in ctx.prices.index and pd.notna(ctx.prices[s])]\n if not hedgers:\n return StepDecision(status=\"skip_day\", message=\"no valid hedge symbols\")\n\n if ctx.price_history is None or len(ctx.price_history) < 3:\n return StepDecision(status=\"skip_day\", message=\"insufficient history for hedge\")\n\n # Estimate current portfolio delta/vega using trailing returns correlation\n port_syms = [s for s in ctx.target_weights if s in ctx.price_history.columns]\n if not port_syms:\n return StepDecision()\n\n rets = ctx.price_history[list(set(port_syms + hedgers))].pct_change().dropna()\n if len(rets) < 3:\n return StepDecision(status=\"skip_day\", message=\"insufficient returns for hedge\")\n\n # Portfolio delta ~ sum(weight_i * beta_i), using beta = std_i as proxy\n port_delta = 0.0\n for s in port_syms:\n if s in rets.columns:\n port_delta += ctx.target_weights.get(s, 0.0) * float(rets[s].std())\n\n delta_gap = self.target_delta - port_delta\n\n # Build Jacobian: each hedger's marginal delta contribution\n n = len(hedgers)\n jacobian = np.zeros((1, n))\n for j, h in enumerate(hedgers):\n if h in rets.columns:\n jacobian[0, j] = float(rets[h].std())\n\n target_vec = np.array([delta_gap])\n try:\n adjustments, _, _, _ = np.linalg.lstsq(jacobian, target_vec, rcond=None)\n except np.linalg.LinAlgError:\n return StepDecision(message=\"hedge solve failed, weights unchanged\")\n\n for j, h in enumerate(hedgers):\n current = ctx.target_weights.get(h, 0.0)\n ctx.target_weights[h] = current + float(adjustments[j])\n\n return StepDecision(message=f\"hedged delta gap={delta_gap:.4f}\")\n\n\nclass Margin:\n \"\"\"Simulate margin/leverage with interest charges and margin calls.\n\n Allows total exposure to exceed cash by borrowing. Charges daily\n interest on borrowed amount. If equity drops below maintenance_pct\n of total exposure, forces liquidation via \"stop\".\n \"\"\"\n\n def __init__(\n self,\n leverage: float = 2.0,\n interest_rate: float = 0.02,\n maintenance_pct: float = 0.25,\n ) -> None:\n self.leverage = float(leverage)\n self.interest_rate = float(interest_rate)\n self.maintenance_pct = float(maintenance_pct)\n self._borrowed = 0.0\n\n def reset(self) -> None:\n self._borrowed = 0.0\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n # Compute current stock value from positions\n stock_value = 0.0\n for sym, qty in ctx.positions.items():\n if sym in ctx.prices.index and pd.notna(ctx.prices[sym]):\n stock_value += float(qty) * float(ctx.prices[sym])\n self._borrowed = max(0.0, stock_value - float(ctx.cash))\n\n # Charge daily interest on borrowed amount\n if self._borrowed > 0:\n daily_interest = self.interest_rate / 252.0 * self._borrowed\n ctx.cash = float(ctx.cash) - daily_interest\n ctx.total_capital = float(ctx.total_capital) - daily_interest\n\n # Margin call check: equity vs total exposure\n equity = float(ctx.cash) + stock_value\n exposure = stock_value\n if exposure > 0 and equity / exposure < self.maintenance_pct:\n return StepDecision(status=\"stop\", message=f\"margin call: equity/exposure={equity / exposure:.2%}\")\n\n # Scale target weights by leverage factor\n if ctx.target_weights:\n ctx.target_weights = {s: w * self.leverage for s, w in ctx.target_weights.items()}\n\n return StepDecision()\n\n\nclass CouponPayingPosition:\n \"\"\"Inject periodic coupon cash flows into the portfolio.\n\n Simulates a fixed-income position by adding coupon_amount to cash\n at the specified frequency. Returns \"stop\" after maturity.\n \"\"\"\n\n _FREQUENCY_MONTHS = {\n \"annual\": 12,\n \"semi-annual\": 6,\n \"quarterly\": 3,\n \"monthly\": 1,\n }\n\n def __init__(\n self,\n coupon_amount: float,\n frequency: str = \"semi-annual\",\n start_date: str | pd.Timestamp | None = None,\n maturity_date: str | pd.Timestamp | None = None,\n ) -> None:\n self.coupon_amount = float(coupon_amount)\n if frequency not in self._FREQUENCY_MONTHS:\n raise ValueError(f\"frequency must be one of {list(self._FREQUENCY_MONTHS)}\")\n self.frequency = frequency\n self._months = self._FREQUENCY_MONTHS[frequency]\n self.start_date = pd.Timestamp(start_date) if start_date else None\n self.maturity_date = pd.Timestamp(maturity_date) if maturity_date else None\n self._last_coupon_month: tuple[int, int] | None = None\n\n def reset(self) -> None:\n self._last_coupon_month = None\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n # Check maturity\n if self.maturity_date and ctx.date >= self.maturity_date:\n ctx.cash = float(ctx.cash) + self.coupon_amount # final coupon\n ctx.total_capital = float(ctx.total_capital) + self.coupon_amount\n return StepDecision(status=\"stop\", message=\"bond matured\")\n\n # Check start date\n if self.start_date and ctx.date < self.start_date:\n return StepDecision()\n\n # Check if this is a coupon month\n month_key = (ctx.date.year, ctx.date.month)\n if self._last_coupon_month == month_key:\n return StepDecision()\n\n # Determine if enough months have passed since last coupon\n if self._last_coupon_month is not None:\n last_y, last_m = self._last_coupon_month\n months_elapsed = (ctx.date.year - last_y) * 12 + (ctx.date.month - last_m)\n if months_elapsed < self._months:\n return StepDecision()\n\n # Pay coupon\n self._last_coupon_month = month_key\n ctx.cash = float(ctx.cash) + self.coupon_amount\n ctx.total_capital = float(ctx.total_capital) + self.coupon_amount\n return StepDecision(message=f\"coupon paid: ${self.coupon_amount:.2f}\")\n\n\nclass ReplayTransactions:\n \"\"\"Replay a pre-recorded trade blotter through the pipeline.\n\n Takes a DataFrame with columns: date, symbol, quantity\n (positive=buy, negative=sell). On each matching date, executes\n the recorded trades at current prices.\n \"\"\"\n\n def __init__(self, blotter: pd.DataFrame) -> None:\n required = {\"date\", \"symbol\", \"quantity\"}\n missing = required - set(blotter.columns)\n if missing:\n raise ValueError(f\"blotter missing columns: {missing}\")\n self._blotter = blotter.copy()\n self._blotter[\"date\"] = pd.to_datetime(self._blotter[\"date\"]).dt.normalize()\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n day_trades = self._blotter[self._blotter[\"date\"] == ctx.date.normalize()]\n if day_trades.empty:\n return StepDecision()\n\n executed = 0\n for _, trade in day_trades.iterrows():\n sym = str(trade[\"symbol\"]).upper()\n qty = float(trade[\"quantity\"])\n if sym not in ctx.prices.index or pd.isna(ctx.prices[sym]):\n continue\n price = float(ctx.prices[sym])\n if price <= 0:\n continue\n cost = qty * price\n ctx.cash = float(ctx.cash) - cost\n ctx.total_capital = float(ctx.total_capital) # recalc handled by backtester\n current_qty = ctx.positions.get(sym, 0.0)\n new_qty = current_qty + qty\n if new_qty == 0:\n ctx.positions.pop(sym, None)\n else:\n ctx.positions[sym] = new_qty\n executed += 1\n\n return StepDecision(message=f\"replayed {executed} trades\")\n\n\n# ---------------------------------------------------------------------------\n# Position management\n# ---------------------------------------------------------------------------\n\nclass CloseDead:\n \"\"\"Close positions where price has dropped to zero or is NaN.\n\n Removes dead positions and frees up the capital (at zero value).\n \"\"\"\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n dead = []\n for sym, qty in ctx.positions.items():\n if sym not in ctx.prices.index or pd.isna(ctx.prices[sym]) or float(ctx.prices[sym]) <= 0:\n dead.append(sym)\n for sym in dead:\n del ctx.positions[sym]\n if dead:\n return StepDecision(message=f\"closed dead: {', '.join(dead)}\")\n return StepDecision()\n\n\nclass ClosePositionsAfterDates:\n \"\"\"Close specific positions on or after given dates.\n\n *schedule* maps symbol names to the date after which they should be closed.\n \"\"\"\n\n def __init__(self, schedule: dict[str, str | pd.Timestamp]) -> None:\n self._schedule = {s.upper(): pd.Timestamp(d).normalize() for s, d in schedule.items()}\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n closed = []\n for sym, close_date in self._schedule.items():\n if ctx.date.normalize() >= close_date and sym in ctx.positions:\n del ctx.positions[sym]\n closed.append(sym)\n if closed:\n return StepDecision(message=f\"closed after date: {', '.join(closed)}\")\n return StepDecision()\n\n\nclass Require:\n \"\"\"Guard: only continue if the wrapped algo returns 'continue'.\n\n Unlike normal pipeline flow, ``Require`` runs the inner algo but does\n NOT break the pipeline on skip — it only checks whether the algo *would*\n have passed. Use it to conditionally gate downstream steps.\n \"\"\"\n\n def __init__(self, algo: Algo) -> None:\n self._algo = algo\n\n def reset(self) -> None:\n if hasattr(self._algo, \"reset\"):\n self._algo.reset()\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n decision = self._algo(ctx)\n if decision.status != \"continue\":\n return StepDecision(status=\"skip_day\", message=f\"requirement not met: {decision.message}\")\n return StepDecision()\n\n\n# ---------------------------------------------------------------------------\n# Rebalancing algos\n# ---------------------------------------------------------------------------\n\nclass Rebalance:\n \"\"\"Rebalance positions to target weights at current prices.\n\n Performs a full liquidate-and-rebuy on each rebalance date.\n \"\"\"\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n if not ctx.target_weights:\n return StepDecision(status=\"skip_day\", message=\"no target weights\")\n new_positions: dict[str, float] = {}\n spent = 0.0\n for sym, w in ctx.target_weights.items():\n price = float(ctx.prices[sym])\n if price <= 0:\n continue\n target_value = float(ctx.total_capital) * w\n qty = float(np.floor(target_value / price))\n new_positions[sym] = qty\n spent += qty * price\n\n ctx.positions.clear()\n ctx.positions.update(new_positions)\n ctx.cash = float(ctx.total_capital - spent)\n return StepDecision()\n\n\nclass RebalanceOverTime:\n \"\"\"Spread rebalancing over *n* periods to reduce market impact.\n\n On each trigger, moves 1/n of the way from current to target weights.\n Must be preceded by a scheduling algo and a weighting algo.\n \"\"\"\n\n def __init__(self, n: int = 5) -> None:\n self._n = int(n)\n self._target: dict[str, float] = {}\n self._remaining = 0\n\n def reset(self) -> None:\n self._target = {}\n self._remaining = 0\n\n def __call__(self, ctx: PipelineContext) -> StepDecision:\n # If new target weights are set, start a new gradual rebalance\n if ctx.target_weights and ctx.target_weights != self._target:\n self._target = dict(ctx.target_weights)\n self._remaining = self._n\n\n if self._remaining <= 0 or not self._target:\n return StepDecision(status=\"skip_day\", message=\"no gradual rebalance in progress\")\n\n # Compute current weights from positions\n total = float(ctx.total_capital)\n if total <= 0:\n return StepDecision(status=\"skip_day\", message=\"no capital\")\n\n current_weights: dict[str, float] = {}\n all_syms = set(self._target.keys()) | set(ctx.positions.keys())\n for sym in all_syms:\n qty = ctx.positions.get(sym, 0.0)\n if sym in ctx.prices.index and pd.notna(ctx.prices[sym]):\n current_weights[sym] = float(qty) * float(ctx.prices[sym]) / total\n else:\n current_weights[sym] = 0.0\n\n # Move fraction of the way toward target\n frac = 1.0 / self._remaining\n blended: dict[str, float] = {}\n for sym in all_syms:\n cur = current_weights.get(sym, 0.0)\n tgt = self._target.get(sym, 0.0)\n blended[sym] = cur + frac * (tgt - cur)\n\n # Apply blended weights\n new_positions: dict[str, float] = {}\n spent = 0.0\n for sym, w in blended.items():\n if sym not in ctx.prices.index or pd.isna(ctx.prices[sym]):\n continue\n price = float(ctx.prices[sym])\n if price <= 0:\n continue\n target_value = total * w\n qty = float(np.floor(target_value / price))\n if qty > 0:\n new_positions[sym] = qty\n spent += qty * price\n\n ctx.positions.clear()\n ctx.positions.update(new_positions)\n ctx.cash = float(total - spent)\n self._remaining -= 1\n return StepDecision()\n\n\nclass AlgoPipelineBacktester:\n \"\"\"Simple stock backtester driven by composable pipeline algos.\"\"\"\n\n def __init__(\n self,\n prices: pd.DataFrame,\n algos: list[Algo],\n initial_capital: float = 1_000_000.0,\n ) -> None:\n self.prices = prices.sort_index()\n self.algos = algos\n self.initial_capital = float(initial_capital)\n self.logs: list[PipelineLogRow] = []\n\n def run(self) -> pd.DataFrame:\n self.logs = []\n for algo in self.algos:\n if hasattr(algo, \"reset\"):\n algo.reset()\n cash = float(self.initial_capital)\n positions: dict[str, float] = {}\n rows: list[dict[str, float | pd.Timestamp]] = []\n\n all_dates = list(self.prices.index)\n for i, (date, price_row) in enumerate(self.prices.iterrows()):\n stocks_cap = float(sum(float(qty) * float(price_row[sym])\n for sym, qty in positions.items()\n if sym in price_row.index and pd.notna(price_row[sym])))\n total_cap = cash + stocks_cap\n # Price history up to current date (for algos that need lookback)\n history = self.prices.iloc[:i + 1] if i > 0 else self.prices.iloc[:1]\n ctx = PipelineContext(\n date=pd.Timestamp(date),\n prices=price_row,\n total_capital=total_cap,\n cash=cash,\n positions=dict(positions),\n price_history=history,\n )\n\n stop_all = False\n for algo in self.algos:\n decision = algo(ctx)\n self.logs.append(\n PipelineLogRow(\n date=pd.Timestamp(date),\n step=algo.__class__.__name__,\n status=decision.status,\n message=decision.message,\n )\n )\n if decision.status == \"skip_day\":\n break\n if decision.status == \"stop\":\n stop_all = True\n break\n\n cash = float(ctx.cash)\n positions = dict(ctx.positions)\n stocks_cap = float(sum(float(qty) * float(price_row[sym])\n for sym, qty in positions.items()\n if sym in price_row.index and pd.notna(price_row[sym])))\n total_cap = cash + stocks_cap\n row: dict[str, float | pd.Timestamp] = {\n \"date\": pd.Timestamp(date),\n \"cash\": cash,\n \"stocks capital\": stocks_cap,\n \"total capital\": total_cap,\n }\n for sym, qty in positions.items():\n row[f\"{sym} qty\"] = float(qty)\n rows.append(row)\n\n if stop_all:\n break\n\n if not rows:\n balance = pd.DataFrame()\n self.balance = balance\n return balance\n balance = pd.DataFrame(rows).set_index(\"date\")\n if not balance.empty:\n balance[\"% change\"] = balance[\"total capital\"].pct_change()\n balance[\"accumulated return\"] = (1.0 + balance[\"% change\"]).cumprod()\n self.balance = balance\n return balance\n\n def set_date_range(self, start=None, end=None):\n \"\"\"Filter results to date range, return new BacktestStats.\"\"\"\n from options_portfolio_backtester.analytics.stats import BacktestStats\n return BacktestStats.from_balance_range(self.balance, start, end)\n\n def logs_dataframe(self) -> pd.DataFrame:\n if not self.logs:\n return pd.DataFrame(columns=[\"date\", \"step\", \"status\", \"message\"])\n return pd.DataFrame([{\n \"date\": r.date,\n \"step\": r.step,\n \"status\": r.status,\n \"message\": r.message,\n } for r in self.logs])\n\n\n# ---------------------------------------------------------------------------\n# Random benchmarking\n# ---------------------------------------------------------------------------\n\n@dataclass(frozen=True)\nclass RandomBenchmarkResult:\n \"\"\"Result of ``benchmark_random``: your strategy vs random portfolios.\"\"\"\n\n strategy_return: float\n random_returns: list[float]\n percentile: float # what % of random runs your strategy beat\n\n @property\n def mean_random(self) -> float:\n return float(np.mean(self.random_returns))\n\n @property\n def std_random(self) -> float:\n return float(np.std(self.random_returns))\n\n\ndef benchmark_random(\n prices: pd.DataFrame,\n strategy_algos: list[Algo],\n n_random: int = 100,\n initial_capital: float = 1_000_000.0,\n seed: int = 42,\n) -> RandomBenchmarkResult:\n \"\"\"Compare a strategy against *n_random* random-weight portfolios.\n\n Runs the given strategy once, then runs *n_random* simulations with\n ``SelectAll → WeighRandomly → Rebalance`` on the same price data.\n Returns a ``RandomBenchmarkResult`` with the strategy's total return,\n the distribution of random returns, and the percentile rank.\n \"\"\"\n # Run the target strategy\n bt = AlgoPipelineBacktester(prices=prices, algos=strategy_algos, initial_capital=initial_capital)\n bal = bt.run()\n if bal.empty:\n strat_ret = 0.0\n else:\n strat_ret = float(bal[\"total capital\"].iloc[-1] / bal[\"total capital\"].iloc[0] - 1)\n\n # Run random strategies\n random_rets: list[float] = []\n for i in range(n_random):\n random_algos: list[Algo] = [\n RunMonthly(),\n SelectAll(),\n WeighRandomly(seed=seed + i),\n Rebalance(),\n ]\n rbt = AlgoPipelineBacktester(prices=prices, algos=random_algos, initial_capital=initial_capital)\n rbal = rbt.run()\n if rbal.empty:\n random_rets.append(0.0)\n else:\n random_rets.append(float(rbal[\"total capital\"].iloc[-1] / rbal[\"total capital\"].iloc[0] - 1))\n\n beaten = sum(1 for r in random_rets if strat_ret > r)\n pct = beaten / max(len(random_rets), 1) * 100\n\n return RandomBenchmarkResult(\n strategy_return=strat_ret,\n random_returns=random_rets,\n percentile=pct,\n )\n"
},
{
"path": "options_portfolio_backtester/engine/strategy_tree.py",
"content": "\"\"\"Hierarchical strategy tree runner.\"\"\"\n\nfrom __future__ import annotations\n\nfrom dataclasses import dataclass, field\n\nimport pandas as pd\n\nfrom options_portfolio_backtester.engine.engine import BacktestEngine\n\n\n@dataclass\nclass StrategyTreeNode:\n \"\"\"Node in a capital-allocation strategy tree.\"\"\"\n\n name: str\n weight: float = 1.0\n max_share: float | None = None\n engine: BacktestEngine | None = None\n children: list[\"StrategyTreeNode\"] = field(default_factory=list)\n\n def __post_init__(self) -> None:\n if self.engine is not None and self.children:\n raise ValueError(\n f\"StrategyTreeNode '{self.name}' has both engine and children; \"\n \"a node must be either a leaf (engine) or a branch (children), not both\"\n )\n\n def is_leaf(self) -> bool:\n return self.engine is not None\n\n def to_dot(self) -> str:\n \"\"\"Generate Graphviz DOT string for this subtree.\"\"\"\n lines = [\n \"digraph StrategyTree {\",\n \" rankdir=TB;\",\n ' node [style=filled, fillcolor=lightyellow];',\n ]\n self._dot_recursive(lines, parent_id=None)\n lines.append(\"}\")\n return \"\\n\".join(lines)\n\n def _dot_recursive(self, lines: list[str], parent_id: str | None) -> None:\n node_id = f\"n{id(self)}\"\n label = f\"{self.name}\\\\nw={self.weight}\"\n if self.max_share is not None:\n label += f\"\\\\nmax={self.max_share}\"\n shape = \"ellipse\" if self.is_leaf() else \"box\"\n lines.append(f' {node_id} [label=\"{label}\", shape={shape}];')\n if parent_id:\n lines.append(f\" {parent_id} -> {node_id};\")\n for child in self.children:\n child._dot_recursive(lines, node_id)\n\n\nclass StrategyTreeEngine:\n \"\"\"Run leaf engines with capital shares implied by tree weights.\"\"\"\n\n def __init__(self, root: StrategyTreeNode, initial_capital: int = 1_000_000) -> None:\n self.root = root\n self.initial_capital = initial_capital\n self.throttles: dict[str, dict[str, float]] = {}\n\n def to_dot(self) -> str:\n \"\"\"Generate Graphviz DOT string for the strategy tree.\"\"\"\n return self.root.to_dot()\n\n def _leaf_shares(self, node: StrategyTreeNode, parent_share: float) -> list[tuple[StrategyTreeNode, float]]:\n if node.is_leaf():\n capped = min(parent_share, node.max_share) if node.max_share is not None else parent_share\n if capped < parent_share:\n self.throttles[node.name] = {\"requested_share\": parent_share, \"applied_share\": capped}\n return [(node, capped)]\n if not node.children:\n return []\n total = sum(c.weight for c in node.children)\n if total <= 0:\n return []\n out: list[tuple[StrategyTreeNode, float]] = []\n for child in node.children:\n out.extend(self._leaf_shares(child, parent_share * (child.weight / total)))\n return out\n\n def run(self, rebalance_freq: int = 0, monthly: bool = False, sma_days: int | None = None) -> dict[str, pd.DataFrame]:\n leaf_allocs = self._leaf_shares(self.root, 1.0)\n results: dict[str, pd.DataFrame] = {}\n self.leaf_weights = {leaf.name: w for leaf, w in leaf_allocs}\n self.attribution = {}\n allocated_share = float(sum(w for _, w in leaf_allocs))\n unallocated_share = max(0.0, 1.0 - allocated_share)\n\n balances: list[pd.DataFrame] = []\n for leaf, share in leaf_allocs:\n cap = round(self.initial_capital * share)\n saved_capital = leaf.engine.initial_capital\n leaf.engine.initial_capital = cap\n trade_log = leaf.engine.run(rebalance_freq=rebalance_freq, monthly=monthly, sma_days=sma_days)\n leaf.engine.initial_capital = saved_capital\n results[leaf.name] = trade_log\n self.attribution[leaf.name] = {\n \"weight\": share,\n \"capital\": cap,\n }\n b = leaf.engine.balance[[\"total capital\"]].rename(columns={\"total capital\": f\"{leaf.name}_capital\"})\n balances.append(b)\n\n if balances:\n self.balance = pd.concat(balances, axis=1)\n cap_cols = [c for c in self.balance.columns if c.endswith(\"_capital\")]\n self.balance[\"unallocated_cash\"] = float(self.initial_capital * unallocated_share)\n self.balance[\"total capital\"] = self.balance[cap_cols].sum(axis=1) + self.balance[\"unallocated_cash\"]\n self.balance[\"% change\"] = self.balance[\"total capital\"].pct_change()\n self.balance[\"accumulated return\"] = (1.0 + self.balance[\"% change\"]).cumprod()\n else:\n self.balance = pd.DataFrame()\n\n return results\n"
},
{
"path": "options_portfolio_backtester/execution/__init__.py",
"content": ""
},
{
"path": "options_portfolio_backtester/execution/_rust_bridge.py",
"content": "\"\"\"Rust execution functions from _ob_rust.\"\"\"\n\nfrom options_portfolio_backtester._ob_rust import (\n rust_option_cost,\n rust_stock_cost,\n rust_fill_price,\n rust_nearest_delta_index,\n rust_max_value_index,\n rust_risk_check,\n)\n"
},
{
"path": "options_portfolio_backtester/execution/cost_model.py",
"content": "\"\"\"Transaction cost models for options and stocks.\"\"\"\n\nfrom __future__ import annotations\n\nfrom abc import ABC, abstractmethod\n\nfrom options_portfolio_backtester.execution._rust_bridge import (\n rust_option_cost, rust_stock_cost,\n)\n\n\nclass TransactionCostModel(ABC):\n \"\"\"Base class for all transaction cost models.\"\"\"\n\n @abstractmethod\n def option_cost(self, price: float, quantity: int, shares_per_contract: int) -> float:\n \"\"\"Return total commission for an options trade.\"\"\"\n ...\n\n @abstractmethod\n def stock_cost(self, price: float, quantity: float) -> float:\n \"\"\"Return total commission for a stock trade.\"\"\"\n ...\n\n\nclass NoCosts(TransactionCostModel):\n \"\"\"Zero transaction costs — matches original behavior.\"\"\"\n\n def option_cost(self, price: float, quantity: int, shares_per_contract: int) -> float:\n return 0.0\n\n def stock_cost(self, price: float, quantity: float) -> float:\n return 0.0\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"NoCosts\"}\n\n\nclass PerContractCommission(TransactionCostModel):\n \"\"\"Fixed per-contract commission (e.g., $0.65/contract for IBKR).\"\"\"\n\n def __init__(self, rate: float = 0.65, stock_rate: float = 0.005) -> None:\n self.rate = rate\n self.stock_rate = stock_rate # per-share\n\n def option_cost(self, price: float, quantity: int, shares_per_contract: int) -> float:\n return rust_option_cost(\"PerContract\", self.rate, self.stock_rate, [], price, float(quantity), shares_per_contract)\n\n def stock_cost(self, price: float, quantity: float) -> float:\n return rust_stock_cost(\"PerContract\", self.rate, self.stock_rate, [], price, float(quantity))\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"PerContract\", \"rate\": self.rate, \"stock_rate\": self.stock_rate}\n\n\nclass TieredCommission(TransactionCostModel):\n \"\"\"Tiered commission schedule with volume discounts.\n\n Tiers are (max_contracts, rate) pairs sorted by max_contracts ascending.\n Contracts beyond the last tier use the last tier's rate.\n \"\"\"\n\n def __init__(self, tiers: list[tuple[int, float]] | None = None,\n stock_rate: float = 0.005) -> None:\n # Default: IBKR-style tiers\n self.tiers = tiers or [\n (10_000, 0.65),\n (50_000, 0.50),\n (100_000, 0.25),\n ]\n self.stock_rate = stock_rate\n\n def option_cost(self, price: float, quantity: int, shares_per_contract: int) -> float:\n return rust_option_cost(\"Tiered\", 0.0, self.stock_rate, self.tiers, price, float(quantity), shares_per_contract)\n\n def stock_cost(self, price: float, quantity: float) -> float:\n return rust_stock_cost(\"Tiered\", 0.0, self.stock_rate, self.tiers, price, float(quantity))\n\n def to_rust_config(self) -> dict:\n return {\n \"type\": \"Tiered\",\n \"tiers\": [(max_qty, rate) for max_qty, rate in self.tiers],\n \"stock_rate\": self.stock_rate,\n }\n\n\nclass SpreadSlippage(TransactionCostModel):\n \"\"\"Model slippage as a fraction of the bid-ask spread.\n\n Example: SpreadSlippage(pct=0.5) means you pay half the spread on top\n of the execution price.\n \"\"\"\n\n def __init__(self, pct: float = 0.5) -> None:\n assert 0.0 <= pct <= 1.0\n self.pct = pct\n\n def option_cost(self, price: float, quantity: int, shares_per_contract: int) -> float:\n # Slippage is modeled separately via fill_model; this returns 0\n # so it can be composed with a commission model.\n return 0.0\n\n def stock_cost(self, price: float, quantity: float) -> float:\n return 0.0\n\n def slippage(self, bid: float, ask: float, quantity: int, shares_per_contract: int) -> float:\n \"\"\"Compute dollar slippage from the spread.\"\"\"\n spread = abs(ask - bid)\n return self.pct * spread * abs(quantity) * shares_per_contract\n"
},
{
"path": "options_portfolio_backtester/execution/fill_model.py",
"content": "\"\"\"Fill models — determine the execution price for trades.\"\"\"\n\nfrom __future__ import annotations\n\nfrom abc import ABC, abstractmethod\n\nimport pandas as pd\n\nfrom options_portfolio_backtester.core.types import Direction\nfrom options_portfolio_backtester.execution._rust_bridge import rust_fill_price\n\n\nclass FillModel(ABC):\n \"\"\"Determines the price at which a trade is filled.\"\"\"\n\n @abstractmethod\n def get_fill_price(self, row: pd.Series, direction: Direction) -> float:\n \"\"\"Return the execution price for a given option quote row and direction.\"\"\"\n ...\n\n\nclass MarketAtBidAsk(FillModel):\n \"\"\"Fill at the bid (sell) or ask (buy) — matches original behavior.\"\"\"\n\n def get_fill_price(self, row: pd.Series, direction: Direction) -> float:\n return float(row[direction.price_column])\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"MarketAtBidAsk\"}\n\n\nclass MidPrice(FillModel):\n \"\"\"Fill at the midpoint of bid and ask.\"\"\"\n\n def get_fill_price(self, row: pd.Series, direction: Direction) -> float:\n bid = float(row[\"bid\"])\n ask = float(row[\"ask\"])\n return (bid + ask) / 2.0\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"MidPrice\"}\n\n\nclass VolumeAwareFill(FillModel):\n \"\"\"Fill price that adjusts for volume impact.\n\n For low-volume contracts, the fill is pushed toward the less favorable\n price. Above `full_volume_threshold`, the fill is at bid/ask.\n \"\"\"\n\n def __init__(self, full_volume_threshold: int = 100) -> None:\n self.full_volume_threshold = full_volume_threshold\n\n def get_fill_price(self, row: pd.Series, direction: Direction) -> float:\n bid = float(row[\"bid\"])\n ask = float(row[\"ask\"])\n is_buy = direction == Direction.BUY\n vol_raw = row.get(\"volume\")\n volume = None if vol_raw is None or (isinstance(vol_raw, float) and vol_raw != vol_raw) else float(vol_raw)\n return rust_fill_price(\"VolumeAware\", self.full_volume_threshold, bid, ask, volume, is_buy)\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"VolumeAware\", \"full_volume_threshold\": self.full_volume_threshold}\n"
},
{
"path": "options_portfolio_backtester/execution/signal_selector.py",
"content": "\"\"\"Signal selectors — choose which contract to trade from a set of candidates.\"\"\"\n\nfrom __future__ import annotations\n\nfrom abc import ABC, abstractmethod\n\nimport pandas as pd\n\nfrom options_portfolio_backtester.execution._rust_bridge import (\n rust_nearest_delta_index, rust_max_value_index,\n)\n\n\nclass SignalSelector(ABC):\n \"\"\"Picks one entry signal from a DataFrame of candidates.\"\"\"\n\n @property\n def column_requirements(self) -> list[str]:\n \"\"\"Extra columns needed from raw options data beyond standard signal fields.\"\"\"\n return []\n\n @abstractmethod\n def select(self, candidates: pd.DataFrame) -> pd.Series:\n \"\"\"Return the single row (as Series) to execute from candidates.\n\n Args:\n candidates: DataFrame of entry signals, pre-sorted if entry_sort was set.\n\n Returns:\n A single row (pd.Series) from candidates.\n \"\"\"\n ...\n\n\nclass FirstMatch(SignalSelector):\n \"\"\"Pick the first row — matches original iloc[0] behavior.\"\"\"\n\n def select(self, candidates: pd.DataFrame) -> pd.Series:\n return candidates.iloc[0]\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"FirstMatch\"}\n\n\nclass NearestDelta(SignalSelector):\n \"\"\"Pick the contract whose delta is closest to `target_delta`.\n\n Requires a 'delta' column in candidates.\n \"\"\"\n\n def __init__(self, target_delta: float = -0.30, delta_column: str = \"delta\") -> None:\n self.target_delta = target_delta\n self.delta_column = delta_column\n\n @property\n def column_requirements(self) -> list[str]:\n return [self.delta_column]\n\n def select(self, candidates: pd.DataFrame) -> pd.Series:\n if self.delta_column not in candidates.columns:\n return candidates.iloc[0]\n values = candidates[self.delta_column].tolist()\n idx = rust_nearest_delta_index(values, self.target_delta)\n return candidates.iloc[idx]\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"NearestDelta\", \"target\": self.target_delta, \"column\": self.delta_column}\n\n\nclass MaxOpenInterest(SignalSelector):\n \"\"\"Pick the contract with the highest open interest (proxy for liquidity).\n\n Requires an 'openinterest' or 'open_interest' column.\n \"\"\"\n\n def __init__(self, oi_column: str = \"openinterest\") -> None:\n self.oi_column = oi_column\n\n @property\n def column_requirements(self) -> list[str]:\n return [self.oi_column]\n\n def select(self, candidates: pd.DataFrame) -> pd.Series:\n if self.oi_column not in candidates.columns:\n return candidates.iloc[0]\n values = candidates[self.oi_column].astype(float).tolist()\n idx = rust_max_value_index(values)\n return candidates.iloc[idx]\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"MaxOpenInterest\", \"column\": self.oi_column}\n"
},
{
"path": "options_portfolio_backtester/execution/sizer.py",
"content": "\"\"\"Position sizing models — determine how many contracts to trade.\"\"\"\n\nfrom __future__ import annotations\n\nfrom abc import ABC, abstractmethod\n\n\nclass PositionSizer(ABC):\n \"\"\"Determines the number of contracts to trade.\"\"\"\n\n @abstractmethod\n def size(self, cost_per_contract: float, available_capital: float,\n total_capital: float) -> int:\n \"\"\"Return the number of contracts to trade.\n\n Args:\n cost_per_contract: Dollar cost for one contract (absolute value).\n available_capital: Capital allocated to this trade.\n total_capital: Total portfolio value.\n \"\"\"\n ...\n\n\nclass CapitalBased(PositionSizer):\n \"\"\"Buy as many contracts as the allocation allows — matches original behavior.\n\n qty = available_capital // cost_per_contract\n \"\"\"\n\n def size(self, cost_per_contract: float, available_capital: float,\n total_capital: float) -> int:\n if cost_per_contract == 0:\n return 0\n return int(available_capital // abs(cost_per_contract))\n\n\nclass FixedQuantity(PositionSizer):\n \"\"\"Always trade a fixed number of contracts.\"\"\"\n\n def __init__(self, quantity: int = 1) -> None:\n self.quantity = quantity\n\n def size(self, cost_per_contract: float, available_capital: float,\n total_capital: float) -> int:\n if abs(cost_per_contract) * self.quantity > available_capital:\n return int(available_capital // abs(cost_per_contract)) if cost_per_contract != 0 else 0\n return self.quantity\n\n\nclass FixedDollar(PositionSizer):\n \"\"\"Size positions to a fixed dollar amount.\"\"\"\n\n def __init__(self, amount: float = 10_000.0) -> None:\n self.amount = amount\n\n def size(self, cost_per_contract: float, available_capital: float,\n total_capital: float) -> int:\n if cost_per_contract == 0:\n return 0\n target = min(self.amount, available_capital)\n return int(target // abs(cost_per_contract))\n\n\nclass PercentOfPortfolio(PositionSizer):\n \"\"\"Size positions as a percentage of total portfolio value.\"\"\"\n\n def __init__(self, pct: float = 0.01) -> None:\n assert 0.0 < pct <= 1.0\n self.pct = pct\n\n def size(self, cost_per_contract: float, available_capital: float,\n total_capital: float) -> int:\n if cost_per_contract == 0:\n return 0\n target = min(self.pct * total_capital, available_capital)\n return int(target // abs(cost_per_contract))\n"
},
{
"path": "options_portfolio_backtester/portfolio/__init__.py",
"content": ""
},
{
"path": "options_portfolio_backtester/portfolio/greeks.py",
"content": "\"\"\"Portfolio-level Greeks aggregation.\"\"\"\n\nfrom __future__ import annotations\n\nfrom options_portfolio_backtester.core.types import Greeks\nfrom options_portfolio_backtester.portfolio.position import OptionPosition\n\n\ndef aggregate_greeks(\n positions: dict[int, OptionPosition],\n leg_greeks_by_position: dict[int, dict[str, Greeks]],\n) -> Greeks:\n \"\"\"Compute portfolio-level Greeks by summing across all positions.\n\n Args:\n positions: {position_id: OptionPosition}.\n leg_greeks_by_position: {position_id: {leg_name: Greeks}}.\n\n Returns:\n Total portfolio Greeks.\n \"\"\"\n total = Greeks()\n for pid, pos in positions.items():\n pos_greeks = leg_greeks_by_position.get(pid, {})\n total = total + pos.greeks(pos_greeks)\n return total\n"
},
{
"path": "options_portfolio_backtester/portfolio/portfolio.py",
"content": "\"\"\"Portfolio — clean replacement for MultiIndex DataFrames.\n\nUses plain dicts and dataclasses instead of MultiIndex DataFrames for\ninventory tracking. Simpler, extensible, debuggable.\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom dataclasses import dataclass, field\nfrom typing import Any\n\nfrom options_portfolio_backtester.core.types import Greeks\nfrom options_portfolio_backtester.portfolio.position import OptionPosition\nfrom options_portfolio_backtester.portfolio.greeks import aggregate_greeks\n\n\n@dataclass\nclass StockHolding:\n \"\"\"A stock position in the portfolio.\"\"\"\n symbol: str\n quantity: float\n cost_basis: float # average price paid\n\n\nclass Portfolio:\n \"\"\"Portfolio state — cash, option positions, stock holdings.\n\n Replaces the old MultiIndex _options_inventory and _stocks_inventory\n DataFrames with typed, inspectable data structures.\n \"\"\"\n\n def __init__(self, initial_cash: float = 0.0) -> None:\n self.cash: float = initial_cash\n self.option_positions: dict[int, OptionPosition] = {}\n self.stock_holdings: dict[str, StockHolding] = {}\n self._next_position_id: int = 0\n\n def next_position_id(self) -> int:\n pid = self._next_position_id\n self._next_position_id += 1\n return pid\n\n # -- Option positions --\n\n def add_option_position(self, pos: OptionPosition) -> None:\n self.option_positions[pos.position_id] = pos\n\n def remove_option_position(self, position_id: int) -> OptionPosition | None:\n return self.option_positions.pop(position_id, None)\n\n def options_value(self, current_prices: dict[int, dict[str, float]],\n shares_per_contract: int) -> float:\n \"\"\"Total mark-to-market value of all option positions.\n\n Args:\n current_prices: {position_id: {leg_name: exit_price}}.\n shares_per_contract: Contract multiplier.\n \"\"\"\n total = 0.0\n for pid, pos in self.option_positions.items():\n prices = current_prices.get(pid, {})\n total += pos.current_value(prices, shares_per_contract)\n return total\n\n # -- Stock holdings --\n\n def set_stock_holding(self, symbol: str, quantity: float,\n price: float) -> None:\n self.stock_holdings[symbol] = StockHolding(\n symbol=symbol, quantity=quantity, cost_basis=price,\n )\n\n def clear_stock_holdings(self) -> None:\n self.stock_holdings.clear()\n\n def stocks_value(self, current_prices: dict[str, float]) -> float:\n \"\"\"Total value of stock holdings at current prices.\"\"\"\n total = 0.0\n for symbol, holding in self.stock_holdings.items():\n price = current_prices.get(symbol, holding.cost_basis)\n total += holding.quantity * price\n return total\n\n # -- Portfolio totals --\n\n def total_value(self, stock_prices: dict[str, float],\n option_prices: dict[int, dict[str, float]],\n shares_per_contract: int) -> float:\n \"\"\"Total portfolio value: cash + stocks + options.\"\"\"\n return (self.cash\n + self.stocks_value(stock_prices)\n + self.options_value(option_prices, shares_per_contract))\n\n def portfolio_greeks(self,\n leg_greeks_by_position: dict[int, dict[str, Greeks]]) -> Greeks:\n \"\"\"Aggregate Greeks across all option positions.\"\"\"\n return aggregate_greeks(self.option_positions, leg_greeks_by_position)\n"
},
{
"path": "options_portfolio_backtester/portfolio/position.py",
"content": "\"\"\"Option position and position leg — replaces MultiIndex inventory rows.\"\"\"\n\nfrom __future__ import annotations\n\nfrom dataclasses import dataclass, field\nfrom typing import Any\n\nfrom options_portfolio_backtester.core.types import (\n Direction, OptionType, Order, Greeks, get_order, Signal,\n)\n\n\n@dataclass\nclass PositionLeg:\n \"\"\"A single leg within an option position.\"\"\"\n name: str\n contract_id: str\n underlying: str\n expiration: Any # pd.Timestamp\n option_type: OptionType\n strike: float\n entry_price: float\n direction: Direction\n order: Order\n\n @property\n def exit_order(self) -> Order:\n return ~self.order\n\n def current_value(self, current_price: float, quantity: int,\n shares_per_contract: int) -> float:\n \"\"\"Mark-to-market value of this leg.\n\n For a BUY leg, value = current_price * qty * spc (we own it).\n For a SELL leg, value = -current_price * qty * spc (we owe it).\n \"\"\"\n sign = -1 if self.direction == Direction.SELL else 1\n return sign * current_price * quantity * shares_per_contract\n\n\n@dataclass\nclass OptionPosition:\n \"\"\"A multi-leg option position.\n\n Replaces one row in the old MultiIndex _options_inventory DataFrame.\n \"\"\"\n position_id: int\n legs: dict[str, PositionLeg] = field(default_factory=dict)\n quantity: int = 0\n entry_cost: float = 0.0 # total cost at entry (negative for debit)\n entry_date: Any = None # pd.Timestamp\n\n def add_leg(self, leg: PositionLeg) -> None:\n self.legs[leg.name] = leg\n\n def current_value(self, current_prices: dict[str, float],\n shares_per_contract: int) -> float:\n \"\"\"Total MTM value of this position across all legs.\n\n Args:\n current_prices: {leg_name: exit_price} for each leg.\n shares_per_contract: Contract multiplier.\n \"\"\"\n total = 0.0\n for leg_name, leg in self.legs.items():\n price = current_prices.get(leg_name, 0.0)\n total += leg.current_value(price, self.quantity, shares_per_contract)\n return total\n\n def greeks(self, leg_greeks: dict[str, Greeks]) -> Greeks:\n \"\"\"Aggregate Greeks across all legs, scaled by quantity.\n\n Args:\n leg_greeks: {leg_name: Greeks} for each leg.\n \"\"\"\n total = Greeks()\n for leg_name, leg in self.legs.items():\n g = leg_greeks.get(leg_name, Greeks())\n sign = 1 if leg.direction == Direction.BUY else -1\n total = total + g * (sign * self.quantity)\n return total\n"
},
{
"path": "options_portfolio_backtester/portfolio/risk.py",
"content": "\"\"\"Risk management — constraints checked before entering positions.\"\"\"\n\nfrom __future__ import annotations\n\nfrom abc import ABC, abstractmethod\nfrom dataclasses import dataclass\n\nfrom options_portfolio_backtester.core.types import Greeks\nfrom options_portfolio_backtester.execution._rust_bridge import rust_risk_check\n\n\nclass RiskConstraint(ABC):\n \"\"\"A single risk constraint.\"\"\"\n\n @abstractmethod\n def check(self, current_greeks: Greeks, proposed_greeks: Greeks,\n portfolio_value: float, peak_value: float) -> bool:\n \"\"\"Return True if the trade is allowed, False if it violates the constraint.\"\"\"\n ...\n\n @abstractmethod\n def describe(self) -> str:\n \"\"\"Human-readable description of the constraint.\"\"\"\n ...\n\n\ndef _greeks_list(g: Greeks) -> list[float]:\n return [g.delta, g.gamma, g.theta, g.vega]\n\n\nclass MaxDelta(RiskConstraint):\n \"\"\"Reject trades that would push portfolio delta beyond a limit.\"\"\"\n\n def __init__(self, limit: float = 100.0) -> None:\n self.limit = limit\n\n def check(self, current_greeks: Greeks, proposed_greeks: Greeks,\n portfolio_value: float, peak_value: float) -> bool:\n return rust_risk_check(\n \"MaxDelta\", self.limit,\n _greeks_list(current_greeks), _greeks_list(proposed_greeks),\n portfolio_value, peak_value,\n )\n\n def describe(self) -> str:\n return f\"MaxDelta(limit={self.limit})\"\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"MaxDelta\", \"limit\": self.limit}\n\n\nclass MaxVega(RiskConstraint):\n \"\"\"Reject trades that would push portfolio vega beyond a limit.\"\"\"\n\n def __init__(self, limit: float = 50.0) -> None:\n self.limit = limit\n\n def check(self, current_greeks: Greeks, proposed_greeks: Greeks,\n portfolio_value: float, peak_value: float) -> bool:\n return rust_risk_check(\n \"MaxVega\", self.limit,\n _greeks_list(current_greeks), _greeks_list(proposed_greeks),\n portfolio_value, peak_value,\n )\n\n def describe(self) -> str:\n return f\"MaxVega(limit={self.limit})\"\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"MaxVega\", \"limit\": self.limit}\n\n\nclass MaxDrawdown(RiskConstraint):\n \"\"\"Reject new entries if portfolio drawdown exceeds a threshold.\"\"\"\n\n def __init__(self, max_dd_pct: float = 0.20) -> None:\n self.max_dd_pct = max_dd_pct\n\n def check(self, current_greeks: Greeks, proposed_greeks: Greeks,\n portfolio_value: float, peak_value: float) -> bool:\n return rust_risk_check(\n \"MaxDrawdown\", self.max_dd_pct,\n _greeks_list(current_greeks), _greeks_list(proposed_greeks),\n portfolio_value, peak_value,\n )\n\n def describe(self) -> str:\n return f\"MaxDrawdown(max_dd_pct={self.max_dd_pct})\"\n\n def to_rust_config(self) -> dict:\n return {\"type\": \"MaxDrawdown\", \"max_dd_pct\": self.max_dd_pct}\n\n\nclass RiskManager:\n \"\"\"Evaluates a set of risk constraints before allowing a trade.\"\"\"\n\n def __init__(self, constraints: list[RiskConstraint] | None = None) -> None:\n self.constraints = constraints or []\n\n def add_constraint(self, constraint: RiskConstraint) -> None:\n self.constraints.append(constraint)\n\n def is_allowed(self, current_greeks: Greeks, proposed_greeks: Greeks,\n portfolio_value: float, peak_value: float) -> tuple[bool, str]:\n \"\"\"Check all constraints. Returns (allowed, reason).\"\"\"\n for c in self.constraints:\n if not c.check(current_greeks, proposed_greeks,\n portfolio_value, peak_value):\n return False, c.describe()\n return True, \"\"\n"
},
{
"path": "options_portfolio_backtester/strategy/__init__.py",
"content": ""
},
{
"path": "options_portfolio_backtester/strategy/presets.py",
"content": "\"\"\"Pre-built strategy constructors for common options strategies.\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import TYPE_CHECKING\n\nfrom options_portfolio_backtester.core.types import Direction, OptionType\nfrom options_portfolio_backtester.strategy.strategy import Strategy\nfrom options_portfolio_backtester.strategy.strategy_leg import StrategyLeg\n\nif TYPE_CHECKING:\n from options_portfolio_backtester.data.schema import Schema\n\n\ndef strangle(\n schema: \"Schema\",\n underlying: str,\n direction: Direction,\n dte_range: tuple[int, int],\n dte_exit: int,\n otm_pct: float = 0.0,\n pct_tolerance: float = 1.0,\n exit_thresholds: tuple[float, float] = (float(\"inf\"), float(\"inf\")),\n) -> Strategy:\n \"\"\"Build a strangle (long or short) strategy.\"\"\"\n strat = Strategy(schema)\n\n otm_lo = (otm_pct - pct_tolerance) / 100\n otm_hi = (otm_pct + pct_tolerance) / 100\n\n call_leg = StrategyLeg(\"leg_1\", schema, option_type=OptionType.CALL, direction=direction)\n call_leg.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n & (schema.strike >= schema.underlying_last * (1 + otm_lo))\n & (schema.strike <= schema.underlying_last * (1 + otm_hi))\n )\n call_leg.exit_filter = schema.dte <= dte_exit\n\n put_leg = StrategyLeg(\"leg_2\", schema, option_type=OptionType.PUT, direction=direction)\n put_leg.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n & (schema.strike <= schema.underlying_last * (1 - otm_lo))\n & (schema.strike >= schema.underlying_last * (1 - otm_hi))\n )\n put_leg.exit_filter = schema.dte <= dte_exit\n\n strat.add_legs([call_leg, put_leg])\n strat.add_exit_thresholds(exit_thresholds[0], exit_thresholds[1])\n return strat\n\n\ndef iron_condor(\n schema: \"Schema\",\n underlying: str,\n dte_range: tuple[int, int],\n dte_exit: int,\n short_delta_call: float = 0.30,\n short_delta_put: float = -0.30,\n wing_width: float = 5.0,\n exit_thresholds: tuple[float, float] = (float(\"inf\"), float(\"inf\")),\n) -> Strategy:\n \"\"\"Build a short iron condor (sell inner, buy outer wings).\n\n This is a simplified version using strike offsets; for delta-based\n selection, use a NearestDelta signal_selector on each leg.\n \"\"\"\n strat = Strategy(schema)\n\n # Short call (inner)\n sc = StrategyLeg(\"leg_1\", schema, option_type=OptionType.CALL, direction=Direction.SELL)\n sc.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n )\n sc.exit_filter = schema.dte <= dte_exit\n\n # Long call (outer wing)\n lc = StrategyLeg(\"leg_2\", schema, option_type=OptionType.CALL, direction=Direction.BUY)\n lc.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n )\n lc.exit_filter = schema.dte <= dte_exit\n\n # Short put (inner)\n sp = StrategyLeg(\"leg_3\", schema, option_type=OptionType.PUT, direction=Direction.SELL)\n sp.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n )\n sp.exit_filter = schema.dte <= dte_exit\n\n # Long put (outer wing)\n lp = StrategyLeg(\"leg_4\", schema, option_type=OptionType.PUT, direction=Direction.BUY)\n lp.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n )\n lp.exit_filter = schema.dte <= dte_exit\n\n strat.add_legs([sc, lc, sp, lp])\n strat.add_exit_thresholds(exit_thresholds[0], exit_thresholds[1])\n return strat\n\n\ndef covered_call(\n schema: \"Schema\",\n underlying: str,\n dte_range: tuple[int, int],\n dte_exit: int,\n otm_pct: float = 2.0,\n pct_tolerance: float = 1.0,\n exit_thresholds: tuple[float, float] = (float(\"inf\"), float(\"inf\")),\n) -> Strategy:\n \"\"\"Build a covered call strategy (sell OTM calls against stock).\"\"\"\n strat = Strategy(schema)\n otm_lo = (otm_pct - pct_tolerance) / 100\n otm_hi = (otm_pct + pct_tolerance) / 100\n\n leg = StrategyLeg(\"leg_1\", schema, option_type=OptionType.CALL, direction=Direction.SELL)\n leg.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n & (schema.strike >= schema.underlying_last * (1 + otm_lo))\n & (schema.strike <= schema.underlying_last * (1 + otm_hi))\n )\n leg.exit_filter = schema.dte <= dte_exit\n\n strat.add_leg(leg)\n strat.add_exit_thresholds(exit_thresholds[0], exit_thresholds[1])\n return strat\n\n\ndef cash_secured_put(\n schema: \"Schema\",\n underlying: str,\n dte_range: tuple[int, int],\n dte_exit: int,\n otm_pct: float = 2.0,\n pct_tolerance: float = 1.0,\n exit_thresholds: tuple[float, float] = (float(\"inf\"), float(\"inf\")),\n) -> Strategy:\n \"\"\"Build a cash-secured put strategy (sell OTM puts).\"\"\"\n strat = Strategy(schema)\n otm_lo = (otm_pct - pct_tolerance) / 100\n otm_hi = (otm_pct + pct_tolerance) / 100\n\n leg = StrategyLeg(\"leg_1\", schema, option_type=OptionType.PUT, direction=Direction.SELL)\n leg.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n & (schema.strike <= schema.underlying_last * (1 - otm_lo))\n & (schema.strike >= schema.underlying_last * (1 - otm_hi))\n )\n leg.exit_filter = schema.dte <= dte_exit\n\n strat.add_leg(leg)\n strat.add_exit_thresholds(exit_thresholds[0], exit_thresholds[1])\n return strat\n\n\ndef collar(\n schema: \"Schema\",\n underlying: str,\n dte_range: tuple[int, int],\n dte_exit: int,\n call_otm_pct: float = 2.0,\n put_otm_pct: float = 2.0,\n pct_tolerance: float = 1.0,\n exit_thresholds: tuple[float, float] = (float(\"inf\"), float(\"inf\")),\n) -> Strategy:\n \"\"\"Build a collar strategy (long put + short call against stock).\"\"\"\n strat = Strategy(schema)\n call_lo = (call_otm_pct - pct_tolerance) / 100\n call_hi = (call_otm_pct + pct_tolerance) / 100\n put_lo = (put_otm_pct - pct_tolerance) / 100\n put_hi = (put_otm_pct + pct_tolerance) / 100\n\n short_call = StrategyLeg(\"leg_1\", schema, option_type=OptionType.CALL, direction=Direction.SELL)\n short_call.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n & (schema.strike >= schema.underlying_last * (1 + call_lo))\n & (schema.strike <= schema.underlying_last * (1 + call_hi))\n )\n short_call.exit_filter = schema.dte <= dte_exit\n\n long_put = StrategyLeg(\"leg_2\", schema, option_type=OptionType.PUT, direction=Direction.BUY)\n long_put.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n & (schema.strike <= schema.underlying_last * (1 - put_lo))\n & (schema.strike >= schema.underlying_last * (1 - put_hi))\n )\n long_put.exit_filter = schema.dte <= dte_exit\n\n strat.add_legs([short_call, long_put])\n strat.add_exit_thresholds(exit_thresholds[0], exit_thresholds[1])\n return strat\n\n\ndef butterfly(\n schema: \"Schema\",\n underlying: str,\n dte_range: tuple[int, int],\n dte_exit: int,\n option_type: OptionType = OptionType.CALL,\n exit_thresholds: tuple[float, float] = (float(\"inf\"), float(\"inf\")),\n) -> Strategy:\n \"\"\"Build a long butterfly spread (buy 1 lower, sell 2 middle, buy 1 upper).\n\n Uses entry_sort on strike to pick the legs. The middle leg is a SELL\n direction with double quantity handled by the sizer.\n \"\"\"\n strat = Strategy(schema)\n\n # Lower wing (buy)\n lower = StrategyLeg(\"leg_1\", schema, option_type=option_type, direction=Direction.BUY)\n lower.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n )\n lower.entry_sort = (\"strike\", True) # ascending — lowest strike first\n lower.exit_filter = schema.dte <= dte_exit\n\n # Middle (sell 2x)\n middle = StrategyLeg(\"leg_2\", schema, option_type=option_type, direction=Direction.SELL)\n middle.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n )\n middle.exit_filter = schema.dte <= dte_exit\n\n # Upper wing (buy)\n upper = StrategyLeg(\"leg_3\", schema, option_type=option_type, direction=Direction.BUY)\n upper.entry_filter = (\n (schema.underlying == underlying)\n & (schema.dte >= dte_range[0])\n & (schema.dte <= dte_range[1])\n )\n upper.entry_sort = (\"strike\", False) # descending — highest strike first\n upper.exit_filter = schema.dte <= dte_exit\n\n strat.add_legs([lower, middle, upper])\n strat.add_exit_thresholds(exit_thresholds[0], exit_thresholds[1])\n return strat\n\n\nclass Strangle(Strategy):\n \"\"\"Class-based Strangle constructor.\"\"\"\n\n def __init__(\n self,\n schema: \"Schema\",\n name: str,\n underlying: str,\n dte_entry_range: tuple[int, int],\n dte_exit: int,\n otm_pct: float = 0,\n pct_tolerance: float = 1,\n exit_thresholds: tuple[float, float] = (float('inf'), float('inf')),\n shares_per_contract: int = 100,\n ) -> None:\n assert (name.lower() == 'short' or name.lower() == 'long')\n super().__init__(schema)\n direction = Direction.SELL if name.lower() == 'short' else Direction.BUY\n\n leg1 = StrategyLeg(\n \"leg_1\",\n schema,\n option_type=OptionType.CALL,\n direction=direction,\n )\n\n otm_lower_bound = (otm_pct - pct_tolerance) / 100\n otm_upper_bound = (otm_pct + pct_tolerance) / 100\n\n leg1.entry_filter = (schema.underlying == underlying) & (schema.dte >= dte_entry_range[0]) & (\n schema.dte <= dte_entry_range[1]) & (schema.strike >= schema.underlying_last *\n (1 + otm_lower_bound)) & (schema.strike <= schema.underlying_last *\n (1 + otm_upper_bound))\n leg1.exit_filter = (schema.dte <= dte_exit)\n\n leg2 = StrategyLeg(\"leg_2\", schema, option_type=OptionType.PUT, direction=direction)\n leg2.entry_filter = (schema.underlying == underlying) & (schema.dte >= dte_entry_range[0]) & (\n schema.dte <= dte_entry_range[1]) & (schema.strike <= schema.underlying_last *\n (1 - otm_lower_bound)) & (schema.strike >= schema.underlying_last *\n (1 - otm_upper_bound))\n leg2.exit_filter = (schema.dte <= dte_exit)\n\n self.add_legs([leg1, leg2])\n self.add_exit_thresholds(exit_thresholds[0], exit_thresholds[1])\n"
},
{
"path": "options_portfolio_backtester/strategy/strategy.py",
"content": "\"\"\"Strategy container — preserved interface with richer execution support.\"\"\"\n\nfrom __future__ import annotations\n\nimport math\nfrom typing import TYPE_CHECKING\n\nimport numpy as np\nimport pandas as pd\n\nfrom options_portfolio_backtester.execution.cost_model import TransactionCostModel, NoCosts\nfrom options_portfolio_backtester.execution.sizer import PositionSizer, CapitalBased\nfrom options_portfolio_backtester.execution.signal_selector import SignalSelector, FirstMatch\n\nif TYPE_CHECKING:\n from options_portfolio_backtester.data.schema import Schema\n from .strategy_leg import StrategyLeg\n\n\nclass Strategy:\n \"\"\"Options strategy — collection of legs with exit thresholds.\n\n API-compatible with backtester.strategy.strategy.Strategy, adding optional\n cost_model, sizer, and signal_selector at the strategy level.\n \"\"\"\n\n def __init__(\n self,\n schema: \"Schema\",\n cost_model: TransactionCostModel | None = None,\n sizer: PositionSizer | None = None,\n signal_selector: SignalSelector | None = None,\n ) -> None:\n self.schema = schema\n self.legs: list[StrategyLeg] = []\n self.conditions: list = []\n self.exit_thresholds: tuple[float, float] = (math.inf, math.inf)\n self.cost_model = cost_model or NoCosts()\n self.sizer = sizer or CapitalBased()\n self.signal_selector = signal_selector or FirstMatch()\n\n def add_leg(self, leg: \"StrategyLeg\") -> \"Strategy\":\n assert self.schema == leg.schema\n leg.name = f\"leg_{len(self.legs) + 1}\"\n self.legs.append(leg)\n return self\n\n def add_legs(self, legs: list[\"StrategyLeg\"]) -> \"Strategy\":\n for leg in legs:\n self.add_leg(leg)\n return self\n\n def remove_leg(self, leg_number: int) -> \"Strategy\":\n self.legs.pop(leg_number)\n return self\n\n def clear_legs(self) -> \"Strategy\":\n self.legs = []\n return self\n\n def add_exit_thresholds(self, profit_pct: float = math.inf,\n loss_pct: float = math.inf) -> None:\n assert profit_pct >= 0\n assert loss_pct >= 0\n self.exit_thresholds = (profit_pct, loss_pct)\n\n def filter_thresholds(self, entry_cost: pd.Series,\n current_cost: pd.Series) -> pd.Series:\n profit_pct, loss_pct = self.exit_thresholds\n excess_return = (current_cost / entry_cost + 1) * -np.sign(entry_cost)\n return (excess_return >= profit_pct) | (excess_return <= -loss_pct)\n\n def __repr__(self) -> str:\n return f\"Strategy(legs={self.legs}, exit_thresholds={self.exit_thresholds})\"\n"
},
{
"path": "options_portfolio_backtester/strategy/strategy_leg.py",
"content": "\"\"\"Strategy leg — re-exports the original StrategyLeg for now.\n\nThe new StrategyLeg is API-compatible with the original and adds support\nfor the new execution components (signal_selector, fill_model).\n\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import TYPE_CHECKING\n\nfrom options_portfolio_backtester.core.types import Direction, OptionType\nfrom options_portfolio_backtester.execution.signal_selector import SignalSelector, FirstMatch\nfrom options_portfolio_backtester.execution.fill_model import FillModel, MarketAtBidAsk\n\nif TYPE_CHECKING:\n from options_portfolio_backtester.data.schema import Filter, Schema\n\n\nclass StrategyLeg:\n \"\"\"A single option leg in a strategy.\n\n API-compatible with backtester.strategy.strategy_leg.StrategyLeg, adding\n optional signal_selector and fill_model.\n \"\"\"\n\n def __init__(\n self,\n name: str,\n schema: \"Schema\",\n option_type: OptionType = OptionType.CALL,\n direction: Direction = Direction.BUY,\n signal_selector: SignalSelector | None = None,\n fill_model: FillModel | None = None,\n ) -> None:\n self.name = name\n self.schema = schema\n self.type = option_type\n self.direction = direction\n self.signal_selector = signal_selector # None = use engine-level default\n self.fill_model = fill_model # None = use engine-level default\n\n self.entry_sort: tuple[str, bool] | None = None\n self._entry_filter: \"Filter\" = self._base_entry_filter()\n self._exit_filter: \"Filter\" = self._base_exit_filter()\n\n @property\n def entry_filter(self) -> \"Filter\":\n return self._entry_filter\n\n @entry_filter.setter\n def entry_filter(self, flt: \"Filter\") -> None:\n self._entry_filter = self._base_entry_filter() & flt\n\n @property\n def exit_filter(self) -> \"Filter\":\n return self._exit_filter\n\n @exit_filter.setter\n def exit_filter(self, flt: \"Filter\") -> None:\n self._exit_filter = self._base_exit_filter() & flt\n\n def _base_entry_filter(self) -> \"Filter\":\n if self.direction == Direction.BUY:\n return (self.schema.type == self.type.value) & (self.schema.ask > 0)\n return (self.schema.type == self.type.value) & (self.schema.bid > 0)\n\n def _base_exit_filter(self) -> \"Filter\":\n return self.schema.type == self.type.value\n\n def __repr__(self) -> str:\n return (\n f\"StrategyLeg(name={self.name}, type={self.type}, \"\n f\"direction={self.direction}, entry_filter={self._entry_filter}, \"\n f\"exit_filter={self._exit_filter})\"\n )\n"
},
{
"path": "pyproject.toml",
"content": "[build-system]\nrequires = [\"maturin>=1.7,<2.0\"]\nbuild-backend = \"maturin\"\n\n[project]\nname = \"options_portfolio_backtester\"\nversion = \"0.3.0\"\ndescription = \"The open-source options backtesting framework\"\nreadme = \"README.md\"\nlicense = {text = \"MIT\"}\nrequires-python = \">=3.11\"\ndependencies = [\n \"pandas>=2.1\",\n \"numpy>=1.26\",\n \"altair>=5.0\",\n \"pyprind>=2.11\",\n \"pyarrow>=14.0\",\n]\n\n[project.optional-dependencies]\nrust = [\"polars>=1.0,<1.6\"]\ncharts = [\"seaborn>=0.13\", \"matplotlib>=3.8\"]\ndev = [\n \"pytest>=8.0\",\n \"hypothesis>=6.0\",\n \"pytest-benchmark\",\n \"mypy>=1.8\",\n \"ruff>=0.3\",\n \"pandas-stubs\",\n \"maturin>=1.7\",\n]\nnotebooks = [\"jupyter\", \"nbconvert\"]\n\n[tool.maturin]\nmanifest-path = \"rust/ob_python/Cargo.toml\"\nmodule-name = \"options_portfolio_backtester._ob_rust\"\npython-source = \".\"\nfeatures = [\"pyo3/extension-module\"]\n\n[tool.setuptools.packages.find]\ninclude = [\"options_portfolio_backtester*\"]\n\n[tool.pytest.ini_options]\ntestpaths = [\"tests\"]\naddopts = \"-m \\\"not bench\\\" --ignore=tests/bench --ignore=tests/convexity --ignore=tests/compat --ignore=tests/test_deep_analytics_convexity.py\"\nmarkers = [\n \"bench: benchmark/property tests requiring explicit opt-in\",\n \"slow: full-range stress tests (17-year SPY, minutes to run)\",\n \"chaos: chaos / fault-injection tests\",\n]\nfilterwarnings = [\"ignore::DeprecationWarning\"]\n\n[tool.mypy]\npython_version = \"3.12\"\nwarn_unused_configs = true\ndisallow_untyped_defs = false\nignore_missing_imports = true\ncheck_untyped_defs = false\n\n[tool.ruff]\nline-length = 119\ntarget-version = \"py312\"\n\n[tool.ruff.lint]\nselect = [\"E\", \"F\", \"W\", \"I\"]\nignore = [\"E126\", \"F403\", \"F405\", \"W504\"]\n"
},
{
"path": "rust/.cargo/config.toml",
"content": "[env]\nPYO3_USE_ABI3_FORWARD_COMPATIBILITY = \"1\"\n"
},
{
"path": "rust/Cargo.toml",
"content": "[workspace]\nmembers = [\"ob_core\", \"ob_python\"]\nresolver = \"2\"\n"
},
{
"path": "rust/ob_core/Cargo.toml",
"content": "[package]\nname = \"ob_core\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n[dependencies]\npolars = { version = \"0.48\", features = [\"lazy\", \"parquet\", \"dtype-struct\", \"semi_anti_join\"] }\narrow = { version = \"55\", features = [\"ffi\"] }\nchrono = \"0.4\"\nrayon = \"1.10\"\nthiserror = \"2\"\n\n[dev-dependencies]\ncriterion = { version = \"0.5\", features = [\"html_reports\"] }\n\n[[bench]]\nname = \"hot_paths\"\nharness = false\n"
},
{
"path": "rust/ob_core/benches/hot_paths.rs",
"content": "use criterion::{black_box, criterion_group, criterion_main, Criterion};\nuse polars::prelude::*;\n\nuse ob_core::entries::{compute_entry_qty, compute_leg_entries};\nuse ob_core::exits::threshold_exit_mask;\nuse ob_core::filter::CompiledFilter;\nuse ob_core::inventory::join_inventory_to_market;\nuse ob_core::stats::compute_stats;\nuse ob_core::types::Direction;\n\nfn make_options_df(n: usize) -> DataFrame {\n let contracts: Vec = (0..n).map(|i| format!(\"SPX_{i}\")).collect();\n let underlyings: Vec<&str> = vec![\"SPX\"; n];\n let types: Vec<&str> = (0..n)\n .map(|i| if i % 2 == 0 { \"put\" } else { \"call\" })\n .collect();\n let expirations: Vec<&str> = vec![\"2024-06-01\"; n];\n let strikes: Vec = (0..n).map(|i| 3800.0 + i as f64 * 5.0).collect();\n let asks: Vec = (0..n).map(|i| 1.0 + (i % 50) as f64 * 0.5).collect();\n let bids: Vec = asks.iter().map(|a| a * 0.95).collect();\n let dtes: Vec = (0..n).map(|i| 30 + (i % 180) as i32).collect();\n\n DataFrame::new(vec![\n Column::new(\"optionroot\".into(), contracts),\n Column::new(\"underlying\".into(), underlyings),\n Column::new(\"type\".into(), types),\n Column::new(\"expiration\".into(), expirations),\n Column::new(\"strike\".into(), strikes),\n Column::new(\"ask\".into(), asks),\n Column::new(\"bid\".into(), bids),\n Column::new(\"dte\".into(), dtes),\n ])\n .unwrap()\n}\n\nfn bench_inventory_join(c: &mut Criterion) {\n let opts = make_options_df(10_000);\n let n_inv = 50;\n let contracts: Vec = (0..n_inv).map(|i| format!(\"SPX_{i}\")).collect();\n let qtys: Vec = vec![10.0; n_inv];\n let types: Vec = (0..n_inv)\n .map(|i| {\n if i % 2 == 0 {\n \"put\".into()\n } else {\n \"call\".into()\n }\n })\n .collect();\n\n let underlyings: Vec = vec![\"SPX\".into(); n_inv];\n let strikes: Vec = (0..n_inv).map(|i| 3800.0 + i as f64 * 5.0).collect();\n\n c.bench_function(\"inventory_join_50x10k\", |b| {\n b.iter(|| {\n let result = join_inventory_to_market(\n black_box(&contracts),\n black_box(&qtys),\n black_box(&types),\n black_box(&underlyings),\n black_box(&strikes),\n black_box(&opts),\n None,\n \"optionroot\",\n \"quotedate\",\n \"bid\",\n None,\n None,\n Direction::Buy,\n 100,\n )\n .unwrap();\n black_box(result.height());\n });\n });\n}\n\nfn bench_filter_compile_and_apply(c: &mut Criterion) {\n let df = make_options_df(10_000);\n\n let filter = CompiledFilter::new(\n \"(type == 'put') & (ask > 0) & (underlying == 'SPX') & (dte >= 60) & (dte <= 120)\",\n )\n .unwrap();\n\n c.bench_function(\"filter_apply_10k\", |b| {\n b.iter(|| {\n let result = filter.apply(black_box(&df)).unwrap();\n black_box(result.height());\n });\n });\n}\n\nfn bench_filter_compile(c: &mut Criterion) {\n c.bench_function(\"filter_compile\", |b| {\n b.iter(|| {\n let f = CompiledFilter::new(black_box(\n \"(type == 'put') & (ask > 0) & (underlying == 'SPX') & (dte >= 60) & (dte <= 120)\",\n ))\n .unwrap();\n black_box(&f);\n });\n });\n}\n\nfn bench_entry_computation(c: &mut Criterion) {\n let opts = make_options_df(10_000);\n let held: Vec = (0..10).map(|i| format!(\"SPX_{i}\")).collect();\n let filter = CompiledFilter::new(\"(type == 'put') & (ask > 0) & (dte >= 60)\").unwrap();\n\n c.bench_function(\"entry_compute_10k\", |b| {\n b.iter(|| {\n let result = compute_leg_entries(\n black_box(&opts),\n black_box(&held),\n black_box(&filter),\n \"optionroot\",\n \"ask\",\n Some(\"strike\"),\n true,\n 100,\n false,\n )\n .unwrap();\n black_box(result.height());\n });\n });\n}\n\nfn bench_exit_mask(c: &mut Criterion) {\n let n = 1000;\n let entries: Vec = (0..n).map(|i| 100.0 + (i % 50) as f64).collect();\n let currents: Vec = (0..n).map(|i| 80.0 + (i % 80) as f64).collect();\n\n let entry_s = Series::new(\"entry\".into(), &entries);\n let current_s = Series::new(\"current\".into(), ¤ts);\n\n c.bench_function(\"exit_mask_1k\", |b| {\n b.iter(|| {\n let mask = threshold_exit_mask(\n black_box(&entry_s),\n black_box(¤t_s),\n Some(0.5),\n Some(0.2),\n )\n .unwrap();\n black_box(mask.len());\n });\n });\n}\n\nfn bench_stats_computation(c: &mut Criterion) {\n let n = 2520; // ~10 years of trading days\n let returns: Vec = (0..n).map(|i| ((i as f64 * 0.1).sin()) * 0.02).collect();\n let pnls: Vec = (0..100)\n .map(|i| if i % 3 == 0 { -50.0 } else { 100.0 })\n .collect();\n\n c.bench_function(\"stats_10yr\", |b| {\n b.iter(|| {\n let s = compute_stats(black_box(&returns), black_box(&pnls), 0.02);\n black_box(s);\n });\n });\n}\n\nfn bench_entry_qty(c: &mut Criterion) {\n let n = 5000;\n let costs: Vec = (0..n).map(|i| 50.0 + (i % 200) as f64).collect();\n let series = Series::new(\"cost\".into(), &costs);\n\n c.bench_function(\"entry_qty_5k\", |b| {\n b.iter(|| {\n let qty = compute_entry_qty(black_box(&series), 1_000_000.0).unwrap();\n black_box(qty.len());\n });\n });\n}\n\ncriterion_group!(\n benches,\n bench_inventory_join,\n bench_filter_compile,\n bench_filter_compile_and_apply,\n bench_entry_computation,\n bench_exit_mask,\n bench_stats_computation,\n bench_entry_qty,\n);\ncriterion_main!(benches);\n"
},
{
"path": "rust/ob_core/src/backtest.rs",
"content": "//! Full backtest loop — mirrors BacktestEngine.run() for parity.\n//!\n//! Pre-partitions all data by date at startup for O(1) lookups instead of\n//! O(n) DataFrame scans on each access. Uses i64 nanosecond timestamps as\n//! HashMap keys to avoid string conversion overhead entirely.\n//!\n//! Key optimizations:\n//! - filter_by_date() → HashMap::get() O(n) → O(1)\n//! - get_contract_field_f64() → DayOptions::get_f64() O(n) → O(1)\n//! - get_contract_field_str() → DayOptions::get_str() O(n) → O(1)\n//! - get_symbol_price() → DayStocks::get_price() O(n) → O(1)\n//! - Date keys are i64 (nanoseconds) — no string allocation or comparison.\n\nuse std::collections::HashMap;\n\nuse chrono::DateTime;\nuse polars::prelude::*;\n\nuse crate::cost_model::CostModel;\nuse crate::entries::compute_leg_entries;\nuse crate::fill_model::FillModel;\nuse crate::filter::CompiledFilter;\nuse crate::risk::{self, RiskConstraint};\nuse crate::signal_selector::SignalSelector;\nuse crate::stats;\nuse crate::stats::Stats;\nuse crate::types::{Direction, Greeks, LegConfig};\n\n#[derive(Clone)]\npub struct BacktestConfig {\n pub allocation_stocks: f64,\n pub allocation_options: f64,\n pub allocation_cash: f64,\n pub initial_capital: f64,\n pub shares_per_contract: i64,\n pub legs: Vec,\n pub profit_pct: Option,\n pub loss_pct: Option,\n pub stock_symbols: Vec,\n pub stock_percentages: Vec,\n /// Pre-computed rebalance dates as nanoseconds since epoch.\n pub rebalance_dates: Vec,\n /// Transaction cost model.\n pub cost_model: CostModel,\n /// Fill model for execution pricing.\n pub fill_model: FillModel,\n /// Engine-level signal selector.\n pub signal_selector: SignalSelector,\n /// Risk constraints checked before entries.\n pub risk_constraints: Vec,\n /// SMA days for stock gating (None = no SMA gate).\n pub sma_days: Option,\n /// Options budget as a percentage of total capital per rebalance (overrides allocation_options).\n pub options_budget_pct: Option,\n /// Annual options budget as a percentage of total capital, auto-divided by rebalances/year.\n pub options_budget_annual_pct: Option,\n /// Stop the backtest if cash goes negative (mirrors Python's stop_if_broke).\n pub stop_if_broke: bool,\n /// Maximum short notional as fraction of total capital (None = no limit).\n pub max_notional_pct: Option,\n /// Check exits on every trading day, not just rebalance dates.\n pub check_exits_daily: bool,\n /// When true, spend the full budget each rebalance ignoring existing position value.\n /// Default (false) uses target model: spend = budget - existing_options_value.\n pub options_budget_fresh_spend: bool,\n /// When true, rebalance stocks immediately after daily option exits.\n /// Allows reinvesting put profits into stocks without waiting for the next rebalance date.\n pub rebalance_stocks_on_exit: bool,\n}\n\npub struct BacktestResult {\n pub balance: DataFrame,\n pub trade_log: DataFrame,\n pub final_cash: f64,\n pub stats: Stats,\n}\n\n/// Configuration for one strategy slot in a multi-strategy backtest.\n#[derive(Clone)]\npub struct StrategySlotConfig {\n pub name: String,\n pub legs: Vec,\n pub weight: f64,\n pub rebalance_dates: Vec,\n pub profit_pct: Option,\n pub loss_pct: Option,\n pub check_exits_daily: bool,\n}\n\nstruct Position {\n leg_contracts: Vec,\n leg_types: Vec,\n leg_directions: Vec,\n quantity: f64,\n entry_cost: f64,\n greeks: Greeks,\n /// Entry-time metadata per leg, used as fallback when contract is missing from today's data.\n leg_underlyings: Vec,\n leg_expirations: Vec,\n leg_strikes: Vec,\n}\n\nstruct StockHolding {\n symbol: String,\n qty: f64,\n price: f64,\n}\n\n/// Per-leg per-position entry in trade log (flat, converted to MultiIndex in Python).\nstruct TradeRow {\n date: i64,\n leg_data: Vec,\n total_cost: f64,\n qty: f64,\n}\n\nstruct LegTradeData {\n contract: String,\n underlying: String,\n expiration: String,\n opt_type: String,\n strike: f64,\n cost: f64,\n order: String,\n}\n\n/// Balance row for a single date range day.\nstruct BalanceDay {\n date: i64,\n cash: f64,\n calls_capital: f64,\n puts_capital: f64,\n options_qty: f64,\n stocks_qty: f64,\n stock_values: Vec<(String, f64)>,\n stock_qtys: Vec<(String, f64)>,\n}\n\n// ---------------------------------------------------------------------------\n// Date conversion helpers.\n// ---------------------------------------------------------------------------\n\n/// Convert nanoseconds since epoch to \"YYYY-MM-DD HH:MM:SS\" string.\nfn ns_to_datestring(ns: i64) -> String {\n let secs = ns.div_euclid(1_000_000_000);\n let nsec = ns.rem_euclid(1_000_000_000) as u32;\n DateTime::from_timestamp(secs, nsec)\n .map(|dt| dt.format(\"%Y-%m-%d %H:%M:%S\").to_string())\n .unwrap_or_default()\n}\n\n/// Parse \"YYYY-MM-DD HH:MM:SS\" to nanoseconds since epoch.\nfn parse_datestring_to_ns(s: &str) -> Option {\n chrono::NaiveDateTime::parse_from_str(s, \"%Y-%m-%d %H:%M:%S\")\n .ok()\n .map(|dt| {\n let ts = dt.and_utc().timestamp();\n ts * 1_000_000_000\n })\n}\n\n/// Extract an i64 date key (nanoseconds) from a column value at index.\n/// Handles Datetime (any time unit), Date, and String columns.\nfn extract_date_ns(col: &Column, idx: usize) -> i64 {\n match col.dtype() {\n DataType::Datetime(tu, _) => {\n let val = col.datetime().unwrap().get(idx).unwrap_or(0);\n match tu {\n TimeUnit::Nanoseconds => val,\n TimeUnit::Microseconds => val * 1_000,\n TimeUnit::Milliseconds => val * 1_000_000,\n }\n }\n DataType::Date => {\n let days = col.date().unwrap().get(idx).unwrap_or(0);\n days as i64 * 86_400_000_000_000i64\n }\n _ => {\n col.str().ok()\n .and_then(|ca| ca.get(idx))\n .and_then(parse_datestring_to_ns)\n .unwrap_or(0)\n }\n }\n}\n\n/// Read a column value as a String, handling both String and Datetime columns.\nfn column_value_to_string(col: &Column, idx: usize) -> String {\n if let Ok(ca) = col.str() {\n return ca.get(idx).unwrap_or(\"\").to_string();\n }\n match col.dtype() {\n DataType::Datetime(tu, _) => {\n let val = col.datetime().unwrap().get(idx).unwrap_or(0);\n let ns = match tu {\n TimeUnit::Nanoseconds => val,\n TimeUnit::Microseconds => val * 1_000,\n TimeUnit::Milliseconds => val * 1_000_000,\n };\n ns_to_datestring(ns)\n }\n DataType::Date => {\n let days = col.date().unwrap().get(idx).unwrap_or(0);\n ns_to_datestring(days as i64 * 86_400_000_000_000i64)\n }\n _ => String::new(),\n }\n}\n\n// ---------------------------------------------------------------------------\n// Pre-partitioned data structures — O(1) date and contract lookups.\n// ---------------------------------------------------------------------------\n\n/// Options data for a single date with O(1) contract lookups.\nstruct DayOptions {\n df: DataFrame,\n /// contract_string → row index within `df`.\n contract_idx: HashMap,\n}\n\nimpl DayOptions {\n fn new(df: DataFrame, contract_col: &str) -> Self {\n let mut contract_idx = HashMap::with_capacity(df.height());\n if let Ok(col) = df.column(contract_col) {\n if let Ok(ca) = col.str() {\n for (i, val) in ca.into_iter().enumerate() {\n if let Some(v) = val {\n // Keep first occurrence (matches original filter + iloc[0]).\n contract_idx.entry(v.to_string()).or_insert(i);\n }\n }\n }\n }\n DayOptions { df, contract_idx }\n }\n\n /// Get a float64 field for a contract — O(1).\n fn get_f64(&self, contract: &str, field: &str) -> Option {\n let &row_idx = self.contract_idx.get(contract)?;\n let col = self.df.column(field).ok()?;\n // Fast path: column is already f64.\n if let Ok(ca) = col.f64() {\n return ca.get(row_idx);\n }\n // Slow path: cast to f64 (e.g. Int64 strike column).\n let casted = col.cast(&DataType::Float64).ok()?;\n casted.f64().ok()?.get(row_idx)\n }\n\n /// Get a string field for a contract — O(1).\n /// Handles both String and Datetime columns (for expiration).\n fn get_str(&self, contract: &str, field: &str) -> Option {\n let &row_idx = self.contract_idx.get(contract)?;\n let col = self.df.column(field).ok()?;\n let s = column_value_to_string(col, row_idx);\n if s.is_empty() { None } else { Some(s) }\n }\n\n fn height(&self) -> usize {\n self.df.height()\n }\n}\n\n/// Stocks data for a single date — O(1) price lookups.\nstruct DayStocks {\n prices: HashMap,\n}\n\nimpl DayStocks {\n fn get_price(&self, symbol: &str) -> Option {\n self.prices.get(symbol).copied()\n }\n}\n\n/// All data pre-partitioned by date.\npub struct PartitionedData {\n options: HashMap,\n stocks: HashMap,\n /// All option dates as nanoseconds, sorted ascending.\n all_dates_sorted: Vec,\n}\n\n/// Schema column name mappings passed from Python.\n#[derive(Clone)]\npub struct SchemaMapping {\n pub contract: String,\n pub date: String,\n pub stocks_date: String,\n pub stocks_sym: String,\n pub stocks_price: String,\n pub underlying: String,\n pub expiration: String,\n pub option_type: String,\n pub strike: String,\n}\n\n// ---------------------------------------------------------------------------\n// Main entry point.\n// ---------------------------------------------------------------------------\n\npub fn run_backtest(\n config: &BacktestConfig,\n options_data: &DataFrame,\n stocks_data: &DataFrame,\n schema: &SchemaMapping,\n) -> PolarsResult {\n let partitioned = prepartition_data(options_data, stocks_data, schema)?;\n run_backtest_prepartitioned(config, &partitioned, schema)\n}\n\n/// Pre-compiled entry and exit filters for a backtest config.\n/// Avoids redundant filter parsing when running multiple configs in a sweep.\npub struct PrecompiledFilters {\n pub entry: Vec>,\n pub exit: Vec>,\n}\n\nimpl PrecompiledFilters {\n /// Compile filters from a BacktestConfig's legs.\n pub fn from_config(config: &BacktestConfig) -> Self {\n let entry = config.legs.iter()\n .map(|leg| leg.entry_filter_query.as_ref().and_then(|q| CompiledFilter::new(q).ok()))\n .collect();\n let exit = config.legs.iter()\n .map(|leg| leg.exit_filter_query.as_ref().and_then(|q| CompiledFilter::new(q).ok()))\n .collect();\n PrecompiledFilters { entry, exit }\n }\n}\n\n/// Run a backtest using pre-partitioned data (avoids re-partitioning in sweeps).\npub fn run_backtest_prepartitioned(\n config: &BacktestConfig,\n partitioned: &PartitionedData,\n schema: &SchemaMapping,\n) -> PolarsResult {\n let filters = PrecompiledFilters::from_config(config);\n run_backtest_with_filters(config, partitioned, schema, &filters)\n}\n\n/// Run a backtest with pre-compiled filters (used by sweep to avoid redundant compilation).\npub fn run_backtest_with_filters(\n config: &BacktestConfig,\n partitioned: &PartitionedData,\n schema: &SchemaMapping,\n filters: &PrecompiledFilters,\n) -> PolarsResult {\n let entry_filters = &filters.entry;\n let exit_filters = &filters.exit;\n\n let mut cash = config.initial_capital;\n let mut positions: Vec = Vec::new();\n let mut stock_holdings: Vec = Vec::new();\n let mut peak_value: f64 = config.initial_capital;\n // Initial value is overwritten inside the rebalance_date macro before first read,\n // but we need a valid initial binding for the macro's mutable capture.\n #[allow(unused_assignments)]\n let mut portfolio_greeks = Greeks::default();\n\n let mut trade_rows: Vec = Vec::new();\n let mut balance_days: Vec = Vec::new();\n\n // Pre-compute SMA per stock symbol if sma_days is set\n let sma_map_by_date = config.sma_days\n .map(|sma_days| compute_sma_map(&partitioned, &config.stock_symbols, sma_days));\n\n let rb_dates = &config.rebalance_dates;\n if rb_dates.is_empty() {\n return build_result(&trade_rows, &balance_days, &config.legs, cash);\n }\n\n // Pre-compute rebalances per year for annual budget conversion.\n let rebalances_per_year = if rb_dates.len() >= 2 {\n let first = rb_dates[0];\n let last = *rb_dates.last().unwrap();\n let years = (last - first) as f64 / (365.25 * 24.0 * 3600.0 * 1e9);\n if years > 0.0 { rb_dates.len() as f64 / years } else { rb_dates.len() as f64 }\n } else {\n 1.0\n };\n\n // Rebalance helper: executes full rebalance logic for a single date.\n // Extracted as a macro to avoid duplicating 60 lines across the two loop\n // variants (rb-only vs all-dates).\n macro_rules! rebalance_date {\n ($rb_date:expr, $prev_rb_date:expr, $partitioned:expr,\n $config:expr, $entry_filters:expr, $exit_filters:expr,\n $schema:expr, $sma_map_by_date:expr,\n $positions:expr, $stock_holdings:expr, $cash:expr,\n $peak_value:expr, $portfolio_greeks:expr,\n $trade_rows:expr, $balance_days:expr) => {{\n let rb_date = $rb_date;\n let prev_rb_date = $prev_rb_date;\n\n // _update_balance(prev_rb_date, rb_date)\n compute_balance_period(\n &$positions, &$stock_holdings,\n $partitioned,\n prev_rb_date, rb_date,\n $config.shares_per_contract, $cash,\n &$config.legs,\n &mut $balance_days,\n );\n\n let day_opts = match $partitioned.options.get(&rb_date) {\n Some(d) if d.height() > 0 => d,\n _ => { continue; }\n };\n let day_stocks = $partitioned.stocks.get(&rb_date);\n\n // Run exit filters\n execute_exits(\n &mut $positions, &mut $cash, day_opts,\n $config.shares_per_contract,\n &$config.legs, $exit_filters,\n $config.profit_pct, $config.loss_pct,\n $schema, rb_date, &mut $trade_rows,\n &$config.cost_model, day_stocks,\n )?;\n\n // Recompute portfolio greeks from current market data after exits\n $portfolio_greeks = compute_portfolio_greeks_from_market(\n &$positions, day_opts, &$config.legs,\n );\n\n // Compute total capital including held options\n let stock_cap = compute_stock_capital(&$stock_holdings, day_stocks);\n let options_cap = compute_options_capital(\n &$positions, day_opts, $config.shares_per_contract, day_stocks,\n );\n let total_capital = $cash + stock_cap + options_cap;\n $peak_value = $peak_value.max(total_capital);\n\n // Rebalance stocks\n let externally_funded = $config.options_budget_pct.is_some()\n || $config.options_budget_annual_pct.is_some();\n let liquid_capital = total_capital - options_cap;\n let stocks_alloc = if externally_funded {\n $config.allocation_stocks * liquid_capital\n } else {\n // Cap to liquid_capital: can't buy stocks with capital locked in options\n ($config.allocation_stocks * total_capital).min(liquid_capital)\n };\n $stock_holdings.clear();\n $cash = liquid_capital;\n\n let sma_prices = $sma_map_by_date.as_ref().and_then(|m| m.get(&rb_date));\n buy_stocks(\n &$config.stock_symbols, &$config.stock_percentages,\n day_stocks, stocks_alloc, &mut $stock_holdings,\n &$config.cost_model, &mut $cash, sma_prices,\n );\n\n // Options: buy with remaining budget only\n let options_alloc = if let Some(pct) = $config.options_budget_pct {\n total_capital * pct\n } else if let Some(annual) = $config.options_budget_annual_pct {\n total_capital * (annual / rebalances_per_year)\n } else {\n $config.allocation_options * total_capital\n };\n let remaining_budget = if $config.options_budget_fresh_spend {\n options_alloc\n } else {\n options_alloc - options_cap\n };\n if remaining_budget > 0.0 {\n let held: Vec = $positions.iter()\n .flat_map(|p| p.leg_contracts.clone())\n .collect();\n\n if externally_funded {\n $cash += remaining_budget;\n }\n\n if let Some(pos) = execute_entries(\n &$config.legs, $entry_filters, day_opts, &held,\n $config.shares_per_contract, remaining_budget,\n $schema, rb_date, &mut $trade_rows,\n &$config.fill_model, &$config.signal_selector,\n &$config.risk_constraints, &$portfolio_greeks,\n total_capital, $peak_value,\n $config.max_notional_pct, &$positions,\n )? {\n let cost = pos.entry_cost * pos.quantity;\n let commission = $config.cost_model.option_cost(\n cost.abs(), pos.quantity, $config.shares_per_contract,\n );\n $cash -= cost + commission;\n if externally_funded {\n // Claw back unspent portion of externally-funded budget\n $cash -= remaining_budget - cost - commission;\n }\n $portfolio_greeks += pos.greeks;\n $positions.push(pos);\n } else if externally_funded {\n $cash -= remaining_budget;\n }\n }\n\n if $config.stop_if_broke && $cash < 0.0 {\n break;\n }\n }};\n }\n\n if config.check_exits_daily {\n // All-dates loop: check exits on every trading day, rebalance on rb dates.\n use std::collections::HashSet;\n let rb_set: HashSet = rb_dates.iter().copied().collect();\n let mut rb_idx: usize = 0;\n\n for &date in &partitioned.all_dates_sorted {\n if rb_set.contains(&date) {\n let prev_rb_date = if rb_idx == 0 { date } else { rb_dates[rb_idx - 1] };\n rebalance_date!(\n date, prev_rb_date, &partitioned,\n config, &entry_filters, &exit_filters,\n schema, sma_map_by_date,\n positions, stock_holdings, cash,\n peak_value, portfolio_greeks,\n trade_rows, balance_days\n );\n rb_idx += 1;\n } else if !positions.is_empty() {\n // Non-rebalance day: only run exits\n if let Some(day_opts) = partitioned.options.get(&date) {\n let day_stocks = partitioned.stocks.get(&date);\n let cash_before = cash;\n execute_exits(\n &mut positions, &mut cash, day_opts,\n config.shares_per_contract,\n &config.legs, &exit_filters,\n config.profit_pct, config.loss_pct,\n schema, date, &mut trade_rows,\n &config.cost_model, day_stocks,\n )?;\n\n // Immediately reinvest freed cash into stocks\n if config.rebalance_stocks_on_exit && cash > cash_before {\n let stock_cap = compute_stock_capital(&stock_holdings, day_stocks);\n let options_cap = compute_options_capital(\n &positions, day_opts, config.shares_per_contract, day_stocks,\n );\n let total_capital = cash + stock_cap + options_cap;\n peak_value = peak_value.max(total_capital);\n\n let externally_funded = config.options_budget_pct.is_some()\n || config.options_budget_annual_pct.is_some();\n let liquid_capital = total_capital - options_cap;\n let stocks_alloc = if externally_funded {\n config.allocation_stocks * liquid_capital\n } else {\n (config.allocation_stocks * total_capital).min(liquid_capital)\n };\n stock_holdings.clear();\n cash = liquid_capital;\n\n let sma_prices = sma_map_by_date.as_ref().and_then(|m| m.get(&date));\n buy_stocks(\n &config.stock_symbols, &config.stock_percentages,\n day_stocks, stocks_alloc, &mut stock_holdings,\n &config.cost_model, &mut cash, sma_prices,\n );\n }\n }\n }\n }\n } else {\n // Fast path: iterate only rebalance dates (typical: ~200 vs ~4500 all dates).\n for (rb_idx, &rb_date) in rb_dates.iter().enumerate() {\n let prev_rb_date = if rb_idx == 0 { rb_date } else { rb_dates[rb_idx - 1] };\n rebalance_date!(\n rb_date, prev_rb_date, &partitioned,\n config, &entry_filters, &exit_filters,\n schema, sma_map_by_date,\n positions, stock_holdings, cash,\n peak_value, portfolio_greeks,\n trade_rows, balance_days\n );\n }\n }\n\n // Final balance update: last rebalance date to end of data\n let last_rb = *rb_dates.last().unwrap();\n let last_date = partitioned.all_dates_sorted.last().copied().unwrap_or(0);\n\n if last_date > 0 {\n compute_balance_period(\n &positions, &stock_holdings,\n &partitioned,\n last_rb, last_date,\n config.shares_per_contract, cash,\n &config.legs,\n &mut balance_days,\n );\n }\n\n build_result(&trade_rows, &balance_days, &config.legs, cash)\n}\n\n// ---------------------------------------------------------------------------\n// Multi-strategy backtest.\n// ---------------------------------------------------------------------------\n\n/// Run a multi-strategy backtest with per-slot inventories, shared stocks/cash.\n///\n/// Each slot has its own legs, rebalance schedule, exit thresholds, and weight.\n/// The shared config provides allocation, stocks, capital, cost/fill/signal models.\npub fn run_multi_strategy(\n config: &BacktestConfig,\n slots: &[StrategySlotConfig],\n partitioned: &PartitionedData,\n schema: &SchemaMapping,\n) -> PolarsResult {\n use std::collections::HashSet;\n\n let mut cash = config.initial_capital;\n let mut stock_holdings: Vec = Vec::new();\n let mut peak_value: f64 = config.initial_capital;\n\n // Per-slot state\n let mut slot_positions: Vec> = slots.iter().map(|_| Vec::new()).collect();\n let slot_filters: Vec = slots.iter().map(|slot| {\n // Build a temporary config just for filter compilation\n let tmp = BacktestConfig {\n legs: slot.legs.clone(),\n ..config.clone()\n };\n PrecompiledFilters::from_config(&tmp)\n }).collect();\n\n let mut trade_rows: Vec = Vec::new();\n let mut balance_days: Vec = Vec::new();\n\n // Pre-compute SMA\n let sma_map_by_date = config.sma_days\n .map(|sma_days| compute_sma_map(partitioned, &config.stock_symbols, sma_days));\n\n // Build set of all rebalance dates (union across slots) and per-slot sets\n let mut all_rb_set: HashSet = HashSet::new();\n let slot_rb_sets: Vec> = slots.iter().map(|slot| {\n let set: HashSet = slot.rebalance_dates.iter().copied().collect();\n all_rb_set.extend(&set);\n set\n }).collect();\n\n // Pre-compute rebalances per year for annual budget conversion.\n // Use the union of all slot rebalance dates.\n let mut all_rb_sorted: Vec = all_rb_set.iter().copied().collect();\n all_rb_sorted.sort_unstable();\n let rebalances_per_year = if all_rb_sorted.len() >= 2 {\n let first = all_rb_sorted[0];\n let last = *all_rb_sorted.last().unwrap();\n let years = (last - first) as f64 / (365.25 * 24.0 * 3600.0 * 1e9);\n if years > 0.0 { all_rb_sorted.len() as f64 / years } else { all_rb_sorted.len() as f64 }\n } else {\n 1.0\n };\n\n // All rebalance dates sorted\n let mut all_rb_dates: Vec = all_rb_set.iter().copied().collect();\n all_rb_dates.sort_unstable();\n\n if all_rb_dates.is_empty() {\n // Use legs from first slot for result columns\n let legs = if slots.is_empty() { &config.legs } else { &slots[0].legs };\n return build_result(&trade_rows, &balance_days, legs, cash);\n }\n\n // Determine if any slot uses daily exits\n let any_daily_exits = config.check_exits_daily\n || slots.iter().any(|s| s.check_exits_daily);\n\n // Track previous rebalance date for balance computation\n let mut prev_global_rb: Option = None;\n\n for &date in &partitioned.all_dates_sorted {\n let is_rebalance = all_rb_set.contains(&date);\n\n // Which slots rebalance on this date?\n let slots_rebalancing: Vec = if is_rebalance {\n (0..slots.len())\n .filter(|&i| slot_rb_sets[i].contains(&date))\n .collect()\n } else {\n Vec::new()\n };\n\n if is_rebalance {\n // Compute balance since previous rebalance\n let prev_rb = prev_global_rb.unwrap_or(date);\n compute_balance_period_multi(\n &slot_positions, &stock_holdings, partitioned,\n prev_rb, date, config.shares_per_contract, cash,\n slots, &mut balance_days,\n );\n prev_global_rb = Some(date);\n\n let day_opts = match partitioned.options.get(&date) {\n Some(d) if d.height() > 0 => d,\n _ => continue,\n };\n let day_stocks = partitioned.stocks.get(&date);\n\n // Phase 1: exits for rebalancing slots\n for &si in &slots_rebalancing {\n execute_exits(\n &mut slot_positions[si], &mut cash, day_opts,\n config.shares_per_contract,\n &slots[si].legs, &slot_filters[si].exit,\n slots[si].profit_pct, slots[si].loss_pct,\n schema, date, &mut trade_rows,\n &config.cost_model, day_stocks,\n )?;\n }\n\n // Phase 2: compute aggregate capital\n let stock_cap = compute_stock_capital(&stock_holdings, day_stocks);\n let options_cap: f64 = slot_positions.iter().map(|positions| {\n compute_options_capital(positions, day_opts, config.shares_per_contract, day_stocks)\n }).sum();\n let total_capital = cash + stock_cap + options_cap;\n peak_value = peak_value.max(total_capital);\n\n // Options allocation\n let options_alloc = if let Some(pct) = config.options_budget_pct {\n total_capital * pct\n } else if let Some(annual) = config.options_budget_annual_pct {\n total_capital * (annual / rebalances_per_year)\n } else {\n config.allocation_options * total_capital\n };\n\n // Phase 3: buy stocks (shared pool)\n let externally_funded = config.options_budget_pct.is_some()\n || config.options_budget_annual_pct.is_some();\n let liquid_capital = total_capital - options_cap;\n let stocks_alloc = if externally_funded {\n config.allocation_stocks * liquid_capital\n } else {\n // Cap to liquid_capital: can't buy stocks with capital locked in options\n (config.allocation_stocks * total_capital).min(liquid_capital)\n };\n stock_holdings.clear();\n cash = liquid_capital;\n\n let sma_prices = sma_map_by_date.as_ref().and_then(|m| m.get(&date));\n buy_stocks(\n &config.stock_symbols, &config.stock_percentages,\n day_stocks, stocks_alloc, &mut stock_holdings,\n &config.cost_model, &mut cash, sma_prices,\n );\n\n // Phase 4: entries per rebalancing slot\n for &si in &slots_rebalancing {\n let slot = &slots[si];\n let slot_opts_cap = compute_options_capital(\n &slot_positions[si], day_opts, config.shares_per_contract, day_stocks,\n );\n let slot_allocation = slot.weight * options_alloc;\n let remaining_budget = if config.options_budget_fresh_spend {\n slot_allocation\n } else {\n slot_allocation - slot_opts_cap\n };\n if remaining_budget > 0.0 {\n let held: Vec = slot_positions[si].iter()\n .flat_map(|p| p.leg_contracts.clone())\n .collect();\n\n if externally_funded {\n cash += remaining_budget;\n }\n\n let portfolio_greeks = compute_portfolio_greeks_from_market(\n &slot_positions[si], day_opts, &slot.legs,\n );\n\n if let Some(pos) = execute_entries(\n &slot.legs, &slot_filters[si].entry, day_opts, &held,\n config.shares_per_contract, remaining_budget,\n schema, date, &mut trade_rows,\n &config.fill_model, &config.signal_selector,\n &config.risk_constraints, &portfolio_greeks,\n total_capital, peak_value,\n config.max_notional_pct, &slot_positions[si],\n )? {\n let cost = pos.entry_cost * pos.quantity;\n let commission = config.cost_model.option_cost(\n cost.abs(), pos.quantity, config.shares_per_contract,\n );\n cash -= cost + commission;\n if externally_funded {\n cash -= remaining_budget - cost - commission;\n }\n slot_positions[si].push(pos);\n } else if externally_funded {\n cash -= remaining_budget;\n }\n }\n }\n\n if config.stop_if_broke && cash < 0.0 {\n break;\n }\n } else if any_daily_exits {\n // Non-rebalance day: run exits for slots with check_exits_daily\n if let Some(day_opts) = partitioned.options.get(&date) {\n let day_stocks = partitioned.stocks.get(&date);\n let cash_before = cash;\n for (si, slot) in slots.iter().enumerate() {\n if (slot.check_exits_daily || config.check_exits_daily)\n && !slot_positions[si].is_empty()\n {\n execute_exits(\n &mut slot_positions[si], &mut cash, day_opts,\n config.shares_per_contract,\n &slot.legs, &slot_filters[si].exit,\n slot.profit_pct, slot.loss_pct,\n schema, date, &mut trade_rows,\n &config.cost_model, day_stocks,\n )?;\n }\n }\n\n // If exits freed cash and rebalance_stocks_on_exit is set,\n // immediately reinvest into stocks (e.g. buy discounted stocks\n // during a crash after puts pay off).\n if config.rebalance_stocks_on_exit && cash > cash_before {\n let stock_cap = compute_stock_capital(&stock_holdings, day_stocks);\n let options_cap: f64 = slot_positions.iter().map(|positions| {\n compute_options_capital(positions, day_opts, config.shares_per_contract, day_stocks)\n }).sum();\n let total_capital = cash + stock_cap + options_cap;\n peak_value = peak_value.max(total_capital);\n\n let externally_funded = config.options_budget_pct.is_some()\n || config.options_budget_annual_pct.is_some();\n let liquid_capital = total_capital - options_cap;\n let stocks_alloc = if externally_funded {\n config.allocation_stocks * liquid_capital\n } else {\n (config.allocation_stocks * total_capital).min(liquid_capital)\n };\n stock_holdings.clear();\n cash = liquid_capital;\n\n let sma_prices = sma_map_by_date.as_ref().and_then(|m| m.get(&date));\n buy_stocks(\n &config.stock_symbols, &config.stock_percentages,\n day_stocks, stocks_alloc, &mut stock_holdings,\n &config.cost_model, &mut cash, sma_prices,\n );\n }\n }\n }\n }\n\n // Final balance update\n if let Some(last_rb) = prev_global_rb {\n let last_date = partitioned.all_dates_sorted.last().copied().unwrap_or(0);\n if last_date > 0 {\n compute_balance_period_multi(\n &slot_positions, &stock_holdings, partitioned,\n last_rb, last_date, config.shares_per_contract, cash,\n slots, &mut balance_days,\n );\n }\n }\n\n // Use legs from first slot for result columns\n let legs = if slots.is_empty() { &config.legs } else { &slots[0].legs };\n build_result(&trade_rows, &balance_days, legs, cash)\n}\n\n/// Compute balance for multi-strategy across all slot positions.\nfn compute_balance_period_multi(\n slot_positions: &[Vec],\n stock_holdings: &[StockHolding],\n partitioned: &PartitionedData,\n start_date: i64,\n end_date: i64,\n spc: i64,\n cash: f64,\n slots: &[StrategySlotConfig],\n balance_days: &mut Vec,\n) {\n let dates = &partitioned.all_dates_sorted;\n let start_idx = dates.partition_point(|&d| d < start_date);\n let end_idx = dates.partition_point(|&d| d < end_date);\n\n for &d in &dates[start_idx..end_idx] {\n let day_opts = partitioned.options.get(&d);\n let day_stocks = partitioned.stocks.get(&d);\n\n let mut calls_cap = 0.0;\n let mut puts_cap = 0.0;\n let mut options_qty = 0.0;\n\n if let Some(opts) = day_opts {\n for (si, positions) in slot_positions.iter().enumerate() {\n let legs = &slots[si].legs;\n for pos in positions {\n options_qty += pos.quantity;\n for (j, leg) in legs.iter().enumerate() {\n if j >= pos.leg_contracts.len() { continue; }\n let exit_price_col = leg.direction.invert().price_column();\n let price = opts.get_f64(&pos.leg_contracts[j], exit_price_col)\n .unwrap_or_else(|| {\n let spot = day_stocks\n .and_then(|ds| ds.get_price(&pos.leg_underlyings[j]))\n .unwrap_or(0.0);\n intrinsic_value(&pos.leg_types[j], pos.leg_strikes[j], spot)\n });\n let sign = leg.direction.invert().sign();\n let value = sign * price * pos.quantity * spc as f64;\n if pos.leg_types[j] == \"call\" {\n calls_cap += value;\n } else {\n puts_cap += value;\n }\n }\n }\n }\n }\n\n let mut stock_values = Vec::new();\n let mut stock_qtys = Vec::new();\n let mut stocks_qty = 0.0;\n for holding in stock_holdings {\n let price = day_stocks\n .and_then(|ds| ds.get_price(&holding.symbol))\n .unwrap_or(holding.price);\n stock_values.push((holding.symbol.clone(), holding.qty * price));\n stock_qtys.push((holding.symbol.clone(), holding.qty));\n stocks_qty += holding.qty;\n }\n\n balance_days.push(BalanceDay {\n date: d, cash, calls_capital: calls_cap, puts_capital: puts_cap,\n options_qty, stocks_qty, stock_values, stock_qtys,\n });\n }\n}\n\n// ---------------------------------------------------------------------------\n// Data pre-partitioning — called once at startup.\n// ---------------------------------------------------------------------------\n\npub fn prepartition_data(\n options_data: &DataFrame,\n stocks_data: &DataFrame,\n schema: &SchemaMapping,\n) -> PolarsResult {\n let date_col = &schema.date;\n let contract_col = &schema.contract;\n\n // Sort options by date (skip if already sorted — common for CSV data).\n // slice() is zero-copy (shares underlying Arrow arrays via Arc).\n let date_series_raw = options_data.column(date_col)?;\n let n_check = options_data.height();\n let already_sorted = if n_check < 2 {\n true\n } else {\n let first = extract_date_ns(date_series_raw, 0);\n let last = extract_date_ns(date_series_raw, n_check - 1);\n if first > last {\n false\n } else {\n // Sample a few points to verify monotonicity cheaply.\n let step = (n_check / 8).max(1);\n let mut prev = first;\n let mut sorted = true;\n let mut i = step;\n while i < n_check {\n let val = extract_date_ns(date_series_raw, i);\n if val < prev {\n sorted = false;\n break;\n }\n prev = val;\n i += step;\n }\n sorted\n }\n };\n let sorted_opts;\n let date_series;\n if already_sorted {\n sorted_opts = options_data.clone();\n date_series = date_series_raw;\n } else {\n sorted_opts = options_data.sort([date_col.as_str()], SortMultipleOptions::default())?;\n date_series = sorted_opts.column(date_col)?;\n };\n let n_opts = sorted_opts.height();\n\n // Estimate ~500 unique dates for typical datasets (avoids HashMap reallocations).\n let mut options_map: HashMap = HashMap::with_capacity(512);\n let mut all_dates: Vec = Vec::with_capacity(512);\n\n if n_opts > 0 {\n let mut start = 0;\n let mut current = extract_date_ns(date_series, 0);\n\n for i in 1..n_opts {\n let d = extract_date_ns(date_series, i);\n if d != current {\n let part = sorted_opts.slice(start as i64, i - start);\n all_dates.push(current);\n options_map.insert(current, DayOptions::new(part, contract_col));\n current = d;\n start = i;\n }\n }\n // Last group\n let part = sorted_opts.slice(start as i64, n_opts - start);\n all_dates.push(current);\n options_map.insert(current, DayOptions::new(part, contract_col));\n }\n\n // Stocks: iterate once and build price HashMaps directly.\n // (Small data — typically 4500 rows, so no sort+slice needed.)\n let stocks_date_col = &schema.stocks_date;\n let sym_col_name = &schema.stocks_sym;\n let price_col_name = &schema.stocks_price;\n\n let stocks_date_series = stocks_data.column(stocks_date_col)?;\n let sym_ca = stocks_data.column(sym_col_name)?.str()?;\n let price_raw = stocks_data.column(price_col_name)?;\n let price_casted = price_raw.cast(&DataType::Float64)?;\n let price_ca = price_casted.f64()?;\n let n_stocks = stocks_data.height();\n\n let mut stocks_map: HashMap = HashMap::with_capacity(512);\n\n for i in 0..n_stocks {\n let date_ns = extract_date_ns(stocks_date_series, i);\n if let (Some(sym), Some(price)) = (sym_ca.get(i), price_ca.get(i)) {\n stocks_map.entry(date_ns)\n .or_insert_with(|| DayStocks { prices: HashMap::new() })\n .prices\n .insert(sym.to_string(), price);\n }\n }\n\n Ok(PartitionedData {\n options: options_map,\n stocks: stocks_map,\n all_dates_sorted: all_dates,\n })\n}\n\n// ---------------------------------------------------------------------------\n// Execute exits.\n// ---------------------------------------------------------------------------\n\nfn execute_exits(\n positions: &mut Vec,\n cash: &mut f64,\n day_opts: &DayOptions,\n spc: i64,\n legs: &[LegConfig],\n exit_filters: &[Option],\n profit_pct: Option,\n loss_pct: Option,\n schema: &SchemaMapping,\n date: i64,\n trade_rows: &mut Vec,\n cost_model: &CostModel,\n day_stocks: Option<&DayStocks>,\n) -> PolarsResult<()> {\n let mut to_remove = Vec::new();\n\n for (i, pos) in positions.iter().enumerate() {\n let mut should_exit = false;\n\n // Check exit filters per leg — direct row evaluation, no Polars lazy overhead.\n for (j, _leg) in legs.iter().enumerate() {\n if let Some(ref flt) = exit_filters[j] {\n let contract = &pos.leg_contracts[j];\n if let Some(&row_idx) = day_opts.contract_idx.get(contract.as_str()) {\n // Contract exists today — check exit filter on its row.\n if flt.eval_row(&day_opts.df, row_idx) {\n should_exit = true;\n }\n } else {\n // Contract not in today's data → exit.\n should_exit = true;\n }\n }\n }\n\n // Check threshold exits — mirrors Python's Strategy.filter_thresholds:\n // excess_return = (current_cost / entry_cost + 1) * -sign(entry_cost)\n if !should_exit {\n let curr = compute_position_exit_cost(pos, day_opts, spc, day_stocks);\n let entry = pos.entry_cost;\n if entry != 0.0 {\n let excess_return = (curr / entry + 1.0) * -entry.signum();\n if profit_pct.is_some_and(|p| excess_return >= p)\n || loss_pct.is_some_and(|l| excess_return <= -l)\n {\n should_exit = true;\n }\n }\n }\n\n if should_exit {\n let exit_cost = compute_position_exit_cost(pos, day_opts, spc, day_stocks);\n *cash -= exit_cost * pos.quantity;\n\n // Apply exit commission\n let commission = cost_model.option_cost(\n exit_cost.abs(), pos.quantity.abs(), spc,\n );\n *cash -= commission;\n\n // Build trade row for exit\n let mut leg_data = Vec::new();\n for (j, leg) in legs.iter().enumerate() {\n let exit_price_col = leg.direction.invert().price_column();\n let price = day_opts.get_f64(&pos.leg_contracts[j], exit_price_col)\n .unwrap_or_else(|| {\n let spot = day_stocks\n .and_then(|ds| ds.get_price(&pos.leg_underlyings[j]))\n .unwrap_or(0.0);\n intrinsic_value(&pos.leg_types[j], pos.leg_strikes[j], spot)\n });\n // Cash flow sign: BUY receives (-1), SELL pays (+1)\n let cash_sign = if leg.direction == Direction::Buy { -1.0 } else { 1.0 };\n let cost = cash_sign * price * spc as f64;\n let order = match leg.direction {\n Direction::Buy => \"STC\",\n Direction::Sell => \"BTC\",\n };\n leg_data.push(LegTradeData {\n contract: pos.leg_contracts[j].clone(),\n underlying: day_opts.get_str(&pos.leg_contracts[j], &schema.underlying)\n .unwrap_or_else(|| pos.leg_underlyings[j].clone()),\n expiration: day_opts.get_str(&pos.leg_contracts[j], &schema.expiration)\n .unwrap_or_else(|| pos.leg_expirations[j].clone()),\n opt_type: pos.leg_types[j].clone(),\n strike: day_opts.get_f64(&pos.leg_contracts[j], &schema.strike)\n .unwrap_or(pos.leg_strikes[j]),\n cost,\n order: order.to_string(),\n });\n }\n trade_rows.push(TradeRow {\n date,\n leg_data,\n total_cost: exit_cost,\n qty: pos.quantity,\n });\n to_remove.push(i);\n }\n }\n\n for &i in to_remove.iter().rev() {\n positions.remove(i);\n }\n Ok(())\n}\n\n// ---------------------------------------------------------------------------\n// Liquidate all remaining option positions (full rebalance).\n// ---------------------------------------------------------------------------\n\n#[allow(dead_code)]\nfn liquidate_all_positions(\n positions: &mut Vec,\n cash: &mut f64,\n day_opts: &DayOptions,\n spc: i64,\n legs: &[LegConfig],\n schema: &SchemaMapping,\n date: i64,\n trade_rows: &mut Vec,\n cost_model: &CostModel,\n day_stocks: Option<&DayStocks>,\n) {\n for pos in positions.iter() {\n let exit_cost = compute_position_exit_cost(pos, day_opts, spc, day_stocks);\n *cash -= exit_cost * pos.quantity;\n\n let commission = cost_model.option_cost(\n exit_cost.abs(), pos.quantity.abs(), spc,\n );\n *cash -= commission;\n\n let mut leg_data = Vec::new();\n for (j, leg) in legs.iter().enumerate() {\n let exit_price_col = leg.direction.invert().price_column();\n let price = day_opts.get_f64(&pos.leg_contracts[j], exit_price_col)\n .unwrap_or_else(|| {\n let spot = day_stocks\n .and_then(|ds| ds.get_price(&pos.leg_underlyings[j]))\n .unwrap_or(0.0);\n intrinsic_value(&pos.leg_types[j], pos.leg_strikes[j], spot)\n });\n let cash_sign = if leg.direction == Direction::Buy { -1.0 } else { 1.0 };\n let cost = cash_sign * price * spc as f64;\n let order = match leg.direction {\n Direction::Buy => \"STC\",\n Direction::Sell => \"BTC\",\n };\n leg_data.push(LegTradeData {\n contract: pos.leg_contracts[j].clone(),\n underlying: day_opts.get_str(&pos.leg_contracts[j], &schema.underlying)\n .unwrap_or_else(|| pos.leg_underlyings[j].clone()),\n expiration: day_opts.get_str(&pos.leg_contracts[j], &schema.expiration)\n .unwrap_or_else(|| pos.leg_expirations[j].clone()),\n opt_type: pos.leg_types[j].clone(),\n strike: day_opts.get_f64(&pos.leg_contracts[j], &schema.strike)\n .unwrap_or(pos.leg_strikes[j]),\n cost,\n order: order.to_string(),\n });\n }\n trade_rows.push(TradeRow {\n date,\n leg_data,\n total_cost: exit_cost,\n qty: pos.quantity,\n });\n }\n positions.clear();\n}\n\n// ---------------------------------------------------------------------------\n// Execute entries.\n// ---------------------------------------------------------------------------\n\n#[allow(clippy::too_many_arguments)]\nfn execute_entries(\n legs: &[LegConfig],\n entry_filters: &[Option],\n day_opts: &DayOptions,\n held_contracts: &[String],\n spc: i64,\n budget: f64,\n schema: &SchemaMapping,\n date: i64,\n trade_rows: &mut Vec,\n fill_model: &FillModel,\n signal_selector: &SignalSelector,\n risk_constraints: &[RiskConstraint],\n portfolio_greeks: &Greeks,\n total_capital: f64,\n peak_value: f64,\n max_notional_pct: Option,\n existing_positions: &[Position],\n) -> PolarsResult> {\n let contract_col = &schema.contract;\n if legs.is_empty() || budget <= 0.0 {\n return Ok(None);\n }\n\n // Determine extra columns needed by selectors\n let mut extra_cols: Vec = Vec::new();\n for col_name in signal_selector.column_requirements() {\n extra_cols.push(col_name.to_string());\n }\n for leg in legs {\n if let Some(ref sel) = leg.signal_selector {\n for col_name in sel.column_requirements() {\n if !extra_cols.contains(&col_name.to_string()) {\n extra_cols.push(col_name.to_string());\n }\n }\n }\n }\n\n let mut leg_results: Vec = Vec::new();\n for (i, leg) in legs.iter().enumerate() {\n let filter = match &entry_filters[i] {\n Some(f) => f,\n None => return Ok(None),\n };\n let entries = compute_leg_entries(\n &day_opts.df, held_contracts, filter, contract_col,\n leg.direction.price_column(),\n leg.entry_sort_col.as_deref(), leg.entry_sort_asc,\n spc, leg.direction == Direction::Sell,\n &extra_cols,\n )?;\n if entries.height() == 0 {\n return Ok(None);\n }\n leg_results.push(entries);\n }\n\n // Pre-filter candidates by affordability (mirrors Python's qty > 0 filter).\n // Python computes qty = allocation // abs(total_cost) for every candidate row\n // and removes rows where qty == 0 before the signal selector runs.\n {\n let min_len = leg_results.iter().map(|df| df.height()).min().unwrap_or(0);\n if min_len == 0 {\n return Ok(None);\n }\n\n // Compute per-row total cost (sum of costs across all legs at each row index)\n let mut affordable = vec![false; min_len];\n for row in 0..min_len {\n let mut combined_cost = 0.0;\n for leg_df in &leg_results {\n if let Ok(col) = leg_df.column(\"cost\") {\n if let Ok(ca) = col.f64() {\n combined_cost += ca.get(row).unwrap_or(0.0);\n }\n }\n }\n let abs_cost = combined_cost.abs();\n if abs_cost > 0.0 && (budget / abs_cost).floor() >= 1.0 {\n affordable[row] = true;\n }\n }\n\n // Build a boolean mask and filter all legs to only affordable rows\n let mask = BooleanChunked::from_slice(\"mask\".into(), &affordable);\n for leg_df in &mut leg_results {\n // Truncate to min_len first (align by position like Python's reset_index)\n if leg_df.height() > min_len {\n *leg_df = leg_df.slice(0, min_len);\n }\n *leg_df = leg_df.filter(&mask)?;\n }\n\n if leg_results.iter().any(|df| df.height() == 0) {\n return Ok(None);\n }\n }\n\n // Apply signal selector per leg to pick the best row\n let mut leg_contracts = Vec::new();\n let mut leg_types = Vec::new();\n let mut leg_directions = Vec::new();\n let mut leg_underlyings = Vec::new();\n let mut leg_expirations = Vec::new();\n let mut leg_strikes = Vec::new();\n let mut total_cost = 0.0;\n let mut original_total_cost = 0.0;\n let mut leg_data = Vec::new();\n let mut entry_greeks = Greeks::default();\n\n for (i, leg_df) in leg_results.iter().enumerate() {\n // Per-leg selector override, or engine-level selector\n let sel = legs[i].signal_selector.as_ref().unwrap_or(signal_selector);\n let row_idx = sel.select_index(leg_df);\n\n let contract = leg_df.column(\"contract\")?.str()?.get(row_idx).unwrap_or(\"\").to_string();\n let opt_type = leg_df.column(\"type\")?.str()?.get(row_idx).unwrap_or(\"\").to_string();\n let original_cost = leg_df.column(\"cost\")?.f64()?.get(row_idx).unwrap_or(0.0);\n let mut cost = original_cost;\n let underlying = leg_df.column(\"underlying\")?.str()?.get(row_idx).unwrap_or(\"\").to_string();\n // Handle expiration as either String or Datetime\n let expiration = column_value_to_string(leg_df.column(\"expiration\")?, row_idx);\n let strike = leg_df.column(\"strike\")?.f64()?.get(row_idx).unwrap_or(0.0);\n\n // Apply fill model to re-price if not MarketAtBidAsk\n let leg_fill = legs[i].fill_model.as_ref().unwrap_or(fill_model);\n if !matches!(leg_fill, FillModel::MarketAtBidAsk) {\n // Look up bid/ask/volume from day data for this contract\n if let (Some(bid), Some(ask)) = (\n day_opts.get_f64(&contract, \"bid\"),\n day_opts.get_f64(&contract, \"ask\"),\n ) {\n let volume = day_opts.get_f64(&contract, \"volume\");\n let is_buy = legs[i].direction == Direction::Buy;\n let fill_price = leg_fill.fill_price(bid, ask, volume, is_buy);\n let sign = if is_buy { 1.0 } else { -1.0 };\n cost = sign * fill_price * spc as f64;\n }\n }\n\n // Collect Greeks from the entry row (for risk checking)\n let dir_sign = if legs[i].direction == Direction::Buy { 1.0 } else { -1.0 };\n let delta = day_opts.get_f64(&contract, \"delta\").unwrap_or(0.0);\n let gamma = day_opts.get_f64(&contract, \"gamma\").unwrap_or(0.0);\n let theta = day_opts.get_f64(&contract, \"theta\").unwrap_or(0.0);\n let vega = day_opts.get_f64(&contract, \"vega\").unwrap_or(0.0);\n\n let order = match legs[i].direction {\n Direction::Buy => \"BTO\",\n Direction::Sell => \"STO\",\n };\n\n leg_contracts.push(contract.clone());\n leg_types.push(opt_type.clone());\n leg_directions.push(legs[i].direction);\n leg_underlyings.push(underlying.clone());\n leg_expirations.push(expiration.clone());\n leg_strikes.push(strike);\n\n leg_data.push(LegTradeData {\n contract,\n underlying,\n expiration,\n opt_type,\n strike,\n cost,\n order: order.to_string(),\n });\n total_cost += cost;\n original_total_cost += original_cost;\n\n // Accumulate greeks (will be scaled by qty later)\n entry_greeks.delta += delta * dir_sign;\n entry_greeks.gamma += gamma * dir_sign;\n entry_greeks.theta += theta * dir_sign;\n entry_greeks.vega += vega * dir_sign;\n }\n\n if original_total_cost.abs() == 0.0 {\n return Ok(None);\n }\n\n // Qty is computed from the original (pre-fill-model) cost, matching Python behavior\n // where qty = allocation // abs(original_cost) is computed before fill model repricing.\n let mut qty = (budget / original_total_cost.abs()).floor();\n if qty <= 0.0 {\n return Ok(None);\n }\n\n // max_notional_pct: cap qty so total short notional stays under limit\n if let Some(max_pct) = max_notional_pct {\n let mut short_notional_per_contract = 0.0;\n for (i, leg) in legs.iter().enumerate() {\n if leg.direction == Direction::Sell {\n short_notional_per_contract += leg_strikes[i] * spc as f64;\n }\n }\n if short_notional_per_contract > 0.0 {\n let existing_short_notional: f64 = existing_positions.iter().map(|pos| {\n pos.leg_strikes.iter().enumerate()\n .filter(|(j, _)| pos.leg_directions[*j] == Direction::Sell)\n .map(|(_, &strike)| strike * pos.quantity * spc as f64)\n .sum::()\n }).sum();\n let max_notional = max_pct * total_capital;\n let available = (max_notional - existing_short_notional).max(0.0);\n let max_qty = (available / short_notional_per_contract).floor();\n qty = qty.min(max_qty);\n if qty <= 0.0 {\n return Ok(None);\n }\n }\n }\n\n // Scale greeks by quantity\n let scaled_greeks = entry_greeks.scale(qty);\n\n // Risk check: reject entry if any constraint fails\n if !risk_constraints.is_empty()\n && !risk::check_all(risk_constraints, portfolio_greeks, &scaled_greeks, total_capital, peak_value)\n {\n return Ok(None);\n }\n\n trade_rows.push(TradeRow {\n date,\n leg_data,\n total_cost,\n qty,\n });\n\n Ok(Some(Position {\n leg_contracts,\n leg_types,\n leg_directions,\n quantity: qty,\n entry_cost: total_cost,\n greeks: scaled_greeks,\n leg_underlyings,\n leg_expirations,\n leg_strikes,\n }))\n}\n\n// ---------------------------------------------------------------------------\n// Compute balance for a date range — uses pre-partitioned data.\n// ---------------------------------------------------------------------------\n\nfn compute_balance_period(\n positions: &[Position],\n stock_holdings: &[StockHolding],\n partitioned: &PartitionedData,\n start_date: i64,\n end_date: i64,\n spc: i64,\n cash: f64,\n legs: &[LegConfig],\n balance_days: &mut Vec,\n) {\n // Binary search for dates in [start_date, end_date).\n let dates = &partitioned.all_dates_sorted;\n let start_idx = dates.partition_point(|&d| d < start_date);\n let end_idx = dates.partition_point(|&d| d < end_date);\n\n for &d in &dates[start_idx..end_idx] {\n let day_opts = partitioned.options.get(&d);\n let day_stocks = partitioned.stocks.get(&d);\n\n // Compute calls/puts capital for each position\n let mut calls_cap = 0.0;\n let mut puts_cap = 0.0;\n let mut options_qty = 0.0;\n\n if let Some(opts) = day_opts {\n for pos in positions {\n options_qty += pos.quantity;\n for (j, leg) in legs.iter().enumerate() {\n if j >= pos.leg_contracts.len() { continue; }\n let exit_price_col = leg.direction.invert().price_column();\n let price = opts.get_f64(&pos.leg_contracts[j], exit_price_col)\n .unwrap_or_else(|| {\n let spot = day_stocks\n .and_then(|ds| ds.get_price(&pos.leg_underlyings[j]))\n .unwrap_or(0.0);\n intrinsic_value(&pos.leg_types[j], pos.leg_strikes[j], spot)\n });\n let sign = leg.direction.invert().sign();\n let value = sign * price * pos.quantity * spc as f64;\n\n if pos.leg_types[j] == \"call\" {\n calls_cap += value;\n } else {\n puts_cap += value;\n }\n }\n }\n }\n\n // Compute stock values\n let mut stock_values = Vec::new();\n let mut stock_qtys = Vec::new();\n let mut stocks_qty = 0.0;\n for holding in stock_holdings {\n let price = day_stocks\n .and_then(|ds| ds.get_price(&holding.symbol))\n .unwrap_or(holding.price);\n stock_values.push((holding.symbol.clone(), holding.qty * price));\n stock_qtys.push((holding.symbol.clone(), holding.qty));\n stocks_qty += holding.qty;\n }\n\n balance_days.push(BalanceDay {\n date: d,\n cash,\n calls_capital: calls_cap,\n puts_capital: puts_cap,\n options_qty,\n stocks_qty,\n stock_values,\n stock_qtys,\n });\n }\n}\n\n// ---------------------------------------------------------------------------\n// SMA computation — uses pre-partitioned stocks data.\n// ---------------------------------------------------------------------------\n\nfn compute_sma_map(\n partitioned: &PartitionedData,\n symbols: &[String],\n sma_days: usize,\n) -> HashMap> {\n let mut result: HashMap> = HashMap::new();\n\n for symbol in symbols {\n // Collect (date_ns, price) pairs for this symbol from pre-partitioned data.\n let mut date_prices: Vec<(i64, f64)> = Vec::new();\n for &date_ns in &partitioned.all_dates_sorted {\n if let Some(ds) = partitioned.stocks.get(&date_ns) {\n if let Some(price) = ds.get_price(symbol) {\n date_prices.push((date_ns, price));\n }\n }\n }\n\n // Compute rolling SMA\n for (i, &(date_ns, _)) in date_prices.iter().enumerate() {\n if i + 1 < sma_days {\n continue; // Not enough data yet\n }\n let start = i + 1 - sma_days;\n let sum: f64 = date_prices[start..=i].iter().map(|&(_, p)| p).sum();\n let sma = sum / sma_days as f64;\n\n result.entry(date_ns)\n .or_default()\n .insert(symbol.clone(), sma);\n }\n }\n\n result\n}\n\n// ---------------------------------------------------------------------------\n// Build result DataFrames.\n// ---------------------------------------------------------------------------\n\nfn build_result(\n trade_rows: &[TradeRow],\n balance_days: &[BalanceDay],\n legs: &[LegConfig],\n final_cash: f64,\n) -> PolarsResult {\n // Build trade log as flat DataFrame (Python converts to MultiIndex)\n let n_trades = trade_rows.len();\n let mut trade_dates: Vec = Vec::with_capacity(n_trades);\n let mut trade_total_costs: Vec = Vec::with_capacity(n_trades);\n let mut trade_qtys: Vec = Vec::with_capacity(n_trades);\n\n // Per-leg columns\n let mut leg_columns: Vec> =\n legs.iter().map(|_| Vec::with_capacity(n_trades)).collect();\n\n for tr in trade_rows {\n trade_dates.push(ns_to_datestring(tr.date));\n trade_total_costs.push(tr.total_cost);\n trade_qtys.push(tr.qty);\n for (j, ld) in tr.leg_data.iter().enumerate() {\n if j < leg_columns.len() {\n leg_columns[j].push((\n ld.contract.clone(), ld.underlying.clone(), ld.expiration.clone(),\n ld.opt_type.clone(), ld.strike, ld.cost, ld.order.clone(),\n ));\n }\n }\n }\n\n let mut trade_cols: Vec = vec![\n Column::new(\"totals__date\".into(), &trade_dates),\n Column::new(\"totals__cost\".into(), &trade_total_costs),\n Column::new(\"totals__qty\".into(), &trade_qtys),\n ];\n for (j, leg) in legs.iter().enumerate() {\n if j < leg_columns.len() {\n let data = &leg_columns[j];\n let prefix = &leg.name;\n trade_cols.push(Column::new(format!(\"{prefix}__contract\").into(),\n data.iter().map(|d| d.0.as_str()).collect::>()));\n trade_cols.push(Column::new(format!(\"{prefix}__underlying\").into(),\n data.iter().map(|d| d.1.as_str()).collect::>()));\n trade_cols.push(Column::new(format!(\"{prefix}__expiration\").into(),\n data.iter().map(|d| d.2.as_str()).collect::>()));\n trade_cols.push(Column::new(format!(\"{prefix}__type\").into(),\n data.iter().map(|d| d.3.as_str()).collect::>()));\n trade_cols.push(Column::new(format!(\"{prefix}__strike\").into(),\n data.iter().map(|d| d.4).collect::>()));\n trade_cols.push(Column::new(format!(\"{prefix}__cost\").into(),\n data.iter().map(|d| d.5).collect::>()));\n trade_cols.push(Column::new(format!(\"{prefix}__order\").into(),\n data.iter().map(|d| d.6.as_str()).collect::>()));\n }\n }\n let trade_log = DataFrame::new(trade_cols)?;\n\n // Build balance DataFrame\n let n_days = balance_days.len();\n let mut bal_dates: Vec = Vec::with_capacity(n_days);\n let mut bal_cash: Vec = Vec::with_capacity(n_days);\n let mut bal_calls: Vec = Vec::with_capacity(n_days);\n let mut bal_puts: Vec = Vec::with_capacity(n_days);\n let mut bal_opts_qty: Vec = Vec::with_capacity(n_days);\n let mut bal_stocks_qty: Vec = Vec::with_capacity(n_days);\n\n // Collect all stock symbols\n let mut stock_symbols: Vec = Vec::new();\n if let Some(first) = balance_days.first() {\n stock_symbols = first.stock_values.iter().map(|(s, _)| s.clone()).collect();\n }\n let mut stock_val_cols: Vec> = stock_symbols.iter().map(|_| Vec::with_capacity(n_days)).collect();\n let mut stock_qty_cols: Vec> = stock_symbols.iter().map(|_| Vec::with_capacity(n_days)).collect();\n\n for day in balance_days {\n bal_dates.push(ns_to_datestring(day.date));\n bal_cash.push(day.cash);\n bal_calls.push(day.calls_capital);\n bal_puts.push(day.puts_capital);\n bal_opts_qty.push(day.options_qty);\n bal_stocks_qty.push(day.stocks_qty);\n for (k, sym) in stock_symbols.iter().enumerate() {\n let val = day.stock_values.iter().find(|(s, _)| s == sym).map(|(_, v)| *v).unwrap_or(0.0);\n let qty = day.stock_qtys.iter().find(|(s, _)| s == sym).map(|(_, q)| *q).unwrap_or(0.0);\n stock_val_cols[k].push(val);\n stock_qty_cols[k].push(qty);\n }\n }\n\n let mut bal_cols: Vec = vec![\n Column::new(\"date\".into(), &bal_dates),\n Column::new(\"cash\".into(), &bal_cash),\n Column::new(\"calls capital\".into(), &bal_calls),\n Column::new(\"puts capital\".into(), &bal_puts),\n Column::new(\"options qty\".into(), &bal_opts_qty),\n Column::new(\"stocks qty\".into(), &bal_stocks_qty),\n ];\n for (k, sym) in stock_symbols.iter().enumerate() {\n bal_cols.push(Column::new(sym.as_str().into(), &stock_val_cols[k]));\n bal_cols.push(Column::new(format!(\"{sym} qty\").into(), &stock_qty_cols[k]));\n }\n let balance = DataFrame::new(bal_cols)?;\n\n // Stats from balance\n let totals: Vec = balance_days.iter().map(|d| {\n let stock_val: f64 = d.stock_values.iter().map(|(_, v)| *v).sum();\n d.cash + d.calls_capital + d.puts_capital + stock_val\n }).collect();\n let daily_returns = compute_daily_returns(&totals);\n let result_stats = stats::compute_stats(&daily_returns, &[], 0.0);\n\n Ok(BacktestResult { balance, trade_log, final_cash, stats: result_stats })\n}\n\n// ---------------------------------------------------------------------------\n// Small helpers.\n// ---------------------------------------------------------------------------\n\n/// Compute intrinsic value of an option: max(0, strike - spot) for puts,\n/// max(0, spot - strike) for calls.\nfn intrinsic_value(opt_type: &str, strike: f64, underlying_price: f64) -> f64 {\n if opt_type == \"call\" {\n (underlying_price - strike).max(0.0)\n } else {\n (strike - underlying_price).max(0.0)\n }\n}\n\n/// Compute the total exit cost for a position — O(1) per leg via DayOptions.\nfn compute_position_exit_cost(pos: &Position, day_opts: &DayOptions, spc: i64, day_stocks: Option<&DayStocks>) -> f64 {\n let mut total = 0.0;\n for (i, contract) in pos.leg_contracts.iter().enumerate() {\n let dir = pos.leg_directions[i];\n let price = day_opts.get_f64(contract, dir.invert().price_column())\n .unwrap_or_else(|| {\n let spot = day_stocks\n .and_then(|ds| ds.get_price(&pos.leg_underlyings[i]))\n .unwrap_or(0.0);\n intrinsic_value(&pos.leg_types[i], pos.leg_strikes[i], spot)\n });\n let cash_sign = if dir == Direction::Buy { -1.0 } else { 1.0 };\n total += cash_sign * price * spc as f64;\n }\n total\n}\n\nfn compute_stock_capital(holdings: &[StockHolding], day_stocks: Option<&DayStocks>) -> f64 {\n let ds = match day_stocks {\n Some(ds) => ds,\n None => return 0.0,\n };\n holdings.iter().map(|h| {\n ds.get_price(&h.symbol).unwrap_or(0.0) * h.qty\n }).sum()\n}\n\nfn compute_options_capital(\n positions: &[Position], day_opts: &DayOptions, spc: i64, day_stocks: Option<&DayStocks>,\n) -> f64 {\n positions.iter().map(|pos| {\n -compute_position_exit_cost(pos, day_opts, spc, day_stocks) * pos.quantity\n }).sum()\n}\n\n/// Compute aggregate portfolio greeks from CURRENT market data, matching\n/// Python's `_compute_portfolio_greeks(options)` which merges inventory\n/// contracts with today's options to get current delta/gamma/theta/vega.\nfn compute_portfolio_greeks_from_market(\n positions: &[Position],\n day_opts: &DayOptions,\n legs: &[LegConfig],\n) -> Greeks {\n let mut total = Greeks::default();\n for pos in positions {\n for (j, leg) in legs.iter().enumerate() {\n if j >= pos.leg_contracts.len() { continue; }\n let contract = &pos.leg_contracts[j];\n let dir_sign = if leg.direction == Direction::Buy { 1.0 } else { -1.0 };\n let delta = day_opts.get_f64(contract, \"delta\").unwrap_or(0.0);\n let gamma = day_opts.get_f64(contract, \"gamma\").unwrap_or(0.0);\n let theta = day_opts.get_f64(contract, \"theta\").unwrap_or(0.0);\n let vega = day_opts.get_f64(contract, \"vega\").unwrap_or(0.0);\n\n total.delta += delta * dir_sign * pos.quantity;\n total.gamma += gamma * dir_sign * pos.quantity;\n total.theta += theta * dir_sign * pos.quantity;\n total.vega += vega * dir_sign * pos.quantity;\n }\n }\n total\n}\n\nfn buy_stocks(\n symbols: &[String], percentages: &[f64],\n day_stocks: Option<&DayStocks>,\n allocation: f64, holdings: &mut Vec,\n cost_model: &CostModel,\n cash: &mut f64,\n sma_prices: Option<&HashMap>,\n) {\n let ds = match day_stocks {\n Some(ds) => ds,\n None => return,\n };\n let mut stock_cost_total = 0.0;\n let mut commission_total = 0.0;\n for (symbol, pct) in symbols.iter().zip(percentages) {\n if let Some(price) = ds.get_price(symbol) {\n if price > 0.0 {\n // SMA gating: only buy if sma < price\n if let Some(sma_map) = sma_prices {\n if let Some(&sma_val) = sma_map.get(symbol) {\n if sma_val >= price {\n holdings.push(StockHolding { symbol: symbol.clone(), qty: 0.0, price });\n continue;\n }\n }\n }\n let qty = (allocation * pct / price).floor();\n commission_total += cost_model.stock_cost(price, qty);\n stock_cost_total += qty * price;\n holdings.push(StockHolding { symbol: symbol.clone(), qty, price });\n }\n }\n }\n *cash -= stock_cost_total + commission_total;\n}\n\nfn compute_daily_returns(totals: &[f64]) -> Vec {\n if totals.len() < 2 { return Vec::new(); }\n totals.windows(2).map(|w| if w[0] != 0.0 { (w[1] - w[0]) / w[0] } else { 0.0 }).collect()\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn daily_returns_basic() {\n let totals = vec![100.0, 110.0, 105.0];\n let returns = compute_daily_returns(&totals);\n assert_eq!(returns.len(), 2);\n assert!((returns[0] - 0.1).abs() < 1e-10);\n assert!((returns[1] - (-5.0 / 110.0)).abs() < 1e-10);\n }\n\n #[test]\n fn daily_returns_empty() {\n assert!(compute_daily_returns(&[]).is_empty());\n assert!(compute_daily_returns(&[100.0]).is_empty());\n }\n\n #[test]\n fn ns_to_datestring_epoch() {\n assert_eq!(ns_to_datestring(0), \"1970-01-01 00:00:00\");\n }\n\n #[test]\n fn ns_roundtrip() {\n let s = \"2024-06-15 00:00:00\";\n let ns = parse_datestring_to_ns(s).unwrap();\n assert_eq!(ns_to_datestring(ns), s);\n }\n\n #[test]\n fn intrinsic_value_put_itm() {\n // Put with strike 400, spot 380 → intrinsic = 20\n assert!((intrinsic_value(\"put\", 400.0, 380.0) - 20.0).abs() < 1e-10);\n }\n\n #[test]\n fn intrinsic_value_put_otm() {\n // Put with strike 400, spot 420 → intrinsic = 0\n assert!((intrinsic_value(\"put\", 400.0, 420.0)).abs() < 1e-10);\n }\n\n #[test]\n fn intrinsic_value_call_itm() {\n // Call with strike 400, spot 420 → intrinsic = 20\n assert!((intrinsic_value(\"call\", 400.0, 420.0) - 20.0).abs() < 1e-10);\n }\n\n #[test]\n fn intrinsic_value_call_otm() {\n // Call with strike 400, spot 380 → intrinsic = 0\n assert!((intrinsic_value(\"call\", 400.0, 380.0)).abs() < 1e-10);\n }\n\n #[test]\n fn intrinsic_value_atm() {\n // ATM: strike == spot → intrinsic = 0 for both\n assert!((intrinsic_value(\"put\", 400.0, 400.0)).abs() < 1e-10);\n assert!((intrinsic_value(\"call\", 400.0, 400.0)).abs() < 1e-10);\n }\n\n #[test]\n fn exit_cost_uses_intrinsic_when_missing() {\n // Position with a put at strike 400, spot at 380\n // Contract not in day options → should use intrinsic (20.0)\n let pos = Position {\n leg_contracts: vec![\"MISSING_CONTRACT\".into()],\n leg_types: vec![\"put\".into()],\n leg_directions: vec![Direction::Sell],\n quantity: 1.0,\n entry_cost: -100.0,\n greeks: Greeks::default(),\n leg_underlyings: vec![\"SPY\".into()],\n leg_expirations: vec![\"2024-06-01\".into()],\n leg_strikes: vec![400.0],\n };\n\n let empty_opts = DayOptions {\n df: DataFrame::default(),\n contract_idx: HashMap::new(),\n };\n\n let mut prices = HashMap::new();\n prices.insert(\"SPY\".to_string(), 380.0);\n let day_stocks = DayStocks { prices };\n\n // Sell direction → exit price col is \"ask\" (invert of Sell = Buy → price_column = \"ask\")\n // cash_sign for Sell = +1\n // exit_cost = +1 * 20.0 * 100 = 2000.0\n let exit_cost = compute_position_exit_cost(&pos, &empty_opts, 100, Some(&day_stocks));\n assert!((exit_cost - 2000.0).abs() < 1e-10,\n \"Expected exit cost 2000.0 for ITM short put, got {exit_cost}\");\n }\n}\n"
},
{
"path": "rust/ob_core/src/balance.rs",
"content": "//! Full _update_balance orchestration in Rust.\n//!\n//! Mirrors Python's BacktestEngine._update_balance: for a date range,\n//! join inventory to market data, compute calls/puts capital, stock values,\n//! and assemble balance rows.\n\nuse polars::prelude::*;\n\nuse crate::inventory::{aggregate_by_type, join_inventory_to_market};\nuse crate::types::Direction;\n\n/// Leg inventory data needed for balance computation.\npub struct LegInventory {\n pub contracts: Vec,\n pub qtys: Vec,\n pub types: Vec,\n pub direction: Direction,\n pub underlyings: Vec,\n pub strikes: Vec,\n}\n\n/// Stock inventory data.\npub struct StockInventory {\n pub symbols: Vec,\n pub qtys: Vec,\n}\n\n/// Compute balance for a date range.\n///\n/// This is the full orchestration of the hot path:\n/// 1. For each leg, join inventory to market data\n/// 2. Aggregate calls/puts capital by date\n/// 3. Compute stock values\n/// 4. Assemble balance rows\npub fn compute_balance(\n legs: &[LegInventory],\n stocks: &StockInventory,\n options_data: &DataFrame,\n stocks_data: &DataFrame,\n contract_col: &str,\n date_col: &str,\n stocks_date_col: &str,\n stocks_sym_col: &str,\n stocks_price_col: &str,\n shares_per_contract: i64,\n cash: f64,\n) -> PolarsResult {\n // Build a stocks snapshot for intrinsic value fallback:\n // For balance computation we pass the full stocks_data to inventory join\n // so it can look up spot prices for missing contracts.\n // Get unique dates from options\n let dates = options_data\n .column(date_col)?\n .unique()?;\n\n let mut calls_total = Series::new(\"calls_capital\".into(), vec![0.0f64; dates.len()]);\n let mut puts_total = Series::new(\"puts_capital\".into(), vec![0.0f64; dates.len()]);\n\n // Process each leg\n for leg in legs {\n if leg.contracts.is_empty() {\n continue;\n }\n\n let cost_field = match leg.direction {\n Direction::Buy => \"bid\", // exit price for buy = bid\n Direction::Sell => \"ask\", // exit price for sell = ask\n };\n\n let joined = join_inventory_to_market(\n &leg.contracts,\n &leg.qtys,\n &leg.types,\n &leg.underlyings,\n &leg.strikes,\n options_data,\n Some(stocks_data),\n contract_col,\n date_col,\n cost_field,\n Some(stocks_sym_col),\n Some(stocks_price_col),\n leg.direction.invert(),\n shares_per_contract,\n )?;\n\n let (calls_df, puts_df) = aggregate_by_type(&joined, date_col)?;\n\n // Add to running totals (would need date alignment in production)\n if calls_df.height() > 0 {\n if let Ok(col) = calls_df.column(\"calls_capital\") {\n let vals = col.f64()?;\n let total_vals = calls_total.f64()?;\n let new: Float64Chunked = total_vals\n .into_iter()\n .zip(vals.into_iter())\n .map(|(a, b)| Some(a.unwrap_or(0.0) + b.unwrap_or(0.0)))\n .collect();\n calls_total = new.into_series();\n }\n }\n\n if puts_df.height() > 0 {\n if let Ok(col) = puts_df.column(\"puts_capital\") {\n let vals = col.f64()?;\n let total_vals = puts_total.f64()?;\n let new: Float64Chunked = total_vals\n .into_iter()\n .zip(vals.into_iter())\n .map(|(a, b)| Some(a.unwrap_or(0.0) + b.unwrap_or(0.0)))\n .collect();\n puts_total = new.into_series();\n }\n }\n }\n\n // Compute stock values\n let stock_values = compute_stock_values(\n stocks,\n stocks_data,\n stocks_date_col,\n stocks_sym_col,\n stocks_price_col,\n )?;\n\n // Assemble balance DataFrame\n let cash_series = Series::new(\"cash\".into(), vec![cash; dates.len()]);\n let options_qty: f64 = legs.iter().flat_map(|l| &l.qtys).sum();\n let options_qty_series = Series::new(\"options_qty\".into(), vec![options_qty; dates.len()]);\n let stocks_qty: f64 = stocks.qtys.iter().sum();\n let stocks_qty_series = Series::new(\"stocks_qty\".into(), vec![stocks_qty; dates.len()]);\n\n let mut columns = vec![\n dates.clone().into_column(),\n cash_series.into_column(),\n options_qty_series.into_column(),\n calls_total.with_name(\"calls_capital\".into()).into_column(),\n puts_total.with_name(\"puts_capital\".into()).into_column(),\n stocks_qty_series.into_column(),\n ];\n\n // Add stock value columns\n for col in stock_values.get_columns() {\n columns.push(col.clone());\n }\n\n DataFrame::new(columns)\n}\n\nfn compute_stock_values(\n stocks: &StockInventory,\n stocks_data: &DataFrame,\n date_col: &str,\n sym_col: &str,\n price_col: &str,\n) -> PolarsResult {\n if stocks.symbols.is_empty() {\n return Ok(DataFrame::default());\n }\n\n let mut result_cols: Vec = Vec::new();\n\n for (symbol, qty) in stocks.symbols.iter().zip(stocks.qtys.iter()) {\n let filtered = stocks_data\n .clone()\n .lazy()\n .filter(col(sym_col).eq(lit(symbol.as_str())))\n .select([\n col(date_col),\n (col(price_col) * lit(*qty)).alias(symbol.as_str()),\n ])\n .collect()?;\n\n if let Ok(val_col) = filtered.column(symbol.as_str()) {\n result_cols.push(val_col.clone());\n }\n }\n\n if result_cols.is_empty() {\n return Ok(DataFrame::default());\n }\n\n DataFrame::new(result_cols)\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn compute_balance_empty_legs() {\n let opts = df!(\n \"optionroot\" => &[\"A\"],\n \"quotedate\" => &[\"2024-01-01\"],\n \"ask\" => &[1.0],\n \"bid\" => &[0.9],\n )\n .unwrap();\n\n let stocks_df = df!(\n \"date\" => &[\"2024-01-01\"],\n \"symbol\" => &[\"SPY\"],\n \"adjClose\" => &[450.0],\n )\n .unwrap();\n\n let result = compute_balance(\n &[], // no legs\n &StockInventory {\n symbols: vec![\"SPY\".into()],\n qtys: vec![100.0],\n },\n &opts,\n &stocks_df,\n \"optionroot\",\n \"quotedate\",\n \"date\",\n \"symbol\",\n \"adjClose\",\n 100,\n 1_000_000.0,\n );\n\n assert!(result.is_ok());\n }\n}\n"
},
{
"path": "rust/ob_core/src/convexity_backtest.rs",
"content": "/// Backtest engine: monthly rebalance loop for tail hedge overlay.\n///\n/// Model: 100% invested in equity (SPY). Each month, sell a fixed budget\n/// worth of equity to buy ~10-delta puts. Put proceeds are reinvested\n/// into equity at settlement. Budget is fixed at initial_capital * budget_pct\n/// (not scaled with portfolio growth) to avoid unrealistic compounding.\n\nuse chrono::{DateTime, Datelike};\n\nuse crate::convexity_scoring;\n\nstruct Position {\n strike: f64,\n expiration_ns: i64,\n entry_ask: f64,\n contracts: i32,\n}\n\npub struct MonthRecord {\n pub date_ns: i64,\n pub shares: f64,\n pub stock_price: f64,\n pub equity_value: f64,\n pub put_cost: f64,\n pub put_exit_value: f64,\n pub put_pnl: f64,\n pub portfolio_value: f64,\n pub convexity_ratio: f64,\n pub strike: f64,\n pub contracts: i32,\n}\n\npub struct BacktestResult {\n pub records: Vec,\n pub daily_dates_ns: Vec,\n pub daily_balances: Vec,\n}\n\nfn ns_to_year_month(ns: i64) -> (i32, u32) {\n let secs = ns / 1_000_000_000;\n let dt = DateTime::from_timestamp(secs, 0).expect(\"valid timestamp\");\n (dt.year(), dt.month())\n}\n\n/// Extract monthly rebalance dates (first trading day of each month).\nfn monthly_rebalance_dates(stock_dates_ns: &[i64]) -> Vec {\n let mut dates = Vec::new();\n if stock_dates_ns.is_empty() {\n return dates;\n }\n\n let mut prev_ym = ns_to_year_month(stock_dates_ns[0]);\n dates.push(stock_dates_ns[0]);\n\n for &d in &stock_dates_ns[1..] {\n let ym = ns_to_year_month(d);\n if ym != prev_ym {\n dates.push(d);\n prev_ym = ym;\n }\n }\n\n dates\n}\n\n/// Binary search for first index where arr[i] >= target.\nfn lower_bound(arr: &[i64], target: i64) -> usize {\n arr.partition_point(|&x| x < target)\n}\n\n/// Find the index range [start, end) for a specific date in sorted data.\nfn find_date_range(dates_ns: &[i64], target: i64) -> (usize, usize) {\n let start = lower_bound(dates_ns, target);\n if start >= dates_ns.len() || dates_ns[start] != target {\n return (start, start);\n }\n let mut end = start + 1;\n while end < dates_ns.len() && dates_ns[end] == target {\n end += 1;\n }\n (start, end)\n}\n\n/// Find stock price on or before a given date.\nfn stock_price_on(stock_dates_ns: &[i64], stock_prices: &[f64], target_ns: i64) -> Option {\n let idx = lower_bound(stock_dates_ns, target_ns);\n if idx < stock_dates_ns.len() && stock_dates_ns[idx] == target_ns {\n Some(stock_prices[idx])\n } else if idx > 0 {\n Some(stock_prices[idx - 1])\n } else {\n None\n }\n}\n\n/// Close a position: find exit value from options data or use intrinsic.\nfn close_position(\n pos: &Position,\n rebal_date_ns: i64,\n put_dates_ns: &[i64],\n put_expirations_ns: &[i64],\n put_strikes: &[f64],\n put_bids: &[f64],\n stock_dates_ns: &[i64],\n stock_prices: &[f64],\n current_stock_price: f64,\n) -> f64 {\n if pos.expiration_ns <= rebal_date_ns {\n let exp_price = stock_price_on(stock_dates_ns, stock_prices, pos.expiration_ns)\n .unwrap_or(current_stock_price);\n let intrinsic = (pos.strike - exp_price).max(0.0);\n intrinsic * 100.0 * pos.contracts as f64\n } else {\n let (start, end) = find_date_range(put_dates_ns, rebal_date_ns);\n for j in start..end {\n if (put_strikes[j] - pos.strike).abs() < 0.001\n && put_expirations_ns[j] == pos.expiration_ns\n {\n return put_bids[j] * 100.0 * pos.contracts as f64;\n }\n }\n let intrinsic = (pos.strike - current_stock_price).max(0.0);\n intrinsic * 100.0 * pos.contracts as f64\n }\n}\n\n#[allow(clippy::too_many_arguments)]\npub fn run_backtest(\n put_dates_ns: &[i64],\n put_expirations_ns: &[i64],\n put_strikes: &[f64],\n put_bids: &[f64],\n put_asks: &[f64],\n put_deltas: &[f64],\n put_underlying: &[f64],\n put_dtes: &[i32],\n _put_ivs: &[f64],\n stock_dates_ns: &[i64],\n stock_prices: &[f64],\n initial_capital: f64,\n budget_pct: f64,\n target_delta: f64,\n dte_min: i32,\n dte_max: i32,\n tail_drop: f64,\n) -> BacktestResult {\n let rebalance_dates = monthly_rebalance_dates(stock_dates_ns);\n\n let mut records = Vec::with_capacity(rebalance_dates.len());\n let mut daily_dates: Vec = Vec::with_capacity(stock_dates_ns.len());\n let mut daily_balances: Vec = Vec::with_capacity(stock_dates_ns.len());\n\n if rebalance_dates.is_empty() || stock_dates_ns.is_empty() {\n return BacktestResult {\n records,\n daily_dates_ns: daily_dates,\n daily_balances,\n };\n }\n\n let first_price = stock_price_on(stock_dates_ns, stock_prices, rebalance_dates[0])\n .unwrap_or(stock_prices[0]);\n let mut shares = initial_capital / first_price;\n let mut position: Option = None;\n let fixed_budget = initial_capital * budget_pct;\n\n for (i, &rebal_date) in rebalance_dates.iter().enumerate() {\n let stock_price =\n stock_price_on(stock_dates_ns, stock_prices, rebal_date).unwrap_or(first_price);\n\n // 1. Close existing position — reinvest proceeds into equity\n let (put_exit_value, prev_put_cost) = if let Some(ref pos) = position {\n let cost = pos.entry_ask * 100.0 * pos.contracts as f64;\n let exit_val = close_position(\n pos,\n rebal_date,\n put_dates_ns,\n put_expirations_ns,\n put_strikes,\n put_bids,\n stock_dates_ns,\n stock_prices,\n stock_price,\n );\n if stock_price > 0.0 {\n shares += exit_val / stock_price;\n }\n (exit_val, cost)\n } else {\n (0.0, 0.0)\n };\n let put_pnl = put_exit_value - prev_put_cost;\n\n // 2. Fixed budget — sell equity worth fixed_budget to fund puts\n let budget = fixed_budget;\n if stock_price > 0.0 {\n shares -= budget / stock_price;\n }\n\n // 3. Open new position\n let (opt_start, opt_end) = find_date_range(put_dates_ns, rebal_date);\n\n let mut new_cost = 0.0;\n let mut new_contracts = 0i32;\n let mut new_strike = 0.0;\n let mut new_ratio = 0.0;\n\n if opt_start < opt_end {\n let slice_deltas = &put_deltas[opt_start..opt_end];\n let slice_dtes = &put_dtes[opt_start..opt_end];\n let slice_asks = &put_asks[opt_start..opt_end];\n\n if let Some(rel_idx) = convexity_scoring::find_target_put(\n slice_deltas,\n slice_dtes,\n slice_asks,\n target_delta,\n dte_min,\n dte_max,\n ) {\n let idx = opt_start + rel_idx;\n let ask = put_asks[idx];\n let strike = put_strikes[idx];\n let underlying = put_underlying[idx];\n\n if ask > 0.0 {\n let contracts = (budget / (ask * 100.0)) as i32;\n if contracts > 0 {\n let cost = ask * 100.0 * contracts as f64;\n new_cost = cost;\n new_contracts = contracts;\n new_strike = strike;\n\n let (ratio, _, _) =\n convexity_scoring::convexity_ratio(strike, underlying, ask, tail_drop);\n new_ratio = ratio;\n\n position = Some(Position {\n strike,\n expiration_ns: put_expirations_ns[idx],\n entry_ask: ask,\n contracts,\n });\n\n // Reinvest leftover\n let leftover = budget - cost;\n if stock_price > 0.0 {\n shares += leftover / stock_price;\n }\n } else {\n position = None;\n if stock_price > 0.0 {\n shares += budget / stock_price;\n }\n }\n } else {\n position = None;\n if stock_price > 0.0 {\n shares += budget / stock_price;\n }\n }\n } else {\n position = None;\n if stock_price > 0.0 {\n shares += budget / stock_price;\n }\n }\n } else {\n position = None;\n if stock_price > 0.0 {\n shares += budget / stock_price;\n }\n }\n\n let final_value = shares * stock_price;\n\n records.push(MonthRecord {\n date_ns: rebal_date,\n shares,\n stock_price,\n equity_value: final_value,\n put_cost: new_cost,\n put_exit_value,\n put_pnl,\n portfolio_value: final_value,\n convexity_ratio: new_ratio,\n strike: new_strike,\n contracts: new_contracts,\n });\n\n // 4. Record daily balances until next rebalance\n let stock_idx = lower_bound(stock_dates_ns, rebal_date);\n let next_rebal = if i + 1 < rebalance_dates.len() {\n rebalance_dates[i + 1]\n } else {\n i64::MAX\n };\n\n for si in stock_idx..stock_dates_ns.len() {\n if stock_dates_ns[si] >= next_rebal {\n break;\n }\n daily_dates.push(stock_dates_ns[si]);\n daily_balances.push(shares * stock_prices[si]);\n }\n }\n\n BacktestResult {\n records,\n daily_dates_ns: daily_dates,\n daily_balances,\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n fn make_ts(year: i32, month: u32, day: u32) -> i64 {\n use chrono::NaiveDate;\n let dt = NaiveDate::from_ymd_opt(year, month, day)\n .unwrap()\n .and_hms_opt(0, 0, 0)\n .unwrap();\n dt.and_utc().timestamp_nanos_opt().unwrap()\n }\n\n #[test]\n fn test_monthly_rebalance_dates() {\n let dates = vec![\n make_ts(2020, 1, 2),\n make_ts(2020, 1, 3),\n make_ts(2020, 1, 6),\n make_ts(2020, 2, 3),\n make_ts(2020, 2, 4),\n make_ts(2020, 3, 2),\n ];\n let rebal = monthly_rebalance_dates(&dates);\n assert_eq!(rebal.len(), 3);\n assert_eq!(rebal[0], dates[0]);\n assert_eq!(rebal[1], dates[3]);\n assert_eq!(rebal[2], dates[5]);\n }\n\n #[test]\n fn test_stock_price_on_exact() {\n let dates = vec![100, 200, 300];\n let prices = vec![10.0, 20.0, 30.0];\n assert_eq!(stock_price_on(&dates, &prices, 200), Some(20.0));\n }\n\n #[test]\n fn test_stock_price_on_before() {\n let dates = vec![100, 200, 300];\n let prices = vec![10.0, 20.0, 30.0];\n assert_eq!(stock_price_on(&dates, &prices, 250), Some(20.0));\n }\n\n #[test]\n fn test_run_backtest_no_options() {\n let stock_dates = vec![make_ts(2020, 1, 2), make_ts(2020, 2, 3)];\n let stock_prices = vec![100.0, 105.0];\n\n let result = run_backtest(\n &[], &[], &[], &[], &[], &[], &[], &[], &[],\n &stock_dates, &stock_prices,\n 100_000.0, 0.005, -0.10, 14, 60, 0.20,\n );\n\n assert_eq!(result.records.len(), 2);\n assert!(result.records[0].contracts == 0);\n }\n}\n"
},
{
"path": "rust/ob_core/src/convexity_scoring.rs",
"content": "/// Convexity ratio scoring: find cheapest tail protection per day.\n\npub struct DailyScore {\n pub date_ns: i64,\n pub convexity_ratio: f64,\n pub strike: f64,\n pub ask: f64,\n pub bid: f64,\n pub delta: f64,\n pub underlying_price: f64,\n pub implied_vol: f64,\n pub dte: i32,\n pub annual_cost: f64,\n pub tail_payoff: f64,\n}\n\n/// Find the put closest to target_delta within DTE range.\n/// Returns the index within the provided slices, or None.\npub fn find_target_put(\n deltas: &[f64],\n dtes: &[i32],\n asks: &[f64],\n target_delta: f64,\n dte_min: i32,\n dte_max: i32,\n) -> Option {\n let mut best_idx: Option = None;\n let mut best_delta_diff = f64::MAX;\n\n for i in 0..deltas.len() {\n if dtes[i] < dte_min || dtes[i] > dte_max {\n continue;\n }\n if asks[i] <= 0.0 || asks[i].is_nan() {\n continue;\n }\n if deltas[i].is_nan() {\n continue;\n }\n\n let delta_diff = (deltas[i] - target_delta).abs();\n if delta_diff < best_delta_diff {\n best_delta_diff = delta_diff;\n best_idx = Some(i);\n }\n }\n\n best_idx\n}\n\n/// Compute convexity ratio for a single put.\n/// Returns (ratio, tail_payoff, annual_cost).\npub fn convexity_ratio(strike: f64, underlying: f64, ask: f64, tail_drop: f64) -> (f64, f64, f64) {\n let tail_price = underlying * (1.0 - tail_drop);\n let tail_payoff = (strike - tail_price).max(0.0) * 100.0;\n let annual_cost = ask * 100.0 * 12.0;\n let ratio = if annual_cost > 0.0 {\n tail_payoff / annual_cost\n } else {\n 0.0\n };\n (ratio, tail_payoff, annual_cost)\n}\n\n/// Compute daily convexity scores from sorted puts data.\n/// Input arrays must be sorted by date. Only put options should be passed.\npub fn compute_daily_scores(\n dates_ns: &[i64],\n strikes: &[f64],\n bids: &[f64],\n asks: &[f64],\n deltas: &[f64],\n underlying_prices: &[f64],\n dtes: &[i32],\n implied_vols: &[f64],\n target_delta: f64,\n dte_min: i32,\n dte_max: i32,\n tail_drop: f64,\n) -> Vec {\n let n = dates_ns.len();\n let mut results = Vec::new();\n\n if n == 0 {\n return results;\n }\n\n // Walk through date groups (consecutive rows with same date)\n let mut start = 0;\n while start < n {\n let current_date = dates_ns[start];\n let mut end = start + 1;\n while end < n && dates_ns[end] == current_date {\n end += 1;\n }\n\n // Find target put in this date's options\n if let Some(rel_idx) = find_target_put(\n &deltas[start..end],\n &dtes[start..end],\n &asks[start..end],\n target_delta,\n dte_min,\n dte_max,\n ) {\n let idx = start + rel_idx;\n let (ratio, tail_payoff, annual_cost) =\n convexity_ratio(strikes[idx], underlying_prices[idx], asks[idx], tail_drop);\n\n results.push(DailyScore {\n date_ns: current_date,\n convexity_ratio: ratio,\n strike: strikes[idx],\n ask: asks[idx],\n bid: bids[idx],\n delta: deltas[idx],\n underlying_price: underlying_prices[idx],\n implied_vol: implied_vols[idx],\n dte: dtes[idx],\n annual_cost,\n tail_payoff,\n });\n }\n\n start = end;\n }\n\n results\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn test_convexity_ratio_basic() {\n let (ratio, payoff, cost) = convexity_ratio(360.0, 400.0, 3.0, 0.20);\n assert!((payoff - 4000.0).abs() < 0.01);\n assert!((cost - 3600.0).abs() < 0.01);\n assert!((ratio - 1.111).abs() < 0.01);\n }\n\n #[test]\n fn test_convexity_ratio_otm_after_crash() {\n let (ratio, payoff, _) = convexity_ratio(300.0, 400.0, 3.0, 0.20);\n assert_eq!(payoff, 0.0);\n assert_eq!(ratio, 0.0);\n }\n\n #[test]\n fn test_find_target_put() {\n let deltas = vec![-0.05, -0.10, -0.15, -0.25, -0.50];\n let dtes = vec![30, 30, 30, 30, 30];\n let asks = vec![1.0, 2.0, 3.0, 5.0, 10.0];\n\n let idx = find_target_put(&deltas, &dtes, &asks, -0.10, 20, 45);\n assert_eq!(idx, Some(1));\n }\n\n #[test]\n fn test_find_target_put_dte_filter() {\n let deltas = vec![-0.10, -0.10, -0.10];\n let dtes = vec![10, 30, 60];\n let asks = vec![1.0, 2.0, 3.0];\n\n let idx = find_target_put(&deltas, &dtes, &asks, -0.10, 20, 45);\n assert_eq!(idx, Some(1));\n }\n\n #[test]\n fn test_find_target_put_skips_zero_ask() {\n let deltas = vec![-0.10, -0.11];\n let dtes = vec![30, 30];\n let asks = vec![0.0, 2.0];\n\n let idx = find_target_put(&deltas, &dtes, &asks, -0.10, 20, 45);\n assert_eq!(idx, Some(1));\n }\n\n #[test]\n fn test_compute_daily_scores() {\n let dates_ns = vec![100, 100, 100, 200, 200, 200];\n let strikes = vec![360.0, 370.0, 380.0, 360.0, 370.0, 380.0];\n let bids = vec![2.5, 3.5, 5.0, 2.0, 3.0, 4.5];\n let asks = vec![3.0, 4.0, 5.5, 2.5, 3.5, 5.0];\n let deltas = vec![-0.08, -0.12, -0.18, -0.09, -0.11, -0.17];\n let underlying = vec![400.0; 6];\n let dtes = vec![30, 30, 30, 30, 30, 30];\n let ivs = vec![0.20, 0.22, 0.25, 0.19, 0.21, 0.24];\n\n let scores = compute_daily_scores(\n &dates_ns, &strikes, &bids, &asks, &deltas, &underlying, &dtes, &ivs, -0.10, 20, 45,\n 0.20,\n );\n\n assert_eq!(scores.len(), 2);\n assert_eq!(scores[0].date_ns, 100);\n assert_eq!(scores[1].date_ns, 200);\n }\n}\n"
},
{
"path": "rust/ob_core/src/cost_model.rs",
"content": "//! Transaction cost models for options and stocks.\n//!\n//! Mirrors Python's `options_portfolio_backtester.execution.cost_model`.\n\n#[derive(Debug, Clone, Default)]\npub enum CostModel {\n /// Zero transaction costs.\n #[default]\n NoCosts,\n /// Fixed per-contract commission (e.g., $0.65/contract for IBKR).\n PerContract { rate: f64, stock_rate: f64 },\n /// Tiered commission schedule with volume discounts.\n /// Tiers are (max_contracts, rate) pairs sorted by max_contracts ascending.\n Tiered { tiers: Vec<(i64, f64)>, stock_rate: f64 },\n}\n\nimpl CostModel {\n /// Compute option trade commission.\n #[inline]\n pub fn option_cost(&self, _price: f64, quantity: f64, _spc: i64) -> f64 {\n let qty = quantity.abs();\n match self {\n CostModel::NoCosts => 0.0,\n CostModel::PerContract { rate, .. } => rate * qty,\n CostModel::Tiered { tiers, .. } => {\n let mut total = 0.0;\n let mut remaining = qty;\n let mut prev_bound: i64 = 0;\n for &(max_qty, rate) in tiers {\n let tier_qty = remaining.min((max_qty - prev_bound) as f64);\n if tier_qty <= 0.0 {\n prev_bound = max_qty;\n continue;\n }\n total += tier_qty * rate;\n remaining -= tier_qty;\n prev_bound = max_qty;\n if remaining <= 0.0 {\n break;\n }\n }\n if remaining > 0.0 {\n if let Some(&(_, last_rate)) = tiers.last() {\n total += remaining * last_rate;\n }\n }\n total\n }\n }\n }\n\n /// Compute stock trade commission.\n #[inline]\n pub fn stock_cost(&self, _price: f64, quantity: f64) -> f64 {\n let qty = quantity.abs();\n match self {\n CostModel::NoCosts => 0.0,\n CostModel::PerContract { stock_rate, .. } => stock_rate * qty,\n CostModel::Tiered { stock_rate, .. } => stock_rate * qty,\n }\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn no_costs() {\n let m = CostModel::NoCosts;\n assert_eq!(m.option_cost(10.0, 5.0, 100), 0.0);\n assert_eq!(m.stock_cost(150.0, 100.0), 0.0);\n }\n\n #[test]\n fn per_contract() {\n let m = CostModel::PerContract { rate: 0.65, stock_rate: 0.005 };\n assert!((m.option_cost(10.0, 10.0, 100) - 6.5).abs() < 1e-10);\n assert!((m.option_cost(10.0, -10.0, 100) - 6.5).abs() < 1e-10);\n assert!((m.stock_cost(150.0, 100.0) - 0.5).abs() < 1e-10);\n }\n\n #[test]\n fn tiered_within_first_tier() {\n let m = CostModel::Tiered {\n tiers: vec![(10_000, 0.65), (50_000, 0.50), (100_000, 0.25)],\n stock_rate: 0.005,\n };\n // 100 contracts, all in first tier\n assert!((m.option_cost(10.0, 100.0, 100) - 65.0).abs() < 1e-10);\n }\n\n #[test]\n fn tiered_spanning_tiers() {\n let m = CostModel::Tiered {\n tiers: vec![(10_000, 0.65), (50_000, 0.50), (100_000, 0.25)],\n stock_rate: 0.005,\n };\n // 15000 contracts: 10000 * 0.65 + 5000 * 0.50\n let expected = 10_000.0 * 0.65 + 5_000.0 * 0.50;\n assert!((m.option_cost(10.0, 15_000.0, 100) - expected).abs() < 1e-10);\n }\n\n #[test]\n fn tiered_beyond_all() {\n let m = CostModel::Tiered {\n tiers: vec![(10_000, 0.65), (50_000, 0.50), (100_000, 0.25)],\n stock_rate: 0.005,\n };\n // 120_000: 10k*0.65 + 40k*0.50 + 50k*0.25 + 20k*0.25\n let expected = 10_000.0 * 0.65 + 40_000.0 * 0.50 + 50_000.0 * 0.25 + 20_000.0 * 0.25;\n assert!((m.option_cost(10.0, 120_000.0, 100) - expected).abs() < 1e-10);\n }\n\n #[test]\n fn tiered_stock_cost() {\n let m = CostModel::Tiered {\n tiers: vec![(10_000, 0.65)],\n stock_rate: 0.005,\n };\n assert!((m.stock_cost(150.0, 100.0) - 0.5).abs() < 1e-10);\n }\n}\n"
},
{
"path": "rust/ob_core/src/entries.rs",
"content": "//! Entry signal computation in Rust.\n//!\n//! Mirrors Python's _execute_option_entries:\n//! 1. Anti-join to exclude held contracts\n//! 2. Apply entry filter\n//! 3. Sort by entry_sort\n//! 4. Select signal fields\n//! 5. Compute totals (cost, qty)\n\nuse polars::prelude::*;\n\nuse crate::filter::CompiledFilter;\n\n/// Compute entry candidates for a single leg.\n///\n/// Steps:\n/// 1. Anti-join options with inventory contracts\n/// 2. Apply compiled entry filter\n/// 3. Sort if entry_sort specified\n/// 4. Select and rename signal fields\npub fn compute_leg_entries(\n options: &DataFrame,\n inventory_contracts: &[String],\n entry_filter: &CompiledFilter,\n contract_col: &str,\n cost_field: &str,\n entry_sort_col: Option<&str>,\n entry_sort_asc: bool,\n shares_per_contract: i64,\n is_sell: bool,\n extra_columns: &[String],\n) -> PolarsResult {\n // Anti-join: exclude already-held contracts\n let inv_contracts = Series::new(\"_held\".into(), inventory_contracts);\n let inv_df = DataFrame::new(vec![inv_contracts.into_column()])?;\n\n let mut lazy = options\n .clone()\n .lazy()\n .join(\n inv_df.lazy(),\n [col(contract_col)],\n [col(\"_held\")],\n JoinArgs::new(JoinType::Anti),\n );\n\n // Apply entry filter\n lazy = lazy.filter(entry_filter.polars_expr.clone());\n\n // Sort if specified\n if let Some(sort_col) = entry_sort_col {\n lazy = lazy.sort(\n [sort_col],\n SortMultipleOptions::default().with_order_descending(!entry_sort_asc),\n );\n }\n\n // Select signal fields and compute cost\n let sign = if is_sell { lit(-1.0) } else { lit(1.0) };\n let spc = lit(shares_per_contract as f64);\n\n let mut select_exprs = vec![\n col(contract_col).alias(\"contract\"),\n col(\"underlying\"),\n col(\"expiration\"),\n col(\"type\"),\n col(\"strike\").cast(DataType::Float64),\n (sign * col(cost_field) * spc).alias(\"cost\"),\n ];\n // Include extra columns needed by signal selectors (e.g. delta, openinterest)\n for extra in extra_columns {\n select_exprs.push(col(extra));\n }\n lazy = lazy.select(select_exprs);\n\n lazy.collect()\n}\n\n/// Compute entry quantities given total costs and available allocation.\npub fn compute_entry_qty(total_costs: &Series, allocation: f64) -> PolarsResult {\n let abs_costs = total_costs.f64()?.apply(|v| v.map(|x| x.abs()));\n let qty: Float64Chunked = abs_costs\n .into_iter()\n .map(|c| c.map(|cost| if cost > 0.0 { (allocation / cost).floor() } else { 0.0 }))\n .collect();\n Ok(qty.into_series())\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n fn sample_options() -> DataFrame {\n df!(\n \"optionroot\" => &[\"A\", \"B\", \"C\", \"D\"],\n \"underlying\" => &[\"SPX\", \"SPX\", \"SPX\", \"SPX\"],\n \"type\" => &[\"put\", \"put\", \"call\", \"put\"],\n \"expiration\" => &[\"2024-06-01\", \"2024-06-01\", \"2024-06-01\", \"2024-06-01\"],\n \"strike\" => &[4000.0, 4100.0, 4200.0, 4300.0],\n \"ask\" => &[10.0, 15.0, 20.0, 25.0],\n \"bid\" => &[9.0, 14.0, 19.0, 24.0],\n \"dte\" => &[90i64, 90, 90, 90],\n )\n .unwrap()\n }\n\n #[test]\n fn compute_entries_excludes_held() {\n let opts = sample_options();\n let filter = CompiledFilter::new(\"type == 'put'\").unwrap();\n\n let result = compute_leg_entries(\n &opts,\n &[\"A\".into()], // A is held\n &filter,\n \"optionroot\",\n \"ask\",\n None,\n true,\n 100,\n false,\n &[],\n )\n .unwrap();\n\n // A is excluded, C is a call (filtered out), so B and D remain\n assert_eq!(result.height(), 2);\n }\n\n #[test]\n fn compute_qty() {\n let costs = Series::new(\"cost\".into(), &[100.0, 200.0, 50.0]);\n let qty = compute_entry_qty(&costs, 1000.0).unwrap();\n let vals: Vec = qty.f64().unwrap().into_no_null_iter().collect();\n assert_eq!(vals, vec![10.0, 5.0, 20.0]);\n }\n}\n"
},
{
"path": "rust/ob_core/src/exits.rs",
"content": "//! Exit mask computation in Rust.\n//!\n//! Mirrors Python's _execute_option_exits:\n//! 1. Compute current option quotes for each leg\n//! 2. Apply exit filters to get filter masks\n//! 3. Apply threshold exits (profit/loss targets)\n//! 4. Combine masks with OR\n\nuse polars::prelude::*;\n\n/// Compute exit mask from profit/loss thresholds.\n///\n/// exit if: current_cost <= entry_cost * (1 - loss_pct) [loss]\n/// or: current_cost >= entry_cost * (1 + profit_pct) [profit]\npub fn threshold_exit_mask(\n entry_costs: &Series,\n current_costs: &Series,\n profit_pct: Option,\n loss_pct: Option,\n) -> PolarsResult {\n let entry = entry_costs.f64()?;\n let current = current_costs.f64()?;\n\n let mask: BooleanChunked = entry\n .into_iter()\n .zip(current.into_iter())\n .map(|(e, c)| {\n match (e, c) {\n (Some(entry_val), Some(curr_val)) => {\n let mut should_exit = false;\n if let Some(p) = profit_pct {\n if entry_val != 0.0 {\n let pnl_pct = (curr_val - entry_val) / entry_val.abs();\n if pnl_pct >= p {\n should_exit = true;\n }\n }\n }\n if let Some(l) = loss_pct {\n if entry_val != 0.0 {\n let pnl_pct = (curr_val - entry_val) / entry_val.abs();\n if pnl_pct <= -l {\n should_exit = true;\n }\n }\n }\n Some(should_exit)\n }\n _ => Some(false),\n }\n })\n .collect();\n\n Ok(mask)\n}\n\n/// Combine multiple boolean masks with OR.\npub fn combine_masks_or(masks: &[BooleanChunked]) -> BooleanChunked {\n if masks.is_empty() {\n return BooleanChunked::new(\"mask\".into(), &[] as &[bool]);\n }\n let mut result = masks[0].clone();\n for mask in &masks[1..] {\n result = result | mask.clone();\n }\n result\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn threshold_profit_exit() {\n let entry = Series::new(\"entry\".into(), &[100.0, 100.0, 100.0]);\n let current = Series::new(\"current\".into(), &[160.0, 110.0, 80.0]);\n\n let mask = threshold_exit_mask(&entry, ¤t, Some(0.50), None).unwrap();\n let vals: Vec = mask.into_no_null_iter().collect();\n assert_eq!(vals, vec![true, false, false]); // 60% profit > 50%\n }\n\n #[test]\n fn threshold_loss_exit() {\n let entry = Series::new(\"entry\".into(), &[100.0, 100.0, 100.0]);\n let current = Series::new(\"current\".into(), &[160.0, 110.0, 70.0]);\n\n let mask = threshold_exit_mask(&entry, ¤t, None, Some(0.20)).unwrap();\n let vals: Vec = mask.into_no_null_iter().collect();\n assert_eq!(vals, vec![false, false, true]); // 30% loss > 20%\n }\n\n #[test]\n fn combine_masks() {\n let a = BooleanChunked::new(\"a\".into(), &[true, false, false]);\n let b = BooleanChunked::new(\"b\".into(), &[false, false, true]);\n\n let result = combine_masks_or(&[a, b]);\n let vals: Vec = result.into_no_null_iter().collect();\n assert_eq!(vals, vec![true, false, true]);\n }\n}\n"
},
{
"path": "rust/ob_core/src/fill_model.rs",
"content": "//! Fill models — determine the execution price for trades.\n//!\n//! Mirrors Python's `options_portfolio_backtester.execution.fill_model`.\n\n#[derive(Debug, Clone, Default)]\npub enum FillModel {\n /// Fill at bid (sell) or ask (buy) — matches original behavior.\n #[default]\n MarketAtBidAsk,\n /// Fill at the midpoint of bid and ask.\n MidPrice,\n /// Fill price adjusts for volume impact. Low volume pushes toward mid.\n VolumeAware { full_volume_threshold: i64 },\n}\n\nimpl FillModel {\n /// Compute fill price given bid, ask, volume, and whether this is a buy.\n ///\n /// `is_buy`: true for BUY direction (fills at ask), false for SELL (fills at bid).\n #[inline]\n pub fn fill_price(&self, bid: f64, ask: f64, volume: Option, is_buy: bool) -> f64 {\n match self {\n FillModel::MarketAtBidAsk => {\n if is_buy { ask } else { bid }\n }\n FillModel::MidPrice => {\n (bid + ask) / 2.0\n }\n FillModel::VolumeAware { full_volume_threshold } => {\n let mid = (bid + ask) / 2.0;\n let target = if is_buy { ask } else { bid };\n let vol = volume.unwrap_or(*full_volume_threshold as f64);\n\n if vol >= *full_volume_threshold as f64 {\n return target;\n }\n\n let ratio = vol / *full_volume_threshold as f64;\n mid + ratio * (target - mid)\n }\n }\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn market_at_bid_ask_buy() {\n let m = FillModel::MarketAtBidAsk;\n assert!((m.fill_price(9.0, 10.0, None, true) - 10.0).abs() < 1e-10);\n }\n\n #[test]\n fn market_at_bid_ask_sell() {\n let m = FillModel::MarketAtBidAsk;\n assert!((m.fill_price(9.0, 10.0, None, false) - 9.0).abs() < 1e-10);\n }\n\n #[test]\n fn mid_price() {\n let m = FillModel::MidPrice;\n assert!((m.fill_price(9.0, 11.0, None, true) - 10.0).abs() < 1e-10);\n assert!((m.fill_price(9.0, 11.0, None, false) - 10.0).abs() < 1e-10);\n }\n\n #[test]\n fn volume_aware_full_volume() {\n let m = FillModel::VolumeAware { full_volume_threshold: 100 };\n // At or above threshold, same as market\n assert!((m.fill_price(9.0, 10.0, Some(100.0), true) - 10.0).abs() < 1e-10);\n assert!((m.fill_price(9.0, 10.0, Some(200.0), false) - 9.0).abs() < 1e-10);\n }\n\n #[test]\n fn volume_aware_zero_volume() {\n let m = FillModel::VolumeAware { full_volume_threshold: 100 };\n // At volume=0, fill at mid\n let mid = (9.0 + 10.0) / 2.0;\n assert!((m.fill_price(9.0, 10.0, Some(0.0), true) - mid).abs() < 1e-10);\n assert!((m.fill_price(9.0, 10.0, Some(0.0), false) - mid).abs() < 1e-10);\n }\n\n #[test]\n fn volume_aware_half_volume() {\n let m = FillModel::VolumeAware { full_volume_threshold: 100 };\n let mid = (9.0 + 10.0) / 2.0;\n // At 50% volume: mid + 0.5 * (ask - mid) = 9.5 + 0.25 = 9.75\n let expected_buy = mid + 0.5 * (10.0 - mid);\n assert!((m.fill_price(9.0, 10.0, Some(50.0), true) - expected_buy).abs() < 1e-10);\n let expected_sell = mid + 0.5 * (9.0 - mid);\n assert!((m.fill_price(9.0, 10.0, Some(50.0), false) - expected_sell).abs() < 1e-10);\n }\n\n #[test]\n fn volume_aware_no_volume_data() {\n let m = FillModel::VolumeAware { full_volume_threshold: 100 };\n // Missing volume defaults to threshold -> market price\n assert!((m.fill_price(9.0, 10.0, None, true) - 10.0).abs() < 1e-10);\n }\n}\n"
},
{
"path": "rust/ob_core/src/filter.rs",
"content": "//! Filter expression parser and evaluator.\n//!\n//! Parses the pandas-eval query strings generated by the Python Filter DSL\n//! into an AST, then evaluates against Polars DataFrames.\n//!\n//! Supported patterns (all generated by schema.py):\n//! \"(type == 'put') & (ask > 0)\"\n//! \"(underlying == 'SPX') & (dte >= 60) & (dte <= 120)\"\n//! \"(strike >= underlying_last * 1.02)\"\n//! \"dte <= 30\"\n\nuse polars::prelude::*;\nuse thiserror::Error;\n\n#[derive(Error, Debug)]\npub enum FilterError {\n #[error(\"parse error: {0}\")]\n Parse(String),\n #[error(\"polars error: {0}\")]\n Polars(#[from] PolarsError),\n}\n\n/// A parsed value literal.\n#[derive(Debug, Clone, PartialEq)]\npub enum Value {\n Int(i64),\n Float(f64),\n Str(String),\n Column(String),\n}\n\n/// Comparison operator.\n#[derive(Debug, Clone, Copy, PartialEq)]\npub enum CmpOp {\n Eq,\n Ne,\n Lt,\n Le,\n Gt,\n Ge,\n}\n\n/// Arithmetic operator for column expressions.\n#[derive(Debug, Clone, Copy, PartialEq)]\npub enum ArithOp {\n Add,\n Sub,\n Mul,\n Div,\n}\n\n/// Compiled filter expression AST.\n#[derive(Debug, Clone, PartialEq)]\npub enum FilterExpr {\n Cmp(String, CmpOp, Value),\n /// column value value\n /// e.g. strike >= underlying_last * 1.02\n ColArith(String, ArithOp, Value, CmpOp, Value),\n And(Box, Box),\n Or(Box, Box),\n Not(Box),\n}\n\n/// Tokenizer for filter expressions.\n#[derive(Debug, Clone, PartialEq)]\nenum Token {\n Ident(String),\n StrLit(String),\n IntLit(i64),\n FloatLit(f64),\n Eq, // ==\n Ne, // !=\n Lt, // <\n Le, // <=\n Gt, // >\n Ge, // >=\n And, // &\n Or, // |\n Not, // !\n LParen,\n RParen,\n Plus,\n Minus,\n Star,\n Slash,\n}\n\nfn tokenize(input: &str) -> Result, FilterError> {\n let mut tokens = Vec::new();\n let chars: Vec = input.chars().collect();\n let mut i = 0;\n\n while i < chars.len() {\n match chars[i] {\n ' ' | '\\t' | '\\n' => i += 1,\n '(' => { tokens.push(Token::LParen); i += 1; }\n ')' => { tokens.push(Token::RParen); i += 1; }\n '&' => { tokens.push(Token::And); i += 1; }\n '|' => { tokens.push(Token::Or); i += 1; }\n '+' => { tokens.push(Token::Plus); i += 1; }\n '-' => { tokens.push(Token::Minus); i += 1; }\n '*' => { tokens.push(Token::Star); i += 1; }\n '/' => { tokens.push(Token::Slash); i += 1; }\n '!' => {\n if i + 1 < chars.len() && chars[i + 1] == '=' {\n tokens.push(Token::Ne);\n i += 2;\n } else {\n tokens.push(Token::Not);\n i += 1;\n }\n }\n '=' => {\n if i + 1 < chars.len() && chars[i + 1] == '=' {\n tokens.push(Token::Eq);\n i += 2;\n } else {\n return Err(FilterError::Parse(format!(\"unexpected '=' at {i}\")));\n }\n }\n '<' => {\n if i + 1 < chars.len() && chars[i + 1] == '=' {\n tokens.push(Token::Le);\n i += 2;\n } else {\n tokens.push(Token::Lt);\n i += 1;\n }\n }\n '>' => {\n if i + 1 < chars.len() && chars[i + 1] == '=' {\n tokens.push(Token::Ge);\n i += 2;\n } else {\n tokens.push(Token::Gt);\n i += 1;\n }\n }\n '\\'' | '\"' => {\n let quote = chars[i];\n i += 1;\n let start = i;\n while i < chars.len() && chars[i] != quote {\n i += 1;\n }\n let s: String = chars[start..i].iter().collect();\n tokens.push(Token::StrLit(s));\n i += 1; // skip closing quote\n }\n c if c.is_ascii_digit() || c == '.' => {\n let start = i;\n let mut has_dot = c == '.';\n let mut has_exp = false;\n i += 1;\n while i < chars.len() && (chars[i].is_ascii_digit() || chars[i] == '.') {\n if chars[i] == '.' { has_dot = true; }\n i += 1;\n }\n // Scientific notation: e/E followed by optional +/- and digits\n if i < chars.len() && (chars[i] == 'e' || chars[i] == 'E') {\n has_exp = true;\n i += 1;\n if i < chars.len() && (chars[i] == '+' || chars[i] == '-') {\n i += 1;\n }\n while i < chars.len() && chars[i].is_ascii_digit() {\n i += 1;\n }\n }\n let num_str: String = chars[start..i].iter().collect();\n if has_dot || has_exp {\n tokens.push(Token::FloatLit(\n num_str.parse().map_err(|e| FilterError::Parse(format!(\"{e}\")))?,\n ));\n } else {\n tokens.push(Token::IntLit(\n num_str.parse().map_err(|e| FilterError::Parse(format!(\"{e}\")))?,\n ));\n }\n }\n c if c.is_ascii_alphabetic() || c == '_' => {\n let start = i;\n i += 1;\n while i < chars.len() && (chars[i].is_ascii_alphanumeric() || chars[i] == '_') {\n i += 1;\n }\n let ident: String = chars[start..i].iter().collect();\n tokens.push(Token::Ident(ident));\n }\n c => return Err(FilterError::Parse(format!(\"unexpected char '{c}' at {i}\"))),\n }\n }\n\n Ok(tokens)\n}\n\n/// Recursive descent parser.\nstruct Parser {\n tokens: Vec,\n pos: usize,\n}\n\nimpl Parser {\n fn new(tokens: Vec) -> Self {\n Self { tokens, pos: 0 }\n }\n\n fn peek(&self) -> Option<&Token> {\n self.tokens.get(self.pos)\n }\n\n fn advance(&mut self) -> Option {\n let tok = self.tokens.get(self.pos)?.clone();\n self.pos += 1;\n Some(tok)\n }\n\n fn expect(&mut self, expected: &Token) -> Result<(), FilterError> {\n let tok = self.advance().ok_or_else(|| FilterError::Parse(\"unexpected end\".into()))?;\n if &tok != expected {\n return Err(FilterError::Parse(format!(\"expected {expected:?}, got {tok:?}\")));\n }\n Ok(())\n }\n\n /// expr = or_expr\n fn parse_expr(&mut self) -> Result {\n self.parse_or()\n }\n\n /// or_expr = and_expr ( '|' and_expr )*\n fn parse_or(&mut self) -> Result {\n let mut left = self.parse_and()?;\n while matches!(self.peek(), Some(Token::Or)) {\n self.advance();\n let right = self.parse_and()?;\n left = FilterExpr::Or(Box::new(left), Box::new(right));\n }\n Ok(left)\n }\n\n /// and_expr = unary ( '&' unary )*\n fn parse_and(&mut self) -> Result {\n let mut left = self.parse_unary()?;\n while matches!(self.peek(), Some(Token::And)) {\n self.advance();\n let right = self.parse_unary()?;\n left = FilterExpr::And(Box::new(left), Box::new(right));\n }\n Ok(left)\n }\n\n /// unary = '!' unary | primary\n fn parse_unary(&mut self) -> Result {\n if matches!(self.peek(), Some(Token::Not)) {\n self.advance();\n let inner = self.parse_unary()?;\n return Ok(FilterExpr::Not(Box::new(inner)));\n }\n self.parse_primary()\n }\n\n /// primary = '(' expr ')' | comparison\n fn parse_primary(&mut self) -> Result {\n if matches!(self.peek(), Some(Token::LParen)) {\n self.advance();\n let expr = self.parse_expr()?;\n self.expect(&Token::RParen)?;\n return Ok(expr);\n }\n self.parse_comparison()\n }\n\n /// comparison = value cmp_op value\n /// value can be: ident, ident arith_op literal, literal\n fn parse_comparison(&mut self) -> Result {\n let left = self.parse_value_expr()?;\n let cmp = self.parse_cmp_op()?;\n let right = self.parse_value_expr()?;\n\n match (left, right) {\n // column cmp literal/column\n (ValueExpr::Column(name), ValueExpr::Literal(val)) => {\n Ok(FilterExpr::Cmp(name, cmp, val))\n }\n (ValueExpr::Column(name), ValueExpr::Column(rhs)) => {\n Ok(FilterExpr::Cmp(name, cmp, Value::Column(rhs)))\n }\n // column_arith cmp value\n (ValueExpr::Arith(name, op, operand), rhs) => {\n Ok(FilterExpr::ColArith(name, op, operand, cmp, self.value_expr_to_value(rhs)?))\n }\n // column cmp column_arith → flip to ColArith form\n // e.g. strike >= underlying_last * 1.02\n // → ColArith(\"underlying_last\", Mul, 1.02, Le, Column(\"strike\"))\n (ValueExpr::Column(name), ValueExpr::Arith(rhs_col, op, operand)) => {\n Ok(FilterExpr::ColArith(rhs_col, op, operand, flip_cmp(cmp), Value::Column(name)))\n }\n // literal cmp column → flip\n (ValueExpr::Literal(val), ValueExpr::Column(name)) => {\n Ok(FilterExpr::Cmp(name, flip_cmp(cmp), val))\n }\n _ => Err(FilterError::Parse(\"unsupported comparison form\".into())),\n }\n }\n\n fn parse_value_expr(&mut self) -> Result {\n let tok = self.advance().ok_or_else(|| FilterError::Parse(\"unexpected end\".into()))?;\n match tok {\n Token::Ident(name) => {\n // Check for arithmetic: ident * 1.02\n if let Some(arith) = self.try_parse_arith() {\n return Ok(ValueExpr::Arith(name, arith.0, arith.1));\n }\n Ok(ValueExpr::Column(name))\n }\n Token::IntLit(n) => {\n // Check for arithmetic: 1.02 * ident (reversed)\n Ok(ValueExpr::Literal(Value::Int(n)))\n }\n Token::FloatLit(f) => Ok(ValueExpr::Literal(Value::Float(f))),\n Token::StrLit(s) => Ok(ValueExpr::Literal(Value::Str(s))),\n // Unary minus: negate the next numeric literal\n Token::Minus => {\n let next = self.advance().ok_or_else(|| FilterError::Parse(\"unexpected end after '-'\".into()))?;\n match next {\n Token::IntLit(n) => Ok(ValueExpr::Literal(Value::Int(-n))),\n Token::FloatLit(f) => Ok(ValueExpr::Literal(Value::Float(-f))),\n t => Err(FilterError::Parse(format!(\"expected number after '-', got {t:?}\"))),\n }\n }\n t => Err(FilterError::Parse(format!(\"unexpected token in value: {t:?}\"))),\n }\n }\n\n fn try_parse_arith(&mut self) -> Option<(ArithOp, Value)> {\n let op = match self.peek()? {\n Token::Plus => ArithOp::Add,\n Token::Minus => ArithOp::Sub,\n Token::Star => ArithOp::Mul,\n Token::Slash => ArithOp::Div,\n _ => return None,\n };\n self.advance();\n let val = match self.advance()? {\n Token::IntLit(n) => Value::Int(n),\n Token::FloatLit(f) => Value::Float(f),\n Token::Ident(s) => Value::Column(s),\n _ => return None,\n };\n Some((op, val))\n }\n\n fn parse_cmp_op(&mut self) -> Result {\n match self.advance() {\n Some(Token::Eq) => Ok(CmpOp::Eq),\n Some(Token::Ne) => Ok(CmpOp::Ne),\n Some(Token::Lt) => Ok(CmpOp::Lt),\n Some(Token::Le) => Ok(CmpOp::Le),\n Some(Token::Gt) => Ok(CmpOp::Gt),\n Some(Token::Ge) => Ok(CmpOp::Ge),\n t => Err(FilterError::Parse(format!(\"expected comparison op, got {t:?}\"))),\n }\n }\n\n fn value_expr_to_value(&self, ve: ValueExpr) -> Result {\n match ve {\n ValueExpr::Column(name) => Ok(Value::Column(name)),\n ValueExpr::Literal(val) => Ok(val),\n ValueExpr::Arith(..) => Err(FilterError::Parse(\n \"arithmetic expressions only supported on left side\".into(),\n )),\n }\n }\n}\n\n#[derive(Debug)]\nenum ValueExpr {\n Column(String),\n Literal(Value),\n Arith(String, ArithOp, Value),\n}\n\nfn flip_cmp(op: CmpOp) -> CmpOp {\n match op {\n CmpOp::Lt => CmpOp::Gt,\n CmpOp::Le => CmpOp::Ge,\n CmpOp::Gt => CmpOp::Lt,\n CmpOp::Ge => CmpOp::Le,\n other => other,\n }\n}\n\n/// Parse a query string into a FilterExpr AST.\npub fn parse(query: &str) -> Result {\n let tokens = tokenize(query)?;\n let mut parser = Parser::new(tokens);\n let expr = parser.parse_expr()?;\n if parser.pos != parser.tokens.len() {\n return Err(FilterError::Parse(format!(\n \"unexpected tokens after position {}\",\n parser.pos\n )));\n }\n Ok(expr)\n}\n\n/// Convert a FilterExpr to a Polars Expr for lazy evaluation.\npub fn to_polars_expr(filter: &FilterExpr) -> Expr {\n match filter {\n FilterExpr::Cmp(column, op, value) => {\n let c = col(column.as_str());\n let v = value_to_lit(value);\n apply_cmp(c, *op, v)\n }\n FilterExpr::ColArith(column, arith_op, arith_val, cmp_op, cmp_val) => {\n let c = col(column.as_str());\n let av = value_to_lit(arith_val);\n let arith_expr = match arith_op {\n ArithOp::Add => c + av,\n ArithOp::Sub => c - av,\n ArithOp::Mul => c * av,\n ArithOp::Div => c / av,\n };\n let cv = value_to_lit(cmp_val);\n apply_cmp(arith_expr, *cmp_op, cv)\n }\n FilterExpr::And(left, right) => {\n to_polars_expr(left).and(to_polars_expr(right))\n }\n FilterExpr::Or(left, right) => {\n to_polars_expr(left).or(to_polars_expr(right))\n }\n FilterExpr::Not(inner) => {\n to_polars_expr(inner).not()\n }\n }\n}\n\nfn value_to_lit(value: &Value) -> Expr {\n match value {\n // Always use f64 for numeric literals to avoid Int128 issues in polars 0.48\n Value::Int(n) => lit(*n as f64),\n Value::Float(f) => lit(*f),\n Value::Str(s) => lit(s.as_str()),\n Value::Column(name) => col(name.as_str()),\n }\n}\n\nfn apply_cmp(left: Expr, op: CmpOp, right: Expr) -> Expr {\n match op {\n CmpOp::Eq => left.eq(right),\n CmpOp::Ne => left.neq(right),\n CmpOp::Lt => left.lt(right),\n CmpOp::Le => left.lt_eq(right),\n CmpOp::Gt => left.gt(right),\n CmpOp::Ge => left.gt_eq(right),\n }\n}\n\n/// A compiled filter: parsed once, evaluated many times.\npub struct CompiledFilter {\n pub expr: FilterExpr,\n pub polars_expr: Expr,\n}\n\nimpl CompiledFilter {\n pub fn new(query: &str) -> Result {\n let expr = parse(query)?;\n let polars_expr = to_polars_expr(&expr);\n Ok(Self { expr, polars_expr })\n }\n\n pub fn apply(&self, df: &DataFrame) -> PolarsResult {\n let mask = df\n .clone()\n .lazy()\n .select([self.polars_expr.clone().alias(\"_mask\")])\n .collect()?;\n let bool_mask = mask.column(\"_mask\")?.bool()?.clone();\n df.filter(&bool_mask)\n }\n\n /// Evaluate filter against a single row — O(1) per comparison, no Polars overhead.\n #[inline]\n pub fn eval_row(&self, df: &DataFrame, row_idx: usize) -> bool {\n eval_expr_row(&self.expr, df, row_idx)\n }\n}\n\n/// Read a numeric value from a column at a given row index.\n#[inline]\nfn read_f64(col: &Column, row: usize) -> Option {\n if let Ok(ca) = col.f64() {\n return ca.get(row);\n }\n if let Ok(ca) = col.i64() {\n return ca.get(row).map(|v| v as f64);\n }\n if let Ok(ca) = col.i32() {\n return ca.get(row).map(|v| v as f64);\n }\n None\n}\n\n/// Read a string value from a column at a given row index.\n#[inline]\nfn read_str<'a>(col: &'a Column, row: usize) -> Option<&'a str> {\n col.str().ok().and_then(|ca| ca.get(row))\n}\n\n/// Compare two f64 values with the given operator.\n#[inline]\nfn cmp_f64(lhs: f64, op: CmpOp, rhs: f64) -> bool {\n match op {\n CmpOp::Eq => (lhs - rhs).abs() < f64::EPSILON,\n CmpOp::Ne => (lhs - rhs).abs() >= f64::EPSILON,\n CmpOp::Lt => lhs < rhs,\n CmpOp::Le => lhs <= rhs,\n CmpOp::Gt => lhs > rhs,\n CmpOp::Ge => lhs >= rhs,\n }\n}\n\n/// Resolve a Value to f64 given a DataFrame and row index.\n#[inline]\nfn resolve_f64(val: &Value, df: &DataFrame, row: usize) -> Option {\n match val {\n Value::Int(n) => Some(*n as f64),\n Value::Float(f) => Some(*f),\n Value::Column(name) => df.column(name).ok().and_then(|c| read_f64(c, row)),\n Value::Str(_) => None,\n }\n}\n\n/// Evaluate a filter expression against a single row directly.\nfn eval_expr_row(expr: &FilterExpr, df: &DataFrame, row: usize) -> bool {\n match expr {\n FilterExpr::Cmp(col_name, op, val) => {\n let col = match df.column(col_name) {\n Ok(c) => c,\n Err(_) => return false,\n };\n match val {\n Value::Str(s) => {\n match read_str(col, row) {\n Some(cell) => match op {\n CmpOp::Eq => cell == s.as_str(),\n CmpOp::Ne => cell != s.as_str(),\n _ => false,\n },\n None => false,\n }\n }\n _ => {\n match (read_f64(col, row), resolve_f64(val, df, row)) {\n (Some(lhs), Some(rhs)) => cmp_f64(lhs, *op, rhs),\n _ => false,\n }\n }\n }\n }\n FilterExpr::ColArith(col_name, arith_op, arith_val, cmp_op, cmp_val) => {\n let col = match df.column(col_name) {\n Ok(c) => c,\n Err(_) => return false,\n };\n let base = match read_f64(col, row) {\n Some(v) => v,\n None => return false,\n };\n let operand = match resolve_f64(arith_val, df, row) {\n Some(v) => v,\n None => return false,\n };\n let arith_result = match arith_op {\n ArithOp::Add => base + operand,\n ArithOp::Sub => base - operand,\n ArithOp::Mul => base * operand,\n ArithOp::Div => base / operand,\n };\n let rhs = match resolve_f64(cmp_val, df, row) {\n Some(v) => v,\n None => return false,\n };\n cmp_f64(arith_result, *cmp_op, rhs)\n }\n FilterExpr::And(l, r) => eval_expr_row(l, df, row) && eval_expr_row(r, df, row),\n FilterExpr::Or(l, r) => eval_expr_row(l, df, row) || eval_expr_row(r, df, row),\n FilterExpr::Not(inner) => !eval_expr_row(inner, df, row),\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn parse_simple_eq() {\n let expr = parse(\"type == 'put'\").unwrap();\n assert_eq!(\n expr,\n FilterExpr::Cmp(\"type\".into(), CmpOp::Eq, Value::Str(\"put\".into()))\n );\n }\n\n #[test]\n fn parse_simple_gte() {\n let expr = parse(\"dte >= 60\").unwrap();\n assert_eq!(\n expr,\n FilterExpr::Cmp(\"dte\".into(), CmpOp::Ge, Value::Int(60))\n );\n }\n\n #[test]\n fn parse_and() {\n let expr = parse(\"(type == 'put') & (ask > 0)\").unwrap();\n match expr {\n FilterExpr::And(left, right) => {\n assert_eq!(\n *left,\n FilterExpr::Cmp(\"type\".into(), CmpOp::Eq, Value::Str(\"put\".into()))\n );\n assert_eq!(\n *right,\n FilterExpr::Cmp(\"ask\".into(), CmpOp::Gt, Value::Int(0))\n );\n }\n _ => panic!(\"expected And\"),\n }\n }\n\n #[test]\n fn parse_col_arith() {\n // \"strike >= underlying_last * 1.02\" flips to:\n // ColArith(\"underlying_last\", Mul, 1.02, Le, Column(\"strike\"))\n let expr = parse(\"strike >= underlying_last * 1.02\").unwrap();\n match expr {\n FilterExpr::ColArith(ref col, ArithOp::Mul, Value::Float(f), CmpOp::Le, Value::Column(ref rhs)) => {\n assert_eq!(col, \"underlying_last\");\n assert!((f - 1.02).abs() < 1e-10);\n assert_eq!(rhs, \"strike\");\n }\n _ => panic!(\"expected ColArith, got {expr:?}\"),\n }\n }\n\n #[test]\n fn parse_chained_and() {\n let expr = parse(\"(underlying == 'SPX') & (dte >= 60) & (dte <= 120)\").unwrap();\n // Should be And(And(eq, gte), lte)\n match expr {\n FilterExpr::And(_, _) => {} // OK\n _ => panic!(\"expected chained And\"),\n }\n }\n\n #[test]\n fn compiled_filter_apply() {\n let df = DataFrame::new(vec![\n Column::new(\"type\".into(), &[\"call\", \"put\", \"put\"]),\n Column::new(\"ask\".into(), &[1.0f64, 2.0, 0.0]),\n ])\n .unwrap();\n\n let f = CompiledFilter::new(\"(type == 'put') & (ask > 0)\").unwrap();\n let result = f.apply(&df).unwrap();\n assert_eq!(result.height(), 1);\n }\n\n #[test]\n fn compiled_filter_dte_range() {\n let df = DataFrame::new(vec![\n Column::new(\"underlying\".into(), &[\"SPX\", \"SPX\", \"AAPL\", \"SPX\"]),\n Column::new(\"dte\".into(), &[30i32, 90, 90, 150]),\n ])\n .unwrap();\n\n let f = CompiledFilter::new(\"(underlying == 'SPX') & (dte >= 60) & (dte <= 120)\").unwrap();\n let result = f.apply(&df).unwrap();\n assert_eq!(result.height(), 1); // Only SPX with dte=90\n }\n\n #[test]\n fn parse_scientific_notation() {\n let expr = parse(\"ask > 1e-5\").unwrap();\n match expr {\n FilterExpr::Cmp(col, CmpOp::Gt, Value::Float(f)) => {\n assert_eq!(col, \"ask\");\n assert!((f - 1e-5).abs() < 1e-15);\n }\n _ => panic!(\"expected Cmp with float, got {expr:?}\"),\n }\n }\n\n #[test]\n fn parse_scientific_notation_positive_exp() {\n let expr = parse(\"strike >= 1.5E3\").unwrap();\n match expr {\n FilterExpr::Cmp(col, CmpOp::Ge, Value::Float(f)) => {\n assert_eq!(col, \"strike\");\n assert!((f - 1500.0).abs() < 1e-10);\n }\n _ => panic!(\"expected Cmp with float, got {expr:?}\"),\n }\n }\n\n #[test]\n fn parse_scientific_notation_no_sign() {\n let expr = parse(\"delta >= 1e2\").unwrap();\n match expr {\n FilterExpr::Cmp(_, CmpOp::Ge, Value::Float(f)) => {\n assert!((f - 100.0).abs() < 1e-10);\n }\n _ => panic!(\"expected float, got {expr:?}\"),\n }\n }\n\n #[test]\n fn compiled_filter_scientific_notation() {\n let df = DataFrame::new(vec![\n Column::new(\"ask\".into(), &[0.0f64, 0.00001, 0.1, 5.0]),\n ]).unwrap();\n\n let f = CompiledFilter::new(\"ask > 1e-3\").unwrap();\n let result = f.apply(&df).unwrap();\n assert_eq!(result.height(), 2); // 0.1 and 5.0\n }\n\n #[test]\n fn parse_negative_float_literal() {\n let expr = parse(\"delta >= -0.25\").unwrap();\n assert_eq!(\n expr,\n FilterExpr::Cmp(\"delta\".into(), CmpOp::Ge, Value::Float(-0.25))\n );\n }\n\n #[test]\n fn parse_negative_int_literal() {\n let expr = parse(\"dte >= -30\").unwrap();\n assert_eq!(\n expr,\n FilterExpr::Cmp(\"dte\".into(), CmpOp::Ge, Value::Int(-30))\n );\n }\n\n #[test]\n fn parse_negative_delta_range() {\n // The exact pattern that fails for Cash-Secured Put / Short Strangle\n let expr = parse(\"(delta >= -0.30) & (delta <= -0.15)\").unwrap();\n match expr {\n FilterExpr::And(left, right) => {\n assert_eq!(\n *left,\n FilterExpr::Cmp(\"delta\".into(), CmpOp::Ge, Value::Float(-0.30))\n );\n assert_eq!(\n *right,\n FilterExpr::Cmp(\"delta\".into(), CmpOp::Le, Value::Float(-0.15))\n );\n }\n _ => panic!(\"expected And, got {expr:?}\"),\n }\n }\n\n #[test]\n fn compiled_filter_negative_delta() {\n let df = DataFrame::new(vec![\n Column::new(\"delta\".into(), &[-0.40f64, -0.25, -0.15, -0.05, 0.10]),\n ]).unwrap();\n\n let f = CompiledFilter::new(\"(delta >= -0.30) & (delta <= -0.10)\").unwrap();\n let result = f.apply(&df).unwrap();\n assert_eq!(result.height(), 2); // -0.25 and -0.15\n }\n\n // --- eval_row tests ---\n\n #[test]\n fn eval_row_simple_eq() {\n let df = DataFrame::new(vec![\n Column::new(\"type\".into(), &[\"call\", \"put\", \"put\"]),\n Column::new(\"ask\".into(), &[1.0f64, 2.0, 0.0]),\n ]).unwrap();\n\n let f = CompiledFilter::new(\"type == 'put'\").unwrap();\n assert!(!f.eval_row(&df, 0)); // call\n assert!(f.eval_row(&df, 1)); // put\n assert!(f.eval_row(&df, 2)); // put\n }\n\n #[test]\n fn eval_row_and_filter() {\n let df = DataFrame::new(vec![\n Column::new(\"type\".into(), &[\"call\", \"put\", \"put\"]),\n Column::new(\"ask\".into(), &[1.0f64, 2.0, 0.0]),\n ]).unwrap();\n\n let f = CompiledFilter::new(\"(type == 'put') & (ask > 0)\").unwrap();\n assert!(!f.eval_row(&df, 0)); // call\n assert!(f.eval_row(&df, 1)); // put, ask=2\n assert!(!f.eval_row(&df, 2)); // put, ask=0\n }\n\n #[test]\n fn eval_row_col_arith() {\n let df = DataFrame::new(vec![\n Column::new(\"strike\".into(), &[110.0f64, 95.0, 105.0]),\n Column::new(\"underlying_last\".into(), &[100.0f64, 100.0, 100.0]),\n ]).unwrap();\n\n // strike >= underlying_last * 1.02 → ColArith(\"underlying_last\", Mul, 1.02, Le, Column(\"strike\"))\n let f = CompiledFilter::new(\"strike >= underlying_last * 1.02\").unwrap();\n assert!(f.eval_row(&df, 0)); // 110 >= 102\n assert!(!f.eval_row(&df, 1)); // 95 < 102\n assert!(f.eval_row(&df, 2)); // 105 >= 102\n }\n\n #[test]\n fn eval_row_negative_delta() {\n let df = DataFrame::new(vec![\n Column::new(\"delta\".into(), &[-0.40f64, -0.25, -0.15, -0.05, 0.10]),\n ]).unwrap();\n\n let f = CompiledFilter::new(\"(delta >= -0.30) & (delta <= -0.10)\").unwrap();\n assert!(!f.eval_row(&df, 0)); // -0.40\n assert!(f.eval_row(&df, 1)); // -0.25\n assert!(f.eval_row(&df, 2)); // -0.15\n assert!(!f.eval_row(&df, 3)); // -0.05\n assert!(!f.eval_row(&df, 4)); // 0.10\n }\n\n #[test]\n fn eval_row_matches_apply() {\n // Verify eval_row matches apply for all rows\n let df = DataFrame::new(vec![\n Column::new(\"underlying\".into(), &[\"SPX\", \"SPX\", \"AAPL\", \"SPX\"]),\n Column::new(\"dte\".into(), &[30i32, 90, 90, 150]),\n ]).unwrap();\n\n let f = CompiledFilter::new(\"(underlying == 'SPX') & (dte >= 60) & (dte <= 120)\").unwrap();\n let apply_result = f.apply(&df).unwrap();\n assert_eq!(apply_result.height(), 1);\n\n // eval_row should match\n assert!(!f.eval_row(&df, 0)); // SPX, dte=30\n assert!(f.eval_row(&df, 1)); // SPX, dte=90\n assert!(!f.eval_row(&df, 2)); // AAPL\n assert!(!f.eval_row(&df, 3)); // SPX, dte=150\n }\n}\n"
},
{
"path": "rust/ob_core/src/inventory.rs",
"content": "//! Inventory join — THE hot path.\n//!\n//! Mirrors the inner loop of Python's `_update_balance`:\n//! inv_info.merge(options_data, left_on=\"_contract\", right_on=contract_col)\n//! then compute _value = sign * price * qty * shares_per_contract\n//! then groupby(date).sum() split by call/put.\n\nuse polars::prelude::*;\n\nuse crate::types::Direction;\n\n/// Join inventory contracts with current market data and compute leg values.\n///\n/// Returns a DataFrame with columns: [date, _value, _type]\n/// where _value = sign * price * qty * shares_per_contract.\npub fn join_inventory_to_market(\n contracts: &[String],\n qtys: &[f64],\n types: &[String],\n underlyings: &[String],\n strikes: &[f64],\n options_data: &DataFrame,\n stocks_data: Option<&DataFrame>,\n contract_col: &str,\n _date_col: &str,\n cost_field: &str,\n stocks_sym_col: Option<&str>,\n stocks_price_col: Option<&str>,\n direction: Direction,\n shares_per_contract: i64,\n) -> PolarsResult {\n let contract_series = Series::new(\"_contract\".into(), contracts);\n let qty_series = Series::new(\"_qty\".into(), qtys);\n let type_series = Series::new(\"_type\".into(), types);\n let underlying_series = Series::new(\"_underlying\".into(), underlyings);\n let strike_series = Series::new(\"_strike\".into(), strikes);\n\n let inv = DataFrame::new(vec![\n contract_series.into_column(),\n qty_series.into_column(),\n type_series.into_column(),\n underlying_series.into_column(),\n strike_series.into_column(),\n ])?;\n\n let mut joined = inv\n .lazy()\n .join(\n options_data.clone().lazy(),\n [col(\"_contract\")],\n [col(contract_col)],\n JoinArgs::new(JoinType::Left),\n )\n .collect()?;\n\n // Fill null cost fields with intrinsic value from stocks data\n if let Some(cost_col) = joined.column(cost_field).ok() {\n let null_mask = cost_col.is_null();\n if null_mask.sum().unwrap_or(0) > 0 {\n // Build a price lookup from stocks data (latest price per symbol)\n let mut price_map: std::collections::HashMap = std::collections::HashMap::new();\n if let (Some(sdf), Some(sym_c), Some(price_c)) = (stocks_data, stocks_sym_col, stocks_price_col) {\n if let (Ok(sym_ca), Ok(price_raw)) = (sdf.column(sym_c), sdf.column(price_c)) {\n if let Ok(sym_str) = sym_ca.str() {\n let price_casted = price_raw.cast(&DataType::Float64).unwrap_or(price_raw.clone());\n if let Ok(price_ca) = price_casted.f64() {\n for i in 0..sdf.height() {\n if let (Some(s), Some(p)) = (sym_str.get(i), price_ca.get(i)) {\n price_map.insert(s.to_string(), p);\n }\n }\n }\n }\n }\n }\n\n let types_ca = joined.column(\"_type\")?.str()?;\n let strikes_ca = joined.column(\"_strike\")?.f64()?;\n let underlyings_ca = joined.column(\"_underlying\")?.str()?;\n let cost_ca = joined.column(cost_field)?.f64()?;\n\n let filled: Vec> = (0..joined.height())\n .map(|i| {\n if cost_ca.get(i).is_some() {\n cost_ca.get(i)\n } else {\n let opt_type = types_ca.get(i).unwrap_or(\"put\");\n let strike = strikes_ca.get(i).unwrap_or(0.0);\n let underlying = underlyings_ca.get(i).unwrap_or(\"\");\n let spot = price_map.get(underlying).copied().unwrap_or(0.0);\n let iv = if opt_type == \"call\" {\n (spot - strike).max(0.0)\n } else {\n (strike - spot).max(0.0)\n };\n Some(iv)\n }\n })\n .collect();\n\n let filled_series = Float64Chunked::from_iter_options(cost_field.into(), filled.into_iter());\n let _ = joined.replace(cost_field, filled_series.into_series());\n }\n }\n\n // Compute _value after filling nulls\n let joined = joined\n .lazy()\n .with_column(\n (lit(direction.sign())\n * col(cost_field)\n * col(\"_qty\")\n * lit(shares_per_contract as f64))\n .alias(\"_value\"),\n )\n .collect()?;\n\n Ok(joined)\n}\n\n/// Aggregate values by date, split into calls and puts capital.\n///\n/// Returns (calls_by_date, puts_by_date) as Series indexed by date.\npub fn aggregate_by_type(\n joined: &DataFrame,\n date_col: &str,\n) -> PolarsResult<(DataFrame, DataFrame)> {\n let calls = joined\n .clone()\n .lazy()\n .filter(col(\"_type\").eq(lit(\"call\")))\n .group_by([col(date_col)])\n .agg([col(\"_value\").sum().alias(\"calls_capital\")])\n .sort([date_col], Default::default())\n .collect()?;\n\n let puts = joined\n .clone()\n .lazy()\n .filter(col(\"_type\").neq(lit(\"call\")))\n .group_by([col(date_col)])\n .agg([col(\"_value\").sum().alias(\"puts_capital\")])\n .sort([date_col], Default::default())\n .collect()?;\n\n Ok((calls, puts))\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n fn sample_options() -> DataFrame {\n df!(\n \"optionroot\" => &[\"SPX_A\", \"SPX_A\", \"SPX_B\", \"SPX_B\"],\n \"quotedate\" => &[\"2024-01-01\", \"2024-01-02\", \"2024-01-01\", \"2024-01-02\"],\n \"ask\" => &[2.0, 2.5, 3.0, 3.5],\n \"bid\" => &[1.8, 2.3, 2.8, 3.3],\n )\n .unwrap()\n }\n\n #[test]\n fn join_computes_values() {\n let opts = sample_options();\n let result = join_inventory_to_market(\n &[\"SPX_A\".into(), \"SPX_B\".into()],\n &[10.0, 5.0],\n &[\"call\".into(), \"put\".into()],\n &[\"SPY\".into(), \"SPY\".into()],\n &[400.0, 400.0],\n &opts,\n None,\n \"optionroot\",\n \"quotedate\",\n \"bid\",\n None,\n None,\n Direction::Buy,\n 100,\n )\n .unwrap();\n\n assert!(result.height() > 0);\n let values = result.column(\"_value\").unwrap();\n // Direction::Buy sign = -1, so values should be negative\n let first_val: f64 = values.f64().unwrap().get(0).unwrap();\n assert!(first_val < 0.0);\n }\n\n #[test]\n fn aggregate_splits_calls_puts() {\n let opts = sample_options();\n let joined = join_inventory_to_market(\n &[\"SPX_A\".into(), \"SPX_B\".into()],\n &[10.0, 5.0],\n &[\"call\".into(), \"put\".into()],\n &[\"SPY\".into(), \"SPY\".into()],\n &[400.0, 400.0],\n &opts,\n None,\n \"optionroot\",\n \"quotedate\",\n \"bid\",\n None,\n None,\n Direction::Buy,\n 100,\n )\n .unwrap();\n\n let (calls, puts) = aggregate_by_type(&joined, \"quotedate\").unwrap();\n assert!(calls.height() > 0);\n assert!(puts.height() > 0);\n }\n}\n"
},
{
"path": "rust/ob_core/src/lib.rs",
"content": "pub mod types;\npub mod inventory;\npub mod balance;\npub mod filter;\npub mod entries;\npub mod exits;\npub mod stats;\npub mod cost_model;\npub mod fill_model;\npub mod signal_selector;\npub mod risk;\npub mod backtest;\npub mod convexity_scoring;\npub mod convexity_backtest;\n"
},
{
"path": "rust/ob_core/src/risk.rs",
"content": "//! Risk management — constraints checked before entering positions.\n//!\n//! Mirrors Python's `options_portfolio_backtester.portfolio.risk`.\n\nuse crate::types::Greeks;\n\n#[derive(Debug, Clone)]\npub enum RiskConstraint {\n /// Reject trades that would push portfolio delta beyond a limit.\n MaxDelta { limit: f64 },\n /// Reject trades that would push portfolio vega beyond a limit.\n MaxVega { limit: f64 },\n /// Reject new entries if portfolio drawdown exceeds a threshold.\n MaxDrawdown { max_dd_pct: f64 },\n}\n\nimpl RiskConstraint {\n /// Check whether a proposed trade is allowed.\n ///\n /// Returns true if the trade passes this constraint.\n pub fn check(\n &self,\n current_greeks: &Greeks,\n proposed_greeks: &Greeks,\n portfolio_value: f64,\n peak_value: f64,\n ) -> bool {\n match self {\n RiskConstraint::MaxDelta { limit } => {\n let new_delta = current_greeks.delta + proposed_greeks.delta;\n new_delta.abs() <= *limit\n }\n RiskConstraint::MaxVega { limit } => {\n let new_vega = current_greeks.vega + proposed_greeks.vega;\n new_vega.abs() <= *limit\n }\n RiskConstraint::MaxDrawdown { max_dd_pct } => {\n if peak_value <= 0.0 {\n return true;\n }\n let dd = (peak_value - portfolio_value) / peak_value;\n dd < *max_dd_pct\n }\n }\n }\n}\n\n/// Check all constraints. Returns (allowed, failing_constraint_index).\npub fn check_all(\n constraints: &[RiskConstraint],\n current_greeks: &Greeks,\n proposed_greeks: &Greeks,\n portfolio_value: f64,\n peak_value: f64,\n) -> bool {\n constraints.iter().all(|c| c.check(current_greeks, proposed_greeks, portfolio_value, peak_value))\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn max_delta_allows() {\n let c = RiskConstraint::MaxDelta { limit: 100.0 };\n let current = Greeks::new(50.0, 0.0, 0.0, 0.0);\n let proposed = Greeks::new(30.0, 0.0, 0.0, 0.0);\n assert!(c.check(¤t, &proposed, 1_000_000.0, 1_000_000.0));\n }\n\n #[test]\n fn max_delta_rejects() {\n let c = RiskConstraint::MaxDelta { limit: 100.0 };\n let current = Greeks::new(80.0, 0.0, 0.0, 0.0);\n let proposed = Greeks::new(30.0, 0.0, 0.0, 0.0);\n assert!(!c.check(¤t, &proposed, 1_000_000.0, 1_000_000.0));\n }\n\n #[test]\n fn max_delta_negative() {\n let c = RiskConstraint::MaxDelta { limit: 100.0 };\n let current = Greeks::new(-80.0, 0.0, 0.0, 0.0);\n let proposed = Greeks::new(-30.0, 0.0, 0.0, 0.0);\n assert!(!c.check(¤t, &proposed, 1_000_000.0, 1_000_000.0));\n }\n\n #[test]\n fn max_vega_allows() {\n let c = RiskConstraint::MaxVega { limit: 50.0 };\n let current = Greeks::new(0.0, 0.0, 0.0, 20.0);\n let proposed = Greeks::new(0.0, 0.0, 0.0, 10.0);\n assert!(c.check(¤t, &proposed, 1_000_000.0, 1_000_000.0));\n }\n\n #[test]\n fn max_vega_rejects() {\n let c = RiskConstraint::MaxVega { limit: 50.0 };\n let current = Greeks::new(0.0, 0.0, 0.0, 40.0);\n let proposed = Greeks::new(0.0, 0.0, 0.0, 20.0);\n assert!(!c.check(¤t, &proposed, 1_000_000.0, 1_000_000.0));\n }\n\n #[test]\n fn max_drawdown_allows() {\n let c = RiskConstraint::MaxDrawdown { max_dd_pct: 0.20 };\n let g = Greeks::default();\n // 10% drawdown from peak\n assert!(c.check(&g, &g, 900_000.0, 1_000_000.0));\n }\n\n #[test]\n fn max_drawdown_rejects() {\n let c = RiskConstraint::MaxDrawdown { max_dd_pct: 0.20 };\n let g = Greeks::default();\n // 25% drawdown from peak\n assert!(!c.check(&g, &g, 750_000.0, 1_000_000.0));\n }\n\n #[test]\n fn max_drawdown_zero_peak() {\n let c = RiskConstraint::MaxDrawdown { max_dd_pct: 0.20 };\n let g = Greeks::default();\n assert!(c.check(&g, &g, 100.0, 0.0));\n }\n\n #[test]\n fn check_all_passes() {\n let constraints = vec![\n RiskConstraint::MaxDelta { limit: 100.0 },\n RiskConstraint::MaxVega { limit: 50.0 },\n ];\n let current = Greeks::new(30.0, 0.0, 0.0, 10.0);\n let proposed = Greeks::new(10.0, 0.0, 0.0, 5.0);\n assert!(super::check_all(&constraints, ¤t, &proposed, 1_000_000.0, 1_000_000.0));\n }\n\n #[test]\n fn check_all_fails_one() {\n let constraints = vec![\n RiskConstraint::MaxDelta { limit: 100.0 },\n RiskConstraint::MaxVega { limit: 50.0 },\n ];\n let current = Greeks::new(30.0, 0.0, 0.0, 40.0);\n let proposed = Greeks::new(10.0, 0.0, 0.0, 20.0);\n // Delta OK (40), but Vega fails (60 > 50)\n assert!(!super::check_all(&constraints, ¤t, &proposed, 1_000_000.0, 1_000_000.0));\n }\n\n #[test]\n fn check_all_empty_passes() {\n let g = Greeks::default();\n assert!(super::check_all(&[], &g, &g, 1_000_000.0, 1_000_000.0));\n }\n}\n"
},
{
"path": "rust/ob_core/src/signal_selector.rs",
"content": "//! Signal selectors — choose which contract to trade from candidates.\n//!\n//! Mirrors Python's `options_portfolio_backtester.execution.signal_selector`.\n\nuse polars::prelude::*;\n\n#[derive(Debug, Clone, Default)]\npub enum SignalSelector {\n /// Pick the first row (default — matches original iloc[0] behavior).\n #[default]\n FirstMatch,\n /// Pick the contract whose column value is closest to `target`.\n NearestDelta { target: f64, column: String },\n /// Pick the contract with the highest value in `column`.\n MaxOpenInterest { column: String },\n}\n\nimpl SignalSelector {\n /// Extra columns this selector needs preserved through the entry pipeline.\n pub fn column_requirements(&self) -> Vec<&str> {\n match self {\n SignalSelector::FirstMatch => vec![],\n SignalSelector::NearestDelta { column, .. } => vec![column.as_str()],\n SignalSelector::MaxOpenInterest { column } => vec![column.as_str()],\n }\n }\n\n /// Select one row index from a DataFrame of candidates. Returns 0-based row index.\n #[inline]\n pub fn select_index(&self, candidates: &DataFrame) -> usize {\n if candidates.height() == 0 {\n return 0;\n }\n match self {\n SignalSelector::FirstMatch => 0,\n SignalSelector::NearestDelta { target, column } => {\n match candidates.column(column).ok() {\n Some(col) => {\n match col.f64() {\n Ok(ca) => {\n let mut best_idx = 0;\n let mut best_diff = f64::MAX;\n for (i, val) in ca.into_iter().enumerate() {\n if let Some(v) = val {\n let diff = (v - target).abs();\n if diff < best_diff {\n best_diff = diff;\n best_idx = i;\n }\n }\n }\n best_idx\n }\n Err(_) => 0,\n }\n }\n None => 0, // column not found, fall back to first\n }\n }\n SignalSelector::MaxOpenInterest { column } => {\n match candidates.column(column).ok() {\n Some(col) => {\n match col.f64() {\n Ok(ca) => {\n let mut best_idx = 0;\n let mut best_val = f64::MIN;\n for (i, val) in ca.into_iter().enumerate() {\n if let Some(v) = val {\n if v > best_val {\n best_val = v;\n best_idx = i;\n }\n }\n }\n best_idx\n }\n Err(_) => {\n // Try i64 column\n match col.i64() {\n Ok(ca) => {\n let mut best_idx = 0;\n let mut best_val = i64::MIN;\n for (i, val) in ca.into_iter().enumerate() {\n if let Some(v) = val {\n if v > best_val {\n best_val = v;\n best_idx = i;\n }\n }\n }\n best_idx\n }\n Err(_) => 0,\n }\n }\n }\n }\n None => 0,\n }\n }\n }\n }\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n fn sample_candidates() -> DataFrame {\n df!(\n \"contract\" => &[\"A\", \"B\", \"C\"],\n \"cost\" => &[100.0, 200.0, 150.0],\n \"delta\" => &[-0.20, -0.30, -0.45],\n \"openinterest\" => &[500.0, 1200.0, 800.0],\n ).unwrap()\n }\n\n #[test]\n fn first_match() {\n let df = sample_candidates();\n let sel = SignalSelector::FirstMatch;\n assert_eq!(sel.select_index(&df), 0);\n }\n\n #[test]\n fn nearest_delta() {\n let df = sample_candidates();\n let sel = SignalSelector::NearestDelta {\n target: -0.30,\n column: \"delta\".into(),\n };\n assert_eq!(sel.select_index(&df), 1); // B has delta=-0.30\n }\n\n #[test]\n fn nearest_delta_between() {\n let df = sample_candidates();\n let sel = SignalSelector::NearestDelta {\n target: -0.35,\n column: \"delta\".into(),\n };\n // -0.30 is 0.05 away, -0.45 is 0.10 away → B wins\n assert_eq!(sel.select_index(&df), 1);\n }\n\n #[test]\n fn max_open_interest() {\n let df = sample_candidates();\n let sel = SignalSelector::MaxOpenInterest {\n column: \"openinterest\".into(),\n };\n assert_eq!(sel.select_index(&df), 1); // B has OI=1200\n }\n\n #[test]\n fn missing_column_falls_back() {\n let df = sample_candidates();\n let sel = SignalSelector::NearestDelta {\n target: -0.30,\n column: \"nonexistent\".into(),\n };\n assert_eq!(sel.select_index(&df), 0);\n }\n\n #[test]\n fn column_requirements_check() {\n assert!(SignalSelector::FirstMatch.column_requirements().is_empty());\n let sel = SignalSelector::NearestDelta { target: 0.0, column: \"delta\".into() };\n assert_eq!(sel.column_requirements(), vec![\"delta\"]);\n let sel = SignalSelector::MaxOpenInterest { column: \"oi\".into() };\n assert_eq!(sel.column_requirements(), vec![\"oi\"]);\n }\n}\n"
},
{
"path": "rust/ob_core/src/stats.rs",
"content": "//! Performance statistics computation.\n//!\n//! Comprehensive stats matching Python's BacktestStats: return metrics,\n//! drawdown analysis, period stats, lookback returns, trade stats,\n//! portfolio metrics (turnover, Herfindahl).\n\nconst TRADING_DAYS_PER_YEAR: f64 = 252.0;\nconst MONTHS_PER_YEAR: f64 = 12.0;\n\n// ---------------------------------------------------------------------------\n// Public result types\n// ---------------------------------------------------------------------------\n\n/// Stats for a specific return frequency (daily, monthly, yearly).\n#[derive(Debug, Clone, Default)]\npub struct PeriodStats {\n pub mean: f64,\n pub vol: f64,\n pub sharpe: f64,\n pub sortino: f64,\n pub skew: f64,\n pub kurtosis: f64,\n pub best: f64,\n pub worst: f64,\n}\n\n/// Trailing-period returns as of the last date.\n#[derive(Debug, Clone, Default)]\npub struct LookbackReturns {\n pub mtd: Option,\n pub three_month: Option,\n pub six_month: Option,\n pub ytd: Option,\n pub one_year: Option,\n pub three_year: Option,\n pub five_year: Option,\n pub ten_year: Option,\n}\n\n/// Comprehensive backtest statistics.\n#[derive(Debug, Clone, Default)]\npub struct FullStats {\n // Trade stats\n pub total_trades: u32,\n pub wins: u32,\n pub losses: u32,\n pub win_pct: f64,\n pub profit_factor: f64,\n pub largest_win: f64,\n pub largest_loss: f64,\n pub avg_win: f64,\n pub avg_loss: f64,\n pub avg_trade: f64,\n\n // Return stats\n pub total_return: f64,\n pub annualized_return: f64,\n pub sharpe_ratio: f64,\n pub sortino_ratio: f64,\n pub calmar_ratio: f64,\n\n // Risk stats\n pub max_drawdown: f64,\n pub max_drawdown_duration: u32,\n pub avg_drawdown: f64,\n pub avg_drawdown_duration: u32,\n pub volatility: f64,\n pub tail_ratio: f64,\n\n // Period stats\n pub daily: PeriodStats,\n pub monthly: PeriodStats,\n pub yearly: PeriodStats,\n\n // Lookback\n pub lookback: LookbackReturns,\n\n // Portfolio metrics\n pub turnover: f64,\n pub herfindahl: f64,\n}\n\n// ---------------------------------------------------------------------------\n// Legacy Stats (kept for backward compat with existing callers)\n// ---------------------------------------------------------------------------\n\n/// Legacy stats struct used by run_backtest_py / parallel_sweep.\n#[derive(Debug, Clone, Default)]\npub struct Stats {\n pub total_return: f64,\n pub annualized_return: f64,\n pub sharpe_ratio: f64,\n pub sortino_ratio: f64,\n pub calmar_ratio: f64,\n pub max_drawdown: f64,\n pub max_drawdown_duration: u32,\n pub profit_factor: f64,\n pub win_rate: f64,\n pub total_trades: u32,\n}\n\n// ---------------------------------------------------------------------------\n// Main entry points\n// ---------------------------------------------------------------------------\n\n/// Compute legacy stats (backward compat).\npub fn compute_stats(\n daily_returns: &[f64],\n trade_pnls: &[f64],\n risk_free_rate: f64,\n) -> Stats {\n let n = daily_returns.len();\n if n == 0 {\n return Stats::default();\n }\n\n let total_return = cum_return(daily_returns);\n let years = n as f64 / TRADING_DAYS_PER_YEAR;\n let annualized_return = annualize(total_return, years);\n\n let sharpe_ratio = sharpe(daily_returns, risk_free_rate, TRADING_DAYS_PER_YEAR);\n let sortino_ratio = sortino(daily_returns, risk_free_rate, TRADING_DAYS_PER_YEAR);\n\n let dd = compute_drawdown_full(daily_returns);\n let calmar_ratio = if dd.max_drawdown > 0.0 {\n annualized_return / dd.max_drawdown\n } else {\n 0.0\n };\n\n let ts = compute_trade_stats(trade_pnls);\n\n Stats {\n total_return,\n annualized_return,\n sharpe_ratio,\n sortino_ratio,\n calmar_ratio,\n max_drawdown: dd.max_drawdown,\n max_drawdown_duration: dd.max_drawdown_duration,\n profit_factor: ts.profit_factor,\n win_rate: ts.win_pct / 100.0, // legacy uses 0-1 scale\n total_trades: ts.total_trades,\n }\n}\n\n/// Compute comprehensive stats from total_capital series + optional trade PnLs.\n///\n/// `total_capital`: daily total capital values (one per trading day).\n/// `timestamps_ns`: nanosecond timestamps for each capital value (for monthly/yearly resampling).\n/// `trade_pnls`: per-trade profit/loss values.\n/// `stock_weights`: flattened [n_days × n_stocks] matrix of portfolio weights (row-major).\n/// `n_stocks`: number of stock columns.\n/// `risk_free_rate`: annualized risk-free rate.\npub fn compute_full_stats(\n total_capital: &[f64],\n timestamps_ns: &[i64],\n trade_pnls: &[f64],\n stock_weights: &[f64],\n n_stocks: usize,\n risk_free_rate: f64,\n) -> FullStats {\n let mut fs = FullStats::default();\n\n if total_capital.len() < 2 {\n return fs;\n }\n\n // Daily returns from capital series\n let daily_returns: Vec = total_capital\n .windows(2)\n .map(|w| if w[0] != 0.0 { w[1] / w[0] - 1.0 } else { 0.0 })\n .collect();\n\n let n = daily_returns.len();\n if n == 0 {\n return fs;\n }\n\n // -- Return metrics --\n fs.total_return = total_capital.last().unwrap() / total_capital[0] - 1.0;\n let years = n as f64 / TRADING_DAYS_PER_YEAR;\n fs.annualized_return = annualize(fs.total_return, years);\n fs.volatility = std_dev(&daily_returns) * TRADING_DAYS_PER_YEAR.sqrt();\n fs.sharpe_ratio = sharpe(&daily_returns, risk_free_rate, TRADING_DAYS_PER_YEAR);\n fs.sortino_ratio = sortino(&daily_returns, risk_free_rate, TRADING_DAYS_PER_YEAR);\n\n // -- Drawdown --\n let dd = compute_drawdown_full(&daily_returns);\n fs.max_drawdown = dd.max_drawdown;\n fs.max_drawdown_duration = dd.max_drawdown_duration;\n fs.avg_drawdown = dd.avg_drawdown;\n fs.avg_drawdown_duration = dd.avg_drawdown_duration;\n\n // Calmar\n if fs.max_drawdown > 0.0 {\n fs.calmar_ratio = fs.annualized_return / fs.max_drawdown;\n }\n\n // Tail ratio\n if n > 20 {\n let p95 = percentile(&daily_returns, 95.0);\n let p5 = percentile(&daily_returns, 5.0).abs();\n if p5 > 0.0 {\n fs.tail_ratio = p95 / p5;\n }\n }\n\n // -- Daily period stats --\n fs.daily = compute_period_stats(&daily_returns, risk_free_rate, TRADING_DAYS_PER_YEAR);\n\n // -- Monthly period stats --\n let monthly_returns = resample_returns(total_capital, timestamps_ns, ResampleFreq::Monthly);\n if !monthly_returns.is_empty() {\n fs.monthly = compute_period_stats(&monthly_returns, risk_free_rate, MONTHS_PER_YEAR);\n }\n\n // -- Yearly period stats --\n let yearly_returns = resample_returns(total_capital, timestamps_ns, ResampleFreq::Yearly);\n if !yearly_returns.is_empty() {\n fs.yearly = compute_period_stats(&yearly_returns, risk_free_rate, 1.0);\n }\n\n // -- Lookback returns --\n fs.lookback = compute_lookback(total_capital, timestamps_ns);\n\n // -- Turnover --\n fs.turnover = compute_turnover(stock_weights, n_stocks);\n\n // -- Herfindahl --\n fs.herfindahl = compute_herfindahl(stock_weights, n_stocks);\n\n // -- Trade stats --\n let ts = compute_trade_stats(trade_pnls);\n fs.total_trades = ts.total_trades;\n fs.wins = ts.wins;\n fs.losses = ts.losses;\n fs.win_pct = ts.win_pct;\n fs.profit_factor = ts.profit_factor;\n fs.largest_win = ts.largest_win;\n fs.largest_loss = ts.largest_loss;\n fs.avg_win = ts.avg_win;\n fs.avg_loss = ts.avg_loss;\n fs.avg_trade = ts.avg_trade;\n\n fs\n}\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nfn cum_return(returns: &[f64]) -> f64 {\n returns.iter().fold(1.0, |acc, &r| acc * (1.0 + r)) - 1.0\n}\n\nfn annualize(total_return: f64, years: f64) -> f64 {\n if years > 0.0 {\n (1.0 + total_return).powf(1.0 / years) - 1.0\n } else {\n 0.0\n }\n}\n\nfn mean(values: &[f64]) -> f64 {\n if values.is_empty() {\n return 0.0;\n }\n values.iter().sum::() / values.len() as f64\n}\n\nfn std_dev(values: &[f64]) -> f64 {\n if values.len() < 2 {\n return 0.0;\n }\n let m = mean(values);\n let variance =\n values.iter().map(|&x| (x - m).powi(2)).sum::() / (values.len() - 1) as f64;\n variance.sqrt()\n}\n\nfn skewness(values: &[f64]) -> f64 {\n let n = values.len();\n if n < 8 {\n return 0.0;\n }\n let m = mean(values);\n let s = std_dev(values);\n if s == 0.0 {\n return 0.0;\n }\n let nf = n as f64;\n let m3: f64 = values.iter().map(|&x| ((x - m) / s).powi(3)).sum::() / nf;\n // Adjusted Fisher-Pearson (matches pandas default)\n let adj = (nf * (nf - 1.0)).sqrt() / (nf - 2.0);\n adj * m3\n}\n\nfn kurtosis_excess(values: &[f64]) -> f64 {\n let n = values.len();\n if n < 8 {\n return 0.0;\n }\n let m = mean(values);\n let s = std_dev(values);\n if s == 0.0 {\n return 0.0;\n }\n let nf = n as f64;\n let m4: f64 = values.iter().map(|&x| ((x - m) / s).powi(4)).sum::() / nf;\n // Excess kurtosis with bias correction (matches pandas default)\n let raw = m4 - 3.0;\n let adj = (nf - 1.0) / ((nf - 2.0) * (nf - 3.0)) * ((nf + 1.0) * raw + 6.0);\n adj\n}\n\nfn sharpe(returns: &[f64], risk_free_rate: f64, periods_per_year: f64) -> f64 {\n if returns.len() < 2 {\n return 0.0;\n }\n let rf_per_period = (1.0 + risk_free_rate).powf(1.0 / periods_per_year) - 1.0;\n let excess: Vec = returns.iter().map(|&r| r - rf_per_period).collect();\n let s = std_dev(&excess);\n if s == 0.0 {\n return 0.0;\n }\n mean(&excess) / s * periods_per_year.sqrt()\n}\n\nfn sortino(returns: &[f64], risk_free_rate: f64, periods_per_year: f64) -> f64 {\n if returns.len() < 2 {\n return 0.0;\n }\n let rf_per_period = (1.0 + risk_free_rate).powf(1.0 / periods_per_year) - 1.0;\n let excess: Vec = returns.iter().map(|&r| r - rf_per_period).collect();\n let downside: Vec = excess.iter().filter(|&&r| r < 0.0).copied().collect();\n if downside.is_empty() {\n return 0.0;\n }\n let s = std_dev(&downside);\n if s == 0.0 {\n return 0.0;\n }\n mean(&excess) / s * periods_per_year.sqrt()\n}\n\nfn percentile(values: &[f64], pct: f64) -> f64 {\n if values.is_empty() {\n return 0.0;\n }\n let mut sorted: Vec = values.to_vec();\n sorted.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));\n let idx = (pct / 100.0) * (sorted.len() - 1) as f64;\n let lo = idx.floor() as usize;\n let hi = idx.ceil() as usize;\n if lo == hi || hi >= sorted.len() {\n sorted[lo.min(sorted.len() - 1)]\n } else {\n let frac = idx - lo as f64;\n sorted[lo] * (1.0 - frac) + sorted[hi] * frac\n }\n}\n\n// -- Drawdown --\n\nstruct DrawdownResult {\n max_drawdown: f64,\n max_drawdown_duration: u32,\n avg_drawdown: f64,\n avg_drawdown_duration: u32,\n}\n\nfn compute_drawdown_full(daily_returns: &[f64]) -> DrawdownResult {\n let mut peak = 1.0_f64;\n let mut equity = 1.0_f64;\n let mut max_dd = 0.0_f64;\n let mut max_dd_dur: u32 = 0;\n let mut current_dur: u32 = 0;\n\n // Track drawdown episodes for avg computation\n let mut episode_depths: Vec = Vec::new();\n let mut episode_durations: Vec = Vec::new();\n let mut current_min_dd = 0.0_f64; // deepest dd in current episode\n\n for &r in daily_returns {\n equity *= 1.0 + r;\n if equity > peak {\n // End of drawdown episode (if we were in one)\n if current_dur > 0 {\n episode_depths.push(current_min_dd);\n episode_durations.push(current_dur);\n }\n peak = equity;\n current_dur = 0;\n current_min_dd = 0.0;\n } else {\n current_dur += 1;\n max_dd_dur = max_dd_dur.max(current_dur);\n }\n let dd = (peak - equity) / peak;\n if dd > max_dd {\n max_dd = dd;\n }\n if dd > current_min_dd {\n current_min_dd = dd;\n }\n }\n // Close last episode if still in drawdown\n if current_dur > 0 {\n episode_depths.push(current_min_dd);\n episode_durations.push(current_dur);\n }\n\n let avg_drawdown = if episode_depths.is_empty() {\n 0.0\n } else {\n mean(&episode_depths)\n };\n\n let avg_drawdown_duration = if episode_durations.is_empty() {\n 0\n } else {\n let dur_f: Vec = episode_durations.iter().map(|&d| d as f64).collect();\n mean(&dur_f) as u32\n };\n\n DrawdownResult {\n max_drawdown: max_dd,\n max_drawdown_duration: max_dd_dur,\n avg_drawdown,\n avg_drawdown_duration,\n }\n}\n\n// -- Period stats --\n\nfn compute_period_stats(returns: &[f64], risk_free_rate: f64, periods_per_year: f64) -> PeriodStats {\n if returns.is_empty() {\n return PeriodStats::default();\n }\n PeriodStats {\n mean: mean(returns),\n vol: std_dev(returns),\n sharpe: sharpe(returns, risk_free_rate, periods_per_year),\n sortino: sortino(returns, risk_free_rate, periods_per_year),\n skew: skewness(returns),\n kurtosis: kurtosis_excess(returns),\n best: returns.iter().cloned().fold(f64::NEG_INFINITY, f64::max),\n worst: returns.iter().cloned().fold(f64::INFINITY, f64::min),\n }\n}\n\n// -- Resampling --\n\n#[derive(Clone, Copy)]\nenum ResampleFreq {\n Monthly,\n Yearly,\n}\n\n/// Resample total_capital to end-of-period values, then compute returns.\nfn resample_returns(\n total_capital: &[f64],\n timestamps_ns: &[i64],\n freq: ResampleFreq,\n) -> Vec {\n if total_capital.len() < 2 || timestamps_ns.len() != total_capital.len() {\n return Vec::new();\n }\n\n // Group by period key, take last value in each period\n let mut period_vals: Vec = Vec::new();\n let mut last_key: Option<(i32, u32)> = None;\n\n for (i, &ts_ns) in timestamps_ns.iter().enumerate() {\n let key = period_key(ts_ns, freq);\n match last_key {\n Some(prev) if prev != key => {\n // Previous period ended at i-1\n period_vals.push(total_capital[i - 1]);\n last_key = Some(key);\n }\n None => {\n last_key = Some(key);\n }\n _ => {}\n }\n }\n // Push the last period value\n if let Some(_) = last_key {\n period_vals.push(*total_capital.last().unwrap());\n }\n\n // Compute returns from period values\n if period_vals.len() < 2 {\n return Vec::new();\n }\n period_vals\n .windows(2)\n .map(|w| if w[0] != 0.0 { w[1] / w[0] - 1.0 } else { 0.0 })\n .collect()\n}\n\n/// Convert nanosecond timestamp to (year, period) key.\nfn period_key(ts_ns: i64, freq: ResampleFreq) -> (i32, u32) {\n // Convert nanoseconds since epoch to days\n let days_since_epoch = (ts_ns / 86_400_000_000_000) as i32;\n // Simple calendar calculation from days since 1970-01-01\n let (year, month, _day) = days_to_ymd(days_since_epoch);\n match freq {\n ResampleFreq::Monthly => (year, month),\n ResampleFreq::Yearly => (year, 0),\n }\n}\n\n/// Convert days since epoch (1970-01-01) to (year, month, day).\nfn days_to_ymd(days: i32) -> (i32, u32, u32) {\n // Algorithm from Howard Hinnant's date library (public domain)\n let z = days + 719468;\n let era = if z >= 0 { z } else { z - 146096 } / 146097;\n let doe = (z - era * 146097) as u32;\n let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;\n let y = yoe as i32 + era * 400;\n let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);\n let mp = (5 * doy + 2) / 153;\n let d = doy - (153 * mp + 2) / 5 + 1;\n let m = if mp < 10 { mp + 3 } else { mp - 9 };\n let year = if m <= 2 { y + 1 } else { y };\n (year, m, d)\n}\n\n// -- Lookback returns --\n\nfn compute_lookback(total_capital: &[f64], timestamps_ns: &[i64]) -> LookbackReturns {\n let mut lb = LookbackReturns::default();\n if total_capital.len() < 2 || timestamps_ns.len() != total_capital.len() {\n return lb;\n }\n\n let end_val = *total_capital.last().unwrap();\n let end_ts = *timestamps_ns.last().unwrap();\n let (end_year, end_month, _end_day) = days_to_ymd((end_ts / 86_400_000_000_000) as i32);\n\n // Helper: find return since the first data point on or after target_ns\n let return_since = |target_ns: i64| -> Option {\n match timestamps_ns.iter().position(|&ts| ts >= target_ns) {\n Some(idx) => {\n let start_val = total_capital[idx];\n if start_val == 0.0 {\n None\n } else {\n Some(end_val / start_val - 1.0)\n }\n }\n None => None,\n }\n };\n\n // MTD: start of current month\n lb.mtd = return_since(ymd_to_ns(end_year, end_month, 1));\n\n // YTD: start of current year\n lb.ytd = return_since(ymd_to_ns(end_year, 1, 1));\n\n // Fixed offsets (in months)\n let offsets: [(fn(&mut LookbackReturns, Option), u32); 6] = [\n (|lb, v| lb.three_month = v, 3),\n (|lb, v| lb.six_month = v, 6),\n (|lb, v| lb.one_year = v, 12),\n (|lb, v| lb.three_year = v, 36),\n (|lb, v| lb.five_year = v, 60),\n (|lb, v| lb.ten_year = v, 120),\n ];\n\n for (setter, months) in offsets {\n let target_ns = subtract_months_ns(end_ts, months);\n setter(&mut lb, return_since(target_ns));\n }\n\n lb\n}\n\nfn ymd_to_ns(year: i32, month: u32, day: u32) -> i64 {\n // Inverse of days_to_ymd: compute days since epoch\n let y = if month <= 2 { year - 1 } else { year } as i64;\n let m = if month <= 2 { month + 9 } else { month - 3 } as i64;\n let era = if y >= 0 { y } else { y - 399 } / 400;\n let yoe = y - era * 400;\n let doy = (153 * m + 2) / 5 + day as i64 - 1;\n let doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;\n let days = era * 146097 + doe - 719468;\n days * 86_400_000_000_000\n}\n\nfn subtract_months_ns(ts_ns: i64, months: u32) -> i64 {\n let (year, month, day) = days_to_ymd((ts_ns / 86_400_000_000_000) as i32);\n let total_months = year * 12 + month as i32 - months as i32;\n let new_year = if total_months > 0 {\n (total_months - 1) / 12\n } else {\n (total_months - 12) / 12\n };\n let new_month = total_months - new_year * 12;\n ymd_to_ns(new_year, new_month as u32, day.min(28)) // clamp day to avoid invalid dates\n}\n\n// -- Portfolio metrics --\n\nfn compute_turnover(stock_weights: &[f64], n_stocks: usize) -> f64 {\n if n_stocks == 0 || stock_weights.is_empty() {\n return 0.0;\n }\n let n_days = stock_weights.len() / n_stocks;\n if n_days < 2 {\n return 0.0;\n }\n\n let mut total_change = 0.0;\n for day in 1..n_days {\n let mut day_change = 0.0;\n for s in 0..n_stocks {\n let prev = stock_weights[(day - 1) * n_stocks + s];\n let curr = stock_weights[day * n_stocks + s];\n day_change += (curr - prev).abs();\n }\n total_change += day_change;\n }\n\n total_change / (n_days - 1) as f64 / 2.0\n}\n\nfn compute_herfindahl(stock_weights: &[f64], n_stocks: usize) -> f64 {\n if n_stocks == 0 || stock_weights.is_empty() {\n return 0.0;\n }\n let n_days = stock_weights.len() / n_stocks;\n if n_days == 0 {\n return 0.0;\n }\n\n let mut total_hhi = 0.0;\n for day in 0..n_days {\n let mut hhi = 0.0;\n for s in 0..n_stocks {\n let w = stock_weights[day * n_stocks + s];\n hhi += w * w;\n }\n total_hhi += hhi;\n }\n\n total_hhi / n_days as f64\n}\n\n// -- Trade stats --\n\nstruct TradeStatsResult {\n total_trades: u32,\n wins: u32,\n losses: u32,\n win_pct: f64,\n profit_factor: f64,\n largest_win: f64,\n largest_loss: f64,\n avg_win: f64,\n avg_loss: f64,\n avg_trade: f64,\n}\n\nfn compute_trade_stats(pnls: &[f64]) -> TradeStatsResult {\n if pnls.is_empty() {\n return TradeStatsResult {\n total_trades: 0,\n wins: 0,\n losses: 0,\n win_pct: 0.0,\n profit_factor: 0.0,\n largest_win: 0.0,\n largest_loss: 0.0,\n avg_win: 0.0,\n avg_loss: 0.0,\n avg_trade: 0.0,\n };\n }\n\n let mut gross_profit = 0.0;\n let mut gross_loss = 0.0;\n let mut wins: u32 = 0;\n let mut losses: u32 = 0;\n let mut largest_win = 0.0_f64;\n let mut largest_loss = 0.0_f64;\n let mut sum_wins = 0.0;\n let mut sum_losses = 0.0;\n\n for &pnl in pnls {\n if pnl > 0.0 {\n gross_profit += pnl;\n wins += 1;\n sum_wins += pnl;\n if pnl > largest_win {\n largest_win = pnl;\n }\n } else {\n gross_loss += pnl.abs();\n losses += 1;\n sum_losses += pnl;\n if pnl < largest_loss {\n largest_loss = pnl;\n }\n }\n }\n\n let total = pnls.len() as u32;\n let win_pct = if total > 0 {\n wins as f64 / total as f64 * 100.0\n } else {\n 0.0\n };\n\n let profit_factor = if gross_loss > 0.0 {\n gross_profit / gross_loss\n } else if gross_profit > 0.0 {\n f64::INFINITY\n } else {\n 0.0\n };\n\n TradeStatsResult {\n total_trades: total,\n wins,\n losses,\n win_pct,\n profit_factor,\n largest_win,\n largest_loss,\n avg_win: if wins > 0 { sum_wins / wins as f64 } else { 0.0 },\n avg_loss: if losses > 0 { sum_losses / losses as f64 } else { 0.0 },\n avg_trade: pnls.iter().sum::() / total as f64,\n }\n}\n\n// ---------------------------------------------------------------------------\n// Tests\n// ---------------------------------------------------------------------------\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn stats_empty() {\n let s = compute_stats(&[], &[], 0.0);\n assert_eq!(s.total_return, 0.0);\n }\n\n #[test]\n fn stats_simple_returns() {\n let returns = vec![0.01, -0.005, 0.02, -0.01, 0.015];\n let s = compute_stats(&returns, &[], 0.0);\n assert!(s.total_return > 0.0);\n assert!(s.sharpe_ratio != 0.0);\n }\n\n #[test]\n fn drawdown_calculation() {\n let returns = vec![0.10, -0.18182]; // 1.0 -> 1.1 -> 0.9\n let dd = compute_drawdown_full(&returns);\n assert!((dd.max_drawdown - 0.18182).abs() < 0.01);\n }\n\n #[test]\n fn profit_factor_calculation() {\n let pnls = vec![100.0, -50.0, 200.0, -30.0];\n let s = compute_stats(&[0.01; 4], &pnls, 0.0);\n assert!((s.profit_factor - 300.0 / 80.0).abs() < 0.01);\n assert_eq!(s.total_trades, 4);\n assert_eq!(s.win_rate, 0.5);\n }\n\n #[test]\n fn full_stats_empty() {\n let fs = compute_full_stats(&[], &[], &[], &[], 0, 0.0);\n assert_eq!(fs.total_return, 0.0);\n assert_eq!(fs.total_trades, 0);\n }\n\n #[test]\n fn full_stats_basic() {\n // 10 days of varying positive returns\n let daily = vec![0.01, 0.005, 0.02, -0.003, 0.015, 0.008, -0.002, 0.012, 0.007, 0.01];\n let mut capital = vec![100_000.0];\n for &r in &daily {\n capital.push(capital.last().unwrap() * (1.0 + r));\n }\n // Generate fake timestamps (2020-01-01 + daily)\n let base_ns: i64 = 1577836800_000_000_000; // 2020-01-01\n let ts: Vec = (0..capital.len())\n .map(|i| base_ns + i as i64 * 86_400_000_000_000)\n .collect();\n\n let fs = compute_full_stats(&capital, &ts, &[], &[], 0, 0.0);\n assert!(fs.total_return > 0.0);\n assert!(fs.volatility > 0.0);\n assert!(fs.daily.mean > 0.0);\n }\n\n #[test]\n fn full_stats_drawdown_avg() {\n // Up, crash, recover, crash again\n let returns = vec![0.10, -0.15, -0.05, 0.30, 0.05, -0.10, 0.20];\n let mut capital = vec![100_000.0];\n for &r in &returns {\n capital.push(capital.last().unwrap() * (1.0 + r));\n }\n let base_ns: i64 = 1577836800_000_000_000;\n let ts: Vec = (0..capital.len())\n .map(|i| base_ns + i as i64 * 86_400_000_000_000)\n .collect();\n\n let fs = compute_full_stats(&capital, &ts, &[], &[], 0, 0.0);\n assert!(fs.max_drawdown > 0.0);\n assert!(fs.avg_drawdown > 0.0);\n assert!(fs.avg_drawdown <= fs.max_drawdown);\n }\n\n #[test]\n fn full_stats_trade_pnls() {\n let capital = vec![100_000.0, 101_000.0, 102_000.0];\n let base_ns: i64 = 1577836800_000_000_000;\n let ts: Vec = (0..3).map(|i| base_ns + i * 86_400_000_000_000).collect();\n let pnls = vec![100.0, 200.0, -50.0];\n\n let fs = compute_full_stats(&capital, &ts, &pnls, &[], 0, 0.0);\n assert_eq!(fs.total_trades, 3);\n assert_eq!(fs.wins, 2);\n assert_eq!(fs.losses, 1);\n assert!((fs.profit_factor - 6.0).abs() < 0.01);\n }\n\n #[test]\n fn full_stats_turnover() {\n // 3 days, 2 stocks\n let weights = vec![\n 0.5, 0.5, // day 0\n 0.6, 0.4, // day 1: 0.1 change each\n 0.6, 0.4, // day 2: no change\n ];\n let t = compute_turnover(&weights, 2);\n // day 1: sum(|0.1|+|0.1|)/2 = 0.1, day 2: 0 → avg = 0.05\n assert!((t - 0.05).abs() < 1e-10);\n }\n\n #[test]\n fn full_stats_herfindahl() {\n // 2 equal stocks → HHI = 0.5\n let weights = vec![0.5, 0.5, 0.5, 0.5];\n let h = compute_herfindahl(&weights, 2);\n assert!((h - 0.5).abs() < 1e-10);\n }\n\n #[test]\n fn percentile_basic() {\n let vals = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0];\n let p50 = percentile(&vals, 50.0);\n assert!((p50 - 5.5).abs() < 0.01);\n let p0 = percentile(&vals, 0.0);\n assert!((p0 - 1.0).abs() < 0.01);\n let p100 = percentile(&vals, 100.0);\n assert!((p100 - 10.0).abs() < 0.01);\n }\n\n #[test]\n fn days_to_ymd_epoch() {\n let (y, m, d) = days_to_ymd(0);\n assert_eq!((y, m, d), (1970, 1, 1));\n }\n\n #[test]\n fn days_to_ymd_known_date() {\n // 2020-01-01 = 18262 days since epoch\n let (y, m, d) = days_to_ymd(18262);\n assert_eq!((y, m, d), (2020, 1, 1));\n }\n\n #[test]\n fn ymd_roundtrip() {\n let ns = ymd_to_ns(2020, 6, 15);\n let days = (ns / 86_400_000_000_000) as i32;\n let (y, m, d) = days_to_ymd(days);\n assert_eq!((y, m, d), (2020, 6, 15));\n }\n\n #[test]\n fn lookback_basic() {\n // ~500 trading days from 2020-01-01\n let n = 500;\n let mut capital = vec![100_000.0];\n for i in 0..n {\n capital.push(capital[i] * 1.001); // small daily growth\n }\n let base_ns: i64 = ymd_to_ns(2020, 1, 1);\n let ts: Vec = (0..=n)\n .map(|i| base_ns + i as i64 * 86_400_000_000_000)\n .collect();\n\n let lb = compute_lookback(&capital, &ts);\n assert!(lb.mtd.is_some());\n assert!(lb.ytd.is_some());\n assert!(lb.one_year.is_some());\n }\n\n #[test]\n fn monthly_resample() {\n // Generate 90 days of data spanning ~3 months\n let n = 90;\n let mut capital = vec![100_000.0];\n for i in 0..n {\n capital.push(capital[i] * 1.001);\n }\n let base_ns: i64 = ymd_to_ns(2020, 1, 1);\n let ts: Vec = (0..=n)\n .map(|i| base_ns + i as i64 * 86_400_000_000_000)\n .collect();\n\n let monthly = resample_returns(&capital, &ts, ResampleFreq::Monthly);\n assert!(monthly.len() >= 2); // At least 2 monthly returns from 3 months\n }\n}\n"
},
{
"path": "rust/ob_core/src/types.rs",
"content": "/// Core domain types mirroring Python's options_portfolio_backtester.core.types.\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]\npub enum Direction {\n Buy,\n Sell,\n}\n\nimpl Direction {\n #[inline]\n pub fn sign(self) -> f64 {\n match self {\n Direction::Buy => -1.0,\n Direction::Sell => 1.0,\n }\n }\n\n #[inline]\n pub fn price_column(self) -> &'static str {\n match self {\n Direction::Buy => \"ask\",\n Direction::Sell => \"bid\",\n }\n }\n\n #[inline]\n pub fn invert(self) -> Direction {\n match self {\n Direction::Buy => Direction::Sell,\n Direction::Sell => Direction::Buy,\n }\n }\n}\n\n#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]\npub enum OptionType {\n Call,\n Put,\n}\n\nimpl OptionType {\n pub fn as_str(self) -> &'static str {\n match self {\n OptionType::Call => \"call\",\n OptionType::Put => \"put\",\n }\n }\n}\n\n/// Configuration for a single strategy leg.\n#[derive(Debug, Clone)]\npub struct LegConfig {\n pub name: String,\n pub option_type: OptionType,\n pub direction: Direction,\n pub entry_filter_query: Option,\n pub exit_filter_query: Option,\n pub entry_sort_col: Option,\n pub entry_sort_asc: bool,\n /// Per-leg signal selector override (None = use engine-level selector).\n pub signal_selector: Option,\n /// Per-leg fill model override (None = use engine-level fill model).\n pub fill_model: Option,\n}\n\n/// Aggregated Greeks for a position or portfolio.\n#[derive(Debug, Clone, Copy, Default)]\npub struct Greeks {\n pub delta: f64,\n pub gamma: f64,\n pub theta: f64,\n pub vega: f64,\n}\n\nimpl Greeks {\n pub fn new(delta: f64, gamma: f64, theta: f64, vega: f64) -> Self {\n Self { delta, gamma, theta, vega }\n }\n\n pub fn scale(self, s: f64) -> Self {\n Self {\n delta: self.delta * s,\n gamma: self.gamma * s,\n theta: self.theta * s,\n vega: self.vega * s,\n }\n }\n}\n\nimpl std::ops::Add for Greeks {\n type Output = Self;\n fn add(self, rhs: Self) -> Self {\n Self {\n delta: self.delta + rhs.delta,\n gamma: self.gamma + rhs.gamma,\n theta: self.theta + rhs.theta,\n vega: self.vega + rhs.vega,\n }\n }\n}\n\nimpl std::ops::AddAssign for Greeks {\n fn add_assign(&mut self, rhs: Self) {\n self.delta += rhs.delta;\n self.gamma += rhs.gamma;\n self.theta += rhs.theta;\n self.vega += rhs.vega;\n }\n}\n\n/// Balance row for a single date.\n#[derive(Debug, Clone, Default)]\npub struct BalanceRow {\n pub cash: f64,\n pub options_qty: f64,\n pub calls_capital: f64,\n pub puts_capital: f64,\n pub stocks_qty: f64,\n pub stock_holdings: Vec<(String, f64)>,\n pub stock_qtys: Vec<(String, f64)>,\n}\n\n#[cfg(test)]\nmod tests {\n use super::*;\n\n #[test]\n fn direction_sign() {\n assert_eq!(Direction::Buy.sign(), -1.0);\n assert_eq!(Direction::Sell.sign(), 1.0);\n }\n\n #[test]\n fn direction_invert() {\n assert_eq!(Direction::Buy.invert(), Direction::Sell);\n assert_eq!(Direction::Sell.invert(), Direction::Buy);\n }\n\n #[test]\n fn greeks_add() {\n let a = Greeks::new(1.0, 2.0, 3.0, 4.0);\n let b = Greeks::new(0.5, 0.5, 0.5, 0.5);\n let c = a + b;\n assert!((c.delta - 1.5).abs() < 1e-10);\n assert!((c.gamma - 2.5).abs() < 1e-10);\n }\n\n #[test]\n fn greeks_scale() {\n let g = Greeks::new(1.0, 2.0, 3.0, 4.0).scale(2.0);\n assert!((g.delta - 2.0).abs() < 1e-10);\n assert!((g.vega - 8.0).abs() < 1e-10);\n }\n}\n"
},
{
"path": "rust/ob_python/Cargo.toml",
"content": "[package]\nname = \"ob_python\"\nversion = \"0.1.0\"\nedition = \"2021\"\n\n[lib]\nname = \"_ob_rust\"\ncrate-type = [\"cdylib\"]\n\n[dependencies]\nob_core = { path = \"../ob_core\" }\npyo3 = { version = \"0.24\", features = [\"extension-module\"] }\npyo3-polars = \"0.21\"\npolars = { version = \"0.48\", features = [\"lazy\"] }\nnumpy = \"0.24\"\nrayon = \"1.10\"\n"
},
{
"path": "rust/ob_python/src/arrow_bridge.rs",
"content": "//! Arrow C Data Interface bridge: pyarrow <-> Polars zero-copy.\n//!\n//! Uses pyo3-polars for direct DataFrame conversions between\n//! Python (pandas/pyarrow) and Rust (Polars).\n\nuse pyo3_polars::PyDataFrame;\nuse polars::prelude::DataFrame;\n\n/// Convert a PyDataFrame (from Python) to a Polars DataFrame.\npub fn py_to_polars(py_df: PyDataFrame) -> DataFrame {\n py_df.0\n}\n\n/// Convert a Polars DataFrame to a PyDataFrame (for Python).\npub fn polars_to_py(df: DataFrame) -> PyDataFrame {\n PyDataFrame(df)\n}\n"
},
{
"path": "rust/ob_python/src/lib.rs",
"content": "use pyo3::prelude::*;\n\nmod arrow_bridge;\nmod py_balance;\nmod py_backtest;\nmod py_convexity;\nmod py_filter;\nmod py_entries;\nmod py_exits;\nmod py_stats;\nmod py_execution;\nmod py_sweep;\n\n#[pymodule]\nfn _ob_rust(m: &Bound<'_, PyModule>) -> PyResult<()> {\n m.add_function(wrap_pyfunction!(py_balance::update_balance, m)?)?;\n m.add_function(wrap_pyfunction!(py_backtest::run_backtest_py, m)?)?;\n m.add_function(wrap_pyfunction!(py_backtest::run_multi_strategy_py, m)?)?;\n m.add_function(wrap_pyfunction!(py_filter::compile_filter, m)?)?;\n m.add_function(wrap_pyfunction!(py_filter::apply_filter, m)?)?;\n m.add_function(wrap_pyfunction!(py_entries::compute_entries, m)?)?;\n m.add_function(wrap_pyfunction!(py_exits::compute_exit_mask, m)?)?;\n m.add_function(wrap_pyfunction!(py_stats::compute_stats, m)?)?;\n m.add_function(wrap_pyfunction!(py_stats::compute_full_stats, m)?)?;\n m.add_function(wrap_pyfunction!(py_sweep::parallel_sweep, m)?)?;\n m.add_function(wrap_pyfunction!(py_convexity::compute_daily_scores, m)?)?;\n m.add_function(wrap_pyfunction!(py_convexity::run_convexity_backtest, m)?)?;\n m.add_function(wrap_pyfunction!(py_execution::rust_option_cost, m)?)?;\n m.add_function(wrap_pyfunction!(py_execution::rust_stock_cost, m)?)?;\n m.add_function(wrap_pyfunction!(py_execution::rust_fill_price, m)?)?;\n m.add_function(wrap_pyfunction!(py_execution::rust_nearest_delta_index, m)?)?;\n m.add_function(wrap_pyfunction!(py_execution::rust_max_value_index, m)?)?;\n m.add_function(wrap_pyfunction!(py_execution::rust_risk_check, m)?)?;\n m.add_class::()?;\n Ok(())\n}\n"
},
{
"path": "rust/ob_python/src/py_backtest.rs",
"content": "//! PyO3 bindings for full backtest loop.\n\nuse pyo3::prelude::*;\nuse pyo3::types::{PyDict, PyList};\nuse pyo3_polars::PyDataFrame;\n\nuse ob_core::backtest::{run_backtest, run_multi_strategy, prepartition_data, BacktestConfig, StrategySlotConfig, SchemaMapping};\nuse ob_core::cost_model::CostModel;\nuse ob_core::fill_model::FillModel;\nuse ob_core::risk::RiskConstraint;\nuse ob_core::signal_selector::SignalSelector;\nuse ob_core::types::{Direction, LegConfig, OptionType};\n\nuse crate::arrow_bridge::{polars_to_py, py_to_polars};\n\n/// Parse schema dict -> SchemaMapping.\npub fn parse_schema(schema: &Bound<'_, PyDict>) -> PyResult {\n Ok(SchemaMapping {\n contract: get_str(schema, \"contract\", \"optionroot\")?,\n date: get_str(schema, \"date\", \"quotedate\")?,\n stocks_date: get_str(schema, \"stocks_date\", \"date\")?,\n stocks_sym: get_str(schema, \"stocks_symbol\", \"symbol\")?,\n stocks_price: get_str(schema, \"stocks_price\", \"adjClose\")?,\n underlying: get_str(schema, \"underlying\", \"underlying\")?,\n expiration: get_str(schema, \"expiration\", \"expiration\")?,\n option_type: get_str(schema, \"type\", \"type\")?,\n strike: get_str(schema, \"strike\", \"strike\")?,\n })\n}\n\n/// Parse a CostModel from a Python dict.\n///\n/// Expected formats:\n/// {\"type\": \"NoCosts\"}\n/// {\"type\": \"PerContract\", \"rate\": 0.65, \"stock_rate\": 0.005}\n/// {\"type\": \"Tiered\", \"tiers\": [[10000, 0.65], [50000, 0.50]], \"stock_rate\": 0.005}\npub fn parse_cost_model(d: &Bound<'_, PyDict>) -> PyResult {\n let model_type = get_str(d, \"type\", \"NoCosts\")?;\n match model_type.as_str() {\n \"NoCosts\" => Ok(CostModel::NoCosts),\n \"PerContract\" => {\n let rate = get_f64(d, \"rate\", 0.65)?;\n let stock_rate = get_f64(d, \"stock_rate\", 0.005)?;\n Ok(CostModel::PerContract { rate, stock_rate })\n }\n \"Tiered\" => {\n let tiers_raw: Vec<(i64, f64)> = d\n .get_item(\"tiers\")?\n .map(|v| v.extract::>())\n .transpose()?\n .unwrap_or_default();\n let stock_rate = get_f64(d, \"stock_rate\", 0.005)?;\n Ok(CostModel::Tiered { tiers: tiers_raw, stock_rate })\n }\n other => Err(pyo3::exceptions::PyValueError::new_err(\n format!(\"unknown cost model type: {other}\"),\n )),\n }\n}\n\n/// Parse a FillModel from a Python dict.\n///\n/// Expected formats:\n/// {\"type\": \"MarketAtBidAsk\"}\n/// {\"type\": \"MidPrice\"}\n/// {\"type\": \"VolumeAware\", \"full_volume_threshold\": 100}\npub fn parse_fill_model(d: &Bound<'_, PyDict>) -> PyResult {\n let model_type = get_str(d, \"type\", \"MarketAtBidAsk\")?;\n match model_type.as_str() {\n \"MarketAtBidAsk\" => Ok(FillModel::MarketAtBidAsk),\n \"MidPrice\" => Ok(FillModel::MidPrice),\n \"VolumeAware\" => {\n let threshold = get_i64(d, \"full_volume_threshold\", 100)?;\n Ok(FillModel::VolumeAware { full_volume_threshold: threshold })\n }\n other => Err(pyo3::exceptions::PyValueError::new_err(\n format!(\"unknown fill model type: {other}\"),\n )),\n }\n}\n\n/// Parse a SignalSelector from a Python dict.\n///\n/// Expected formats:\n/// {\"type\": \"FirstMatch\"}\n/// {\"type\": \"NearestDelta\", \"target\": -0.30, \"column\": \"delta\"}\n/// {\"type\": \"MaxOpenInterest\", \"column\": \"openinterest\"}\npub fn parse_signal_selector(d: &Bound<'_, PyDict>) -> PyResult {\n let sel_type = get_str(d, \"type\", \"FirstMatch\")?;\n match sel_type.as_str() {\n \"FirstMatch\" => Ok(SignalSelector::FirstMatch),\n \"NearestDelta\" => {\n let target = get_f64(d, \"target\", -0.30)?;\n let column = get_str(d, \"column\", \"delta\")?;\n Ok(SignalSelector::NearestDelta { target, column })\n }\n \"MaxOpenInterest\" => {\n let column = get_str(d, \"column\", \"openinterest\")?;\n Ok(SignalSelector::MaxOpenInterest { column })\n }\n other => Err(pyo3::exceptions::PyValueError::new_err(\n format!(\"unknown signal selector type: {other}\"),\n )),\n }\n}\n\n/// Parse a single RiskConstraint from a Python dict.\n///\n/// Expected formats:\n/// {\"type\": \"MaxDelta\", \"limit\": 100.0}\n/// {\"type\": \"MaxVega\", \"limit\": 50.0}\n/// {\"type\": \"MaxDrawdown\", \"max_dd_pct\": 0.20}\npub fn parse_risk_constraint(d: &Bound<'_, PyDict>) -> PyResult {\n let c_type = get_str(d, \"type\", \"\")?;\n match c_type.as_str() {\n \"MaxDelta\" => {\n let limit = get_f64(d, \"limit\", 100.0)?;\n Ok(RiskConstraint::MaxDelta { limit })\n }\n \"MaxVega\" => {\n let limit = get_f64(d, \"limit\", 50.0)?;\n Ok(RiskConstraint::MaxVega { limit })\n }\n \"MaxDrawdown\" => {\n let max_dd_pct = get_f64(d, \"max_dd_pct\", 0.20)?;\n Ok(RiskConstraint::MaxDrawdown { max_dd_pct })\n }\n other => Err(pyo3::exceptions::PyValueError::new_err(\n format!(\"unknown risk constraint type: {other}\"),\n )),\n }\n}\n\n/// Parse config dict -> BacktestConfig.\npub fn parse_config_from_dict(config: &Bound<'_, PyDict>) -> PyResult {\n let alloc_obj = config\n .get_item(\"allocation\")?\n .ok_or_else(|| pyo3::exceptions::PyKeyError::new_err(\"allocation\"))?;\n let alloc: &Bound<'_, PyDict> = alloc_obj\n .downcast::()\n .map_err(|e| pyo3::exceptions::PyTypeError::new_err(e.to_string()))?;\n\n let alloc_stocks = get_f64(alloc, \"stocks\", 0.0)?;\n let alloc_options = get_f64(alloc, \"options\", 0.0)?;\n let alloc_cash = get_f64(alloc, \"cash\", 0.0)?;\n\n let initial_capital = get_f64(config, \"initial_capital\", 1_000_000.0)?;\n let spc = get_i64(config, \"shares_per_contract\", 100)?;\n\n let profit_pct: Option = config\n .get_item(\"profit_pct\")?\n .and_then(|v| v.extract::().ok());\n let loss_pct: Option = config\n .get_item(\"loss_pct\")?\n .and_then(|v| v.extract::().ok());\n\n let rebalance_dates: Vec = config\n .get_item(\"rebalance_dates\")?\n .map(|v| v.extract::>())\n .transpose()?\n .unwrap_or_default();\n\n let legs_list: Vec> = config\n .get_item(\"legs\")?\n .ok_or_else(|| pyo3::exceptions::PyKeyError::new_err(\"legs\"))?\n .extract::>>()?;\n\n let legs: Vec = legs_list\n .iter()\n .map(|d| parse_leg_config(d))\n .collect::>>()?;\n\n let stocks_list: Vec<(String, f64)> = config\n .get_item(\"stocks\")?\n .map(|v| v.extract::>())\n .transpose()?\n .unwrap_or_default();\n\n let stock_symbols: Vec = stocks_list.iter().map(|(s, _)| s.clone()).collect();\n let stock_percentages: Vec = stocks_list.iter().map(|(_, p)| *p).collect();\n\n // Parse new execution model configs (optional — defaults to NoCosts/MarketAtBidAsk/FirstMatch/empty)\n let cost_model = match config.get_item(\"cost_model\")? {\n Some(v) if !v.is_none() => {\n let d = v.downcast::()\n .map_err(|e| pyo3::exceptions::PyTypeError::new_err(e.to_string()))?;\n parse_cost_model(d)?\n }\n _ => CostModel::NoCosts,\n };\n\n let fill_model = match config.get_item(\"fill_model\")? {\n Some(v) if !v.is_none() => {\n let d = v.downcast::()\n .map_err(|e| pyo3::exceptions::PyTypeError::new_err(e.to_string()))?;\n parse_fill_model(d)?\n }\n _ => FillModel::MarketAtBidAsk,\n };\n\n let signal_selector = match config.get_item(\"signal_selector\")? {\n Some(v) if !v.is_none() => {\n let d = v.downcast::()\n .map_err(|e| pyo3::exceptions::PyTypeError::new_err(e.to_string()))?;\n parse_signal_selector(d)?\n }\n _ => SignalSelector::FirstMatch,\n };\n\n let risk_constraints: Vec = match config.get_item(\"risk_constraints\")? {\n Some(v) if !v.is_none() => {\n let list = v.downcast::()\n .map_err(|e| pyo3::exceptions::PyTypeError::new_err(e.to_string()))?;\n list.iter()\n .map(|item| {\n let d = item.downcast::()\n .map_err(|e| pyo3::exceptions::PyTypeError::new_err(e.to_string()))?;\n parse_risk_constraint(d)\n })\n .collect::>>()?\n }\n _ => Vec::new(),\n };\n\n let sma_days: Option = config\n .get_item(\"sma_days\")?\n .and_then(|v| v.extract::().ok());\n\n let options_budget_pct: Option = config\n .get_item(\"options_budget_pct\")?\n .and_then(|v| v.extract::().ok());\n\n let options_budget_annual_pct: Option = config\n .get_item(\"options_budget_annual_pct\")?\n .and_then(|v| v.extract::().ok());\n\n let stop_if_broke: bool = config\n .get_item(\"stop_if_broke\")?\n .map(|v| v.extract::