# zamanzadeh/carla architecture

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

- Interactive diagram: https://gitdiagram.com/zamanzadeh/carla
- Repository: https://github.com/zamanzadeh/carla

## Overview

##### Project Overview and Main Components
- Purpose: CARLA is a research implementation built using Python and PyTorch. Its goal is to perform time series anomaly detection using a two-stage approach: a contrastive pretext learning stage (with anomaly injection) and a self-supervised classification stage.
- Main components to highlight:
a. Data Module: Handles dataset ingestion, augmentation, and preparation (see the “data” directory with files like MSL.py, KPI.py, augment.py, custom_dataset.py, etc.).
b. Configuration Module: Central configuration stored in “configs/env.yml” and experiment-specific YAML files under “configs/pretext” and “configs/classification” that define model parameters, dataset paths, and stage-specific settings.
c. Pretext Stage: Implemented in carla_pretext.py and its associated config files – this stage performs the self-supervised contrastive representation learning (with anomaly injection).
d. Self-Supervised Classification Stage: Implemented in carla_classification.py using configuration in “configs/classification”. This stage builds on the learned representations to differentiate between normal and anomalous windows.
e. Models and Loss Functions: Contained in the “models” and “losses” directories, these files define network architectures and contrastive losses.
f. Metrics and Evaluation: Metrics (e.g., AUC, F1, etc.) are implemented in the “metrics” directory. Supplementary evaluation and train utilities located in “utils” assist in running and managing experiments.
g. Notebook Files & Scripts: “Evaluation.ipynb”, “run.ipynb”, and “run.py” provide examples of how to execute training and evaluation pipelines.

##### Relationship and Data Flow
- Begin at “Data Input” where raw datasets (e.g., MSL, KPI, etc.) are loaded using the data module.
- “Configuration” is loaded from the YAML files, setting parameters for both stages.
- In the “Pretext Stage”, the system uses anomaly injection to generate positive/negative pairs and leverages contrastive learning to obtain robust representation of time series windows.
- The output representations from the pretext stage then feed into the “Self-Supervised Classification Stage”, where normal versus anomalous labels are reinforced using learned nearest/furthest neighbor relations.
- “Model Components” (neural network layers) and “Loss Modules” work together in both stages.
- “Evaluation Metrics” calculate performance based on anomaly scores, using files in the metrics folder.
- Utility functions support training, configuration, and data management throughout the pipeline.

##### Architectural Patterns and Key Design Principles
- Separation of Concerns: The design cleanly separates configuration, data handling, model definitions, training scripts, and evaluation logic.
- Modular Structure: Distinct modules for pretext and classification stages allow independent adjustments and easy extension.
- Pipeline Flow: The sequential pipeline from data ingestion → contrastive learning (with anomaly injection) → self-supervised classification is central, with each stage having clearly defined inputs and outputs.
- Use of YAML-based Configurations: Improves reproducibility and flexibility by isolating environment and experiment parameters.

##### Relevant Technologies, Frameworks, or Libraries
- Python (primary language)
- PyTorch (model implementation and training)
- YAML for configuration management
- Jupyter Notebooks for exploratory evaluation and pipeline demonstration

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Data & Configuration"
        DataModule["Data Module"]:::data
        ConfigModule["Configuration Module"]:::config
    end

    subgraph "Contrastive Pretext Stage"
        Pretext["Pretext Stage (ContrastiveLearning&AnomalyInjection)"]:::stage
    end

    subgraph "Self-Supervised Classification Stage"
        Classification["Self-Supervised Classification Stage"]:::stage
    end

    subgraph "Evaluation & Metrics"
        Metrics["Metrics (Evaluation Metrics)"]:::eval
        Evaluation["Evaluation Notebooks"]:::eval
    end

    subgraph "Supporting Modules"
        Models["Model Definitions"]:::support
        Losses["Loss Functions"]:::support
        Utils["Utility Functions"]:::support
    end

    %% Data Flow from Data & Configuration to Pretext Stage
    DataModule -->|"feeds"| Pretext
    ConfigModule -->|"configures"| Pretext

    %% Configuration also supports Classification Stage
    ConfigModule -->|"supplies"| Classification

    %% Pretext Stage feeds into Classification Stage
    Pretext -->|"representations"| Classification

    %% Classification Stage flows into Evaluation & Metrics
    Classification -->|"results"| Metrics
    Metrics -->|"evaluates"| Evaluation

    %% Supporting Modules connections
    Pretext ---|"uses"| Models
    Classification ---|"uses"| Models

    Pretext ---|"employs"| Losses
    Classification ---|"employs"| Losses

    Pretext ---|"supported_by"| Utils
    Classification ---|"supported_by"| Utils
    Metrics ---|"assisted_by"| Utils
    Evaluation ---|"assisted_by"| Utils

    %% Click Events
    click DataModule "https://github.com/zamanzadeh/carla/tree/main/data/"
    click ConfigModule "https://github.com/zamanzadeh/carla/tree/main/configs/"
    click Pretext "https://github.com/zamanzadeh/carla/blob/main/carla_pretext.py"
    click Classification "https://github.com/zamanzadeh/carla/blob/main/carla_classification.py"
    click Models "https://github.com/zamanzadeh/carla/blob/main/models/models.py"
    click Losses "https://github.com/zamanzadeh/carla/blob/main/losses/losses.py"
    click Utils "https://github.com/zamanzadeh/carla/tree/main/utils/"
    click Metrics "https://github.com/zamanzadeh/carla/blob/main/metrics/AUC.py"
    click Evaluation "https://github.com/zamanzadeh/carla/blob/main/Evaluation.ipynb"

    %% Styles
    classDef data fill:#add8e6,stroke:#333,stroke-width:1.5px,color:#000;
    classDef config fill:#ffd700,stroke:#333,stroke-width:1.5px,color:#000;
    classDef stage fill:#ffb6c1,stroke:#333,stroke-width:1.5px,color:#000;
    classDef eval fill:#90ee90,stroke:#333,stroke-width:1.5px,color:#000;
    classDef support fill:#d3d3d3,stroke:#333,stroke-width:1.5px,color:#000;
```
