From cb9560a4df6c9d9ac292fee210afd4253b50b313 Mon Sep 17 00:00:00 2001
From: ria5ingh <160563896+ria5ingh@users.noreply.github.com>
Date: Sun, 20 Sep 2026 15:24:00 -0400
Subject: [PATCH 1/6] updating location selection in file path and args

---
 sim/config.py |  4 ++++
 sim/main.py   | 40 ++++++++++++++++++++++------------------
 2 files changed, 26 insertions(+), 18 deletions(-)

diff --git a/sim/config.py b/sim/config.py
index c93f582..3c2c737 100644
--- a/sim/config.py
+++ b/sim/config.py
@@ -8,6 +8,7 @@
 @dataclass
 class TrackConfig:
     name: str
+    file_path_name: str
     location: str
     latitude: float
     longitude: float
@@ -143,6 +144,7 @@ def get_available_tracks() -> List[TrackConfig]:
     return [
         TrackConfig(
             name="Shenandoah Speedway",
+            file_path_name="shenandoah_speedway",
             location="Page County, Virginia",
             latitude=38.5110,
             longitude=-78.6359,
@@ -151,6 +153,7 @@ def get_available_tracks() -> List[TrackConfig]:
         ),
         TrackConfig(
             name= "Virginia International Raceway (Patriot Course)",
+            file_path_name="virginia_international_raceway", 
             location="Alton, Virginia",
             latitude=36.5666,
             longitude=-79.2058,
@@ -159,6 +162,7 @@ def get_available_tracks() -> List[TrackConfig]:
         ),
         TrackConfig(
             name= "Brainerd International Raceway (Donnybrooke Course)",
+            file_path_name="brainerd_international_raceway",
             location="Brainerd, Minnesota",
             latitude=46.4176,
             longitude=-94.2853,
diff --git a/sim/main.py b/sim/main.py
index c6c0d00..aff101a 100644
--- a/sim/main.py
+++ b/sim/main.py
@@ -24,8 +24,8 @@ def parse_args():
     parser = argparse.ArgumentParser(description="Modular laps race simulator")
     parser.add_argument(
         "--location",
-        choices=["shenandoah"],
-        default="shenandoah",
+        choices=["shenandoah_speedway", "virginia_international_raceway", "brainerd_international_raceway"],
+        default=None,
         help="Race location selection (currently only Shenandoah)",
     )
     parser.add_argument(
@@ -126,22 +126,26 @@ def main():
         car = CarConfig()
         print("Using default car parameters")
 
-    print("Choose a track to test on:")
-    for i in range(len(tracks)):
-        print(f"({i+1}) {tracks[i].name}")
-    num = 1
-    while True:
-        inp = input()
-        if inp.isdigit():
-            num = int(inp)
-            if num <= 0 or num > len(tracks):
-                print("Invalid int")
-            else:
+    if args.location is not None:
+        track = next(track for track in tracks
+        if track.file_path_name == args.location)
+    else:
+        print("Choose a track to test on:")
+        for i, available_track in enumerate(tracks, start=1):
+            print(f"({i}) {available_track.name}")
+
+        num = 1
+        while True:
+            inp = input()
+            if inp.isdigit():
+                num = int(inp)
+                if num <= 0 or num > len(tracks):
+                    print("Invalid int")
+                else:
+                    break
+            elif inp == "":
                 break
-        elif inp == "":
-            break
-
-    track = tracks[num-1]
+        track = tracks[num-1]
 
     if args.plan:
         base_race = RaceConfig(
@@ -231,7 +235,7 @@ def main():
     reporter.print_summary()
 
     output_dir = os.path.join("plots", "laps_modular")
-    prefix = f"shenandoah_{selected_strategy}"
+    prefix = f"{track.file_path_name}_{selected_strategy}"
     plotter = SimulationPlotter(results, track)
     saved = save_all_plots(plotter, output_dir, prefix)
 

From 82365f92545364fa8e01e8ffa4a8d6807d775513 Mon Sep 17 00:00:00 2001
From: ria5ingh <160563896+ria5ingh@users.noreply.github.com>
Date: Sun, 20 Sep 2026 15:55:13 -0400
Subject: [PATCH 2/6] adding initial scenario inputs documentation (GOING TO
 EDIT)

---
 docs/scenario_inputs.md | 255 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 255 insertions(+)
 create mode 100644 docs/scenario_inputs.md

diff --git a/docs/scenario_inputs.md b/docs/scenario_inputs.md
new file mode 100644
index 0000000..b26fdca
--- /dev/null
+++ b/docs/scenario_inputs.md
@@ -0,0 +1,255 @@
+# Pre-Race Simulation Scenario Inputs
+
+This document defines the inputs needed to run a pre-race simulation and planning study.
+
+## Required Inputs
+
+### Car Parameter File
+
+**Source:** `Simulator/car_params.json`
+
+The car parameter file is loaded through `CarConfig.from_json()` in `sim/config.py`.
+
+The file may define:
+
+- `mass`: Vehicle mass in kilograms.
+- `battery_capacity`: Battery capacity in watt-hours.
+- `solar_panel_area`: Solar panel area in square meters.
+- `solar_panel_efficiency`: Solar conversion efficiency.
+- `electrical_efficiency`: Electrical drivetrain efficiency.
+- `C_dA`: Aerodynamic drag-area coefficient.
+- `tire_pressure`: Tire pressure used to estimate rolling resistance.
+- `regen_efficiency`: Regenerative braking efficiency.
+- `rho`: Air density.
+- `g`: Gravitational acceleration.
+
+These values affect energy consumption, solar generation, regenerative braking, achievable speed, final state of charge (SOC), and total laps.
+
+If the file is missing, the simulator uses the default `CarConfig` values. For reproducible planning results, provide an explicit car parameter file.
+
+### Tracks
+
+**Source:** `TrackConfig` in `sim/config.py`
+
+A course requires:
+
+- `name`: Human-readable course name.
+- `file_path_name`: Filename-safe identifier for output files.
+- `location`: Human-readable geographic location.
+- `latitude` and `longitude`: Coordinates used for weather data.
+- `lap_distance_km`: Course lap length.
+- `timezone`: Local timezone used for weather timestamps.
+
+The selected course affects:
+
+- Weather retrieved from the Open-Meteo API.
+- Solar energy available during the race.
+- Distance accumulated per lap.
+- Report and plot labels.
+- Output filenames.
+
+The CLI supports these course identifiers:
+
+- `shenandoah_speedway`
+- `virginia_international_raceway`
+- `brainerd_international_raceway`
+
+A course can be selected interactively or with `--location`.
+
+### Race Start and End Time
+
+**Configuration:** `RaceConfig.start_time_hour` and `RaceConfig.end_time_hour`
+
+The default race window is:
+
+- Start: `10.0` local hours
+- End: `18.0` local hours
+
+The race window determines:
+
+- How many simulation timesteps are generated.
+- Which weather interval is selected.
+- How much sunlight is available.
+- The total time available to complete laps.
+
+The Open-Meteo weather path requires complete weather coverage for the selected time window.
+
+### Initial SOC
+
+**Configuration:** `RaceConfig.start_soc`
+
+The default is `1.0`, representing 100% battery charge.
+
+Initial SOC determines the energy available at race start. A lower initial SOC generally reduces achievable speed and total distance and increases the likelihood of reaching the minimum SOC threshold early.
+
+### Weather Assumptions
+
+Weather is controlled by `LapsRaceSimulator` and `WeatherService` in `sim/weather.py`.
+
+By default, the simulator attempts to retrieve:
+
+- Shortwave solar radiation, used as GHI.
+- Cloud cover.
+
+Weather is requested using the selected course's coordinates and timezone.
+
+If the API request fails, the simulator falls back to synthetic weather. Synthetic weather uses a daylight-shaped solar curve and randomized cloud cover.
+
+Set `use_api_weather=False` when deterministic synthetic weather is preferred, such as for repeatable tests. Planning sweeps also support a synthetic weather seed.
+
+Weather affects:
+
+- Solar charging.
+- The ideal SOC trajectory.
+- The calculated feasible baseline speed.
+- Controller speed adjustments.
+- Final SOC and total laps.
+
+## Optional Inputs
+
+### Target and Minimum SOC
+
+**Configuration:** `RaceConfig.target_soc` and `RaceConfig.min_soc`
+
+Defaults:
+
+- Target SOC: `0.10`
+- Minimum SOC: `0.10`
+
+`target_soc` is the planned ending SOC used when calculating the energy budget and ideal SOC trajectory.
+
+`min_soc` is the operational lower bound. If the vehicle reaches it, the simulation stops early and records when it happened.
+
+### Strategy
+
+**Configuration:** `RaceConfig.strategy`
+
+Available strategies:
+
+- `pi`: Continuous proportional-integral SOC feedback.
+- `stepped`: Discrete speed changes based on SOC error.
+- `interval-hold`: Recomputes a feasible speed periodically and holds it between updates.
+- `fixed`: Maintains a configured fixed speed.
+
+The strategy affects how speed responds to SOC and weather conditions.
+
+### Aggressiveness
+
+**Configuration:** `RaceConfig.aggressiveness`
+
+Aggressiveness controls the size of controller responses. Higher values generally produce stronger speed changes when SOC differs from its target trajectory.
+
+Default planning values are defined in `sim/planning/sweep.py`:
+
+- `pi`: `1.5`
+- `stepped`: `1.2`
+- `interval-hold`: `1.0`
+- `fixed`: `1.0`
+
+### Energy Safety Scale
+
+**Configuration:** `RaceConfig.energy_safety_scale`
+
+Default: `1.0`
+
+This scales the calculated energy budget. Lower values reserve more energy and produce a more conservative speed plan.
+
+Values are constrained to the range `0.01` through `1.0`.
+
+### Speed Limits and Initial Speed
+
+**Configuration:** `RaceConfig`
+
+Optional speed settings include:
+
+- `initial_speed_mps`
+- `fixed_speed_mps`
+- `min_speed_mps`
+- `max_speed_mps`
+
+The minimum and maximum speeds constrain controller output. `fixed_speed_mps` is used by the fixed-speed strategy and fixed-speed planning sweep.
+
+### Simulation Timestep
+
+**Configuration:** `RaceConfig.time_step_minutes`
+
+Default: `1.0` minute.
+
+A smaller timestep provides more frequent controller updates and finer timing resolution but requires more simulation steps.
+
+## Expected Planning Outputs
+
+The planning study in `sim/planning/sweep.py` produces two comparisons:
+
+1. A fixed-speed sweep across configured speeds.
+2. A strategy sweep across the available strategies.
+
+Each planning result includes:
+
+- Strategy or fixed speed.
+- Total laps.
+- Total distance in miles.
+- Final SOC percentage.
+- Minimum SOC percentage.
+- Average speed.
+- Maximum and minimum speed.
+- Whether the full race window was completed.
+- Whether the simulation reached minimum SOC early.
+
+The planning report in `sim/planning/report.py` summarizes:
+
+- Best fixed speed.
+- Strategy comparison.
+- Whether each strategy completed the race or reached minimum SOC.
+- A recommended speed or strategy.
+
+A normal simulation also produces:
+
+- SOC plot.
+- Speed plot.
+- Weather plot.
+- Race dashboard.
+- Text summary of race performance.
+
+## Example Scenario
+
+```text
+Course:
+  Virginia International Raceway (Patriot Course)
+  Identifier: virginia_international_raceway
+  Lap distance: 1.77 km
+  Timezone: America/New_York
+
+Car:
+  Load parameters from car_params.json
+
+Race window:
+  Start: 10:00 local time
+  End: 18:00 local time
+
+Battery:
+  Initial SOC: 100%
+  Target SOC: 10%
+  Minimum SOC: 10%
+
+Weather:
+  Use Open-Meteo forecast data
+  Fall back to synthetic weather if the API is unavailable
+
+Strategy:
+  interval-hold
+  Aggressiveness: 1.0
+  Energy safety scale: 1.0
+  Timestep: 1 minute
+
+Planning study:
+  Run the fixed-speed sweep
+  Compare pi, stepped, interval-hold, and fixed strategies
+
+Expected outputs:
+  Best fixed speed
+  Strategy comparison
+  Recommended strategy
+  Expected laps
+  Final SOC
+  Whether the full eight-hour window is completed
\ No newline at end of file

From 1698eec4109afc1727931eeeaeb75b6d2abf2628 Mon Sep 17 00:00:00 2001
From: ria5ingh <160563896+ria5ingh@users.noreply.github.com>
Date: Sun, 20 Sep 2026 15:57:48 -0400
Subject: [PATCH 3/6] adding scenario inputs documentation (GOING TO EDIT)

---
 docs/scenario_inputs.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/scenario_inputs.md b/docs/scenario_inputs.md
index b26fdca..821af14 100644
--- a/docs/scenario_inputs.md
+++ b/docs/scenario_inputs.md
@@ -211,6 +211,8 @@ A normal simulation also produces:
 - Race dashboard.
 - Text summary of race performance.
 
+
+
 ## Example Scenario
 
 ```text

From 5510d36dfb9eb9920e7292a6f8052996aec3d2ef Mon Sep 17 00:00:00 2001
From: ria5ingh <160563896+ria5ingh@users.noreply.github.com>
Date: Sun, 27 Sep 2026 15:36:54 -0400
Subject: [PATCH 4/6] updating the scenario inputs md

---
 docs/scenario_inputs.md | 354 ++++++++++++----------------------------
 1 file changed, 102 insertions(+), 252 deletions(-)

diff --git a/docs/scenario_inputs.md b/docs/scenario_inputs.md
index 821af14..cc60e71 100644
--- a/docs/scenario_inputs.md
+++ b/docs/scenario_inputs.md
@@ -1,257 +1,107 @@
 # Pre-Race Simulation Scenario Inputs
 
-This document defines the inputs needed to run a pre-race simulation and planning study.
-
-## Required Inputs
-
-### Car Parameter File
-
-**Source:** `Simulator/car_params.json`
-
-The car parameter file is loaded through `CarConfig.from_json()` in `sim/config.py`.
-
-The file may define:
-
-- `mass`: Vehicle mass in kilograms.
-- `battery_capacity`: Battery capacity in watt-hours.
-- `solar_panel_area`: Solar panel area in square meters.
-- `solar_panel_efficiency`: Solar conversion efficiency.
-- `electrical_efficiency`: Electrical drivetrain efficiency.
-- `C_dA`: Aerodynamic drag-area coefficient.
-- `tire_pressure`: Tire pressure used to estimate rolling resistance.
-- `regen_efficiency`: Regenerative braking efficiency.
-- `rho`: Air density.
-- `g`: Gravitational acceleration.
-
-These values affect energy consumption, solar generation, regenerative braking, achievable speed, final state of charge (SOC), and total laps.
-
-If the file is missing, the simulator uses the default `CarConfig` values. For reproducible planning results, provide an explicit car parameter file.
-
-### Tracks
-
-**Source:** `TrackConfig` in `sim/config.py`
-
-A course requires:
-
-- `name`: Human-readable course name.
-- `file_path_name`: Filename-safe identifier for output files.
-- `location`: Human-readable geographic location.
-- `latitude` and `longitude`: Coordinates used for weather data.
-- `lap_distance_km`: Course lap length.
-- `timezone`: Local timezone used for weather timestamps.
-
-The selected course affects:
-
-- Weather retrieved from the Open-Meteo API.
-- Solar energy available during the race.
-- Distance accumulated per lap.
-- Report and plot labels.
-- Output filenames.
-
-The CLI supports these course identifiers:
-
-- `shenandoah_speedway`
-- `virginia_international_raceway`
-- `brainerd_international_raceway`
-
-A course can be selected interactively or with `--location`.
-
-### Race Start and End Time
-
-**Configuration:** `RaceConfig.start_time_hour` and `RaceConfig.end_time_hour`
-
-The default race window is:
-
-- Start: `10.0` local hours
-- End: `18.0` local hours
-
-The race window determines:
-
-- How many simulation timesteps are generated.
-- Which weather interval is selected.
-- How much sunlight is available.
-- The total time available to complete laps.
-
-The Open-Meteo weather path requires complete weather coverage for the selected time window.
-
-### Initial SOC
-
-**Configuration:** `RaceConfig.start_soc`
-
-The default is `1.0`, representing 100% battery charge.
-
-Initial SOC determines the energy available at race start. A lower initial SOC generally reduces achievable speed and total distance and increases the likelihood of reaching the minimum SOC threshold early.
-
-### Weather Assumptions
-
-Weather is controlled by `LapsRaceSimulator` and `WeatherService` in `sim/weather.py`.
-
-By default, the simulator attempts to retrieve:
-
-- Shortwave solar radiation, used as GHI.
-- Cloud cover.
-
-Weather is requested using the selected course's coordinates and timezone.
-
-If the API request fails, the simulator falls back to synthetic weather. Synthetic weather uses a daylight-shaped solar curve and randomized cloud cover.
-
-Set `use_api_weather=False` when deterministic synthetic weather is preferred, such as for repeatable tests. Planning sweeps also support a synthetic weather seed.
-
-Weather affects:
-
-- Solar charging.
-- The ideal SOC trajectory.
-- The calculated feasible baseline speed.
-- Controller speed adjustments.
-- Final SOC and total laps.
-
-## Optional Inputs
-
-### Target and Minimum SOC
-
-**Configuration:** `RaceConfig.target_soc` and `RaceConfig.min_soc`
-
-Defaults:
-
-- Target SOC: `0.10`
-- Minimum SOC: `0.10`
-
-`target_soc` is the planned ending SOC used when calculating the energy budget and ideal SOC trajectory.
-
-`min_soc` is the operational lower bound. If the vehicle reaches it, the simulation stops early and records when it happened.
-
-### Strategy
-
-**Configuration:** `RaceConfig.strategy`
-
-Available strategies:
-
-- `pi`: Continuous proportional-integral SOC feedback.
-- `stepped`: Discrete speed changes based on SOC error.
-- `interval-hold`: Recomputes a feasible speed periodically and holds it between updates.
-- `fixed`: Maintains a configured fixed speed.
-
-The strategy affects how speed responds to SOC and weather conditions.
-
-### Aggressiveness
-
-**Configuration:** `RaceConfig.aggressiveness`
-
-Aggressiveness controls the size of controller responses. Higher values generally produce stronger speed changes when SOC differs from its target trajectory.
-
-Default planning values are defined in `sim/planning/sweep.py`:
-
-- `pi`: `1.5`
-- `stepped`: `1.2`
-- `interval-hold`: `1.0`
-- `fixed`: `1.0`
-
-### Energy Safety Scale
-
-**Configuration:** `RaceConfig.energy_safety_scale`
-
-Default: `1.0`
-
-This scales the calculated energy budget. Lower values reserve more energy and produce a more conservative speed plan.
-
-Values are constrained to the range `0.01` through `1.0`.
-
-### Speed Limits and Initial Speed
-
-**Configuration:** `RaceConfig`
-
-Optional speed settings include:
-
-- `initial_speed_mps`
-- `fixed_speed_mps`
-- `min_speed_mps`
-- `max_speed_mps`
-
-The minimum and maximum speeds constrain controller output. `fixed_speed_mps` is used by the fixed-speed strategy and fixed-speed planning sweep.
-
-### Simulation Timestep
-
-**Configuration:** `RaceConfig.time_step_minutes`
-
-Default: `1.0` minute.
-
-A smaller timestep provides more frequent controller updates and finer timing resolution but requires more simulation steps.
+This document separates inputs provided by a user from the configuration parameters that define a scenario.
+
+## User-Defined Inputs
+
+| User input | How it is provided | Maps to |
+|---|---|---|
+| Car parameters | `car_params.json` | `CarConfig` |
+| Track | `--location` or prompt | `TrackConfig` |
+| Strategy | `--strategy` or prompt | `RaceConfig.strategy` |
+| Aggressiveness | `--aggressiveness` | `RaceConfig.aggressiveness` |
+| Energy safety scale | Interactive prompt | `RaceConfig.energy_safety_scale` |
+| Fixed-speed sweep | `--speed-sweep` | Planning settings |
+| Planning study | `--plan` | Planning settings |
+| Weather source | Currently set in code | Weather settings |
+| Race times, SOC, speed limits, timestep | Currently set in code | `RaceConfig` |
+
+*For Car Parameters, the program automatically searches in `car_params.json` in the project root and pulls the configs from there.*
+## Config/Scenario Parameters
+
+These are the fields a future scenario configuration should contain. Values marked optional can use the listed default.
+
+### Car Configuration
+
+Source: `car_params.json`
+
+| Parameter | Units | Required | Affects |
+|---|---:|---|---|
+| `mass` | kg | Yes | Rolling resistance, regenerative energy, total energy use |
+| `battery_capacity` | Wh | Yes | Available battery energy and SOC changes |
+| `solar_panel_area` | m² | Yes | Solar power collected |
+| `solar_panel_efficiency` | fraction | Yes | Solar power collected |
+| `electrical_efficiency` | fraction | Yes | Driving power consumption |
+| `C_dA` | m² | Yes | Aerodynamic drag and speed energy use |
+| `tire_pressure` | pressure units | Yes | Rolling resistance and energy use |
+| `regen_efficiency` | fraction | Yes | Energy recovered during deceleration |
+| `rho` | kg/m³ | Yes | Aerodynamic drag |
+| `g` | m/s² | Yes | Rolling resistance |
+
+### Track Configuration
+
+| Parameter | Units | Required | Affects |
+|---|---:|---|---|
+| `name` | text | Yes | Report and plot labels |
+| `file_path_name` | text | Yes | Track identifier and output filenames |
+| `location` | text | Yes | Human-readable location |
+| `latitude`, `longitude` | degrees | Yes | Weather API location |
+| `lap_distance_km` | km | Yes | Distance and lap count |
+| `timezone` | IANA timezone | Yes | Local race and weather times |
+
+Available track IDs: `shenandoah_speedway`, `virginia_international_raceway`, `brainerd_international_raceway`.
+
+### Race and Battery Conditions
+
+| Parameter | Units | Required | Default | Affects |
+|---|---:|---|---:|---|
+| `start_time_hour` | local hour | Yes | `10.0` | Race duration and weather window |
+| `end_time_hour` | local hour | Yes | `18.0` | Race duration and weather window |
+| `start_soc` | fraction | Yes | `1.0` | Starting energy and achievable distance |
+| `target_soc` | fraction | No | `0.10` | Planned energy budget and SOC trajectory |
+| `min_soc` | fraction | No | `0.10` | Early-stop safety threshold |
+| `energy_safety_scale` | fraction | No | `1.0` | Energy reserve and conservatism |
+
+### Weather Configuration
+
+| Parameter | Type | Required | Default | Affects |
+|---|---|---|---|---|
+| `source` | `api` / `synthetic` / `file` | Yes | API | Weather data used |
+| `race_date` | date | No | Auto-selected | Forecast date |
+| `weather_file` | path | No | None | User-provided GHI and cloud data |
+| `random_seed` | integer | No | `7` in sweeps | Synthetic-weather repeatability |
+| `GHI`, `cloud_cover` | weather data | File source only | None | Solar charging and SOC trajectory |
+
+The current API uses Open-Meteo shortwave radiation and cloud cover. API failure falls back to synthetic weather.
+
+### Strategy and Speed
+
+| Parameter | Units / values | Required | Default | Affects |
+|---|---|---|---|---|
+| `strategy` | `pi`, `stepped`, `interval-hold`, `fixed` | Yes | `pi` | Speed response to SOC and weather |
+| `aggressiveness` | scalar | No | Strategy-specific | Controller response strength |
+| `fixed_speed_mps` | m/s | No | `15.0` | Fixed-strategy speed |
+| `min_speed_mps` | m/s | No | `4.0` | Lower speed limit |
+| `max_speed_mps` | m/s | No | `35.0` | Upper speed limit |
+| `initial_speed_mps` | m/s | No | `20.0` | Currently unused |
+
+Planning aggressiveness defaults: `pi=1.5`, `stepped=1.2`, `interval-hold=1.0`, `fixed=1.0`.
+
+### Simulation and Planning
+
+| Parameter | Type | Required | Default | Affects |
+|---|---|---|---|---|
+| `time_step_minutes` | minutes | No | `1.0` | Simulation resolution and update frequency |
+| `use_api_weather` | boolean | No | `True` | API versus synthetic weather |
+| `planning_enabled` | boolean | No | `False` | Single run versus planning study |
+| `strategies` | list | No | All strategies | Strategies compared |
+| `fixed_speed_values_mph` | list | No | `10`-`46`, step `2` | Speeds compared |
 
 ## Expected Planning Outputs
 
-The planning study in `sim/planning/sweep.py` produces two comparisons:
-
-1. A fixed-speed sweep across configured speeds.
-2. A strategy sweep across the available strategies.
-
-Each planning result includes:
-
-- Strategy or fixed speed.
-- Total laps.
-- Total distance in miles.
-- Final SOC percentage.
-- Minimum SOC percentage.
-- Average speed.
-- Maximum and minimum speed.
-- Whether the full race window was completed.
-- Whether the simulation reached minimum SOC early.
-
-The planning report in `sim/planning/report.py` summarizes:
-
-- Best fixed speed.
-- Strategy comparison.
-- Whether each strategy completed the race or reached minimum SOC.
-- A recommended speed or strategy.
-
-A normal simulation also produces:
-
-- SOC plot.
-- Speed plot.
-- Weather plot.
-- Race dashboard.
-- Text summary of race performance.
-
-
-
-## Example Scenario
-
-```text
-Course:
-  Virginia International Raceway (Patriot Course)
-  Identifier: virginia_international_raceway
-  Lap distance: 1.77 km
-  Timezone: America/New_York
-
-Car:
-  Load parameters from car_params.json
-
-Race window:
-  Start: 10:00 local time
-  End: 18:00 local time
-
-Battery:
-  Initial SOC: 100%
-  Target SOC: 10%
-  Minimum SOC: 10%
-
-Weather:
-  Use Open-Meteo forecast data
-  Fall back to synthetic weather if the API is unavailable
-
-Strategy:
-  interval-hold
-  Aggressiveness: 1.0
-  Energy safety scale: 1.0
-  Timestep: 1 minute
-
-Planning study:
-  Run the fixed-speed sweep
-  Compare pi, stepped, interval-hold, and fixed strategies
-
-Expected outputs:
-  Best fixed speed
-  Strategy comparison
-  Recommended strategy
-  Expected laps
-  Final SOC
-  Whether the full eight-hour window is completed
\ No newline at end of file
+- Best fixed speed and strategy recommendation
+- Total laps and distance
+- Final and minimum SOC
+- Average, minimum, and maximum speed
+- Full-window completion status
+- Time and laps when minimum SOC was reached

From 825b21cb7e8866567a975a0de36e0b7ce35e95eb Mon Sep 17 00:00:00 2001
From: ria5ingh <160563896+ria5ingh@users.noreply.github.com>
Date: Sun, 27 Sep 2026 15:42:12 -0400
Subject: [PATCH 5/6] updating the scenario inputs md

---
 docs/scenario_inputs.md | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/docs/scenario_inputs.md b/docs/scenario_inputs.md
index cc60e71..efb0907 100644
--- a/docs/scenario_inputs.md
+++ b/docs/scenario_inputs.md
@@ -27,14 +27,14 @@ Source: `car_params.json`
 
 | Parameter | Units | Required | Affects |
 |---|---:|---|---|
-| `mass` | kg | Yes | Rolling resistance, regenerative energy, total energy use |
-| `battery_capacity` | Wh | Yes | Available battery energy and SOC changes |
+| `mass` | kg | Yes | Rolling resistance, Regen energy, total energy use |
+| `battery_capacity` | Wh | Yes | Available battery energy, SOC changes |
 | `solar_panel_area` | m² | Yes | Solar power collected |
 | `solar_panel_efficiency` | fraction | Yes | Solar power collected |
 | `electrical_efficiency` | fraction | Yes | Driving power consumption |
-| `C_dA` | m² | Yes | Aerodynamic drag and speed energy use |
-| `tire_pressure` | pressure units | Yes | Rolling resistance and energy use |
-| `regen_efficiency` | fraction | Yes | Energy recovered during deceleration |
+| `C_dA` | m² | Yes | Aerodynamic drag, energy use |
+| `tire_pressure` | pressure units | Yes | Rolling resistance,  energy use |
+| `regen_efficiency` | fraction | Yes | Regen energy |
 | `rho` | kg/m³ | Yes | Aerodynamic drag |
 | `g` | m/s² | Yes | Rolling resistance |
 
@@ -55,12 +55,12 @@ Available track IDs: `shenandoah_speedway`, `virginia_international_raceway`, `b
 
 | Parameter | Units | Required | Default | Affects |
 |---|---:|---|---:|---|
-| `start_time_hour` | local hour | Yes | `10.0` | Race duration and weather window |
-| `end_time_hour` | local hour | Yes | `18.0` | Race duration and weather window |
-| `start_soc` | fraction | Yes | `1.0` | Starting energy and achievable distance |
-| `target_soc` | fraction | No | `0.10` | Planned energy budget and SOC trajectory |
+| `start_time_hour` | local hour | Yes | `10.0` | Race duration, weather window |
+| `end_time_hour` | local hour | Yes | `18.0` | Race duration, weather window |
+| `start_soc` | fraction | Yes | `1.0` | Starting energy, achievable distance |
+| `target_soc` | fraction | No | `0.10` | Planned energy budget, SOC trajectory |
 | `min_soc` | fraction | No | `0.10` | Early-stop safety threshold |
-| `energy_safety_scale` | fraction | No | `1.0` | Energy reserve and conservatism |
+| `energy_safety_scale` | fraction | No | `1.0` | Energy reserve |
 
 ### Weather Configuration
 
@@ -69,8 +69,8 @@ Available track IDs: `shenandoah_speedway`, `virginia_international_raceway`, `b
 | `source` | `api` / `synthetic` / `file` | Yes | API | Weather data used |
 | `race_date` | date | No | Auto-selected | Forecast date |
 | `weather_file` | path | No | None | User-provided GHI and cloud data |
-| `random_seed` | integer | No | `7` in sweeps | Synthetic-weather repeatability |
-| `GHI`, `cloud_cover` | weather data | File source only | None | Solar charging and SOC trajectory |
+| `random_seed` | integer | No | `7` in sweeps | Synthetic-weather generation |
+| `GHI`, `cloud_cover` | weather data | File source only | None | Solar charging, SOC trajectory |
 
 The current API uses Open-Meteo shortwave radiation and cloud cover. API failure falls back to synthetic weather.
 
@@ -78,12 +78,12 @@ The current API uses Open-Meteo shortwave radiation and cloud cover. API failure
 
 | Parameter | Units / values | Required | Default | Affects |
 |---|---|---|---|---|
-| `strategy` | `pi`, `stepped`, `interval-hold`, `fixed` | Yes | `pi` | Speed response to SOC and weather |
+| `strategy` | `pi`, `stepped`, `interval-hold`, `fixed` | Yes | `pi` | Speed strategy |
 | `aggressiveness` | scalar | No | Strategy-specific | Controller response strength |
 | `fixed_speed_mps` | m/s | No | `15.0` | Fixed-strategy speed |
 | `min_speed_mps` | m/s | No | `4.0` | Lower speed limit |
 | `max_speed_mps` | m/s | No | `35.0` | Upper speed limit |
-| `initial_speed_mps` | m/s | No | `20.0` | Currently unused |
+| `initial_speed_mps` | m/s | No | `20.0` | *Currently unused* |
 
 Planning aggressiveness defaults: `pi=1.5`, `stepped=1.2`, `interval-hold=1.0`, `fixed=1.0`.
 
@@ -91,8 +91,8 @@ Planning aggressiveness defaults: `pi=1.5`, `stepped=1.2`, `interval-hold=1.0`,
 
 | Parameter | Type | Required | Default | Affects |
 |---|---|---|---|---|
-| `time_step_minutes` | minutes | No | `1.0` | Simulation resolution and update frequency |
-| `use_api_weather` | boolean | No | `True` | API versus synthetic weather |
+| `time_step_minutes` | minutes | No | `1.0` | Simulation update frequency |
+| `use_api_weather` | boolean | No | `True` | Weather data source |
 | `planning_enabled` | boolean | No | `False` | Single run versus planning study |
 | `strategies` | list | No | All strategies | Strategies compared |
 | `fixed_speed_values_mph` | list | No | `10`-`46`, step `2` | Speeds compared |

From 2cd831e32babf08f77b7b305c46305085d29b422 Mon Sep 17 00:00:00 2001
From: ria5ingh <160563896+ria5ingh@users.noreply.github.com>
Date: Sun, 11 Oct 2026 15:07:46 -0400
Subject: [PATCH 6/6] adding the example scenarios

---
 docs/scenario_inputs.md | 73 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 70 insertions(+), 3 deletions(-)

diff --git a/docs/scenario_inputs.md b/docs/scenario_inputs.md
index efb0907..339633e 100644
--- a/docs/scenario_inputs.md
+++ b/docs/scenario_inputs.md
@@ -66,11 +66,10 @@ Available track IDs: `shenandoah_speedway`, `virginia_international_raceway`, `b
 
 | Parameter | Type | Required | Default | Affects |
 |---|---|---|---|---|
-| `source` | `api` / `synthetic` / `file` | Yes | API | Weather data used |
+| `source` | `api` / `synthetic` | Yes | API | Weather data used |
 | `race_date` | date | No | Auto-selected | Forecast date |
-| `weather_file` | path | No | None | User-provided GHI and cloud data |
 | `random_seed` | integer | No | `7` in sweeps | Synthetic-weather generation |
-| `GHI`, `cloud_cover` | weather data | File source only | None | Solar charging, SOC trajectory |
+| `GHI`, `cloud_cover` | weather data | Generated or API-provided | None | Solar charging, SOC trajectory |
 
 The current API uses Open-Meteo shortwave radiation and cloud cover. API failure falls back to synthetic weather.
 
@@ -105,3 +104,71 @@ Planning aggressiveness defaults: `pi=1.5`, `stepped=1.2`, `interval-hold=1.0`,
 - Average, minimum, and maximum speed
 - Full-window completion status
 - Time and laps when minimum SOC was reached
+
+### Example Scenario Outlines
+The following are examples of format files that can be implemented as YAML.
+
+1. Scenario 1: 
+    - Track: Shenandoah Raceway
+    - Strategy: fixed-speed sweep strategy comparison
+
+```
+scenario:
+  name: Shenandoah fixed-speed sweep
+  car_params: car_params.json
+  track: shenandoah_speedway
+
+  mode: sweep
+
+  race:
+    start_time_hour: 10.0
+    end_time_hour: 18.0
+    start_soc: 1.0
+    target_soc: 0.10
+    min_soc: 0.10
+
+  weather:
+    source: api
+
+  strategy:
+    name: fixed
+    aggressiveness: 1.0
+
+  planning:
+    fixed_speed_values_mph: [18, 22, 26, 30, 34, 38]
+
+  simulation:
+    time_step_minutes: 1.0
+```
+
+2. Scenario 2: 
+    - Track: Brainerd
+    - Strategy: PI with aggressiveness = 0.9.
+
+```
+scenario:
+  name: Brainerd PI controller run
+  car_params: car_params.json
+  track: brainerd_international_raceway
+
+  mode: strategy
+
+  race:
+    start_time_hour: 10.0
+    end_time_hour: 18.0
+    start_soc: 1.0
+    target_soc: 0.10
+    min_soc: 0.10
+
+  strategy:
+    name: pi
+    aggressiveness: 0.9
+    min_speed_mps: 4.0
+    max_speed_mps: 35.0
+
+  weather:
+    source: api
+
+  simulation:
+    time_step_minutes: 1.0
+```
\ No newline at end of file