# larocs/sac_uav architecture

> Architecture diagram of the GitHub repository larocs/sac_uav, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/larocs/sac_uav
- Repository: https://github.com/larocs/sac_uav

## Overview

1. This repository implements a Soft Actor-Critic (SAC) reinforcement-learning pipeline for low-level UAV control. The core goal is to train a policy that drives a drone from a randomized старт state back to a fixed target at the origin.

2. The main architectural boundary is between the Python RL code and the external robotics simulation stack. The repo’s code talks to PyRep, which in turn drives CoppeliaSim. That simulator is the environment backend; this repo does not embed physics itself.

3. The training entry point is `main.py`. It is the central orchestration script for the SAC loop: initialize the environment, collect transitions from the simulator, update the agent, and periodically persist policies. The presence of `training.sh` suggests the canonical training path is shell-driven rather than a library API.

4. The evaluation path is separated from training. `evaluate.py` and `evaluate_container.py` are dedicated inference/rollout entry points, with matching shell wrappers `evaluate.sh` and `evaluate_container.sh`. This separation implies the trained policy is loaded from disk and executed without learning updates.

5. The model definitions live under `networks/`, especially `networks/structures.py`. This is the policy/value-function subsystem: actor and critic network structure, and likely SAC-specific modules used by the training loop. This is the main “learned function approximation” boundary in the repo.

6. Shared support code is in `common/`, with `common/utils.py` acting as a utility layer. This is where reusable helpers, bookkeeping, tensor handling, or environment/action utilities likely sit, keeping the main loop and network code cleaner.

7. The trained artifacts are stored in `saved_policies/`, which contains `.pt` files for pretrained SAC policies. This directory is the handoff point between training and evaluation: training produces policy checkpoints, evaluation consumes them.

8. Containerization is a first-class operational concern. `Dockerfile`, `Makefile`, and the `*_container.sh` scripts indicate a reproducible execution path for both training and evaluation inside a Docker image, useful for cluster runs or environments where CoppeliaSim/PyRep dependencies are hard to install manually.

9. The repo also includes visualization and analysis outputs rather than runtime code. `notebooks/` contains notebooks for reproducing figures and trajectory plots; `assets/` stores static diagrams used by the README. These are downstream analysis/communication artifacts, not part of the control loop.

10. The overall data flow is: simulator state/observations from CoppeliaSim/PyRep → SAC agent code in `main.py` → actor/critic modules in `networks/` → actions back to the simulator → logged trajectories/rewards → checkpoints in `saved_policies/` and figures in `notebooks/`. That loop is the central architecture to capture in a diagram.

11. The repo is intentionally lightweight in Python package structure: `requirements.txt` declares dependencies, while README instructions mention external prerequisites such as CoppeliaSim and PyRep. Those are material to the architecture because the project depends on an external simulator runtime rather than a pure-Python environment.

12. In short, the repository is organized around one learning system with three clear layers: simulation backend, SAC training/evaluation logic, and artifact/reproducibility tooling. The key diagram should show the simulator as an external service, the Python agent as the control and learning core, and checkpoints/notebooks/Docker as supporting outputs and execution paths.

