# charlesxu0124/cablerouting architecture

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

- Interactive diagram: https://gitdiagram.com/charlesxu0124/cablerouting
- Repository: https://github.com/charlesxu0124/cablerouting

## Overview

##### Project type and purpose
- This is a research-oriented machine learning pipeline (“CableRouting”) implementing a multi-stage cable routing policy via hierarchical imitation learning.
- It ingests geometric trajectory data, preprocesses it, pretrains a ResNet encoder, learns a low-level routing policy (behavior cloning), learns a high-level primitive-selection policy, then fine-tunes end-to-end. Logging and checkpointing integrate with W&B.

##### File structure
- Top-level directories:
- data/ – raw and processed datasets; contains processing script process_route_trajectories.py
- local_scripts/ – bash scripts orchestrating each training stage
- src/ – core Python code: entry points (bc_main.py, primitive_selection_main.py), model definitions (model.py), utilities (data.py, jax_utils.py, train_utils.py, utils.py)
- requirements.txt – dependency list (jax, torch, wandb, etc.)
- README.md – describes data download, environment setup, and training workflow

##### README for additional insights
- Four main training stages, each invoked via a script:
1) pretrain_resnet_embedding
2) train_routing_bc
3) train_highlevel
4) finetune_highlevel
- Uses JAX for embedding pretraining, PyTorch for policies, and W&B for logging.

##### Detail
- Every stage as a distinct component
- Environment setup (conda env, requirements.txt) as a preliminary step or footnote
- Don’t omit any data transformation or checkpoint artifact

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    RawData["Raw Trajectory Data\n(Dataset Host)"]:::external
    %% Processing
    DataIngest["Data Ingestion & Processing\n(process_route_trajectories.py)\nPython"]:::compute
    ProcData["Processed Data\nroute_transitions.npy"]:::data

    %% Pipeline Stages
    Pretrain["ResNet Embedding Pretraining\n(local_scripts/pretrain_resnet_embedding.sh)\nJAX"]:::compute
    ResNetCP["ResNet Checkpoint\nmodel.pkl"]:::data

    RoutingBC["Routing Behavior Cloning\n(local_scripts/train_routing_bc.sh)\nPyTorch"]:::compute
    RoutingCP["Routing Checkpoint\nmodel.pkl"]:::data

    HighLevel["High-Level Primitive Selection\n(local_scripts/train_highlevel.sh)\nPyTorch"]:::compute
    HighCP["High-Level Checkpoint\nmodel.pkl"]:::data

    FineTune["Fine-Tuning Stage\n(local_scripts/finetune_highlevel.sh)\nJAX+PyTorch"]:::compute
    FineCP["Fine-Tuned Checkpoint\nmodel.pkl"]:::data

    %% Utilities and Definitions
    ModelDef["Model Definitions\n(src/model.py)"]:::util
    JaxUtils["JAX Utils\n(src/jax_utils.py)"]:::util
    TrainUtils["Train Utils\n(src/train_utils.py)"]:::util
    GeneralUtils["General Utils\n(src/utils.py)"]:::util

    %% Services
    CheckpointStore["Checkpoint Store\n(src/train_utils.py)"]:::util
    WandB["Weights & Biases\nLogging Service"]:::external

    %% Flow
    RawData --> DataIngest --> ProcData
    ProcData --> Pretrain --> ResNetCP
    ProcData --> RoutingBC --> RoutingCP
    ResNetCP --> HighLevel --> HighCP
    RoutingCP --> FineTune --> FineCP
    HighCP --> FineTune

    %% Checkpoint Store Connections
    ResNetCP --> CheckpointStore
    RoutingCP --> CheckpointStore
    HighCP --> CheckpointStore
    FineCP --> CheckpointStore

    %% Logging
    Pretrain -->|logs metrics| WandB
    RoutingBC -->|logs metrics| WandB
    HighLevel -->|logs metrics| WandB
    FineTune -->|logs metrics| WandB

    %% Utilities Dependencies
    ModelDef --> Pretrain
    ModelDef --> RoutingBC
    ModelDef --> HighLevel
    ModelDef --> FineTune

    JaxUtils --> Pretrain
    JaxUtils --> FineTune

    TrainUtils --> RoutingBC
    TrainUtils --> HighLevel
    TrainUtils --> FineTune
    TrainUtils --> CheckpointStore

    GeneralUtils --> Pretrain
    GeneralUtils --> RoutingBC
    GeneralUtils --> HighLevel
    GeneralUtils --> FineTune

    %% Click Events
    click DataIngest "https://github.com/charlesxu0124/cablerouting/blob/main/data/process_route_trajectories.py"
    click Pretrain "https://github.com/charlesxu0124/cablerouting/blob/main/local_scripts/pretrain_resnet_embedding.sh"
    click RoutingBC "https://github.com/charlesxu0124/cablerouting/blob/main/local_scripts/train_routing_bc.sh"
    click HighLevel "https://github.com/charlesxu0124/cablerouting/blob/main/local_scripts/train_highlevel.sh"
    click FineTune "https://github.com/charlesxu0124/cablerouting/blob/main/local_scripts/finetune_highlevel.sh"

    click ModelDef "https://github.com/charlesxu0124/cablerouting/blob/main/src/model.py"
    click JaxUtils "https://github.com/charlesxu0124/cablerouting/blob/main/src/jax_utils.py"
    click TrainUtils "https://github.com/charlesxu0124/cablerouting/blob/main/src/train_utils.py"
    click GeneralUtils "https://github.com/charlesxu0124/cablerouting/blob/main/src/utils.py"
    click RoutingBC "https://github.com/charlesxu0124/cablerouting/blob/main/src/bc_main.py"
    click HighLevel "https://github.com/charlesxu0124/cablerouting/blob/main/src/primitive_selection_main.py"
    click FineTune "https://github.com/charlesxu0124/cablerouting/blob/main/src/primitive_selection_main.py"
    click FineTune "https://github.com/charlesxu0124/cablerouting/blob/main/src/bc_main.py"

    %% Styles
    classDef compute fill:#ADD8E6,stroke:#000000
    classDef data fill:#90EE90,stroke:#000000
    classDef external fill:#F5DEB3,stroke:#000000
    classDef util fill:#D3D3D3,stroke:#000000
```
