# tudelft-cns-atm/bluesky-gym architecture

> Architecture diagram of the GitHub repository tudelft-cns-atm/bluesky-gym, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tudelft-cns-atm/bluesky-gym
- Repository: https://github.com/tudelft-cns-atm/bluesky-gym

## Overview

BlueSky-Gym is a Gymnasium-style library of reinforcement-learning environments for air-traffic-management scenarios, backed by the BlueSky simulator. The principal workflow is: a user registers and selects an environment, an agent repeatedly supplies actions through Gymnasium, and the environment advances the simulation and returns observations, rewards, and episode status. The repository also includes training-metric logging and optional wind and uncertainty wrappers. Several environment implementations and wrapper relationships were not excerpted, so their internal links are omitted rather than inferred.

Main entry points: [`bluesky_gym/envs/common/functions.py`](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/common/functions.py) (Navigation Geometry), [`bluesky_gym/envs/horizontal_cr_env.py`](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/horizontal_cr_env.py) (Horizontal Conflict), [`bluesky_gym/envs/merge_env.py`](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/merge_env.py) (Traffic Merge), [`bluesky_gym/envs/sector_cr_env.py`](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/sector_cr_env.py) (Sector Conflict)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Gymnasium API"]
  node_gym["Gymnasium"]
  node_registration["Environment Registration<br/>[__init__.py]"]
end

subgraph group_scenarios["Air Traffic Scenarios"]
  node_descent["Descent Scenario<br/>[descent_env.py]"]
  node_waypoint["Waypoint Planning"]
  node_horizontal["Horizontal Conflict"]
  node_vertical["Vertical Conflict<br/>[vertical_cr_env.py]"]
  node_merge["Traffic Merge<br/>[merge_env.py]"]
  node_sector["Sector Conflict<br/>[sector_cr_env.py]"]
  node_obstacle["Static Obstacles"]
end

subgraph group_shared["Shared Environment Logic"]
  node_geometry["Navigation Geometry<br/>[functions.py]"]
  node_polygons["Polygon Generation"]
  node_screen["Dummy Screen<br/>[screen_dummy.py]"]
  node_wind["Wind Wrapper<br/>[wind.py]"]
  node_uncertainty["Uncertainty Wrapper<br/>[uncertainty.py]"]
end

subgraph group_support["RL Support"]
  node_logger["Training CSV Logger<br/>[logger.py]"]
end

node_user(("Environment User"))
node_agent(("RL Agent"))
node_bluesky["BlueSky Simulator"]

node_user -->|"registers"| node_registration
node_user -->|"selects environment"| node_gym
node_registration -->|"registers environments"| node_gym
node_gym -->|"creates"| node_descent
node_gym -->|"creates"| node_waypoint
node_gym -->|"creates"| node_horizontal
node_gym -->|"creates"| node_vertical
node_gym -->|"creates"| node_merge
node_gym -->|"creates"| node_sector
node_gym -->|"creates"| node_obstacle
node_agent -->|"steps with actions"| node_gym
node_gym -->|"returns results"| node_agent
node_descent -.->|"advances simulation"| node_bluesky
node_waypoint -.->|"advances simulation"| node_bluesky
node_horizontal -->|"advances simulation"| node_bluesky
node_vertical -->|"commands simulation"| node_bluesky
node_merge -->|"advances simulation"| node_bluesky
node_sector -->|"checks airspace"| node_bluesky
node_obstacle -->|"advances simulation"| node_bluesky
node_horizontal -->|"uses angle helper"| node_geometry
node_merge -->|"uses angle helper"| node_geometry
node_sector -->|"uses coordinate helpers"| node_geometry
node_obstacle -->|"uses angle helper"| node_geometry
node_agent -.->|"logs training"| node_logger

