# riccardodmts/rclpod_yolo architecture

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

- Interactive diagram: https://gitdiagram.com/riccardodmts/rclpod_yolo
- Repository: https://github.com/riccardodmts/rclpod_yolo

## Overview

##### Project Type and Purpose
- This is a Python-based Machine Learning research toolkit implementing several Continual Learning (CL) strategies (Naive FT, Replay, OCDM, LwF, Pseudo-label, and the proposed RCLPOD) on top of the YOLOv8 object detector.
- It provides a command-line interface (CLI) to launch experiments, a configurable pipeline for dataset preparation, training, replay memory management, label propagation, evaluation, and plotting.

##### File Structure Analysis
- Top-level:
- clod/                ← core source folder
- docs/                ← Sphinx documentation
- README.md, LICENSE.
- clod/ substructure:
- cfg/                 ← experiment configurations (VOC/COCO scenarios)
- data/                ← dataset abstractions and replay memory logic
- loss/                ← custom loss functions (YOLO loss, LwF, our loss, LwF loss)
- trainer/             ← base and method-specific training loops
- validation/          ← evaluation & validation hooks
- plot/                ← plotting utilities and notebooks
- *.py scripts         ← entry-points for each CL method
- utils.py, prepare_data.py
- Dependencies:
- ultralytics (YOLOv8 backbone)
- micromind (data/model utilities)
- PyTorch, YAML, standard ML libs

##### High-Level System Components
a. CLI / Entry-Point Layer
- Scripts (naive_train, replay_train, ..., RCLPOD_train_yolov8.py)
- Parse command-line args → load config file (cfg/yolov8*.py)
b. Configuration Loader
- Reads dataset paths, experiment settings (exp name, replay size, CL schedule)
c. Dataset Manager
- clod/data/mydataset.py: handles initial dataset (VOC/COCO)
- clod/data/replay_data.py & OCDM.py: implements replay memory selection
d. Model & Loss Layer
- ultralytics YOLOv8 model instantiation
- Custom loss modules (in clod/loss/) plugged into trainer
e. Trainer Layer
- BaseTrainer (common training loop)
- Specialized trainers (lwf_trainer, yolo_trainer, ours_trainer, etc.)
- Manages forward/backward, replay sampling, label propagation, optimizer, scheduler
f. Validation & Logging
- clod/validation/validator.py: computes metrics
- plot utils: generate result curves and tables
g. External Services / Libraries
- ultralytics module for model/API
- micromind toolkit for additional data/model utilities

##### Relationships and Data Flow
1. User invokes a training script with a config file.
2. Config Loader parses scenario and hyperparameters.
3. Dataset Manager loads initial images and ground-truth.
4. Trainer instantiates YOLO model and selects a CL strategy:
- If RCLPOD: initializes replay memory + label propagation module.
5. Training loop:
a. Sample a batch from current task + replay memory
b. Forward pass through YOLO model
c. Compute loss via appropriate Loss module
d. Backprop, update model parameters
e. Update replay memory (e.g. OCDM selection)
6. Periodic validation via Validation component.
7. Plotting and result storage (weights, logs, figures).