Main entry points: [`main.py`](https://github.com/larocs/sac_uav/blob/master/main.py) (Train loop), [`evaluate.py`](https://github.com/larocs/sac_uav/blob/master/evaluate.py) (Evaluate), [`Dockerfile`](https://github.com/larocs/sac_uav/tree/master/Dockerfile) (Dockerfile), [`evaluate_container.py`](https://github.com/larocs/sac_uav/blob/master/evaluate_container.py) (Eval container)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["SAC pipeline"]
  node_main["Train loop<br/>orchestrator<br/>[main.py]"]
  node_eval["Evaluate<br/>inference<br/>[evaluate.py]"]
  node_net["Networks<br/>model code<br/>[structures.py]"]
  node_utils["Common utils<br/>shared helpers<br/>[utils.py]"]
end

subgraph group_ops["Ops and artifacts"]
  node_eval_container["Eval container<br/>inference wrapper"]
  node_train_sh["Train script<br/>shell entry<br/>[training.sh]"]
  node_eval_sh["Eval script<br/>shell entry<br/>[evaluate.sh]"]
  node_evalc_sh["Eval container<br/>shell entry"]
  node_policies[("Checkpoints<br/>artifacts")]
  node_nb["Notebooks<br/>analysis"]
  node_figures["Figures<br/>outputs"]
  node_docker["Dockerfile<br/>container build"]
  node_make["Makefile<br/>build orchestration"]
end

subgraph group_external["Simulator backend"]
  node_sim[("PyRep/CoppeliaSim<br/>external simulator")]
end

node_train_sh -->|"launches"| node_main
node_main -->|"steps env"| node_sim
node_main -->|"updates"| node_net
node_main -->|"uses"| node_utils
node_main -->|"saves"| node_policies
node_eval_sh -->|"launches"| node_eval
node_evalc_sh -->|"launches"| node_eval_container
node_eval_container -->|"delegates"| node_eval
node_eval -->|"rolls out"| node_sim
node_eval -->|"loads"| node_net
node_eval -->|"reads"| node_policies
node_eval -->|"uses"| node_utils
node_docker -->|"packages"| node_main
node_docker -->|"packages"| node_eval_container
node_make -->|"drives"| node_docker
node_nb -->|"produces"| node_figures
node_nb -->|"analyzes"| node_policies

click node_main "https://github.com/larocs/sac_uav/blob/master/main.py"
click node_eval "https://github.com/larocs/sac_uav/blob/master/evaluate.py"
click node_eval_container "https://github.com/larocs/sac_uav/blob/master/evaluate_container.py"
click node_train_sh "https://github.com/larocs/sac_uav/blob/master/training.sh"
click node_eval_sh "https://github.com/larocs/sac_uav/blob/master/evaluate.sh"
click node_evalc_sh "https://github.com/larocs/sac_uav/blob/master/evaluate_container.sh"
click node_net "https://github.com/larocs/sac_uav/blob/master/networks/structures.py"
click node_utils "https://github.com/larocs/sac_uav/blob/master/common/utils.py"
click node_policies "https://github.com/larocs/sac_uav/tree/master/saved_policies"
click node_nb "https://github.com/larocs/sac_uav/tree/master/notebooks"
click node_figures "https://github.com/larocs/sac_uav/tree/master/notebooks/figures"
click node_docker "https://github.com/larocs/sac_uav/tree/master/Dockerfile"
click node_make "https://github.com/larocs/sac_uav/tree/master/Makefile"

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_main,node_eval,node_net,node_utils toneBlue
class node_eval_container,node_train_sh,node_eval_sh,node_evalc_sh,node_policies,node_nb,node_figures,node_docker,node_make toneAmber
class node_sim toneMint
```

## Components

### SAC pipeline

Training and evaluation entry points plus the learning modules they orchestrate.

- [Train loop](https://github.com/larocs/sac_uav/blob/master/main.py): orchestrator · Central SAC training entry point: environment setup, rollout collection, updates, and checkpointing. · `main.py`
- [Evaluate](https://github.com/larocs/sac_uav/blob/master/evaluate.py): inference · Standalone rollout/inference entry point for loaded policies. · `evaluate.py`
- [Networks](https://github.com/larocs/sac_uav/blob/master/networks/structures.py): model code · Actor/critic and SAC-specific network structure definitions. · `networks/structures.py`
- [Common utils](https://github.com/larocs/sac_uav/blob/master/common/utils.py): shared helpers · Reusable helper layer for bookkeeping and environment/action support. · `common/utils.py`

### Ops and artifacts

Reproducibility scripts, container execution, and generated outputs.

- [Eval container](https://github.com/larocs/sac_uav/blob/master/evaluate_container.py): inference wrapper · Container-oriented evaluation entry point. · `evaluate_container.py`
- [Train script](https://github.com/larocs/sac_uav/blob/master/training.sh): shell entry · Canonical shell wrapper for launching training. · `training.sh`
- [Eval script](https://github.com/larocs/sac_uav/blob/master/evaluate.sh): shell entry · Shell wrapper for standard evaluation runs. · `evaluate.sh`
- [Eval container](https://github.com/larocs/sac_uav/blob/master/evaluate_container.sh): shell entry · Shell wrapper for containerized evaluation runs. · `evaluate_container.sh`
- [Checkpoints](https://github.com/larocs/sac_uav/tree/master/saved_policies): artifacts · Persisted SAC policy weights consumed by evaluation. · `saved_policies`
- [Notebooks](https://github.com/larocs/sac_uav/tree/master/notebooks): analysis · Trajectory analysis and figure reproduction notebooks. · `notebooks`
- [Figures](https://github.com/larocs/sac_uav/tree/master/notebooks/figures): outputs · Static plots exported by notebooks for documentation and analysis. · `notebooks/figures`
- [Dockerfile](https://github.com/larocs/sac_uav/tree/master/Dockerfile): container build · Container image definition for reproducible execution. · `Dockerfile`
- [Makefile](https://github.com/larocs/sac_uav/tree/master/Makefile): build orchestration · Build and execution convenience targets. · `Makefile`

### Simulator backend

External robotics stack driven through PyRep and CoppeliaSim.

- **PyRep/CoppeliaSim**: external simulator · External robotics simulation backend providing state and physics.

## Connections

- Train script → Train loop: launches · Shell wrapper starts the training orchestrator.
- Train loop → PyRep/CoppeliaSim: steps env · Training collects transitions by interacting with the simulator backend.
- Train loop → Networks: updates · Training uses actor/critic networks for policy and value learning.
- Train loop → Common utils: uses · Shared helper functions support rollout, logging, and training bookkeeping.
- Train loop → Checkpoints: saves · Training periodically writes policy checkpoints.
- Eval script → Evaluate: launches · Shell wrapper starts standard evaluation.
- Eval container → Eval container: launches · Shell wrapper starts containerized evaluation.
- Eval container → Evaluate: delegates · Container entry point reuses the evaluation flow.
- Evaluate → PyRep/CoppeliaSim: rolls out · Evaluation runs the trained policy in the simulator backend.
- Evaluate → Networks: loads · Evaluation instantiates the learned policy/value structure.
- Evaluate → Checkpoints: reads · Evaluation loads saved policy checkpoints from disk.
- Evaluate → Common utils: uses · Shared helpers support inference and result handling.
- Dockerfile → Train loop: packages · Container image supports reproducible training runs.
- Dockerfile → Eval container: packages · Container image supports reproducible evaluation runs.
- Makefile → Dockerfile: drives · Make targets likely wrap image/build/runtime commands.
- Notebooks → Figures: produces · Notebooks generate analysis figures and plots.
- Notebooks → Checkpoints: analyzes · Notebook workflows consume trained checkpoints for trajectory studies.
