# waymentsteelelab/dyna-1 architecture

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

- Interactive diagram: https://gitdiagram.com/waymentsteelelab/dyna-1
- Repository: https://github.com/waymentsteelelab/dyna-1

## Overview

##### Project Type and Purpose
- Dyna-1 is a research-oriented protein dynamics prediction tool. It takes protein sequence and/or structure as input and predicts the probability of micro-to-millisecond motions per residue.
- The README makes it clear that Dyna-1 leverages pre-trained models (ESM-3 and ESM-2 embeddings) for inference, is used for scientific research, and includes components for visualization (via PyMol) and analysis (via Jupyter notebooks).

##### File Structure to Extract Main Components
- Top-level directories:
– analysis: Contains Jupyter notebooks that analyze datasets and model outputs.
– assets: Stores images (e.g., for the README) used in documentation.
– colab: Provides Google Colab notebooks to demo/infer using Dyna-1.
– configs: Contains configuration files (e.g., af2.yml, esm2.yml, and esm3.yml) which suggest configurable model settings.
– data: Holds multiple types of datasets (JSON zip files, Excel spreadsheets, CSVs) and dataloader scripts. This clearly shows data ingestion and pre-processing are integral.
– esm: A large folder with submodules (data, layers, models, tokenization, utils, widgets) – essentially encapsulating the ESM (Evolutionary Scale Model) framework and associated utilities. This is used to process sequence/structure data and interface with pre-trained model weights.
– model: Houses the main implementation for Dyna-1 (e.g., model.py, naive_classifier.py, transformer.py) along with a folder for model weights – this forms the core prediction engine.
– scripts: Provides shell scripts to evaluate different configurations or variants of the model.
– Other files (e.g., dyna1.py, dyna1-esm2.py) are direct entry points for inference using different pre-trained weights.
- Additional configuration and utility files (e.g., requirements.txt, utils.py, LICENSE.txt) support deployment and reproducible research.

##### Design the System Components
A. Data Ingestion & Preprocessing
– Include data sources (datasets in JSON, CSV, Excel, and compressed files in the “data” folder).
– The “data/dataloader.py” and related scripts handle file parsing, splitting, and vocabulary processing.
B. Configuration Management
– The “configs” folder holds YAML files that define model parameters for various run modes (af2, baseline, esm2, esm3).
C. Core Model & Prediction Engine
– The Dyna-1 model code in the “model” directory implements the prediction logic.
– It integrates components from the “esm” folder, such as layers, tokenization, and pre-trained model modules.
D. ESM Framework Integration
– The “esm” directory encompasses:
- Data management (for handling domain-specific inputs),
- Model layers (attention, transformer stacks, etc.),
- Tokenization strategies for sequences and structures,
- SDK/API components (e.g., for integration with HuggingFace and Sagemaker).
– This should be depicted as a unified module that the Dyna-1 engine leverages.
E. Inference Interfaces & Scripts
– Represent the various command-line interfaces (dyna1.py, dyna1-esm2.py) and the “scripts” folder that facilitates evaluation of different configurations.
F. Analysis & Visualization
– Additionally, illustrate the connection to external visualization tools like PyMol (used for putty-rendered structures).
G. External Dependencies & Integration Points

##### Design Principles and Relationships Between Components
- Clear separation between configuration, data processing, model prediction, and visualization.
- That the inference scripts (dyna1.py and dyna1-esm2.py) serve as entry points that integrate multiple backend modules (esm, model, and data).
- Use connectors to indicate that the “esm” framework provides pre-trained model functionality which is wrapped by the Dyna-1 predictive model.
- That modularity exists via the configuration files allowing the same structure to run different model configurations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion & Preprocessing
    subgraph "Data Ingestion & Preprocessing"
        DS["Datasets"]:::module
        DL["Data Loader"]:::module
        VP["Vocabulary Processor"]:::module
        DS --> DL
        DL --> VP
    end

    %% Configuration Management
    subgraph "Configuration Management"
        CF["Configuration Files"]:::config
    end

    %% ESM Framework Integration
    subgraph "ESM Framework Integration"
        ESM["ESM Framework"]:::module
        ESMData["ESM Data"]:::module
        ESMLayers["ESM Layers"]:::module
        ESMModels["ESM Models"]:::module
        ESMToken["ESM Tokenization"]:::module
        ESMUtils["ESM Utils"]:::module
        ESMWidgets["ESM Widgets"]:::module
        ESM --> ESMData
        ESM --> ESMLayers
        ESM --> ESMModels
        ESM --> ESMToken
        ESM --> ESMUtils
        ESM --> ESMWidgets
    end

    %% Core Model & Prediction Engine
    subgraph "Core Model & Prediction Engine"
        CM["Model Core"]:::module
        NC["Naive Classifier"]:::module
        TM["Transformer Module"]:::module
        Dyna1ESM3["Dyna1 Inference (ESM-3)"]:::inference
        Dyna1ESM2["Dyna1 Inference (ESM-2)"]:::inference
        EScripts["Evaluation Scripts"]:::module
        CM --> NC
        CM --> TM
        Dyna1ESM3 --> CM
        Dyna1ESM2 --> CM
        EScripts --> CM
    end

    %% Analysis & Visualization
    subgraph "Analysis & Visualization"
        AN["Analysis Notebooks"]:::analysis
        CN["Colab Notebooks"]:::analysis
        PM["PyMol Visualization"]:::external
    end

    %% External Dependencies & Integration Points
    subgraph "External Dependencies"
        PT["PyTorch"]:::external
        HF["HuggingFace"]:::external
        ELM["ESM Licensing"]:::external
    end

    %% Data flow connections
    VP --> CM
    CF --> CM
    ESM --> CM
    Dyna1ESM3 --> ESM
    Dyna1ESM2 --> ESM

    %% External dependencies connections
    PT --- ESM
    HF --- ESM
    HF --- CM
    ELM --- ESM

    %% Output flow to Analysis & Visualization
    CM --> AN
    CM --> CN
    CM --> PM

    %% Click Events
    click DL "https://github.com/waymentsteelelab/dyna-1/blob/main/data/dataloader.py"
    click VP "https://github.com/waymentsteelelab/dyna-1/blob/main/data/vocab.py"
    click DS "https://github.com/waymentsteelelab/dyna-1/tree/main/data/"
    click CF "https://github.com/waymentsteelelab/dyna-1/tree/main/configs/"
    click CM "https://github.com/waymentsteelelab/dyna-1/tree/main/model/"
    click Dyna1ESM3 "https://github.com/waymentsteelelab/dyna-1/blob/main/dyna1.py"
    click Dyna1ESM2 "https://github.com/waymentsteelelab/dyna-1/blob/main/dyna1-esm2.py"
    click EScripts "https://github.com/waymentsteelelab/dyna-1/tree/main/scripts/"
    click ESM "https://github.com/waymentsteelelab/dyna-1/tree/main/esm/"
    click AN "https://github.com/waymentsteelelab/dyna-1/tree/main/analysis/"
    click CN "https://github.com/waymentsteelelab/dyna-1/tree/main/colab/"

    %% Styles
    classDef module fill:#fde2e2,stroke:#b30000,stroke-width:2px;
    classDef config fill:#e2f7e2,stroke:#007300,stroke-width:2px;
    classDef inference fill:#e2eaf7,stroke:#0000b3,stroke-width:2px;
    classDef analysis fill:#fff2cc,stroke:#b38f00,stroke-width:2px;
    classDef external fill:#e6f7ff,stroke:#0073e6,stroke-width:2px;
```
