# pku-yuangroup/taxdiff architecture

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

- Interactive diagram: https://gitdiagram.com/pku-yuangroup/taxdiff
- Repository: https://github.com/pku-yuangroup/taxdiff

## Overview

##### Project Type and Purpose
- TaxDiff is a Python-based, diffusion-model inference tool for taxonomic-guided protein sequence generation.
- It provides only inference code; training will be released later.

##### Core Components (and their locations)
a. Data Sources & Artifacts
- taxonomy labels: data_reader/Taxonnmic_classfication.xlsx
- decoder vocabulary: decoder_data/model_10.txt and model_10_info.txt
- pretrained weights: ckpt/0012802_eval.pt
b. Code Modules
- data_reader/decoder.py – loads taxonomy labels and decodes tokens
- models.py – defines the protein transformer architecture
- diffusion/gaussian_diffusion.py – core diffusion operations
- diffusion/timestep_sampler.py – schedules and samples timesteps
- diffusion/respace.py – timestep rescaling utilities
- diffusion/diffusion_utils.py – helper functions (noise scheduler, loss)
- sample_protein.py – CLI entry point for inference
c. Output
- Generated protein sequences file (e.g., GeneratedSequences.txt)

##### Key Interaction Flow
- sample_protein.py loads taxonomy labels via decoder.py
- It loads the pretrained checkpoint
- Instantiates the model (models.py) and diffusion modules
- Executes the reverse diffusion loop: at each timestep, NoiseSampler → ReverseStep → ConditionalGuidance → next ReverseStep
- Decodes tokens back to amino acid sequences → writes output file

##### Architectural Patterns & Design Principles
- Modular separation: data ingestion vs. model definition vs. inference logic
- Emphasis on the diffusion loop as the computational core

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "DataSources"
        A1["data_reader/Taxonnmic_classfication.xlsx"]:::data
        A2["decoder_data/model_10.txt"]:::data
        A3["decoder_data/model_10_info.txt"]:::data
        A4["ckpt/0012802_eval.pt"]:::checkpoint
    end

    subgraph "Modules"
        B1["data_reader/decoder.py"]:::module
        B2["sample_protein.py"]:::module
        B3["models.py"]:::module
        B4["diffusion/gaussian_diffusion.py"]:::module
        B5["diffusion/timestep_sampler.py"]:::module
        B6["diffusion/respace.py"]:::module
        B7["diffusion/diffusion_utils.py"]:::module
    end

    subgraph "Diffusion Reverse Process"
        DL1["NoiseSampler"]:::function
        DL2["ReverseStep"]:::function
        DL3["ConditionalGuidance"]:::function
    end

    A1 --> B1
    A2 --> B1
    A3 --> B1
    B1 --> B2
    A4 --> B2
    B2 --> B3
    B3 --> B4
    B4 --> DL1
    DL1 --> DL2
    DL2 --> DL3
    DL3 --> DL2
    DL2 --> B2
    B2 --> Z["GeneratedSequences.txt"]:::output

    click A1 "https://github.com/pku-yuangroup/taxdiff/blob/main/data_reader/Taxonnmic_classfication.xlsx"
    click A2 "https://github.com/pku-yuangroup/taxdiff/blob/main/decoder_data/model_10.txt"
    click A3 "https://github.com/pku-yuangroup/taxdiff/blob/main/decoder_data/model_10_info.txt"
    click A4 "https://github.com/pku-yuangroup/taxdiff/blob/main/ckpt/0012802_eval.pt"
    click B1 "https://github.com/pku-yuangroup/taxdiff/blob/main/data_reader/decoder.py"
    click B2 "https://github.com/pku-yuangroup/taxdiff/blob/main/sample_protein.py"
    click B3 "https://github.com/pku-yuangroup/taxdiff/blob/main/models.py"
    click B4 "https://github.com/pku-yuangroup/taxdiff/blob/main/diffusion/gaussian_diffusion.py"
    click B5 "https://github.com/pku-yuangroup/taxdiff/blob/main/diffusion/timestep_sampler.py"
    click B6 "https://github.com/pku-yuangroup/taxdiff/blob/main/diffusion/respace.py"
    click B7 "https://github.com/pku-yuangroup/taxdiff/blob/main/diffusion/diffusion_utils.py"

    classDef data fill:#cfe2f3,stroke:#0c4a6e,stroke-width:1px,shape:cylinder
    classDef checkpoint fill:#fde68a,stroke:#b45309,stroke-width:1px,shape:cylinder
    classDef module fill:#e2e8f0,stroke:#1e293b,stroke-width:1px,shape:rectangle
    classDef function fill:#dbeafe,stroke:#1e3a8a,stroke-width:1px,shape:rectangle
    classDef output fill:#d1fae5,stroke:#166534,stroke-width:1px,shape:note
```
