Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 28 additions & 47 deletions docs/scenario_inputs.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,20 +105,34 @@ Planning aggressiveness defaults: `pi=1.5`, `stepped=1.2`, `interval-hold=1.0`,
- 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.
## YAML Scenario File Format

1. Scenario 1:
- Track: Shenandoah Raceway
- Strategy: fixed-speed sweep strategy comparison
YAML is used for scenario files to represent nested race,
weather, and strategy settings clearly, and for convenient editing.

```
scenario:
name: Shenandoah fixed-speed sweep
car_params: car_params.json
track: shenandoah_speedway
Each scenario file contains:

mode: sweep
| Field | Required | Description |
|---|---|---|
| `scenario.name` | Yes | Human-readable scenario name |
| `scenario.car_parameter_file` | Yes | Path to the car parameter JSON file |
| `scenario.course_file` | Yes | Path to the course/track definition file |
| `scenario.race.start_time_hour` | Yes | Local race start time, expressed as decimal hours |
| `scenario.race.end_time_hour` | Yes | Local race end time, expressed as decimal hours |
| `scenario.race.start_soc` | Yes | Initial battery state of charge from `0.0` to `1.0` |
| `scenario.weather.source` | Yes | `synthetic` for offline weather or `api` for Open-Meteo |
| `scenario.weather.random_seed` | No | Seed for reproducible synthetic weather |
| `scenario.strategy.name` | Yes | `fixed`, `pi`, `stepped`, or `interval-hold` |
| `scenario.strategy.fixed_speed_mps` | For `fixed` | Constant target speed in metres per second |
| `scenario.strategy.aggressiveness` | No | Controller response strength |

The example below uses synthetic (offline) weather and the `fixed` strategy with a constant speed. More examples are in `scenarios_examples/`

```yaml
scenario:
name: Shenandoah offline constant-speed planning
car_parameter_file: car_params.json
course_file: courses/shenandoah_speedway.json

race:
start_time_hour: 10.0
Expand All @@ -128,47 +142,14 @@ scenario:
min_soc: 0.10

weather:
source: api
source: synthetic
random_seed: 7

strategy:
name: fixed
fixed_speed_mps: 15.0
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
```
23 changes: 23 additions & 0 deletions docs/scenarios_examples/brainerd-api-stepped-aggressive.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
scenario:
name: Brainerd API forecast aggressive stepped run
car_parameter_file: car_params.json
course_file: courses/brainerd_international_raceway.json

race:
start_time_hour: 9.0
end_time_hour: 17.0
start_soc: 1.0
target_soc: 0.10
min_soc: 0.10

weather:
source: api

strategy:
name: stepped
aggressiveness: 1.4
min_speed_mps: 4.0
max_speed_mps: 35.0

simulation:
time_step_minutes: 1.0
31 changes: 31 additions & 0 deletions docs/scenarios_examples/brainerd-api-strategy-comparison.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
scenario:
name: Brainerd API strategy comparison
car_parameter_file: car_params.json
course_file: courses/brainerd_international_raceway.json

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

planning:
enabled: true
strategies: [pi, stepped, interval-hold, fixed]
aggressiveness_by_strategy:
pi: 1.5
stepped: 1.2
interval-hold: 1.0
fixed: 1.0

strategy:
name: fixed
fixed_speed_mps: 15.0
aggressiveness: 1.0

simulation:
time_step_minutes: 1.0
24 changes: 24 additions & 0 deletions docs/scenarios_examples/shenandoah-synthetic-interval-hold.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
scenario:
name: Shenandoah offline interval-hold endurance run
car_parameter_file: car_params.json
course_file: courses/shenandoah_speedway.json

race:
start_time_hour: 10.0
end_time_hour: 18.0
start_soc: 0.95
target_soc: 0.20
min_soc: 0.10

weather:
source: synthetic
random_seed: 21

strategy:
name: interval-hold
aggressiveness: 0.8
min_speed_mps: 4.0
max_speed_mps: 32.0

simulation:
time_step_minutes: 1.0
23 changes: 23 additions & 0 deletions docs/scenarios_examples/vir-api-pi-conservative.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
scenario:
name: VIR API forecast conservative PI run
car_parameter_file: car_params.json
course_file: courses/virginia_international_raceway.json

race:
start_time_hour: 10.0
end_time_hour: 18.0
start_soc: 1.0
target_soc: 0.15
min_soc: 0.10

weather:
source: api

strategy:
name: pi
aggressiveness: 0.9
min_speed_mps: 4.0
max_speed_mps: 30.0

simulation:
time_step_minutes: 1.0
23 changes: 23 additions & 0 deletions docs/scenarios_examples/vir-synthetic-fixed-low-speed.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
scenario:
name: VIR offline low-speed energy-conservation run
car_parameter_file: car_params.json
course_file: courses/virginia_international_raceway.json

race:
start_time_hour: 11.0
end_time_hour: 17.0
start_soc: 0.80
target_soc: 0.20
min_soc: 0.10

weather:
source: synthetic
random_seed: 4

strategy:
name: fixed
fixed_speed_mps: 12.0
aggressiveness: 1.0

simulation:
time_step_minutes: 1.0
Loading