click node_registration "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/__init__.py"
click node_descent "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/descent_env.py"
click node_waypoint "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/plan_waypoint_env.py"
click node_horizontal "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/horizontal_cr_env.py"
click node_vertical "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/vertical_cr_env.py"
click node_merge "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/merge_env.py"
click node_sector "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/sector_cr_env.py"
click node_obstacle "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/static_obstacle_env.py"
click node_geometry "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/common/functions.py"
click node_polygons "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/common/polygon_generator.py"
click node_screen "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/common/screen_dummy.py"
click node_wind "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/wrappers/wind.py"
click node_uncertainty "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/wrappers/uncertainty.py"
click node_logger "https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/utils/logger.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_gym,node_registration,node_user toneBlue
class node_descent,node_waypoint,node_horizontal,node_vertical,node_merge,node_sector,node_obstacle toneAmber
class node_geometry,node_polygons,node_screen,node_wind,node_uncertainty toneMint
class node_logger toneRose
class node_agent,node_bluesky toneIndigo
```

## Components

### Gymnasium API

- **Gymnasium**
- [Environment Registration](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/__init__.py): `bluesky_gym/__init__.py`

### Air Traffic Scenarios

- [Descent Scenario](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/descent_env.py): `bluesky_gym/envs/descent_env.py`
- [Waypoint Planning](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/plan_waypoint_env.py): `bluesky_gym/envs/plan_waypoint_env.py`
- [Horizontal Conflict](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/horizontal_cr_env.py): `bluesky_gym/envs/horizontal_cr_env.py`
- [Vertical Conflict](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/vertical_cr_env.py): `bluesky_gym/envs/vertical_cr_env.py`
- [Traffic Merge](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/merge_env.py): `bluesky_gym/envs/merge_env.py`
- [Sector Conflict](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/sector_cr_env.py): `bluesky_gym/envs/sector_cr_env.py`
- [Static Obstacles](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/static_obstacle_env.py): `bluesky_gym/envs/static_obstacle_env.py`

### Shared Environment Logic

- [Navigation Geometry](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/common/functions.py): `bluesky_gym/envs/common/functions.py`
- [Polygon Generation](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/common/polygon_generator.py): `bluesky_gym/envs/common/polygon_generator.py`
- [Dummy Screen](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/envs/common/screen_dummy.py): `bluesky_gym/envs/common/screen_dummy.py`
- [Wind Wrapper](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/wrappers/wind.py): `bluesky_gym/wrappers/wind.py`
- [Uncertainty Wrapper](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/wrappers/uncertainty.py): `bluesky_gym/wrappers/uncertainty.py`

### RL Support

- [Training CSV Logger](https://github.com/tudelft-cns-atm/bluesky-gym/blob/main/bluesky_gym/utils/logger.py): `bluesky_gym/utils/logger.py`

### Other components

- **Environment User**
- **RL Agent**
- **BlueSky Simulator**

## Connections

- Environment User → Environment Registration: registers (evidence: `README.md`)
- Environment User → Gymnasium: selects environment (evidence: `README.md`)
- Environment Registration → Gymnasium: registers environments (evidence: `bluesky_gym/__init__.py`)
- Gymnasium → Descent Scenario: creates
- Gymnasium → Waypoint Planning: creates
- Gymnasium → Horizontal Conflict: creates
- Gymnasium → Vertical Conflict: creates
- Gymnasium → Traffic Merge: creates
- Gymnasium → Sector Conflict: creates
- Gymnasium → Static Obstacles: creates
- RL Agent → Gymnasium: steps with actions (evidence: `README.md`)
- Gymnasium → RL Agent: returns results (evidence: `README.md`)
- Descent Scenario → BlueSky Simulator: advances simulation (evidence: `README.md`)
- Waypoint Planning → BlueSky Simulator: advances simulation (evidence: `README.md`)
- Horizontal Conflict → BlueSky Simulator: advances simulation (evidence: `bluesky_gym/envs/horizontal_cr_env.py`)
- Vertical Conflict → BlueSky Simulator: commands simulation (evidence: `bluesky_gym/envs/vertical_cr_env.py`)
- Traffic Merge → BlueSky Simulator: advances simulation (evidence: `bluesky_gym/envs/merge_env.py`)
- Sector Conflict → BlueSky Simulator: checks airspace (evidence: `bluesky_gym/envs/sector_cr_env.py`)
- Static Obstacles → BlueSky Simulator: advances simulation (evidence: `bluesky_gym/envs/static_obstacle_env.py`)
- Horizontal Conflict → Navigation Geometry: uses angle helper (evidence: `bluesky_gym/envs/horizontal_cr_env.py`)
- Traffic Merge → Navigation Geometry: uses angle helper (evidence: `bluesky_gym/envs/merge_env.py`)
- Sector Conflict → Navigation Geometry: uses coordinate helpers (evidence: `bluesky_gym/envs/sector_cr_env.py`)
- Static Obstacles → Navigation Geometry: uses angle helper (evidence: `bluesky_gym/envs/static_obstacle_env.py`)
- RL Agent → Training CSV Logger: logs training (evidence: `README.md`)
