# nusha97/quad-lcd architecture

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

- Interactive diagram: https://gitdiagram.com/nusha97/quad-lcd
- Repository: https://github.com/nusha97/quad-lcd

## Overview

##### Project type and purpose
- This is a research-oriented full-stack robotics codebase (“Quad-LCD”) for dynamics-aware trajectory generation and control of quadrotors.
- It provides pipelines for data generation (using RotorPy simulator and hardware bag sync), training (ICNNs/MLPs for penalty learning), and inference (trajectory regularization), as well as deployment in simulation (ROS/RViz) and on hardware.

##### File structure
- Top-level:
- Dockerfile / build.sh / run.sh – containerized environment build & launch
- configs/ – YAML experiment and model parameters
- notebooks/ – Jupyter workflows for data inspection, model debugging, visualization
- scripts/ – stand-alone Python entrypoints for data gen, training, inference
- src/layered_quadrotor_control/ – ROS-compatible Python/C++ package:
– scripts/datagen/ (detailed data-generation modules)
– scripts/learning/ (core learning utilities in JAX)
– scripts/inference/ (inference & regularized trajectory modules)
– scripts/utils/ (common helpers, plotting, bag-processing)
– src/sync_msg/ (C++ node for ROS bag synchronization)
- Key patterns:
- Layered pipeline: Data → Training → Inference → Deployment
- Separation of concerns: Python high-level scripts vs. C++ real-time sync node
- Containerization (Docker + run/build scripts)
- ROS package structure (CMakeLists, package.xml)

##### README for additional insights
- Confirms three major stages: data gen → model training → inference
- Leverages RotorPy for simulation backbone
- Targets two quadrotor platforms (Crazyflie, Dragonfly) in sim & hardware
- Points to ROS deployment (rviz, rosrun sync_msg)
- Specifies Python (JAX, MLP/ICNN), CMake/C++, YAML configs

