# josejuan98/transformer-attention-with-hdc-binding architecture

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

- Interactive diagram: https://gitdiagram.com/josejuan98/transformer-attention-with-hdc-binding
- Repository: https://github.com/josejuan98/transformer-attention-with-hdc-binding

## Overview

##### Project Type and Purpose
- This is an open-source research framework and library for experimenting with Transformer models augmented by Hyperdimensional Computing (HDC) binding for positional encodings, specifically targeting time-series classification tasks (with potential NLP extensions).
- It combines:
- A reusable experiment framework (data loading, preprocessing, runner, metrics, error handling)
- A modular model library (embedding layers, binding operations, positional encodings, Transformer components)
- Scripts and configuration for orchestrating experiments, visualizations, and hardware backends

##### High-Level Components
a. Experiment CLI & Orchestration
- Makefile & shell scripts (`scripts/`)
- Poetry/pyproject for dependency management
- GitHub Actions workflows for linting and testing
b. Experiment Framework (`src/experiment_framework`)
- Config parsers & factories (`config/`)
- Data pipeline & datamodule (`data/`)
- Runner (training loop, metrics handling, error handling) (`runner/`)
c. Model Library (`src/models`)
- Architectures (time-series transformer classifier)
- Embedding layers (linear projection, convolutional)
- Binding methods (additive, multiplicative, circular convolution)
- Positional encodings (sinusoidal variants, random, fractional, HDC binding integration)
- Transformer internals (attention, feed-forward, encoder)
- Callbacks (learning rate finder, fine-tuning)
d. Experiment Definitions & Scripts (`src/experiments`)
- Time series experiment configurations and launcher (`run.py`)
- Metric aggregation, layer & similarity visualizations
e. Utilities (`src/utils`)
- Logging, config utilities, plot helpers, cache management
f. Data & Artifacts
- External UCR/UEA datasets (downloaded via datamodule)
- Local `artifacts/` directory for datasets, model checkpoints, logs, metrics
- `docs/experiment_results` for aggregated CSVs and plots
g. Testing (`src/test`)
- Unit tests for framework, models, transformer modules

##### Interactions and Data Flow
1. User runs `make run-ts` or invokes `scripts/install.sh` / `setup_cuda_server.sh`.
2. Makefile calls the experiment script (`src/experiments/time_series/run.py`), passing experiment and model configuration.
3. Runner loads config via `experiment_framework.config`, instantiates datamodule and model via factories.
4. Data pipeline (`experiment_framework.data`) fetches and preprocesses UCR/UEA datasets.
5. Model library constructs embedding + binding + positional encoding + Transformer encoder layers.
6. Training loop executes forward/backward passes, invoking callbacks and metrics handlers.
7. Metrics and checkpoints are saved under `artifacts/models` and logged via `utils/log.py`.
8. Post-processing scripts aggregate metrics (`src/experiments/aggregate_metrics.py`) and visualization modules generate plots in `docs/plots`.

