# aspiaspace/earthpt architecture

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

- Interactive diagram: https://gitdiagram.com/aspiaspace/earthpt
- Repository: https://github.com/aspiaspace/earthpt

## Overview

##### Project type and purpose
- EarthPT is a domain-specific, full-stack (code-only) machine learning project for time-series Earth Observation (EO) modeling.
- Its primary goal is to train a GPT-style large observation model on satellite time-series data (EarthPT-700M).

##### File structure
Top-level:
- config/           – Python configuration modules (e.g., earthpt700m.py)
- data/             – data preparation scripts (prepare_data.py)
- src/              – core code: configurator, model definition, sampling, training
- requirements.txt  – dependencies
- README.md         – project overview
- COPYING           – license
Patterns & Roles:
- config/earthpt700m.py – hyperparameters & paths for a specific model
- data/prepare_data.py  – raw EO ingestion & tokenization
- src/configurator.py   – unified config loader and experiment manager
- src/model.py          – GPT model + MLP tokenizer + loss
- src/sample_eo.py      – inference / sample generation module
- src/train.py          – training loop (+ logging & checkpointing)

##### README for additional insights
- The README confirms the core workflow: data preparation → model definition → training → evaluation.
- Dependencies: standard ML ecosystem (PyTorch, numpy, etc.).
- External integrations: HuggingFace for pretrained weights, ArXiv / CCAI for citations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Pipeline
    subgraph "Data Pipeline"
        RawData["Raw EO Data"]:::external
        DataPrep["Data Prep"]:::code
        TokenDataset["Tokenized Dataset"]:::datastore
    end

    %% Core Modules
    subgraph "Core Modules"
        Configurator["Configurator"]:::code
        ConfigFile["Config: earthpt700m.py"]:::code
        Model["Model Definition"]:::code
        Trainer["Training Loop"]:::code
        Sampler["Sampling Module"]:::code
    end

    %% Runtime
    subgraph "Runtime"
        ComputeCluster["Compute Cluster (8×A100 GPUs)"]:::compute
    end

    %% Storage
    subgraph "Storage"
        Checkpoints["Checkpoints & Logs"]:::datastore
        GeneratedSeq["Generated Sequences"]:::datastore
    end

    %% External Services
    subgraph "External Services"
        HFHub["HuggingFace Hub"]:::external
    end

    %% Documentation
    subgraph "Docs & Metadata"
        Assets["Assets"]:::external
        Readme["README.md"]:::external
        Requirements["requirements.txt"]:::external
        License["COPYING"]:::external
    end

    %% Connections
    RawData -->|ingest & tokenize| DataPrep
    DataPrep --> TokenDataset
    TokenDataset --> Trainer
    ConfigFile --> Configurator
    Configurator --> Trainer
    Configurator --> Sampler
    Trainer -->|logs & checkpoints| Checkpoints
    Trainer -->|compute| ComputeCluster
    ComputeCluster -->|accelerates| Trainer
    Checkpoints <-->|push/pull| HFHub
    Checkpoints --> Sampler
    Sampler --> GeneratedSeq

    %% Click Events
    click DataPrep "https://github.com/aspiaspace/earthpt/blob/main/data/prepare_data.py"
    click Configurator "https://github.com/aspiaspace/earthpt/blob/main/src/configurator.py"
    click Model "https://github.com/aspiaspace/earthpt/blob/main/src/model.py"
    click Trainer "https://github.com/aspiaspace/earthpt/blob/main/src/train.py"
    click Sampler "https://github.com/aspiaspace/earthpt/blob/main/src/sample_eo.py"
    click ConfigFile "https://github.com/aspiaspace/earthpt/blob/main/config/earthpt700m.py"
    click Assets "https://github.com/aspiaspace/earthpt/tree/main/assets/"
    click Readme "https://github.com/aspiaspace/earthpt/blob/main/README.md"
    click Requirements "https://github.com/aspiaspace/earthpt/blob/main/requirements.txt"
    click License "https://github.com/aspiaspace/earthpt/tree/main/COPYING"

    %% Styles
    classDef code fill:#f9f,stroke:#a0a,stroke-width:2px
    classDef datastore fill:#ff9,stroke:#d33,stroke-width:2px
    classDef external fill:#9cf,stroke:#06c,stroke-width:2px
    classDef compute fill:#cfc,stroke:#090,stroke-width:2px
```