1. Environment & Orchestration
– Docker Container (base image, dependencies), build.sh/run.sh
– Conda environment
2. Configuration Store
– configs/*.yaml (experiment parameters, network hyperparams)
3. Data Generation Layer
– Python entrypoint: scripts/rotorpy_data.py
– Module: src/.../scripts/datagen (RotorPy sim, hardware bag loaders)
– ROS C++ node: sync_msg for bag recording
4. Training Layer
– scripts/training.py
– JAX models (MLP, ICNN) in scripts/learning/
5. Inference Layer
– scripts/singletraj_inference.py
– scripts/inference/regularized_trajectory.py, l1adaptive_control, SGD
6. Deployment & Visualization
– ROS simulation: demo_sim.sh, rviz
– Hardware interface: mav_layer_interface, rosrun layered_ref_control
– Notebooks for analysis (Inference.ipynb, Testing_*.ipynb)
– configs → DataGen
– DataGen → RawDatasets (bag files, numpy arrays)
– RawDatasets → Training → TrainedModel artifacts
– TrainedModel + configs → Inference → RegularizedTrajectories
– RegularizedTrajectories → ROS Simulation / Hardware
– Notebooks can consume data at each stage
c. Architectural patterns & principles:
– Layered pipeline (clear stage separation)
– Modular ROS package and standalone scripts
– Containerized reproducibility
– Data-driven learning loop with feedback (rollouts → penalty learning → planning)
d. Technologies, frameworks, libraries:
– Python 3, JAX, PyTorch (if used), NumPy, YAML
– ROS (C++, Python nodes), CMake, package.xml
– RotorPy simulator
– Docker, Conda
– Jupyter notebooks

##### Capturing essential architectural elements
- Container boundary enclosing all Python/C++ code and dependencies.
- Detail the ROS package structure within the container.
- How configs parameterize each stage.
- Iterative learning loop (rollout → penalty update → replan).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Docker Container"
        direction TB
        subgraph "Environment & Orchestration"
            Dockerfile["Dockerfile"]:::config
            Build["build.sh"]:::config
            Run["run.sh"]:::config
        end
        subgraph "Configuration Store"
            Configs["configs/*.yaml"]:::data
        end
        subgraph "Data Generation Layer"
            RPData["scripts/rotorpy_data.py"]:::python
            DGMod["datagen modules"]:::python
            SyncMsg["sync_msg.cpp"]:::cpp
        end
        subgraph "Training Layer"
            Train["scripts/training.py"]:::python
            MLPJax["scripts/mlp_jax.py"]:::python
            ModelLearn["scripts/model_learning.py"]:::python
            JaxUtils["learning utilities"]:::python
        end
        subgraph "Inference Layer"
            SingleInf["scripts/singletraj_inference.py"]:::python
            RegTrajComp["regularized_trajectory.py"]:::python
            L1Ctrl["l1adaptive_control.py"]:::python
            SGD["sgd_jax.py"]:::python
        end
        subgraph "Deployment & Visualization"
            CMake["CMakeLists.txt"]:::cpp
            PKGXML["package.xml"]:::cpp
            MAVInt["mav_layer_interface.py"]:::python
            Notebooks["Notebooks"]:::notebook
            subgraph "Simulation & Hardware"
                RViz["RViz"]:::external
                Crazy["Crazyflie"]:::external
                Dragon["Dragonfly"]:::external
            end
        end
        RawData["RawDatasets"]:::data
        TrainedModel["TrainedModel artifacts"]:::data
        RegTrajStore["RegularizedTrajectories"]:::data
    end

    Configs --> RPData
    Configs --> DGMod
    RPData --> RawData
    DGMod --> RawData
    SyncMsg --> RawData
    RawData --> Train
    Train --> TrainedModel
    TrainedModel --> SingleInf
    Configs --> SingleInf
    SingleInf --> RegTrajStore
    RegTrajStore --> RViz
    RegTrajStore --> Crazy
    RegTrajStore --> Dragon
    RawData --> Notebooks
    TrainedModel --> Notebooks
    RegTrajStore --> Notebooks

    click Dockerfile "https://github.com/nusha97/quad-lcd/tree/main/Dockerfile"
    click Build "https://github.com/nusha97/quad-lcd/blob/main/build.sh"
    click Run "https://github.com/nusha97/quad-lcd/blob/main/run.sh"
    click Configs "https://github.com/nusha97/quad-lcd/blob/main/configs/params.yaml"
    click RPData "https://github.com/nusha97/quad-lcd/blob/main/scripts/rotorpy_data.py"
    click DGMod "https://github.com/nusha97/quad-lcd/blob/main/src/layered_quadrotor_control/scripts/datagen/generate_data.py"
    click SyncMsg "https://github.com/nusha97/quad-lcd/blob/main/src/layered_quadrotor_control/src/sync_msg/sync_msg.cpp"
    click Train "https://github.com/nusha97/quad-lcd/blob/main/scripts/training.py"
    click MLPJax "https://github.com/nusha97/quad-lcd/blob/main/scripts/mlp_jax.py"
    click ModelLearn "https://github.com/nusha97/quad-lcd/blob/main/scripts/model_learning.py"
    click JaxUtils "https://github.com/nusha97/quad-lcd/blob/main/src/layered_quadrotor_control/scripts/learning/inference_jax.py"
    click SingleInf "https://github.com/nusha97/quad-lcd/blob/main/scripts/singletraj_inference.py"
    click RegTrajComp "https://github.com/nusha97/quad-lcd/blob/main/src/layered_quadrotor_control/scripts/inference/regularized_trajectory.py"
    click L1Ctrl "https://github.com/nusha97/quad-lcd/blob/main/src/layered_quadrotor_control/scripts/inference/l1adaptive_control.py"
    click SGD "https://github.com/nusha97/quad-lcd/blob/main/src/layered_quadrotor_control/scripts/inference/sgd_jax.py"
    click CMake "https://github.com/nusha97/quad-lcd/blob/main/src/layered_quadrotor_control/CMakeLists.txt"
    click PKGXML "https://github.com/nusha97/quad-lcd/blob/main/src/layered_quadrotor_control/package.xml"
    click MAVInt "https://github.com/nusha97/quad-lcd/blob/main/src/layered_quadrotor_control/scripts/mav_layer_interface.py"
    click Notebooks "https://github.com/nusha97/quad-lcd/blob/main/notebooks/Inference.ipynb"

    classDef python fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef cpp fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px
    classDef notebook fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
    classDef config fill:#90EE90,stroke:#333,stroke-width:1px
```
