# zhenjiagan/cateso architecture

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

- Interactive diagram: https://gitdiagram.com/zhenjiagan/cateso
- Repository: https://github.com/zhenjiagan/cateso

## Overview

CatESO predicts enzyme kcat from protein embeddings and substrate molecular graphs, and optimizes enzyme sequences against that prediction objective. Its main paths are embedding generation, ensemble training/inference, and differentiable sequence optimization with optional ESMFold structural constraints. The graph also shows the model and structure-prediction layers. Relationships are based on README statements and SOURCE INDEX references; unsampled implementation details are not expanded.

Main entry points: [`models.py`](https://github.com/zhenjiagan/cateso/blob/main/models.py) (CatESO Model), [`esm/esmfold/v1/esmfold.py`](https://github.com/zhenjiagan/cateso/blob/main/esm/esmfold/v1/esmfold.py) (ESMFold), [`main_ensemble.py`](https://github.com/zhenjiagan/cateso/blob/main/main_ensemble.py) (Ensemble Training), [`inference.py`](https://github.com/zhenjiagan/cateso/blob/main/inference.py) (Ensemble Inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prediction["kcat Prediction"]
  node_train["Ensemble Training<br/>[main_ensemble.py]"]
  node_inference["Ensemble Inference<br/>[inference.py]"]
  node_dataset["Prediction Dataset<br/>[dataloader.py]"]
  node_trainer["Training Runtime<br/>[trainer.py]"]
end

subgraph group_embedding["Protein Embeddings"]
  node_embeddinggen["Embedding Generation<br/>[embedding.py]"]
  node_esm2["ESM-2<br/>[esm2.py]"]
  node_esmdata["Sequence Batching<br/>[data.py]"]
end

subgraph group_optimization["Sequence Optimization"]
  node_optimizerentry["Optimization Entry<br/>[main_optimize.py]"]
  node_seqopt["Sequence Optimizer"]
  node_esmmanager["ESM-2 Manager<br/>[esm_manager.py]"]
  node_foldconstraint["Fold Evaluator"]
end

subgraph group_structure["Structure Modeling"]
  node_esmfold["ESMFold<br/>[esmfold.py]"]
  node_foldtrunk["Folding Trunk<br/>[trunk.py]"]
  node_openfoldstructure["Structure Module"]
  node_proteincoords["Protein Structures<br/>[protein.py]"]
  node_residueconstants["Residue Constants"]
end

subgraph group_model["Model Internals"]
  node_catmodel["CatESO Model<br/>[models.py]"]
  node_fusion["Substrate Fusion<br/>[CN.py]"]
  node_proteinencoder["Protein Encoder<br/>[Encoder.py]"]
  node_transformer["Transformer Layers<br/>[Transformer.py]"]
end

node_user(("Researcher"))

node_user -->|"trains"| node_train
node_user -->|"requests prediction"| node_inference
node_user -->|"starts optimization"| node_optimizerentry
node_embeddinggen -->|"embeds sequences"| node_esm2
node_embeddinggen -.->|"batches sequences"| node_esmdata
node_train -->|"trains"| node_catmodel
node_train -.->|"uses runtime"| node_trainer
node_inference -->|"loads rows"| node_dataset
node_inference -->|"predicts with"| node_catmodel
node_dataset -->|"supplies inputs"| node_catmodel
node_catmodel -->|"uses"| node_fusion
node_catmodel -->|"uses"| node_proteinencoder
node_fusion -->|"uses"| node_transformer
node_optimizerentry -->|"runs"| node_seqopt
node_optimizerentry -->|"loads ESM-2"| node_esmmanager
node_seqopt -->|"optimizes against"| node_catmodel
node_seqopt -->|"requests constraint"| node_foldconstraint
node_foldconstraint -->|"evaluates folds"| node_esmfold
node_esmfold -->|"uses trunk"| node_foldtrunk
node_foldtrunk -->|"uses structure module"| node_openfoldstructure
node_esmfold -->|"uses residue definitions"| node_residueconstants
node_esmfold -->|"uses protein structures"| node_proteincoords
node_esmmanager -->|"loads model"| node_esm2

click node_train "https://github.com/zhenjiagan/cateso/blob/main/main_ensemble.py"
click node_inference "https://github.com/zhenjiagan/cateso/blob/main/inference.py"
click node_dataset "https://github.com/zhenjiagan/cateso/blob/main/run/dataloader.py"
click node_catmodel "https://github.com/zhenjiagan/cateso/blob/main/models.py"
click node_fusion "https://github.com/zhenjiagan/cateso/blob/main/module/CN.py"
click node_proteinencoder "https://github.com/zhenjiagan/cateso/blob/main/module/Encoder.py"
click node_transformer "https://github.com/zhenjiagan/cateso/blob/main/module/Transformer.py"
click node_embeddinggen "https://github.com/zhenjiagan/cateso/blob/main/scripts/embedding.py"
click node_esm2 "https://github.com/zhenjiagan/cateso/blob/main/esm/model/esm2.py"
click node_esmdata "https://github.com/zhenjiagan/cateso/blob/main/esm/data.py"
click node_trainer "https://github.com/zhenjiagan/cateso/blob/main/run/trainer.py"
click node_optimizerentry "https://github.com/zhenjiagan/cateso/blob/main/main_optimize.py"
click node_seqopt "https://github.com/zhenjiagan/cateso/blob/main/optimizer/sequence_optimizer.py"
click node_esmmanager "https://github.com/zhenjiagan/cateso/blob/main/optimizer/esm_manager.py"
click node_foldconstraint "https://github.com/zhenjiagan/cateso/blob/main/optimizer/esmfold_evaluator.py"
click node_esmfold "https://github.com/zhenjiagan/cateso/blob/main/esm/esmfold/v1/esmfold.py"
click node_foldtrunk "https://github.com/zhenjiagan/cateso/blob/main/esm/esmfold/v1/trunk.py"
click node_openfoldstructure "https://github.com/zhenjiagan/cateso/blob/main/openfold/openfold/model/structure_module.py"
click node_proteincoords "https://github.com/zhenjiagan/cateso/blob/main/openfold/openfold/np/protein.py"
click node_residueconstants "https://github.com/zhenjiagan/cateso/blob/main/openfold/openfold/np/residue_constants.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_train,node_inference,node_dataset,node_trainer toneBlue
class node_embeddinggen,node_esm2,node_esmdata toneAmber
class node_optimizerentry,node_seqopt,node_esmmanager,node_foldconstraint toneMint
class node_esmfold,node_foldtrunk,node_openfoldstructure,node_proteincoords,node_residueconstants toneRose
class node_catmodel,node_fusion,node_proteinencoder,node_transformer,node_user toneIndigo
```

## Components

### kcat Prediction

- [Ensemble Training](https://github.com/zhenjiagan/cateso/blob/main/main_ensemble.py): `main_ensemble.py`
- [Ensemble Inference](https://github.com/zhenjiagan/cateso/blob/main/inference.py): `inference.py`
- [Prediction Dataset](https://github.com/zhenjiagan/cateso/blob/main/run/dataloader.py): `run/dataloader.py`
- [Training Runtime](https://github.com/zhenjiagan/cateso/blob/main/run/trainer.py): `run/trainer.py`

### Protein Embeddings

- [Embedding Generation](https://github.com/zhenjiagan/cateso/blob/main/scripts/embedding.py): `scripts/embedding.py`
- [ESM-2](https://github.com/zhenjiagan/cateso/blob/main/esm/model/esm2.py): `esm/model/esm2.py`
- [Sequence Batching](https://github.com/zhenjiagan/cateso/blob/main/esm/data.py): `esm/data.py`

### Sequence Optimization

- [Optimization Entry](https://github.com/zhenjiagan/cateso/blob/main/main_optimize.py): `main_optimize.py`
- [Sequence Optimizer](https://github.com/zhenjiagan/cateso/blob/main/optimizer/sequence_optimizer.py): `optimizer/sequence_optimizer.py`
- [ESM-2 Manager](https://github.com/zhenjiagan/cateso/blob/main/optimizer/esm_manager.py): `optimizer/esm_manager.py`
- [Fold Evaluator](https://github.com/zhenjiagan/cateso/blob/main/optimizer/esmfold_evaluator.py): `optimizer/esmfold_evaluator.py`

### Structure Modeling

- [ESMFold](https://github.com/zhenjiagan/cateso/blob/main/esm/esmfold/v1/esmfold.py): `esm/esmfold/v1/esmfold.py`
- [Folding Trunk](https://github.com/zhenjiagan/cateso/blob/main/esm/esmfold/v1/trunk.py): `esm/esmfold/v1/trunk.py`
- [Structure Module](https://github.com/zhenjiagan/cateso/blob/main/openfold/openfold/model/structure_module.py): `openfold/openfold/model/structure_module.py`
- [Protein Structures](https://github.com/zhenjiagan/cateso/blob/main/openfold/openfold/np/protein.py): `openfold/openfold/np/protein.py`
- [Residue Constants](https://github.com/zhenjiagan/cateso/blob/main/openfold/openfold/np/residue_constants.py): `openfold/openfold/np/residue_constants.py`

### Model Internals

- [CatESO Model](https://github.com/zhenjiagan/cateso/blob/main/models.py): `models.py`
- [Substrate Fusion](https://github.com/zhenjiagan/cateso/blob/main/module/CN.py): `module/CN.py`
- [Protein Encoder](https://github.com/zhenjiagan/cateso/blob/main/module/Encoder.py): `module/Encoder.py`
- [Transformer Layers](https://github.com/zhenjiagan/cateso/blob/main/module/Transformer.py): `module/Transformer.py`

### Other components

- **Researcher**

## Connections

- Researcher → Ensemble Training: trains
- Researcher → Ensemble Inference: requests prediction
- Researcher → Optimization Entry: starts optimization
- Embedding Generation → ESM-2: embeds sequences
- Embedding Generation → Sequence Batching: batches sequences
- Ensemble Training → CatESO Model: trains
- Ensemble Training → Training Runtime: uses runtime
- Ensemble Inference → Prediction Dataset: loads rows (evidence: `inference.py`)
- Ensemble Inference → CatESO Model: predicts with (evidence: `inference.py`)
- Prediction Dataset → CatESO Model: supplies inputs
- CatESO Model → Substrate Fusion: uses (evidence: `models.py`)
- CatESO Model → Protein Encoder: uses (evidence: `models.py`)
- Substrate Fusion → Transformer Layers: uses (evidence: `module/CN.py`)
- Optimization Entry → Sequence Optimizer: runs (evidence: `main_optimize.py`)
- Optimization Entry → ESM-2 Manager: loads ESM-2 (evidence: `main_optimize.py`)
- Sequence Optimizer → CatESO Model: optimizes against
- Sequence Optimizer → Fold Evaluator: requests constraint (evidence: `optimizer/sequence_optimizer.py`)
- Fold Evaluator → ESMFold: evaluates folds
- ESMFold → Folding Trunk: uses trunk (evidence: `esm/esmfold/v1/esmfold.py`)
- Folding Trunk → Structure Module: uses structure module (evidence: `esm/esmfold/v1/trunk.py`)
- ESMFold → Residue Constants: uses residue definitions (evidence: `esm/esmfold/v1/esmfold.py`)
- ESMFold → Protein Structures: uses protein structures
- ESM-2 Manager → ESM-2: loads model (evidence: `optimizer/esm_manager.py`)
