# thanhhau097/google_fast_or_slow architecture

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

- Interactive diagram: https://gitdiagram.com/thanhhau097/google_fast_or_slow
- Repository: https://github.com/thanhhau097/google_fast_or_slow

## Overview

##### Project Type and Purpose
- This repository is a machine learning competition solution. It is built for predicting AI model runtimes using an ensemble of models, applied to both layout and tile data.
- The project involves data preprocessing, multiple training pipelines (for tile and layout with different strategies like XLA, NLP, k-fold), and an inference system that produces submission outputs.
- It integrates external datasets and pre-trained model weights, making it a complete end-to-end machine learning pipeline from raw data to final prediction.

##### File Structure
- Top-level files such as README.md, various shell scripts (train_tile.sh, train_xla_default.sh, etc.), and training/inference scripts (train.py, predict.sh) indicate that the repository is divided into distinct stages: data handling, model training, and inference.
- The “data” directory contains data preprocessing scripts (data_compression.py) and an exploratory notebook (eda.ipynb). Other files like dataset.py, engine.py, model.py, loss.py, and graph_display.py support different stages of the machine learning pipeline.
- Several argument configuration files (data_args.py, model_args.py) support setting hyperparameters and runtime configurations.
- The presence of multiple training scripts and shell scripts for different modalities (Tile and Layout with XLA and NLP variations) points to a design that executes different training pipelines in parallel or sequentially.

##### Examining the README for Architectural Insights
- The README explains the preprocessing steps and the training/inference procedures. It mentions ensemble methods (averaging predictions across models) and external dependencies (Kaggle dataset downloads and pre-trained weights) that play major roles in the solution.
- Instructions for running scripts imply a pipeline where raw data is preprocessed using scripts in the “data” directory, models are trained with varying configurations, and predictions are generated through a final inferencing step.

a. Main Components:
- Data Acquisition & Preprocessing: This includes the “data” directory (data_compression.py, eda.ipynb) plus dataset.py for dataset handling.
- Model Training Modules: This includes engine.py, model.py, loss.py, model_args.py, train.py, train_kfold.py, and the various training shell scripts (train_tile.sh, train_xla_default.sh, train_xla_random.sh, train_nlp_default.sh, train_nlp_random.sh).
- Ensemble & Post-Processing: Scripts like merge_csvs.py, merge_preds_tile.py, and mlp_ensembling.ipynb define how individual models (whose weights are saved as mlp_ensemble_512.pt) are combined.
- Inference: The predict.sh script defines the pipeline for generating the final submission.csv.
- Auxiliary/Visualization: graph_display.py may be used for debugging or performance visualization.
- Data Configuration & Parameters: data_args.py and model_args.py help structure parameters for data loading and model initialization.
- External Interactions: Integration with Kaggle API for dataset download, and instructions for external model weights.

b. Relationships and Interactions:
- Data flows from the Acquisition & Preprocessing component into the Model Training modules. For instance, processed data from data_compression.py and dataset.py is fed into engine.py and model.py.
- Multiple training pipelines run in parallel or sequentially with different configurations (as seen by the several training shell scripts).
- After training, the ensemble scripts merge and filter predictions (merge_csvs.py, merge_preds_tile.py) to produce final model outputs.
- The Inference module (triggered by predict.sh) uses the ensemble outputs and pre-trained model weights to generate the submission file.
- Auxiliary scripts (like graph_display.py) and notebooks (eda.ipynb, mlp_ensembling.ipynb) support exploration and diagnostic analysis.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: Clear separation between data preprocessing, model training, ensembling, and inference.
- Modularity: Different scripts and modules handle specific tasks, allowing for iterative development and easy debugging.
- Ensemble Learning: The design supports training multiple models on various configurations and then aggregating predictions.
- Parameter Configuration: Use of argument files for modular hyperparameter settings and reproducibility.

d. Relevant Technologies and Frameworks:
- Python (core scripting and notebooks), and a machine learning framework (likely PyTorch given the .pt file extension for saved models).
- Shell scripting is used to orchestrate different training and evaluation stages.
- Integration with Kaggle tools for data and model weight acquisition.
- Conda and pip for environment management and dependency installation.

- Clear labels for each component (e.g., Data Acquisition, Data Preprocessing, Model Training, Ensemble, Inference, Auxiliary Visualization).
– From Data Download/Preprocessing → Dataset Loading → Model Training → Ensemble Aggregation → Prediction/Submission.
- Modular separation (each training script representing a distinct branch of the architecture).
- Possibly include notes on external dependencies and how the workflow is orchestrated via shell scripts.

