This program simulates multiple sessions of blackjack play according to specific rules and a predefined strategy. It tracks the player's bankroll over time and provides data and visualizations for analysis.
- Simulates any number of blackjack sessions with configurable parameters
- Implements specific blackjack rules as described in the requirements
- Uses a basic strategy table to determine player actions
- Tracks bankroll progression throughout each session
- Generates both static and interactive visualizations
- Supports debug mode with predefined card scenarios for testing
- Sessions end when bankroll is <= 0 or >= 2x starting stake
- Output files are timestamped for easy organization
- Python 3.7+
- pandas
- matplotlib
- numpy
- plotly (optional, for interactive HTML plots)
- Clone the repository or download the source code
- Install the required packages:
pip install pandas matplotlib numpy
- For interactive HTML plots, install plotly:
pip install plotly
- Ensure the provided strategy file is in the
data
directory
blackjack_sim/
├── README.md
├── blackjack_sim.py # Main entry point
├── modules/
│ ├── card.py # Card and Deck classes
│ ├── hand.py # Hand management
│ ├── strategy.py # Strategy parser
│ ├── game.py # Core game logic
│ ├── simulator.py # Simulation engine
│ └── plotting.py # Results visualization
├── data/
│ └── basic-strategy.csv # Default strategy file
└── output/ # Results and plots directory
Run the simulator with default settings:
python blackjack_sim.py
--num_sessions
: Number of sessions to simulate (default: 1)--num_hands
: Number of hands per session (default: 100)--starting_stake
: Initial bankroll amount (default: 1000)--standard_bet
: Standard bet amount (default: 10)--verbose
: Enable detailed hand-by-hand logging--debug
: Enable debug mode with hand verification--strategy_file
: Path to strategy CSV file (default: data/basic-strategy.csv)--scenario
: Test scenario to run in debug mode (default: split_8s)
Run 10 sessions of 500 hands each with a $2000 starting bankroll:
python blackjack_sim.py --num_sessions 10 --num_hands 500 --starting_stake 2000
Run in debug mode to test splitting 8s:
python blackjack_sim.py --debug --scenario split_8s
Run with verbose logging:
python blackjack_sim.py --verbose
The simulator produces three main outputs with timestamped filenames (format: YYYYMMDD_HHMM_filename):
- CSV Data File: Contains the bankroll value after each hand for each session
- Static Plot: A PNG line graph showing bankroll progression over time for each session
- Interactive HTML Plot: An interactive visualization that allows exploring the results in detail
These files are saved in the output
directory.
The static plot shows the bankroll value (y-axis) after each hand (x-axis) for each session. The starting stake and double stake values are indicated by horizontal lines.
The interactive HTML plot provides additional functionality:
- Toggle visibility of individual sessions by clicking on the legend
- Hover over lines to see exact values
- Filter sessions by outcome (doubled stake, positive, negative, zero)
- Reset view to default zoom level
- Pan and zoom for detailed exploration
The terminal output includes comprehensive statistics:
- Average/median/max/min final bankroll
- Percentage of sessions ending with a profit
- Detailed outcome distribution:
- Sessions ending with doubled starting stake
- Sessions ending positive but not doubled
- Sessions ending negative but not zero
- Sessions ending with zero bankroll
A session will end when any of these conditions are met:
- The specified number of hands has been played
- The bankroll drops to zero or below (bust)
- The bankroll reaches or exceeds twice the starting stake (success)
The simulator implements specific blackjack rules as described in the requirements:
- Uses 6 decks of cards (312 cards)
- Dealer hits on soft 17
- Blackjack pays 3:2
- Double down allowed on first two cards
- Splitting allowed, including re-splitting
- Double after split allowed
- Surrender allowed on initial two cards
- No insurance
- Reshuffling when fewer than 10% of cards remain
Player decisions are strictly based on the provided basic strategy table. The strategy is loaded from a CSV file where:
- Rows represent player hand values
- Columns represent dealer up card values
- Cell values indicate the action to take (H, S, D, P, X, B, U)
Debug mode allows testing specific scenarios to verify the game logic. Available test scenarios:
split_8s
: Tests pair splittingsoft_17
: Tests dealer soft 17 behaviordouble_after_split
: Tests doubling after splitsoft19v6
: Tests soft total strategysplit_aces
: Tests ace splitting rules
The simulator is designed to handle large-scale simulations efficiently. It can run 100 sessions of 500 hands each in under 5 minutes on a standard personal computer with 12GB RAM.