# nitin3560/uav-marl-task-allocation architecture

> Architecture diagram of the GitHub repository nitin3560/uav-marl-task-allocation, 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-marl-task-allocation
- Repository: https://github.com/nitin3560/uav-marl-task-allocation

## Overview

This repository is an experimental multi-UAV task-allocation and relay-routing study. Its main workflow trains or selects a joint policy/baseline, runs it against the task-and-communication environment, and evaluates task completion, delivery, energy, throughput, and AoI; analysis plots compare logged outcomes. The environment’s task, network, energy, and reward models are distinct internal stages. Evaluation relationships are supported by the eval-runner reference list and excerpts; some training and plotting connections are documented only at a high level, so those are marked unverified.

Main entry points: [`evaluation/eval_runner.py`](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/evaluation/eval_runner.py) (Episode evaluation), [`envs/lawn_task_comm_env.py`](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/lawn_task_comm_env.py) (Parallel environment), [`training`](https://github.com/nitin3560/uav-marl-task-allocation/tree/main/training) (Policy training), [`agents/marl_policy.py`](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/agents/marl_policy.py) (MAPPO policy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_environment["Swarm environment"]
  node_environment_runtime["Parallel environment"]
  node_task_model["Task lifecycle<br/>[task_models.py]"]
  node_network_model["Network routing<br/>[network_models.py]"]
  node_energy_model["Energy accounting<br/>[energy_models.py]"]
  node_reward_model["Team reward<br/>[reward.py]"]
  node_motion_control["Motion helper"]
end

subgraph group_policies["Policies and training"]
  node_trainer["Policy training"]
  node_marl_policy["MAPPO policy<br/>[marl_policy.py]"]
  node_ctde["CTDE wrapper<br/>[ctde.py]"]
  node_baselines["Baseline policies"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation_runner["Episode evaluation<br/>[eval_runner.py]"]
  node_fault_injector["Fault injection<br/>[fault_injector.py]"]
  node_metrics["Evaluation metrics"]
end

subgraph group_analysis["Results analysis"]
  node_analysis_plots["Result plots<br/>[plots.py]"]
  node_results["Evaluation logs"]
end

node_researcher(("Experimenter"))

node_researcher -.->|"trains policies"| node_trainer
node_trainer -.->|"trains on"| node_environment_runtime
node_trainer -.->|"optimizes"| node_marl_policy
node_ctde -->|"wraps"| node_environment_runtime
node_evaluation_runner -->|"steps episodes"| node_environment_runtime
node_evaluation_runner -->|"loads and calls"| node_marl_policy
node_evaluation_runner -->|"selects and calls"| node_baselines
node_evaluation_runner -->|"calls"| node_motion_control
node_evaluation_runner -->|"configures"| node_fault_injector
node_evaluation_runner -->|"computes"| node_metrics
node_environment_runtime -->|"uses"| node_task_model
node_environment_runtime -->|"uses"| node_network_model
node_environment_runtime -->|"uses"| node_energy_model
node_environment_runtime -->|"uses"| node_reward_model
node_analysis_plots -->|"reads logs"| node_results
node_evaluation_runner -.->|"writes results"| node_results

click node_trainer "https://github.com/nitin3560/uav-marl-task-allocation/tree/main/training"
click node_marl_policy "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/agents/marl_policy.py"
click node_ctde "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/utils/ctde.py"
click node_baselines "https://github.com/nitin3560/uav-marl-task-allocation/tree/main/baselines"
click node_environment_runtime "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/lawn_task_comm_env.py"
click node_task_model "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/task_models.py"
click node_network_model "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/network_models.py"
click node_energy_model "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/energy_models.py"
click node_reward_model "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/reward.py"
click node_motion_control "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/controllers/motion_controller.py"
click node_evaluation_runner "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/evaluation/eval_runner.py"
click node_fault_injector "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/evaluation/fault_injector.py"
click node_metrics "https://github.com/nitin3560/uav-marl-task-allocation/tree/main/metrics"
click node_analysis_plots "https://github.com/nitin3560/uav-marl-task-allocation/blob/main/analysis/plots.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_environment_runtime,node_task_model,node_network_model,node_energy_model,node_reward_model,node_motion_control toneBlue
class node_trainer,node_marl_policy,node_ctde,node_baselines toneAmber
class node_evaluation_runner,node_fault_injector,node_metrics toneMint
class node_analysis_plots,node_results toneRose
class node_researcher toneIndigo
```

## Components

### Swarm environment

- [Parallel environment](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/lawn_task_comm_env.py): `envs/lawn_task_comm_env.py`
- [Task lifecycle](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/task_models.py): `envs/task_models.py`
- [Network routing](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/network_models.py): `envs/network_models.py`
- [Energy accounting](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/energy_models.py): `envs/energy_models.py`
- [Team reward](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/envs/reward.py): `envs/reward.py`
- [Motion helper](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/controllers/motion_controller.py): `controllers/motion_controller.py`

### Policies and training

- [Policy training](https://github.com/nitin3560/uav-marl-task-allocation/tree/main/training): `training`
- [MAPPO policy](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/agents/marl_policy.py): `agents/marl_policy.py`
- [CTDE wrapper](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/utils/ctde.py): `utils/ctde.py`
- [Baseline policies](https://github.com/nitin3560/uav-marl-task-allocation/tree/main/baselines): `baselines`

### Evaluation

- [Episode evaluation](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/evaluation/eval_runner.py): `evaluation/eval_runner.py`
- [Fault injection](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/evaluation/fault_injector.py): `evaluation/fault_injector.py`
- [Evaluation metrics](https://github.com/nitin3560/uav-marl-task-allocation/tree/main/metrics): `metrics`

### Results analysis

- [Result plots](https://github.com/nitin3560/uav-marl-task-allocation/blob/main/analysis/plots.py): `analysis/plots.py`
- **Evaluation logs**

### Other components

- **Experimenter**

## Connections

- Experimenter → Policy training: trains policies
- Policy training → Parallel environment: trains on
- Policy training → MAPPO policy: optimizes
- CTDE wrapper → Parallel environment: wraps (evidence: `utils/ctde.py`)
- Episode evaluation → Parallel environment: steps episodes (evidence: `evaluation/eval_runner.py`)
- Episode evaluation → MAPPO policy: loads and calls (evidence: `evaluation/eval_runner.py`)
- Episode evaluation → Baseline policies: selects and calls (evidence: `evaluation/eval_runner.py`)
- Episode evaluation → Motion helper: calls (evidence: `evaluation/eval_runner.py`)
- Episode evaluation → Fault injection: configures (evidence: `evaluation/eval_runner.py`)
- Episode evaluation → Evaluation metrics: computes (evidence: `evaluation/eval_runner.py`)
- Parallel environment → Task lifecycle: uses (evidence: `envs/lawn_task_comm_env.py`)
- Parallel environment → Network routing: uses (evidence: `envs/lawn_task_comm_env.py`)
- Parallel environment → Energy accounting: uses (evidence: `envs/lawn_task_comm_env.py`)
- Parallel environment → Team reward: uses (evidence: `envs/lawn_task_comm_env.py`)
- Result plots → Evaluation logs: reads logs (evidence: `analysis/plots.py`)
- Episode evaluation → Evaluation logs: writes results
