F1 Race Strategy Simulator

Simulate and compare F1 pit stop strategies using real-world data from the OpenF1 API.

Purpose

This application serves two goals:

1. Learn GitHub Copilot — Every part of this codebase is designed to help you explore Copilot features (code completion, chat, skills, agents, custom instructions). See COPILOT_LEARNING_GUIDE.md.
2. Simulate F1 race strategies — Model tire degradation, fuel effects, and weather impacts to find the optimal pit stop strategy.

Features

• Live Data Explorer — Browse real F1 sessions, drivers, stints, pit stops, and weather from OpenF1
• Strategy Simulator — Configure tire compounds, pit stops, fuel load, and weather, then simulate the race lap-by-lap
• Strategy Comparison — Compare 2-5 strategies side-by-side with interactive charts
• Tire Degradation Model — Realistic compound-specific degradation curves with cliff effects
• Fuel Weight Model — Lap time improvement as fuel burns off

Tech Stack

Layer	Technology
Backend	Python 3.12, FastAPI
Frontend	HTML/CSS/JS, Chart.js
Data	OpenF1 REST API
Testing	pytest, pytest-asyncio

Setup

Prerequisites

• Python 3.12+
• pip

Installation

# Clone the repository
git clone <repo-url>
cd Matthew

# Create virtual environment
python -m venv .venv

# Activate (Windows)
.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

Running

python -m src.main

The app starts at http://127.0.0.1:8000.

Running Tests

pytest tests/ -v --cov=src --cov-report=term-missing

Dependencies

Package	Version	Purpose
fastapi	0.115.6	Web framework
uvicorn	0.34.0	ASGI server
httpx	0.28.1	Async HTTP client
pydantic	2.10.4	Data validation
jinja2	3.1.5	Template engine
python-dotenv	1.0.1	Environment variable loading
pytest	8.3.4	Testing framework
pytest-asyncio	0.24.0	Async test support
pytest-cov	6.0.0	Coverage reporting

Required Permissions

• Network access to api.openf1.org (public API, no API key required)
• No elevated OS permissions required

Configuration

All environment-specific values are configured via environment variables or a .env file:

Variable	Default	Description
OPENF1_BASE_URL	https://api.openf1.org/v1	OpenF1 API base URL
API_HOST	127.0.0.1	Server bind address
API_PORT	8000	Server port
DEFAULT_TIRE_DEGRADATION_RATE	0.05	Base deg rate
DEFAULT_PIT_STOP_TIME_SECONDS	22.0	Default pit time loss
LOG_LEVEL	INFO	Logging level

Project Structure

├── .github/
│   └── copilot-instructions.md    # Copilot engineering standards
├── src/
│   ├── api/
│   │   └── routes.py              # FastAPI endpoints
│   ├── data/
│   │   └── f1_client.py           # OpenF1 API client
│   ├── models/
│   │   └── schemas.py             # Pydantic data models
│   ├── simulator/
│   │   ├── strategy.py            # Race simulation engine
│   │   └── tire_model.py          # Tire degradation model
│   ├── config.py                  # Configuration management
│   └── main.py                    # Application entry point
├── static/
│   ├── index.html                 # Web UI
│   ├── css/styles.css             # Styling
│   └── js/
│       ├── app.js                 # UI logic
│       └── charts.js              # Chart.js visualizations
├── tests/
│   ├── test_tire_model.py         # Tire model unit tests
│   ├── test_strategy.py           # Strategy engine tests
│   └── test_f1_client.py          # API client tests
├── requirements.txt               # Pinned dependencies
├── COPILOT_LEARNING_GUIDE.md      # GitHub Copilot feature guide
└── README.md                      # This file

API Endpoints

Live Data (GET)

• GET /api/sessions?year=2024 — List race sessions
• GET /api/sessions/{key}/drivers — Drivers in a session
• GET /api/sessions/{key}/laps?driver_number=1 — Lap data
• GET /api/sessions/{key}/pit-stops — Pit stop data
• GET /api/sessions/{key}/stints — Tire stint data
• GET /api/sessions/{key}/weather — Weather data

Simulation (POST)

• POST /api/simulate — Run a single strategy simulation
• POST /api/compare — Compare multiple strategies

License

Internal / Learning Project