# nitin3560/uav-autonomy-research-suite architecture

> Architecture diagram of the GitHub repository nitin3560/uav-autonomy-research-suite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nitin3560/uav-autonomy-research-suite
- Repository: https://github.com/nitin3560/uav-autonomy-research-suite

## Overview

The repository is a three-part UAV autonomy research suite: PyBullet fault-aware formation control, learned relay coordination, and a lightweight fault-study runner. The main user workflow is to configure and run simulations or experiments, inject or model faults, then measure and compare outcomes. Case Study 1 has a sampled runner-to-components path; Case Studies 2 and 3 are represented at subsystem level where implementation wiring was not sampled. README capability statements support their high-level roles, not unshown calls.

Main entry points: [`Case Studies/Case Study 1 Flight Control/code/src/run_one.py`](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/run_one.py) (Flight Runner), [`Case Studies/Case Study 3 Fault Study/code/run_study.py`](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/run_study.py) (Study Runner), [`Case Studies/Case Study 2 Relay Coordination/code/evaluation`](https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/evaluation) (Relay Evaluation), [`Case Studies/Case Study 1 Flight Control/ROS 2 Bridge/src/failure_aware_swarm_ros2/failure_aware_swarm_ros2/pybullet_sim_node.py`](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/ROS%202%20Bridge/src/failure_aware_swarm_ros2/failure_aware_swarm_ros2/pybullet_sim_node.py) (ROS Simulation Node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_flight["Fault-Aware Flight"]
  node_flight_runner["Flight Runner<br/>[run_one.py]"]
  node_flight_env["PyBullet Environment<br/>[env_factory.py]"]
  node_trajectory["Formation Trajectories<br/>[trajectories.py]"]
  node_disturbance["Disturbance Model<br/>[disturbances.py]"]
  node_faults["Fault Injection<br/>[fault_injector.py]"]
  node_controllers["Flight Controllers"]
  node_pid_core["PID Core<br/>[pid_core.py]"]
  node_supervisor["Failure Supervisor"]
  node_failure_aware["Failure-Aware Logic<br/>[failure_aware.py]"]
  node_flight_metrics["Flight Metrics<br/>[metrics.py]"]
end

subgraph group_relay["Relay Coordination"]
  node_relay_env["Task and Network Environment"]
  node_relay_policy["MARL Policy<br/>[marl_policy.py]"]
  node_relay_training["Policy Training"]
  node_relay_baselines["Coordination Baselines"]
  node_relay_evaluation["Relay Evaluation"]
  node_relay_analysis["Results Analysis"]
end

subgraph group_study["Lightweight Fault Study"]
  node_study_runner["Study Runner<br/>[run_study.py]"]
  node_study_matrix["Scenario Matrix<br/>[run_matrix.py]"]
  node_study_env["Study Environment<br/>[env.py]"]
  node_study_faults["Study Fault Models<br/>[faults.py]"]
  node_study_control["Study Controllers<br/>[controllers.py]"]
  node_study_diagnosis["Fault Diagnosis<br/>[diagnosis.py]"]
  node_study_estimation["State Estimation<br/>[estimation.py]"]
  node_study_metrics["Study Metrics<br/>[metrics.py]"]
end

subgraph group_bridge["ROS 2 Bridge"]
  node_ros_node["ROS Simulation Node"]
end

node_flight_user(("Experimenter"))
node_relay_user(("Relay Researcher"))
node_study_user(("Study Researcher"))
node_ros_user(("ROS 2 Operator"))

node_flight_user -->|"runs"| node_flight_runner
node_flight_runner -->|"creates"| node_flight_env
node_flight_runner -->|"uses"| node_trajectory
node_flight_runner -->|"uses"| node_disturbance
node_flight_runner -->|"uses"| node_faults
node_flight_runner -->|"selects"| node_controllers
node_flight_runner -->|"uses"| node_supervisor
node_flight_runner -->|"uses"| node_failure_aware
node_flight_runner -->|"uses"| node_flight_metrics
node_flight_env -->|"gets references"| node_trajectory
node_controllers -->|"uses"| node_pid_core
node_ros_user -->|"launches"| node_ros_node
node_ros_node -->|"wraps simulation"| node_flight_env
node_ros_node -->|"uses"| node_disturbance
node_ros_node -.->|"uses"| node_faults
node_relay_user -->|"trains policies"| node_relay_training
node_relay_training -->|"trains"| node_relay_policy
node_relay_user -->|"evaluates"| node_relay_evaluation
node_relay_evaluation -->|"evaluates policies"| node_relay_env
node_relay_evaluation -.->|"compares"| node_relay_baselines
node_relay_evaluation -.->|"summarizes results"| node_relay_analysis
node_study_user -->|"runs studies"| node_study_runner
node_study_user -->|"runs sweeps"| node_study_matrix
node_study_runner -.->|"simulates scenarios"| node_study_env
node_study_runner -.->|"injects faults"| node_study_faults
node_study_runner -.->|"compares controllers"| node_study_control
node_study_runner -.->|"supports ablations"| node_study_diagnosis
node_study_runner -.->|"supports ablations"| node_study_estimation
node_study_runner -.->|"measures outcomes"| node_study_metrics

click node_flight_runner "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/run_one.py"
click node_flight_env "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/env_factory.py"
click node_trajectory "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/trajectories.py"
click node_disturbance "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/disturbances.py"
click node_faults "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/faults/fault_injector.py"
click node_controllers "https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/controllers"
click node_pid_core "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/control_core/pid_core.py"
click node_supervisor "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/controllers/agentic_supervisor.py"
click node_failure_aware "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/failure_aware.py"
click node_flight_metrics "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/metrics.py"
click node_relay_env "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/envs/lawn_task_comm_env.py"
click node_relay_policy "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/agents/marl_policy.py"
click node_relay_training "https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/training"
click node_relay_baselines "https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/baselines"
click node_relay_evaluation "https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/evaluation"
click node_relay_analysis "https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/analysis"
click node_study_runner "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/run_study.py"
click node_study_matrix "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/run_matrix.py"
click node_study_env "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/env.py"
click node_study_faults "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/faults.py"
click node_study_control "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/controllers.py"
click node_study_diagnosis "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/diagnosis.py"
click node_study_estimation "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/estimation.py"
click node_study_metrics "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/metrics.py"
click node_ros_node "https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/ROS%202%20Bridge/src/failure_aware_swarm_ros2/failure_aware_swarm_ros2/pybullet_sim_node.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_flight_runner,node_flight_env,node_trajectory,node_disturbance,node_faults,node_controllers,node_pid_core,node_supervisor,node_failure_aware,node_flight_metrics toneBlue
class node_relay_env,node_relay_policy,node_relay_training,node_relay_baselines,node_relay_evaluation,node_relay_analysis toneAmber
class node_study_runner,node_study_matrix,node_study_env,node_study_faults,node_study_control,node_study_diagnosis,node_study_estimation,node_study_metrics toneMint
class node_ros_node toneRose
class node_flight_user,node_relay_user,node_study_user,node_ros_user toneIndigo
```

## Components

### Fault-Aware Flight

- [Flight Runner](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/run_one.py): `Case Studies/Case Study 1 Flight Control/code/src/run_one.py`
- [PyBullet Environment](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/env_factory.py): `Case Studies/Case Study 1 Flight Control/code/src/env_factory.py`
- [Formation Trajectories](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/trajectories.py): `Case Studies/Case Study 1 Flight Control/code/src/trajectories.py`
- [Disturbance Model](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/disturbances.py): `Case Studies/Case Study 1 Flight Control/code/src/disturbances.py`
- [Fault Injection](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/faults/fault_injector.py): `Case Studies/Case Study 1 Flight Control/code/src/faults/fault_injector.py`
- [Flight Controllers](https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/controllers): `Case Studies/Case Study 1 Flight Control/code/src/controllers`
- [PID Core](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/control_core/pid_core.py): `Case Studies/Case Study 1 Flight Control/code/src/control_core/pid_core.py`
- [Failure Supervisor](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/controllers/agentic_supervisor.py): `Case Studies/Case Study 1 Flight Control/code/src/controllers/agentic_supervisor.py`
- [Failure-Aware Logic](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/failure_aware.py): `Case Studies/Case Study 1 Flight Control/code/src/failure_aware.py`
- [Flight Metrics](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/code/src/metrics.py): `Case Studies/Case Study 1 Flight Control/code/src/metrics.py`

### Relay Coordination

- [Task and Network Environment](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/envs/lawn_task_comm_env.py): `Case Studies/Case Study 2 Relay Coordination/code/envs/lawn_task_comm_env.py`
- [MARL Policy](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/agents/marl_policy.py): `Case Studies/Case Study 2 Relay Coordination/code/agents/marl_policy.py`
- [Policy Training](https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/training): `Case Studies/Case Study 2 Relay Coordination/code/training`
- [Coordination Baselines](https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/baselines): `Case Studies/Case Study 2 Relay Coordination/code/baselines`
- [Relay Evaluation](https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/evaluation): `Case Studies/Case Study 2 Relay Coordination/code/evaluation`
- [Results Analysis](https://github.com/nitin3560/uav-autonomy-research-suite/tree/main/Case%20Studies/Case%20Study%202%20Relay%20Coordination/code/analysis): `Case Studies/Case Study 2 Relay Coordination/code/analysis`

### Lightweight Fault Study

- [Study Runner](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/run_study.py): `Case Studies/Case Study 3 Fault Study/code/run_study.py`
- [Scenario Matrix](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/run_matrix.py): `Case Studies/Case Study 3 Fault Study/code/run_matrix.py`
- [Study Environment](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/env.py): `Case Studies/Case Study 3 Fault Study/code/env.py`
- [Study Fault Models](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/faults.py): `Case Studies/Case Study 3 Fault Study/code/faults.py`
- [Study Controllers](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/controllers.py): `Case Studies/Case Study 3 Fault Study/code/controllers.py`
- [Fault Diagnosis](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/diagnosis.py): `Case Studies/Case Study 3 Fault Study/code/diagnosis.py`
- [State Estimation](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/estimation.py): `Case Studies/Case Study 3 Fault Study/code/estimation.py`
- [Study Metrics](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%203%20Fault%20Study/code/metrics.py): `Case Studies/Case Study 3 Fault Study/code/metrics.py`

### ROS 2 Bridge

- [ROS Simulation Node](https://github.com/nitin3560/uav-autonomy-research-suite/blob/main/Case%20Studies/Case%20Study%201%20Flight%20Control/ROS%202%20Bridge/src/failure_aware_swarm_ros2/failure_aware_swarm_ros2/pybullet_sim_node.py): `Case Studies/Case Study 1 Flight Control/ROS 2 Bridge/src/failure_aware_swarm_ros2/failure_aware_swarm_ros2/pybullet_sim_node.py`

### Other components

- **Experimenter**
- **Relay Researcher**
- **Study Researcher**
- **ROS 2 Operator**

## Connections

- Experimenter → Flight Runner: runs
- Flight Runner → PyBullet Environment: creates (evidence: `Case Studies/Case Study 1 Flight Control/code/src/run_one.py`)
- Flight Runner → Formation Trajectories: uses (evidence: `Case Studies/Case Study 1 Flight Control/code/src/run_one.py`)
- Flight Runner → Disturbance Model: uses (evidence: `Case Studies/Case Study 1 Flight Control/code/src/run_one.py`)
- Flight Runner → Fault Injection: uses (evidence: `Case Studies/Case Study 1 Flight Control/code/src/run_one.py`)
- Flight Runner → Flight Controllers: selects (evidence: `Case Studies/Case Study 1 Flight Control/code/src/run_one.py`)
- Flight Runner → Failure Supervisor: uses (evidence: `Case Studies/Case Study 1 Flight Control/code/src/run_one.py`)
- Flight Runner → Failure-Aware Logic: uses (evidence: `Case Studies/Case Study 1 Flight Control/code/src/run_one.py`)
- Flight Runner → Flight Metrics: uses (evidence: `Case Studies/Case Study 1 Flight Control/code/src/run_one.py`)
- PyBullet Environment → Formation Trajectories: gets references (evidence: `Case Studies/Case Study 1 Flight Control/code/src/env_factory.py`)
- Flight Controllers → PID Core: uses (evidence: `Case Studies/Case Study 1 Flight Control/code/src/controllers/pid.py`)
- ROS 2 Operator → ROS Simulation Node: launches
- ROS Simulation Node → PyBullet Environment: wraps simulation (evidence: `Case Studies/Case Study 1 Flight Control/ROS 2 Bridge/src/failure_aware_swarm_ros2/failure_aware_swarm_ros2/pybullet_sim_node.py`)
- ROS Simulation Node → Disturbance Model: uses (evidence: `Case Studies/Case Study 1 Flight Control/ROS 2 Bridge/src/failure_aware_swarm_ros2/failure_aware_swarm_ros2/pybullet_sim_node.py`)
- ROS Simulation Node → Fault Injection: uses
- Relay Researcher → Policy Training: trains policies
- Policy Training → MARL Policy: trains
- Relay Researcher → Relay Evaluation: evaluates
- Relay Evaluation → Task and Network Environment: evaluates policies
- Relay Evaluation → Coordination Baselines: compares
- Relay Evaluation → Results Analysis: summarizes results
- Study Researcher → Study Runner: runs studies
- Study Researcher → Scenario Matrix: runs sweeps
- Study Runner → Study Environment: simulates scenarios
- Study Runner → Study Fault Models: injects faults
- Study Runner → Study Controllers: compares controllers
- Study Runner → Fault Diagnosis: supports ablations
- Study Runner → State Estimation: supports ablations
- Study Runner → Study Metrics: measures outcomes