##### Architectural Patterns & Principles
- Modular layering: CLI → Config → Data → Model → Trainer → Validation → Plot.
- Strategy pattern for trainers: interchangeable CL methods extend BaseTrainer.
- Separation of concerns: data loading, replay management, loss computation, model definition, training loop, and evaluation are decoupled.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI & Config Layer
    subgraph "CLI & Entry-Point Layer"
        direction TB
        naive_train["naive_train_yolov8.py"]:::cliConfig
        replay_train["replay_train_yolov8.py"]:::cliConfig
        ocdm_train["ocdm_replay_train_yolov8.py"]:::cliConfig
        lwf_train["lwf_train_yolov8.py"]:::cliConfig
        pseudo_train["pseudo_label_train_yolov8.py"]:::cliConfig
        rclpod_train["RCLPOD_train_yolov8.py"]:::cliConfig
    end

    subgraph "Configuration Loader" 
        direction TB
        cfg_coco["yolov8coco.py"]:::cliConfig
        cfg_voc["yolov8voc.py"]:::cliConfig
        data_yaml["data/*.yaml"]:::cliConfig
        names_voc["voc.names"]:::cliConfig
        names_coco["coco.names"]:::cliConfig
    end

    %% Data Layer
    subgraph "Data & Replay Memory" 
        direction TB
        mybase["mybase.py"]:::data
        mybuild["mybuild.py"]:::data
        mydataset["mydataset.py"]:::data
        replay_data["replay_data.py"]:::data
        replay_store["Replay Memory"]:::dataStore
        OCDM["OCDM.py"]:::data
    end

    %% Model & Loss Layer
    subgraph "Model & Loss"
        direction TB
        ultralytics["Ultralytics YOLOv8"]:::external
        yolo_loss["yolo_loss.py"]:::model
        lwf_loss["LwFloss.py"]:::model
        our_loss["our_loss.py"]:::model
    end

    %% Trainer Layer
    subgraph "Trainer Layer"
        direction TB
        base_trainer["basetrainer.py"]:::trainer
        yolo_trainer["yolo_trainer.py"]:::trainer
        lwf_trainer["lwf_trainer.py"]:::trainer
        ours_trainer["ours_trainer.py"]:::trainer
    end

    %% Validation & Plotting
    subgraph "Validation & Plotting"
        direction TB
        validator["validator.py"]:::validation
        autobackend["autobackend.py"]:::validation
        plot_utils["utils.py"]:::validation
        notebook["plot_notebook.ipynb"]:::validation
    end

    %% Connections
    naive_train -->|"load_cfg"| cfg_coco
    naive_train -->|"load_cfg"| cfg_voc
    replay_train -->|"load_cfg"| cfg_coco
    replay_train -->|"load_cfg"| cfg_voc
    ocdm_train -->|"load_cfg"| cfg_coco
    lwf_train -->|"load_cfg"| cfg_voc
    pseudo_train -->|"load_cfg"| cfg_coco
    rclpod_train -->|"load_cfg"| cfg_voc

    cfg_coco -->|"init_data"| mydataset
    cfg_voc --> mydataset

    mydataset -->|"build_dataset"| mybase
    mydataset --> mybuild
    mydataset --> replay_store
    replay_data --> replay_store
    OCDM --> replay_store

    base_trainer --> yolo_trainer
    base_trainer --> lwf_trainer
    base_trainer --> ours_trainer

    rclpod_train --> base_trainer
    lwf_train --> base_trainer
    yolo_trainer --> ultralytics
    yolo_trainer --> yolo_loss
    lwf_trainer --> lwf_loss
    ours_trainer --> our_loss
    ours_trainer --> replay_data
    ours_trainer --> OCDM

    base_trainer -->|"sample_batch"| replay_store
    base_trainer -->|"forward"| ultralytics
    ultralytics -->|"predictions"| our_loss
    our_loss -->|"loss"| base_trainer
    base_trainer -->|"update_memory"| replay_data

    base_trainer -->|"validate"| validator
    validator --> autobackend
    validator -->|"metrics"| plot_utils
    plot_utils --> notebook

    %% Click Events
    click naive_train "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/naive_train_yolov8.py"
    click replay_train "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/replay_train_yolov8.py"
    click ocdm_train "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/ocdm_replay_train_yolov8.py"
    click lwf_train "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/lwf_train_yolov8.py"
    click pseudo_train "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/pseudo_label_train_yolov8.py"
    click rclpod_train "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/RCLPOD_train_yolov8.py"
    click cfg_coco "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/cfg/yolov8coco.py"
    click cfg_voc "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/cfg/yolov8voc.py"
    click data_yaml "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/cfg/data/*.yaml"
    click names_voc "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/cfg/data/voc.names"
    click names_coco "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/cfg/data/coco.names"
    click mybase "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/data/mybase.py"
    click mybuild "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/data/mybuild.py"
    click mydataset "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/data/mydataset.py"
    click replay_data "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/data/replay_data.py"
    click OCDM "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/data/OCDM.py"
    click yolo_loss "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/loss/yolo_loss.py"
    click lwf_loss "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/loss/LwFloss.py"
    click our_loss "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/loss/our_loss.py"
    click base_trainer "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/trainer/basetrainer.py"
    click yolo_trainer "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/trainer/yolo_trainer.py"
    click lwf_trainer "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/trainer/lwf_trainer.py"
    click ours_trainer "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/trainer/ours_trainer.py"
    click validator "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/validation/validator.py"
    click autobackend "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/validation/autobackend.py"
    click plot_utils "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/plot/utils.py"
    click notebook "https://github.com/riccardodmts/rclpod_yolo/blob/main/clod/plot_notebook.ipynb"

    %% Styles
    classDef cliConfig fill:#D0E6FF,stroke:#1E70BF
    classDef data fill:#DFFFE0,stroke:#31A100
    classDef dataStore fill:#B3FFB3,stroke:#31A100,stroke-dasharray: 5 5
    classDef model fill:#FFE8B3,stroke:#E68A00
    classDef trainer fill:#E6D0FF,stroke:#8A2BE2
    classDef validation fill:#FFF5B3,stroke:#E6B800
    classDef external fill:#F0F0F0,stroke:#999999,stroke-dasharray: 2 2
```