##### Final Advice
- Be as detailed as possible. For each file or script, indicate its role and position it within the broader pipeline.
- That the architecture reflects the ensemble learning strategy and the multi-faceted training approaches.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Source
    A("Kaggle Dataset"):::external

    %% Data Acquisition & Preprocessing
    subgraph "Data Acquisition & Preprocessing"
        DP1("Data Compression Script"):::data
        DP2("Exploratory Notebook"):::data
        DP3("Dataset Loader"):::data
    end

    %% Data Configuration & Parameters
    subgraph "Configuration"
        C1("Data Args"):::config
        C2("Model Args Config"):::config
    end

    %% Model Training Modules
    subgraph "Model Training Modules"
        M1("Engine Module"):::training
        M2("Model Definition"):::training
        M3("Loss Functions"):::training
        M4("Training Script"):::training
        M5("K-Fold Training"):::training
        M6("Tile Training Shell"):::training
        M7("XLA Default Shell"):::training
        M8("XLA Random Shell"):::training
        M9("NLP Default Shell"):::training
        M10("NLP Random Shell"):::training
    end

    %% Ensemble & Post-Processing
    subgraph "Ensemble & Post-Processing"
        E1("Merge CSVs"):::ensemble
        E2("Merge Predictions"):::ensemble
        E3("Ensembling Notebook"):::ensemble
        E4("Model Weights"):::ensemble
    end

    %% Inference
    subgraph "Inference"
        I1("Predict Script"):::inference
    end

    %% Auxiliary/Visualization
    subgraph "Auxiliary/Visualization"
        AUX("Graph Display"):::aux
    end

    %% Connections
    A -->|"feeds"| DP1
    DP1 -->|"processes"| DP3
    DP2 ---|"explores"| DP1
    DP3 -->|"provides data to"| M1

    C1 -->|"configures"| M1
    C2 -->|"configures"| M1

    M1 -->|"defines"| M2
    M1 -->|"defines"| M3
    M1 -->|"triggers"| M4
    M1 -->|"triggers"| M5
    M4 -->|"executes"| M6
    M4 -->|"executes"| M7
    M4 -->|"executes"| M8
    M4 -->|"executes"| M9
    M4 -->|"executes"| M10

    M4 -->|"outputs"| E1
    M5 -->|"outputs"| E1
    E1 -->|"merges"| E2
    E2 -->|"aggregates"| E3
    E3 -->|"finalizes"| E4
    E4 -->|"feeds into"| I1

    M1 ---|"visualizes"| AUX

    %% Click Events for Data Acquisition & Preprocessing
    click DP1 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/data/data_compression.py"
    click DP2 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/data/eda.ipynb"
    click DP3 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/dataset.py"

    %% Click Events for Model Training Modules
    click M1 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/engine.py"
    click M2 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/model.py"
    click M3 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/loss.py"
    click C2 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/model_args.py"
    click M4 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/train.py"
    click M5 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/train_kfold.py"
    click M6 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/train_tile.sh"
    click M7 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/train_xla_default.sh"
    click M8 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/train_xla_random.sh"
    click M9 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/train_nlp_default.sh"
    click M10 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/train_nlp_random.sh"

    %% Click Events for Ensemble & Post-Processing
    click E1 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/merge_csvs.py"
    click E2 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/merge_preds_tile.py"
    click E3 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/mlp_ensembling.ipynb"
    click E4 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/mlp_ensemble_512.pt"

    %% Click Events for Inference
    click I1 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/predict.sh"

    %% Click Events for Auxiliary/Visualization
    click AUX "https://github.com/thanhhau097/google_fast_or_slow/blob/main/graph_display.py"

    %% Click Events for Data Configuration & Parameters
    click C1 "https://github.com/thanhhau097/google_fast_or_slow/blob/main/data_args.py"

    %% Styles
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px
    classDef data fill:#C0EB75,stroke:#333,stroke-width:2px
    classDef training fill:#A7C7E7,stroke:#333,stroke-width:2px
    classDef ensemble fill:#AAF0D1,stroke:#333,stroke-width:2px
    classDef inference fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef config fill:#FDD9B5,stroke:#333,stroke-width:2px
    classDef aux fill:#E6E6FA,stroke:#333,stroke-width:2px
```
