gap analysis rules - VforVitorio/F1_Strat_Manager GitHub Wiki

Gap Analysis Rules

VforVitorio/F1_Strat_Manager

powered by

Devin

Gap Analysis Rules

This page documents the Gap Analysis Rules system within the F1 Strategy Manager. The system analyzes the time differences between cars on track to identify strategic opportunities like undercuts, overcuts, and defensive pit stops. These rules complement the other rule systems - for information about those, see Degradation Rules, Radio Message Rules, and Integrated Rule Engine.

Overview

Gap analysis is a critical component of Formula 1 race strategy. By analyzing the time differences between cars, strategists can identify opportunities for overtaking through pit stop timing. The Gap Analysis Rules system converts raw timing data into actionable strategic recommendations.

Key Concepts in F1 Strategy

Before discussing the rules, it's important to understand two fundamental concepts in F1 strategy:

Undercut vs. Overcut

Undercut: When a car pits earlier than the car ahead to gain the advantage of fresh tires, completing faster laps while the car ahead is still on worn tires.

Overcut: The opposite approach - staying out longer while competitors pit, maintaining competitive lap times in clean air, then pitting later to gain position.

Gap Data Processing

The system processes raw timing data to extract actionable gap information through several steps:

1. Data Extraction

Racing data is obtained from FastF1 API, providing access to lap timing, position data, and car information:

2. Gap Calculation

The system calculates several critical metrics from the timing data:

The calculate_all_gaps() function processes lap timing data to determine gaps between cars at each lap completion. It:

  • Sorts drivers by time to determine their relative positions
  • Calculates time differences between adjacent cars
  • Generates metrics like gap to leader, gap to car ahead/behind, etc.

3. Gap Consistency Analysis

Gap consistency is critical for strategic decisions - a consistently small gap is more likely to present a valid strategic opportunity than a fluctuating one.

The calculate_gap_consistency() function:

  • Tracks how many consecutive laps a car has maintained a gap within specific windows
  • Categorizes gaps into windows (e.g., "undercut_window", "drs_window", "safe_window")
  • Records the consistency count for both gaps ahead and behind

This consistency data helps ensure strategic recommendations are based on stable patterns rather than momentary fluctuations.

Gap Analysis Rules

The F1GapRules class implements four key rules that trigger strategic recommendations:

1. Undercut Opportunity Rule

Description: Identifies when a driver has been consistently close behind another car, suggesting they may benefit from pitting early to gain an advantage with fresh tires.

Implementation: The rule checks if:

  • Gap to car ahead is less than 2.0 seconds
  • This gap has been consistent for at least 3 laps
  • Current lap is within a valid range for an undercut (early or mid-race)

Response: Recommends "perform_undercut" action with high confidence (0.85) and priority (2)

2. Defensive Pit Stop Rule

Description: Identifies when a driver is being consistently followed closely by another car, indicating they should pit to avoid being undercut.

Implementation: The rule checks if:

  • Gap to car behind is less than 2.0 seconds
  • This gap has been consistent for at least 3 laps
  • Current lap is within a valid range for a defensive stop

Response: Recommends "defensive_pit" action with high confidence (0.8) and priority (2)

3. Strategic Overcut Rule

Description: Identifies when a driver might benefit from staying out longer than the car ahead, especially when the gap is slightly larger than undercut range.

Implementation: The rule checks if:

  • Gap to car ahead is between 2.0 and 3.5 seconds
  • This gap has been consistent for at least 4 laps
  • Current lap is within a valid range for an overcut strategy

Response: Recommends "perform_overcut" action with high confidence (0.8) and priority (2)

4. Traffic Management Rule

Description: Identifies when a driver might encounter traffic after a pit stop, suggesting adjustments to the pit window.

Implementation: The rule checks if:

  • Car is running in a position behind 10th
  • Gap to the leader is more than 30 seconds
  • Current lap is within a valid strategic window

Response: Recommends "adjust_pit_window" action with moderate confidence (0.7) and lower priority (1)

Strategic Windows and Thresholds

The gap analysis system uses carefully defined thresholds based on F1 strategic principles and empirical data. These thresholds determine when various strategies become viable:

Strategy Gap Range Consistency Required Confidence Priority
Undercut < 2.0s ≥ 3 laps 0.85 2
Overcut 2.0-3.5s ≥ 4 laps 0.80 2
Defensive < 2.0s behind ≥ 3 laps 0.80 2
Traffic Management > 30s to leader N/A 0.70 1

Race Phase Consideration: The system also considers the race phase when evaluating strategies:

  • Early stint: Laps 6-26
  • Mid stint: Laps 27-48
  • Outside these ranges, certain strategies may be less effective

Integration with the Complete Strategy Engine

The gap analysis rules are integrated with other rule systems in the F1CompleteStrategyEngine. This integrated engine ensures that gap-based recommendations work harmoniously with recommendations from other systems.

Conflict Resolution

When conflicting recommendations arise from different rule systems, the F1CompleteStrategyEngine._resolve_conflicts() method resolves them based on:

  1. Priority level of recommendations
  2. Confidence scores
  3. Predefined conflict rules (e.g., can't extend stint and pit simultaneously)

For example, if the gap analysis suggests an undercut but tire degradation rules suggest extending the stint, the engine will select the recommendation with higher priority and confidence.

The engine also tracks which rule systems have been activated through the active_systems dictionary, which includes a key for 'gap' that is set to True when gap rules fire.

Data Flow and Transformation

The complete data flow for gap analysis, from raw timing data to strategic recommendations, follows this sequence:

The transform_all_facts() function in the rule merging module handles the conversion of various data sources into facts that can be processed by the rule engine:

  1. For gap data:

    • Ensures gap consistency is calculated
    • Transforms the data into a GapFact object
    • Handles missing or null values with sensible defaults
    • Integrates this with other facts from different systems

Example: Gap Analysis in Action

To illustrate how the gap analysis system works in practice, let's consider a racing scenario:

  1. Driver #44 (Hamilton) is running 2.0 seconds behind Driver #1 (Verstappen) for 4 consecutive laps

  2. The system calculates gap metrics through calculate_all_gaps()

  3. Gap consistency is tracked through calculate_gap_consistency()

  4. The GapFact is created with:

    • gap_ahead = 2.0
    • consistent_gap_ahead_laps = 4
    • car_ahead = 1

  5. The F1GapRules engine evaluates this fact

  6. The strategic_overcut rule triggers since the gap is 2.0 seconds and consistency is 4 laps

  7. A StrategyRecommendation for "perform_overcut" is generated

  8. This is evaluated alongside other system recommendations in the F1CompleteStrategyEngine

  9. After conflict resolution, final recommendations are presented

The system provides not just the recommendation but detailed explanations including the specific gap metrics that triggered the recommendation, giving the strategist insight into the reasoning.

Implementation Notes

When implementing or extending the Gap Analysis Rules system, consider these key aspects:

  1. Gap Thresholds: The current thresholds (e.g., 2.0s for undercut, 3.5s for overcut) are based on general F1 principles but may need adjustment for specific tracks or conditions.

  2. Consistency Requirements: Rules require multiple consecutive laps within a threshold to avoid reacting to momentary fluctuations. These consistency counts (3-4 laps) can be tuned based on track characteristics.

  3. Race Phase Consideration: Different strategies are appropriate at different race phases. The system currently defines early stint (laps 6-26) and mid stint (laps 27-48), which may need adjustment for races with different lap counts.

  4. Integration: When implementing new rules, ensure they're properly detected in the record_rule_fired() method of F1CompleteStrategyEngine to accurately track rule system activation.

On this page