# jiaxiang-cheng/pytorch-transformer-for-rul-prediction architecture

> Architecture diagram of the GitHub repository jiaxiang-cheng/pytorch-transformer-for-rul-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction
- Repository: https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction

## Overview

##### Project type & purpose (what you’re diagramming)
This is **not** a multi-service “system” in the web sense; it’s a **single-node ML training/evaluation pipeline** implemented in Python using **PyTorch**, for **Remaining Useful Life (RUL) prediction** on the **NASA CMAPSS turbofan datasets (FD001–FD004)**.

##### What the repo structure implies (map files to responsibilities)
From the tree + README, the core components are:

##### Data assets
- `CMAPSSData/`
- `train_FD00x.txt`, `test_FD00x.txt`, `RUL_FD00x.txt`: raw CMAPSS splits + ground-truth RUL for test engines.
- `Damage Propagation Modeling.pdf`, `readme.txt`: dataset documentation.

##### Data preprocessing / feature-label construction
- `add_remaining_useful_life.py`
- Likely computes per-timestep RUL labels for training trajectories (common CMAPSS step: `RUL = max_cycle - current_cycle`, maybe capped).
- `loading_data.py`
- Likely parses the CMAPSS text files into pandas/numpy and/or builds PyTorch datasets/dataloaders (windowing / normalization / sensor selection).

##### Model definition
- `model.py`
- Defines the **Transformer encoder + convolutional layers** (as described in README). This is the “core IP” of the repo.

##### Training / evaluation / experimentation
- `train.py`
- Entry point (`python train.py --dataset FD001`), orchestrates: load data → build model → train epochs → evaluate each epoch → print loss/RMSE.
- `testing.py`
- Encapsulates evaluation logic and RMSE computation on the test set (likely uses `RUL_FD00x.txt` for final per-engine RUL).
- Produces plots (loss curves, predicted vs actual RUL, etc.) using matplotlib.

##### Environment / packaging
- `requirements.txt`: pins dependencies.

##### Data layer (left side)
- **CMAPSS Raw Files**
- `train_FD00x.txt`
- `test_FD00x.txt`
- `RUL_FD00x.txt`
- **Dataset selection**
- CLI arg: `--dataset FD001` (in `train.py`) controls which files are loaded.

##### Data processing layer
- **Parser/Loader** (`loading_data.py`)
- Reads text → pandas/numpy tables
- Splits into train/val/test (if implemented)
- Adds computed RUL labels for training series
- **Windowing / Sequence builder** (often in loader)
- Converts per-engine time series into fixed-length sequences for Transformer input
- **Normalization / scaling**
- Often applied per-sensor; show it as a distinct component even if it’s just a few lines in `loading_data.py`.
- **PyTorch Dataset / DataLoader**
- Produces batched tensors to the training loop

##### Model layer (center)
Inside `model.py`, represent subcomponents explicitly:
- **Input embedding / projection** (if present)
- **Convolutional feature extractor**
- (1D conv blocks / gated conv unit per cited paper)
- **Transformer Encoder stack**
- Multi-head self-attention
- Feed-forward layers
- Residual + LayerNorm (if implemented)
- **Regression head**
- Maps encoder output → scalar RUL prediction

##### Training & evaluation layer (right side)
- **Training Orchestrator** (`train.py`)
- Argument parsing
- Instantiates dataset/dataloader and model
- Optimizer + loss function
- Epoch loop
- **Backprop / Optimizer step**
- “Loss → gradients → weight update”
- **Evaluation** (`testing.py`)
- Runs model on test set
- Computes **RMSE** (explicitly called out in README)
- Plots metrics/predictions

##### Outputs / artifacts (far right / bottom)
- **Console metrics**
- Epoch loss, RMSE
- (If implemented) **Model checkpoints**
- e.g., `*.pt` / `*.pth` (not in tree, but many training scripts save weights—confirm by scanning `train.py`)
- **Plots**

##### each epoch: `train.py` → `testing.py` → RMSE result → `train.py` prints

**library dependencies** as annotations:
- `loading_data.py` depends on **pandas/numpy**
- `model.py/train.py/testing.py` depend on **PyTorch**

##### Architectural patterns to highlight (what’s “important” here)
- **Pipeline architecture**: deterministic flow from raw data → processed sequences → model → metrics.
- **Separation of concerns by file**:
- data prep (`loading_data.py`, `add_remaining_useful_life.py`)
- model definition (`model.py`)
- orchestration (`train.py`)
- evaluation (`testing.py`)
- **Sequence modeling** pattern:
- convolutional front-end (local feature extraction)
- transformer encoder (global temporal dependencies)
- regression head (scalar RUL)

