options-payoff

# Options Payoff — Option P&L Analysis Methodology ## Overview This skill is designed for option strategy analysis scenarios within the Vibe-Trading quantitative framework, covering: - P&L curve generation for single-leg and multi-leg option portfolios - Black-Scholes pricing and Greeks calculation - Implied volatility inversion - Strategy selection decision support **Constraint**: For research and backtesting only. Do not output live trading instructions, in line with the project's guardrails. ### Built-in execution tool Load this skill for methodology, then call `options_payoff` for production calculations. Pass signed `legs` (`qty > 0` long, `qty < 0` short), `entry_spot`, and `expiry_days`; optionally pass actual per-share premiums, multiplier, commission, chart bounds, and IV scenarios. The tool returns an expiry curve, a spot × IV scenario matrix, and analytic breakeven/max-risk results that do not depend on the display grid containing every strike. --- ## 1. Supported Strategy Types ### 1.1 Single-Leg Strategies | Strategy | Bias | Premium | Max Profit | Max Loss | |------|------|--------|----------|----------| | Long Call | Bullish | Paid | Unlimited | Premium | | Long Put | Bearish | Paid | Strike - premium | Premium | | Short Call | Neutral / mildly bearish | Received | Premium | Unlimited | | Short Put | Neutral / mildly bullish | Received | Premium | Strike - premium | ### 1.2 Vertical Spreads | Strategy | Structure | Market View | Net Premium | |------|------|----------|----------| | Bull Call Spread | Long Call (lower K) + Short Call (higher K) | Moderately bullish | Net debit | | Bear Put Spread | Long Put (higher K) + Short Put (lower K) | Moderately bearish | Net debit | | Bull Put Spread | Short Put (higher K) + Long Put (lower K) | Moderately bullish | Net credit | | Bear Call Spread | Short Call (lower K) + Long Call (higher K) | Moderately bearish | Net credit | ### 1.3 Straddles / Strangles (Volatility Strategies) | Strategy | Structure | Market View | |------|------|----------| | Long Straddle | Long Call (ATM) + Long Put (ATM) | Large move up or down, low volatility | | Short Straddle | Short Call (ATM) + Short Put (ATM) | Range-bound market, high volatility | | Long Strangle | Long Call (OTM) + Long Put (OTM) | Large move, lower cost than a straddle | | Short Strangle | Short Call (OTM) + Short Put (OTM) | Tight range, collect two-sided premium | ### 1.4 Butterflies / Iron Butterflies | Strategy | Structure | Feature | |------|------|------| | Long Butterfly (Call) | Long Call (K1) + 2× Short Call (K2) + Long Call (K3) | Low-cost bet that the underlying expires near K2 | | Long Butterfly (Put) | Long Put (K3) + 2× Short Put (K2) + Long Put (K1) | Same logic, built with puts | | Iron Butterfly | Short Call (K2) + Short Put (K2) + Long Call (K3) + Long Put (K1) | Net credit, max profit at K2 | ### 1.5 Condors / Iron Condors | Strategy | Structure | Feature | |------|------|------| | Long Condor (Call) | Long Call (K1) + Short Call (K2) + Short Call (K3) + Long Call (K4) | Bet that the underlying stays between K2 and K3 | | Iron Condor | Short Put (K2) + Long Put (K1) + Short Call (K3) + Long Call (K4) | Most common neutral strategy with capped risk on both sides | Here K1 < K2 < K3 < K4, and K2 / K3 are usually OTM. ### 1.6 Calendar Spreads (Time Spreads) | Strategy | Structure | Market View | |------|------|----------| | Calendar Spread | Short near-month Call/Put (K) + Long far-month Call/Put (K) | Short-term range-bound market + rising forward volatility | | Diagonal Spread | Short near-month Call/Put (K1) + Long far-month Call/Put (K2) | Calendar spread with mild directional bias | Calendar spreads profit because near-month Theta decay is faster than far-month Theta decay. ### 1.7 Ratio Spreads | Strategy | Structure | Feature | |------|------|------| | Ratio Call Spread | Long 1× Call (K1) + Short N× Call (K2), N>1 | Limited upside profit, losses if the upside move becomes extreme | | Ratio Put Spread | Long 1× Put (K2) + Short N× Put (K1) | Limited downside profit, losses if the downside move becomes extreme | | Call Back Spread | Short 1× Call (K1) + Long N× Call (K2), N>1 | Profits from extreme upside, loses on a modest rally | | Put Back Spread | Short 1× Put (K2) + Long N× Put (K1), N>1 | Profits from extreme downside, loses on a mild decline | ### 1.8 Protective / Hedging Strategies | Strategy | Structure | Use Case | |------|------|------| | Covered Call | Long underlying + Short Call (K) | Generate income on an existing position, give up gains above K | | Protective Put | Long underlying + Long Put (K) | Downside protection on an existing position, pay an insurance premium | | Collar | Long underlying + Long Put (K1) + Short Call (K2) | Lock the position into a zero-cost / low-cost range | --- ## 2. Black-Scholes Pricing Model ### 2.1 Core Assumptions - The underlying price follows geometric Brownian motion (lognormal distribution) - Risk-free rate `r` is constant - Volatility `σ` is constant (historical or implied) - No dividends, or adjust with a continuous dividend yield `q` - European options only (exercise at expiration) ### 2.2 Full Formula ``` S = current underlying price K = strike price T = time to expiration (years) r = risk-free rate (annualized continuous compounding) q = continuous dividend yield (commonly used for China A-share / index options) σ = annualized volatility N = standard normal CDF d1 = [ln(S/K) + (r - q + σ²/2) × T] / (σ × √T) d2 = d1 - σ × √T Call = S × e^(-qT) × N(d1) - K × e^(-rT) × N(d2) Put = K × e^(-rT) × N(-d2) - S × e^(-qT) × N(-d1) ``` ### 2.3 Put-Call Parity ``` Call - Put = S × e^(-qT) - K × e^(-rT) ``` Use this to verify pricing consistency and detect arbitrage. When dividends exist, replace `S` with `S × e^(-qT)`. ### 2.4 Greeks Calculation #### Delta (Price Sensitivity) ``` Delta(Call) = e^(-qT) × N(d1) Delta(Put) = e^(-qT) × (N(d1) - 1) ``` - Range: Call [0, 1], Put [-1, 0] - ATM ≈ ±0.5, deep ITM → ±1, deep OTM → 0 #### Gamma (Rate of Change of Delta) ``` Gamma = e^(-qT) × N'(d1) / (S × σ × √T) N'(x) = (1/√(2π)) × e^(-x²/2) [standard normal PDF] ``` - Calls and puts have the same Gamma - Gamma is highest near ATM and explodes as expiration approaches #### Theta (Time Decay, per day) ``` Theta(Call) = [-S × e^(-qT) × N'(d1) × σ / (2√T) - r × K × e^(-rT) × N(d2) + q × S × e^(-qT) × N(d1)] / 365 Theta(Put) = [-S × e^(-qT) × N'(d1) × σ / (2√T) + r × K × e^(-rT) × N(-d2) - q × S × e^(-qT) × N(-d1)] / 365 ``` - Usually negative for option holders - ATM options near expiration have the largest Theta magnitude, which benefits option sellers the most #### Vega (Volatility Sensitivity, per 1% vol change) ``` Vega = S × e^(-qT) × N'(d1) × √T / 100 ``` - Calls and puts have the same Vega - ATM Vega is the largest, and Vega approaches 0 at expiration #### Rho (Interest Rate Sensitivity, per 1% rate change) ``` Rho(Call) = K × T × e^(-rT) × N(d2) / 100 Rho(Put) = -K × T × e^(-rT) × N(-d2) / 100 ``` - The rate effect is usually small and often negligible for short-dated options ### 2.5 Implied Volatility Inversion (Newton-Raphson) Given a market price `P_market`, solve for `σ` such that `BS(σ) = P_market`: ``` Iteration: σ_{n+1} = σ_n - [BS(σ_n) - P_market] / Vega(σ_n) Stopping condition: |BS(σ_n) - P_market| < 1e-6 Initial guess: σ_0 = √(2π/T) × P_market/S (Brenner-Subrahmanyam approximation) Notes: - If Vega is close to 0 (deep OTM / ITM), switch to bisection - If the iteration does not converge (>100 rounds), return NaN and raise a warning - IV > 500% is usually an outlier and should be filtered ``` This is already implemented, guards included, as `src.quantlib.options.implied_volatility` — see section 4.1. The formulas above document what it computes; they are not an instruction to rewrite it. --- ## 3. Payoff Diagram Analysis ### 3.1 Expiry Payoff Curve **Calculation logic**: ``` For each leg i (Call/Put, Long/Short, strike K_i, quantity n_i): Payoff_i(S_T) = n_i × direction_i × max(0, S_T - K_i) # Call Payoff_i(S_T) = n_i × direction_i × max(0, K_i - S_T) # Put Where direction = +1 (Long) / -1 (Short) Portfolio payoff = Σ Payoff_i - net premium cost (paid premium is positive, received premium is negative) ``` **X-axis range**: `[min(K) × 0.7, max(K) × 1.3]`, step size 0.5 or 1 ### 3.2 Theoretical Value Curve (Current Black-Scholes Pricing) For each underlying price `S`, hold `T`, `r`, and `σ` constant and compute current theoretical PnL using the Black-Scholes formula: ``` TheoValue(S) = Σ n_i × direction_i × BS_price(S, K_i, T, r, σ, type_i) - net premium cost ``` The gap between the theoretical value curve and the expiry curve equals the remaining time value. ### 3.3 Break-Even Points Expiry payoff is piecewise linear. Solve `Payoff(S_T) = 0` on intervals formed by `S=0`, every unique strike, and the right tail. Do not search only the chart grid: a narrow grid can miss a valid root beyond its bounds. - Single-leg strategies: - Long Call BEP = K + premium - Long Put BEP = K - premium - Short Call BEP = K + premium received - Short Put BEP = K - premium received - Multi-leg strategies can have more than two breakevens; inspect every strike interval and the unbounded right interval. ### 3.4 Max Profit / Max Loss Evaluate payoff at `S=0` and every unique strike. Those are all finite points where slope can change, so finite extrema occur in that set. Then inspect the right-tail slope: positive means unlimited profit, negative means unlimited loss, and zero means the payoff remains flat. Never derive max profit/loss only from sampled chart points. ### 3.5 P&L Under Different Volatility Scenarios Generate a `σ` scenario matrix using `current IV × [0.5, 0.75, 1.0, 1.25, 1.5]`. Plot one theoretical value curve for each `σ` and distinguish them by color to observe Vega sensitivity. --- ## 4. Python Code Templates ### 4.1 Black-Scholes Pricing Functions — Import, Do Not Retype `bs_price`, `bs_greeks` and `implied_volatility` are implemented once in `src/quantlib/options.py` and pinned by `tests/quantlib/test_options.py` (published Hull reference values, put-call parity, Greeks against finite-difference bumps, implied-vol round-trips). Import them. **Do not retype the formulas from section 2 into your own helper.** A retyped copy is a different, untested function on every run, and the copies that used to live here had two live defects: they crashed on a non-positive spot or strike, and they reported a zero Delta for an expiring in-the-money option. ```python from src.quantlib.options import bs_greeks, bs_price, implied_volatility price = bs_price(S=100, K=100, T=0.25, r=0.03, sigma=0.20, option_type="call", q=0.0) greeks = bs_greeks(100, 100, 0.25, 0.03, 0.20, "call") # delta gamma theta vega rho iv = implied_volatility(market_price=5.0, S=100, K=100, T=0.25, r=0.03, option_type="call") ``` Argument order is `(S, K, T, r, sigma, option_type="call", q=0.0)` for both pricing functions; `implied_volatility` takes `market_price` first, then `(S, K, T, r, option_type="call", q=0.0, tol=1e-6, max_iter=200)`. Contract worth knowing before you use the numbers: | Point | Behaviour | |---|---| | Units | Theta per calendar day; Vega and Rho per 1 percentage point; Delta and Gamma per 1.0 of spot. Nothing is rounded | | `option_type` | Case-insensitive; anything other than call/put raises `ValueError` | | Degenerate input | `T <= 0`, `sigma <= 0`, `S <= 0` or `K <= 0` returns intrinsic value, and Greeks with the correct ±1/0 point-mass Delta — it does not raise | | IV lower guard | Raises `ValueError` below the **discounted** forward intrinsic. Using undiscounted `K - S` instead would wrongly reject deep ITM European puts, which really do trade below it | | IV upper guard | Raises `ValueError` at or above the no-arbitrage ceiling (`S·e^(-qT)` for a call, `K·e^(-rT)` for a put) — no volatility reaches it | | IV failure | Newton seeded by Brenner-Subrahmanyam, falling back to bisection when Vega collapses; returns `nan` only if neither converges | ### 4.2 Multi-Leg Portfolio Payoff Calculation ```python from dataclasses import dataclass from typing import Literal import numpy as np from scipy.optimize import brentq from src.quantlib.options import bs_price @dataclass class OptionLeg: """Single option leg definition. Attributes: option_type: "call" or "put" K: Strike price direction: +1 for Long / -1 for Short quantity: Number of contracts, defaults to 1 premium: Actual traded premium, positive when paid and negative when received T: Time to expiration in years, used for theoretical Black-Scholes pricing sigma: Volatility used in pricing """ option_type: Literal["call", "put"] K: float