# hparklab/ifum architecture

> Architecture diagram of the GitHub repository hparklab/ifum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hparklab/ifum
- Repository: https://github.com/hparklab/ifum

## Overview

IFUM predicts protein folding stability (ΔG) from sequence or folded structures. Its main workflow accepts FASTA or PDB/CIF input, predicts structures for FASTA with ESMFold, creates ProtT5 and ESM-IF1 embeddings, packages those with folded-state coordinates, runs the pretrained IEFFEUM model, and writes CSV predictions; optional per-residue output annotates structures. A separate training workflow prepares embeddings and trains the model. The sampled sources show the inference helpers, dataset, model, training, and visualization code; some internal calls in the unsampled portions of predict.py are therefore supported by its documented workflow rather than inspected implementation.

Main entry points: [`scripts/predict.py`](https://github.com/hparklab/ifum/blob/main/scripts/predict.py) (Prediction driver), [`src/IEFFEUM/model.py`](https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/model.py) (IEFFEUM model), [`src/IEFFEUM/utils.py`](https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/utils.py) (Inference helpers), [`scripts/training/train.py`](https://github.com/hparklab/ifum/blob/main/scripts/training/train.py) (Model trainer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inference["Prediction workflow"]
  node_predict["Prediction driver<br/>[predict.py]"]
  node_csv["ΔG CSV"]
end

subgraph group_features["Structure and features"]
  node_esmfold["ESMFold"]
  node_structure_features["Structure embeddings<br/>[predict.py]"]
  node_sequence_features["Sequence embeddings<br/>[predict.py]"]
  node_prepared_inputs["Prepared inputs<br/>[predict.py]"]
end

subgraph group_runtime["Inference runtime"]
  node_dataset["Embedding dataset<br/>[dataset.py]"]
  node_collation["Batch collation<br/>[dataset.py]"]
  node_inference_helpers["Inference helpers<br/>[utils.py]"]
  node_ifum_model["IEFFEUM model<br/>[model.py]"]
  node_weights["Model parameters<br/>[params.pth]"]
end

subgraph group_training["Training"]
  node_training_prep["Training embeddings"]
  node_training_data["Training data"]
  node_trainer["Model trainer<br/>[train.py]"]
  node_flory["Unfolded ensemble<br/>[flory.py]"]
end

subgraph group_interpretation["Per-residue interpretation"]
  node_per_residue["Residue annotation<br/>[predict.py]"]
  node_visualizer["Structure coloring<br/>[per_resi_dG.py]"]
end

node_user(("Protein researcher"))
node_fasta["FASTA sequences"]
node_structures["PDB/CIF structures"]

node_user -->|"runs"| node_predict
node_fasta -->|"provides sequence"| node_predict
node_structures -->|"provides structures"| node_predict
node_predict -.->|"predicts structures"| node_esmfold
node_predict -->|"extracts embeddings"| node_structure_features
node_predict -->|"generates embeddings"| node_sequence_features
node_predict -->|"packages features"| node_prepared_inputs
node_prepared_inputs -->|"loads files"| node_dataset
node_dataset -->|"pads batches"| node_collation
node_predict -->|"loads inference"| node_inference_helpers
node_inference_helpers -->|"constructs dataset"| node_dataset
node_inference_helpers -->|"loads model"| node_ifum_model
node_weights -->|"parameter state"| node_ifum_model
node_predict -->|"runs prediction"| node_ifum_model
node_predict -->|"writes results"| node_csv
node_user -.->|"prepares training"| node_training_prep
node_training_prep -->|"saves embeddings"| node_training_data
node_training_data -->|"loads examples"| node_trainer
node_trainer -->|"trains model"| node_ifum_model
node_trainer -.->|"builds ensemble"| node_flory
node_predict -->|"optionally annotates"| node_per_residue
node_per_residue -.->|"writes annotations"| node_visualizer

click node_predict "https://github.com/hparklab/ifum/blob/main/scripts/predict.py"
click node_structure_features "https://github.com/hparklab/ifum/blob/main/scripts/predict.py"
click node_sequence_features "https://github.com/hparklab/ifum/blob/main/scripts/predict.py"
click node_prepared_inputs "https://github.com/hparklab/ifum/blob/main/scripts/predict.py"
click node_dataset "https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/dataset.py"
click node_collation "https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/dataset.py"
click node_inference_helpers "https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/utils.py"
click node_ifum_model "https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/model.py"
click node_weights "https://github.com/hparklab/ifum/blob/main/weights/params.pth"
click node_training_prep "https://github.com/hparklab/ifum/blob/main/scripts/training/prepare_embeddings.py"
click node_trainer "https://github.com/hparklab/ifum/blob/main/scripts/training/train.py"
click node_flory "https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/flory.py"
click node_per_residue "https://github.com/hparklab/ifum/blob/main/scripts/predict.py"
click node_visualizer "https://github.com/hparklab/ifum/blob/main/scripts/per_resi_dG.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_predict,node_csv toneBlue
class node_esmfold,node_structure_features,node_sequence_features,node_prepared_inputs toneAmber
class node_dataset,node_collation,node_inference_helpers,node_ifum_model,node_weights toneMint
class node_training_prep,node_training_data,node_trainer,node_flory toneRose
class node_per_residue,node_visualizer,node_user,node_fasta,node_structures toneIndigo
```

## Components

### Prediction workflow

- [Prediction driver](https://github.com/hparklab/ifum/blob/main/scripts/predict.py): `scripts/predict.py`
- **ΔG CSV**

### Structure and features

- **ESMFold**
- [Structure embeddings](https://github.com/hparklab/ifum/blob/main/scripts/predict.py): `scripts/predict.py`
- [Sequence embeddings](https://github.com/hparklab/ifum/blob/main/scripts/predict.py): `scripts/predict.py`
- [Prepared inputs](https://github.com/hparklab/ifum/blob/main/scripts/predict.py): `scripts/predict.py`

### Inference runtime

- [Embedding dataset](https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/dataset.py): `src/IEFFEUM/dataset.py`
- [Batch collation](https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/dataset.py): `src/IEFFEUM/dataset.py`
- [Inference helpers](https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/utils.py): `src/IEFFEUM/utils.py`
- [IEFFEUM model](https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/model.py): `src/IEFFEUM/model.py`
- [Model parameters](https://github.com/hparklab/ifum/blob/main/weights/params.pth): `weights/params.pth`

### Training

- [Training embeddings](https://github.com/hparklab/ifum/blob/main/scripts/training/prepare_embeddings.py): `scripts/training/prepare_embeddings.py`
- **Training data**
- [Model trainer](https://github.com/hparklab/ifum/blob/main/scripts/training/train.py): `scripts/training/train.py`
- [Unfolded ensemble](https://github.com/hparklab/ifum/blob/main/src/IEFFEUM/flory.py): `src/IEFFEUM/flory.py`

### Per-residue interpretation

- [Residue annotation](https://github.com/hparklab/ifum/blob/main/scripts/predict.py): `scripts/predict.py`
- [Structure coloring](https://github.com/hparklab/ifum/blob/main/scripts/per_resi_dG.py): `scripts/per_resi_dG.py`

### Other components

- **Protein researcher**
- **FASTA sequences**
- **PDB/CIF structures**

## Connections

- Protein researcher → Prediction driver: runs (evidence: `README.md`)
- FASTA sequences → Prediction driver: provides sequence (evidence: `README.md`)
- PDB/CIF structures → Prediction driver: provides structures (evidence: `README.md`)
- Prediction driver → ESMFold: predicts structures (evidence: `README.md`)
- Prediction driver → Structure embeddings: extracts embeddings (evidence: `scripts/predict.py`)
- Prediction driver → Sequence embeddings: generates embeddings (evidence: `scripts/predict.py`)
- Prediction driver → Prepared inputs: packages features (evidence: `scripts/predict.py`)
- Prepared inputs → Embedding dataset: loads files
- Embedding dataset → Batch collation: pads batches (evidence: `src/IEFFEUM/dataset.py`)
- Prediction driver → Inference helpers: loads inference (evidence: `scripts/predict.py`)
- Inference helpers → Embedding dataset: constructs dataset (evidence: `src/IEFFEUM/utils.py`)
- Inference helpers → IEFFEUM model: loads model (evidence: `src/IEFFEUM/utils.py`)
- Model parameters → IEFFEUM model: parameter state
- Prediction driver → IEFFEUM model: runs prediction (evidence: `README.md`)
- Prediction driver → ΔG CSV: writes results (evidence: `README.md`)
- Protein researcher → Training embeddings: prepares training (evidence: `scripts/training/prepare_embeddings.py`)
- Training embeddings → Training data: saves embeddings (evidence: `scripts/training/prepare_embeddings.py`)
- Training data → Model trainer: loads examples (evidence: `scripts/training/train.py`)
- Model trainer → IEFFEUM model: trains model (evidence: `scripts/training/train.py`)
- Model trainer → Unfolded ensemble: builds ensemble
- Prediction driver → Residue annotation: optionally annotates (evidence: `scripts/predict.py`)
- Residue annotation → Structure coloring: writes annotations
