# aise-cps-research/teach-to-crash-paper-package architecture

> Architecture diagram of the GitHub repository aise-cps-research/teach-to-crash-paper-package, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aise-cps-research/teach-to-crash-paper-package
- Repository: https://github.com/aise-cps-research/teach-to-crash-paper-package

## Overview

This repository is a CARLA-based research harness for generating, mutating, executing, and evaluating safety-critical driving scenarios. The main workflow iteratively asks a Student/Teacher LLM pair for scenario changes, runs them in CARLA, and records safety outcomes; separate batch-search and ChatScene-to-PAFOT paths provide non-LLM search and prompt-driven scenario generation. The README documents the major flows and shared modules; sampled source is partial, so some internal links are omitted where ownership is not established.

Main entry points: [`teach_to_crash.py`](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/teach_to_crash.py) (Teach-to-Crash Loop), [`tests.py`](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/tests.py) (Batch Search Runner), [`chatscene_replication/run_chatscene_scenarios.py`](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/chatscene_replication/run_chatscene_scenarios.py) (ChatScene Replay), [`chatscene_replication/generate_scenarios_chatscene.py`](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/chatscene_replication/generate_scenarios_chatscene.py) (PAFOT Conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_search["LLM Scenario Search"]
  node_teach["Teach-to-Crash Loop<br/>[teach_to_crash.py]"]
  node_scenario["Scenario Candidates"]
end

subgraph group_sim["Simulation and Metrics"]
  node_ego["Ego Vehicle<br/>[ego.py]"]
  node_liability["Safety Evaluation<br/>[liability.py]"]
  node_utility["Simulation Utilities<br/>[utility.py]"]
  node_replay["Single Scenario Replay<br/>[run_scenario.py]"]
  node_results["Run Results"]
end

subgraph group_batch["Batch PAFOT Search"]
  node_batch_tests["Batch Search Runner<br/>[tests.py]"]
  node_mutator["Genetic Mutator<br/>[mutator.py]"]
end

subgraph group_chat["ChatScene Replication"]
  node_description_gen["Prompt Generation"]
  node_scenario_gen["PAFOT Conversion"]
  node_pafot["Bundled PAFOT"]
  node_chat_replay["ChatScene Replay"]
end

subgraph group_runtime["API and Navigation"]
  node_api["Student/Teacher API"]
  node_agents["Driving Agents<br/>[basic_agent.py]"]
  node_controller["PID Control<br/>[controller.py]"]
end

node_researcher(("Researcher"))
node_openai["OpenAI Models"]
node_carla["CARLA Simulator"]
node_chatscene["ChatScene"]

node_researcher -->|"starts loop"| node_teach
node_teach -->|"requests prompts"| node_api
node_api -->|"forwards prompts"| node_openai
node_openai -->|"returns responses"| node_api
node_api -->|"returns guidance"| node_teach
node_teach -->|"generates candidates"| node_scenario
node_teach -->|"runs scenarios"| node_carla
node_teach -->|"evaluates safety"| node_liability
node_teach -->|"controls ego"| node_ego
node_teach -->|"records metrics"| node_results
node_researcher -->|"starts search"| node_batch_tests
node_batch_tests -->|"mutates candidates"| node_mutator
node_batch_tests -->|"evaluates scenarios"| node_liability
node_batch_tests -->|"simulates scenarios"| node_carla
node_batch_tests -->|"writes results"| node_results
node_researcher -->|"starts replay"| node_replay
node_replay -->|"runs scenario"| node_carla
node_replay -->|"measures safety"| node_liability
node_description_gen -->|"requests descriptions"| node_chatscene
node_chatscene -->|"returns prompts"| node_description_gen
node_description_gen -->|"provides descriptions"| node_scenario_gen
node_scenario_gen -->|"requests plans"| node_chatscene
node_chatscene -->|"returns plans"| node_scenario_gen
node_scenario_gen -->|"formats scenarios"| node_pafot
node_researcher -->|"starts replay"| node_chat_replay
node_chat_replay -->|"loads scenarios"| node_pafot
node_chat_replay -->|"runs scenarios"| node_carla
node_chat_replay -->|"measures safety"| node_liability
node_agents -->|"computes control"| node_controller
node_controller -->|"applies vehicle control"| node_carla

click node_teach "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/teach_to_crash.py"
click node_api "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/student_teacher_api.py"
click node_ego "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/ego.py"
click node_agents "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/agents/navigation/basic_agent.py"
click node_controller "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/agents/navigation/controller.py"
click node_liability "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/liability.py"
click node_utility "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/utility.py"
click node_batch_tests "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/tests.py"
click node_mutator "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/mutator.py"
click node_replay "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/run_scenario.py"
click node_description_gen "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/chatscene_replication/generate_chatscene_descriptions.py"
click node_scenario_gen "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/chatscene_replication/generate_scenarios_chatscene.py"
click node_pafot "https://github.com/aise-cps-research/teach-to-crash-paper-package/tree/main/chatscene_replication/pafot"
click node_chat_replay "https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/chatscene_replication/run_chatscene_scenarios.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_teach,node_scenario toneBlue
class node_ego,node_liability,node_utility,node_replay,node_results toneAmber
class node_batch_tests,node_mutator toneMint
class node_description_gen,node_scenario_gen,node_pafot,node_chat_replay toneRose
class node_api,node_agents,node_controller,node_researcher,node_openai,node_carla,node_chatscene toneIndigo
```

## Components

### LLM Scenario Search

- [Teach-to-Crash Loop](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/teach_to_crash.py): `teach_to_crash.py`
- **Scenario Candidates**

### Simulation and Metrics

- [Ego Vehicle](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/ego.py): `ego.py`
- [Safety Evaluation](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/liability.py): `liability.py`
- [Simulation Utilities](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/utility.py): `utility.py`
- [Single Scenario Replay](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/run_scenario.py): `run_scenario.py`
- **Run Results**

### Batch PAFOT Search

- [Batch Search Runner](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/tests.py): `tests.py`
- [Genetic Mutator](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/mutator.py): `mutator.py`

### ChatScene Replication

- [Prompt Generation](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/chatscene_replication/generate_chatscene_descriptions.py): `chatscene_replication/generate_chatscene_descriptions.py`
- [PAFOT Conversion](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/chatscene_replication/generate_scenarios_chatscene.py): `chatscene_replication/generate_scenarios_chatscene.py`
- [Bundled PAFOT](https://github.com/aise-cps-research/teach-to-crash-paper-package/tree/main/chatscene_replication/pafot): `chatscene_replication/pafot`
- [ChatScene Replay](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/chatscene_replication/run_chatscene_scenarios.py): `chatscene_replication/run_chatscene_scenarios.py`

### API and Navigation

- [Student/Teacher API](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/student_teacher_api.py): `student_teacher_api.py`
- [Driving Agents](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/agents/navigation/basic_agent.py): `agents/navigation/basic_agent.py`
- [PID Control](https://github.com/aise-cps-research/teach-to-crash-paper-package/blob/main/agents/navigation/controller.py): `agents/navigation/controller.py`

### Other components

- **Researcher**
- **OpenAI Models**
- **CARLA Simulator**
- **ChatScene**

## Connections

- Researcher → Teach-to-Crash Loop: starts loop
- Teach-to-Crash Loop → Student/Teacher API: requests prompts
- Student/Teacher API → OpenAI Models: forwards prompts
- OpenAI Models → Student/Teacher API: returns responses
- Student/Teacher API → Teach-to-Crash Loop: returns guidance
- Teach-to-Crash Loop → Scenario Candidates: generates candidates
- Teach-to-Crash Loop → CARLA Simulator: runs scenarios
- Teach-to-Crash Loop → Safety Evaluation: evaluates safety
- Teach-to-Crash Loop → Ego Vehicle: controls ego
- Teach-to-Crash Loop → Run Results: records metrics
- Researcher → Batch Search Runner: starts search
- Batch Search Runner → Genetic Mutator: mutates candidates
- Batch Search Runner → Safety Evaluation: evaluates scenarios
- Batch Search Runner → CARLA Simulator: simulates scenarios
- Batch Search Runner → Run Results: writes results
- Researcher → Single Scenario Replay: starts replay
- Single Scenario Replay → CARLA Simulator: runs scenario
- Single Scenario Replay → Safety Evaluation: measures safety
- Prompt Generation → ChatScene: requests descriptions
- ChatScene → Prompt Generation: returns prompts
- Prompt Generation → PAFOT Conversion: provides descriptions
- PAFOT Conversion → ChatScene: requests plans
- ChatScene → PAFOT Conversion: returns plans
- PAFOT Conversion → Bundled PAFOT: formats scenarios
- Researcher → ChatScene Replay: starts replay
- ChatScene Replay → Bundled PAFOT: loads scenarios
- ChatScene Replay → CARLA Simulator: runs scenarios
- ChatScene Replay → Safety Evaluation: measures safety
- Driving Agents → PID Control: computes control
- PID Control → CARLA Simulator: applies vehicle control