- **Clear labels**: use filenames as subtitles (e.g., “Data Loader (loading_data.py)”).
- Rectangles: Python modules/scripts
- Rounded rectangles: runtime constructs (DataLoader, Optimizer)
- “sensor sequences”, “RUL labels”, “predicted RUL”, “loss”, “RMSE”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1 — System Context
  %% =========================
  subgraph "Diagram 1 — System Context (single-node offline ML workflow)"
    direction TB

    User["Researcher / Engineer"]:::external
    CLI["CLI command\npython train.py --dataset FD00x"]:::external

    TrainEntry["Training Orchestrator\n(train.py)"]:::script

    subgraph "CMAPSS Raw Dataset (NASA Turbofan)"
      direction TB
      CMAPSSDir[("CMAPSSData/")]:::data

      TrainFiles[("Train splits\ntrain_FD001–FD004.txt")]:::data
      TestFiles[("Test splits\ntest_FD001–FD004.txt")]:::data
      RULFiles[("Test ground-truth\nRUL_FD001–FD004.txt")]:::data
      Docs[("Docs\nreadme.txt + PDF")]:::data
    end

    Outputs["Outputs\nConsole metrics + plots\n(+ optional checkpoints)"]:::artifact
  end

  User -->|"runs"| CLI
  CLI -->|"invokes"| TrainEntry
  TrainEntry -->|"reads"| CMAPSSDir
  TrainEntry -->|"prints/saves"| Outputs

  %% ==========================================
  %% Diagram 2 — Training/Evaluation Dataflow
  %% ==========================================
  subgraph "Diagram 2 — Training/Evaluation Container & Dataflow (main pipeline)"
    direction TB

    subgraph "Data Processing Layer"
      direction TB
      Loader["Parser/Loader + Preprocessing\n(loading_data.py)"]:::script
      RULBuilder["RUL Label Construction\n(add_remaining_useful_life.py)"]:::script

      Parse["Parse CMAPSS .txt -> tables\n(pandas/numpy)"]:::process
      Normalize["Normalization / scaling\n(per-sensor)"]:::process
      Windowing["Windowing / sequence builder\n(fixed-length sequences)"]:::process

      TorchDataset["PyTorch Dataset"]:::runtime
      TorchLoader["PyTorch DataLoader\n(batched tensors)"]:::runtime
    end

    subgraph "Model Layer"
      direction TB
      ModelDef["Model Definition\n(model.py)"]:::model
      ModelForward["Forward pass\nsensor sequence -> predicted RUL"]:::runtime
    end

    subgraph "Training & Evaluation Layer"
      direction TB
      TrainLoop["Epoch loop + optimization\n(train.py)"]:::script
      LossFn["Loss computation\n(e.g., MSE)"]:::runtime
      Backprop["Backpropagation\nloss -> gradients"]:::runtime
      Optim["Optimizer step\n(e.g., Adam)"]:::runtime

      TestLogic["Evaluation / Testing\n(testing.py)"]:::script
      RMSE["RMSE computation\n(on test set)"]:::metric

      Viz["Visualization\n(visualize.py)"]:::script
    end

    subgraph "Library Dependencies (annotations)"
      direction TB
      PandasNumpy["pandas / numpy"]:::lib
      PyTorch["PyTorch"]:::lib
      Matplotlib["matplotlib"]:::lib
    end
  end

  %% Dataset selection + raw inputs
  TrainEntry -->|"selects_dataset\nFD001–FD004"| Loader
  CMAPSSDir -->|"raw_files"| Loader
  TrainFiles -->|"train_FD00x.txt"| Loader
  TestFiles -->|"test_FD00x.txt"| Loader
  RULFiles -->|"RUL_FD00x.txt"| TestLogic
  Docs -.->|"reference"| Loader

  %% Preprocessing flow
  Loader -->|"uses"| Parse
  Parse -->|"tables"| Normalize
  Normalize -->|"normalized_sensors"| Windowing
  Windowing -->|"sensor_sequences"| RULBuilder
  RULBuilder -->|"RUL_labels"| TorchDataset
  Windowing -->|"sequences"| TorchDataset
  TorchDataset -->|"batches"| TorchLoader
  TorchLoader -->|"x,y batches"| TrainLoop

  %% Training flow
  TrainLoop -.->|"imports/instantiates"| ModelDef
  ModelDef -->|"builds"| ModelForward
  TrainLoop -->|"forward(x)"| ModelForward
  ModelForward -->|"predicted_RUL"| LossFn
  TrainLoop -->|"y_true"| LossFn
  LossFn -->|"loss"| Backprop
  Backprop -->|"gradients"| Optim
  Optim -->|"weight_update"| ModelDef

  %% Evaluation flow (per-epoch)
  TrainLoop -->|"each_epoch_eval"| TestLogic
  TestLogic -->|"runs_model_on_test"| ModelForward
  TestLogic -->|"compares_to_ground_truth"| RULFiles
  TestLogic -->|"computes"| RMSE
  RMSE -->|"reported_metric"| TrainLoop
  TrainLoop -->|"logs_metrics"| Outputs

  %% Visualization
  TrainLoop -.->|"passes_metrics/preds\nor reads logs"| Viz
  TestLogic -.->|"passes_preds/targets\nor reads logs"| Viz
  Viz -->|"plots"| Outputs

  %% Library dependencies (dashed)
  Loader -.->|"depends_on"| PandasNumpy
  Parse -.->|"depends_on"| PandasNumpy
  Normalize -.->|"depends_on"| PandasNumpy

  ModelDef -.->|"depends_on"| PyTorch
  TrainLoop -.->|"depends_on"| PyTorch
  LossFn -.->|"depends_on"| PyTorch
  Optim -.->|"depends_on"| PyTorch
  TestLogic -.->|"depends_on"| PyTorch

  Viz -.->|"depends_on"| Matplotlib

  %% ======================================
  %% Diagram 3 — Model Component Breakdown
  %% ======================================
  subgraph "Diagram 3 — Model Component Diagram (inside model.py)"
    direction TB

    ModelIn["Input tensor\n[batch, seq, sensors]"]:::tensor

    subgraph "Conv Feature Extractor"
      direction TB
      InProj["Input embedding / projection"]:::model
      ConvBlocks["1D Conv blocks\n(local temporal features)"]:::model
    end

    PosEnc["Positional encoding\n(sequence order signal)"]:::model

    subgraph "Transformer Encoder Stack"
      direction TB
      MHA["Multi-head self-attention"]:::model
      FFN["Feed-forward network"]:::model
      AddNorm["Residual + LayerNorm"]:::model
      EncOut["Encoder output\n[batch, seq, d_model]"]:::tensor
    end

    RegHead["Regression head\n-> scalar RUL"]:::model
    ModelOut["Predicted RUL\n[batch, 1]"]:::tensor
  end

  ModelIn -->|"project"| InProj
  InProj -->|"features"| ConvBlocks
  ConvBlocks -->|"tokens"| PosEnc
  PosEnc -->|"encoded_tokens"| MHA
  MHA -->|"attended"| AddNorm
  AddNorm -->|"normalized"| FFN
  FFN -->|"refined"| AddNorm
  AddNorm -->|"stack_output"| EncOut
  EncOut -->|"pool/select_timestep"| RegHead
  RegHead -->|"prediction"| ModelOut

  %% ============
  %% Click events
  %% ============
  click CMAPSSDir "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/tree/master/CMAPSSData/"
  click TrainFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/train_FD001.txt"
  click TestFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/test_FD001.txt"
  click RULFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/RUL_FD001.txt"
  click Docs "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/readme.txt"

  click Loader "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/loading_data.py"
  click RULBuilder "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/add_remaining_useful_life.py"
  click ModelDef "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/model.py"
  click TrainEntry "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/train.py"
  click TrainLoop "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/train.py"
  click TestLogic "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/testing.py"
  click Viz "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/visualize.py"

  %% Additional mapped raw files (direct click targets)
  click TrainFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/train_FD002.txt"
  click TrainFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/train_FD003.txt"
  click TrainFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/train_FD004.txt"
  click TestFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/test_FD002.txt"
  click TestFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/test_FD003.txt"
  click TestFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/test_FD004.txt"
  click RULFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/RUL_FD002.txt"
  click RULFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/RUL_FD003.txt"
  click RULFiles "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/RUL_FD004.txt"
  click Docs "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/CMAPSSData/Damage Propagation Modeling.pdf"

  %% Repo meta
  click Outputs "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/README.md"
  click PandasNumpy "https://github.com/jiaxiang-cheng/pytorch-transformer-for-rul-prediction/blob/master/requirements.txt"

  %% ======
  %% Styles
  %% ======
  classDef external fill:#0b3d91,color:#ffffff,stroke:#072b66,stroke-width:1.5px
  classDef data fill:#1b5e20,color:#ffffff,stroke:#0f3d14,stroke-width:1.5px
  classDef script fill:#4a148c,color:#ffffff,stroke:#2e0d57,stroke-width:1.5px
  classDef process fill:#6a1b9a,color:#ffffff,stroke:#3f0f5b,stroke-width:1.5px
  classDef runtime fill:#006064,color:#ffffff,stroke:#00363a,stroke-width:1.5px
  classDef model fill:#ad1457,color:#ffffff,stroke:#6b0c35,stroke-width:1.5px
  classDef metric fill:#e65100,color:#ffffff,stroke:#8a2f00,stroke-width:1.5px
  classDef artifact fill:#263238,color:#ffffff,stroke:#11181d,stroke-width:1.5px
  classDef lib fill:#37474f,color:#ffffff,stroke:#1f2a30,stroke-width:1.5px
  classDef tensor fill:#c62828,color:#ffffff,stroke:#7a1717,stroke-width:1.5px
```
