Changelog: Expected Move Integration

Summary

Integrated market-calibrated expected move from straddle pricing into the Monte Carlo simulation, along with intelligent strategy execution rules that reflect real trading decisions.

Changes Made

1. New Parameters in `SimulationParams`

expected_move_pct: float | None = None  # Expected move from straddle (e.g., 8.5%)
use_dynamic_strikes: bool = True        # Enable dynamic strike selection
early_exit_on_large_move: bool = True   # Exit if move > 1.5x expected

2. Auto-Calibration from Market Data

When expected_move_pct is provided: - Automatically overrides earnings_jump_std - Sets earnings jump distribution to match market expectations - Prints calibration details to console

Example:

Calibrated earnings jump from expected move:
  Expected move: 8.50%
  Earnings jump std: 0.0500 -> 0.0850

3. Strategy Execution Rules

Profit Target Exit (Enhanced)

Exit when P&L reaches profit target
Exit reason tracked: "profit_target"

Large Move Exit (NEW)

Trigger: After earnings, if actual move > 1.5x expected move
Logic: abs(price_move) > expected_move_pct * 1.5
Rationale: Outsized moves may indicate repricing, lock gains/limit losses
Exit reason: "large_move"

Stop Loss Exit (NEW)

Trigger: Position down 75%+ of initial cost after earnings
Logic: pnl < -initial_cost * 0.75
Rationale: Cut losses on severely adverse scenarios
Exit reason: "stop_loss"

Expiration Exit (Default)

Hold to front month expiration if no other rule triggers
Exit reason: "expiration"

4. Enhanced Output

Console Output

Shows calibration details
Displays exit reason breakdown
Reports strategy rules applied

Example:

Exit Reason Breakdown:
  Profit Target: 54.9%
  Expiration: 13.8%
  Large Move: 31.3%
  Stop Loss: 0.0%

Visualization Updates

Summary panel includes expected move
Exit reason statistics displayed
Strategy rules documented in charts

5. Updated Scripts

`monte_carlo.py`

Added new parameters to SimulationParams
Enhanced run_single_simulation() with strategy rules
Updated run_yearly_simulation() to track exit reasons
Modified analyze_results() to include exit reason stats
Enhanced plot_results() to display new metrics

`run_yearly_analysis.py`

Set example expected_move_pct=8.5
Enabled strategy execution rules
Added documentation comments

6. New Documentation

Created MONTE_CARLO_GUIDE.md with: - Overview of expected move integration - Strategy execution rules explained - Parameter documentation - Usage examples - Workflow integration guide - Troubleshooting section

Updated README.md with: - Enhanced script descriptions - References to new guide - Configuration examples

How to Get Expected Move

Method 1: From calculator.py

uv run python scripts/calculator.py
# Enter ticker (e.g., NVDA)
# Output: Expected Move: 8.5%

Method 2: From strategy.py

from trade_calc.strategy import compute_recommendation

result = compute_recommendation("NVDA")
expected_move_pct = result["expected_move_pct"]

Method 3: Manual Calculation

# From options data
expected_move_pct = (straddle_price / stock_price) * 100

Usage Example

Before (Manual Configuration):

params = SimulationParams(
    earnings_jump_std=0.05,  # Guessed
    # ...
)

After (Market Calibrated):

params = SimulationParams(
    earnings_jump_std=0.05,  # Will be overridden
    expected_move_pct=8.5,   # From calculator.py
    use_dynamic_strikes=True,
    early_exit_on_large_move=True,
    # ...
)

Test Results

Sample test with 50 simulations showed: - Calibration: 5% → 8.5% jump std (based on expected move) - Exit reasons: 54.9% profit target, 31.3% large move, 13.8% expiration, 0% stop loss - Performance: Avg yearly P&L $46.24, 100% win rate (all years profitable)

Backward Compatibility

All changes are backward compatible: - expected_move_pct=None (default) → uses manual earnings_jump_std - use_dynamic_strikes=False → disables dynamic adjustments - early_exit_on_large_move=False → disables early exits - Existing scripts work unchanged

Benefits

Market Realism: Uses actual market expectations instead of guesses
Strategy Accuracy: Models real trading decisions and exits
Risk Management: Automatic stop losses and early exits
Better Analysis: See why trades exit, not just final P&L
Stock Comparison: Compare different expected move profiles
Workflow Integration: Seamless flow from analysis to simulation

Files Modified

scripts/monte_carlo.py - Core simulation logic
scripts/run_yearly_analysis.py - Example with expected move
README.md - Updated documentation
MONTE_CARLO_GUIDE.md - New comprehensive guide (NEW)
CHANGELOG_EXPECTED_MOVE.md - This file (NEW)

Next Steps

To use the new features:

Run calculator.py on your target ticker to get expected move
Update simulation parameters with expected_move_pct
Run run_yearly_analysis.py to see full year with strategy execution
Analyze exit reason breakdown to understand strategy behavior
Compare different stocks by varying expected_move_pct

Questions?

See MONTE_CARLO_GUIDE.md for detailed documentation, examples, and troubleshooting.