##### Architectural Patterns and Principles
- Factory Pattern: for configs, models, data modules, binding and embedding choices.
- Separation of Concerns: clear layers—config, data, model, runner, scripts, utilities.
- Modular & Extensible: adding a new binding method only requires updating `models/binding/factory.py` and implementing the new class.
- Reproducibility: fixed random seeds, config-driven experiments, automated CI.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Orchestration Layer
    subgraph "Orchestration" 
        direction TB
        Makefile["Makefile"]:::ci
        InstallScript["scripts/install.sh"]:::ci
        CudaScript["scripts/setup_cuda_server.sh"]:::ci
        LintCI[".github/workflows/lint.yml"]:::ci
        TestCI[".github/workflows/test.yml"]:::ci
    end

    %% Framework Layer
    subgraph "Experiment Framework" 
        direction TB
        ConfigPkg["config/"]:::framework
        DataPkg["data/"]:::framework
        RunnerPkg["runner/"]:::framework
    end

    %% Model Library Layer
    subgraph "Model Library"
        direction TB
        Arch["time_series_classifier.py"]:::model
        BaseModel["base_model.py"]:::model
        ArgFmt["arg_formatter.py"]:::model
        ModelFactory["factory.py"]:::model
        subgraph "Embedding"
            direction TB
            EmbBase["base.py"]:::model
            EmbFactory["factory.py"]:::model
            LinProj["linear_projection.py"]:::model
            TempSpatial["temporal_spatial.py"]:::model
            TSConv["ts_convolutional.py"]:::model
        end
        subgraph "Binding"
            direction TB
            BindBasic["basic.py"]:::model
            BindAdd["additive.py"]:::model
            BindMul["multiplicative.py"]:::model
            BindConv["convolutional.py"]:::model
            BindFactory["factory.py"]:::model
        end
        subgraph "Positional Encoding"
            direction TB
            PEBase["base.py"]:::model
            PEFactory["factory.py"]:::model
            PESin["sinusoidal.py"]:::model
            PESplit["split_sinusoidal.py"]:::model
            PERand["random.py"]:::model
            PEFraq["fractional.py"]:::model
            PEAdap["adaptive_sinusoidal.py"]:::model
            PERotary["rotary.py"]:::model
            PETape["tape.py"]:::model
            PENull["null_pe.py"]:::model
        end
        subgraph "Transformer"
            direction TB
            subgraph "Attention"
                direction TB
                AttBase["base_multihead_attention.py"]:::model
                AttMulti["multi_head_attention.py"]:::model
                AttErpe["erpe_attention.py"]:::model
                AttRotary["rotary_multi_head_attention.py"]:::model
                AttSelf["self_attention.py"]:::model
                AttMla["mla.py"]:::model
                AttFactory["factory.py"]:::model
            end
            Enc["encoder.py"]:::model
            FF["feed_forward.py"]:::model
        end
        subgraph "Callbacks"
            direction TB
            LRFinder["fine_tune_lr_finder.py"]:::model
            Pocket["pocket_algorithm.py"]:::model
        end
    end

    %% Experiment Definitions
    subgraph "Experiment Definitions & Scripts"
        direction TB
        RunTS["src/experiments/time_series/run.py"]:::experiments
        BindingMethods["src/experiments/time_series/binding_methods/"]:::experiments
        BindingN4["src/experiments/time_series/binding_methods_N_L_4/"]:::experiments
        PEExp["src/experiments/time_series/positional_encodings/"]:::experiments
        SOTAExp["src/experiments/time_series/sota/"]:::experiments
        AggMetrics["src/experiments/aggregate_metrics.py"]:::experiments
        PEVis["src/experiments/pe_visualization/"]:::experiments
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        LogUtil["src/utils/log.py"]:::utils
        ConfigUtil["src/utils/config.py"]:::utils
        BaseConfig["src/utils/base_config.py"]:::utils
        CacheClean["src/utils/cache_cleaner.py"]:::utils
        PlotUtil["src/utils/plot.py"]:::utils
    end

    %% Data & Artifacts
    subgraph "Data & Artifacts"
        direction TB
        UCR["UCR/UEA Datasets"]:::external
        Artifacts["artifacts/"]:::data
        ExperResults["docs/experiment_results/"]:::data
        PlotsDoc["docs/plots/"]:::data
    end

    %% CI/Testing
    subgraph "Testing"
        direction TB
        TestMetrics["test_metrics_handler.py"]:::test
        TestTSClassifier["test_time_series_classifier.py"]:::test
        TestArgFmt["test_arg_formatter.py"]:::test
        TestMHA["test_multi_head_attention.py"]:::test
        TestSelfAtt["test_self_attention.py"]:::test
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch Backend"]:::external
    end

    %% Relationships
    Makefile -->|invokes| RunTS
    InstallScript -->|setup| ExperimentFramework
    CudaScript -->|setup| PyTorch

    RunTS -->|loads config| ConfigPkg
    RunTS -->|instantiates| DataPkg
    RunTS -->|instantiates| ModelFactory
    DataPkg -->|fetches| UCR
    DataPkg -->|preprocess| Artifacts
    ModelFactory --> Arch
    Arch --> EmbFactory
    EmbFactory --> EmbBase
    EmbFactory --> LinProj
    EmbFactory --> TempSpatial
    EmbFactory --> TSConv
    BindFactory --> BindBasic
    BindFactory --> BindAdd
    BindFactory --> BindMul
    BindFactory --> BindConv
    PEFactory --> PEBase
    PEFactory --> PESin
    PEFactory --> PESplit
    PEFactory --> PERand
    PEFactory --> PEFraq
    PEFactory --> PEAdap
    PEFactory --> PERotary
    PEFactory --> PETape
    PEFactory --> PENull
    ModelFactory --> BindFactory
    ModelFactory --> PEFactory
    ModelFactory --> AttFactory
    AttFactory --> AttBase
    AttFactory --> AttMulti
    AttFactory --> AttErpe
    AttFactory --> AttRotary
    AttFactory --> AttSelf
    AttFactory --> AttMla
    ModelFactory --> Enc
    ModelFactory --> FF
    RunnerPkg
```
