# tangcyu/gen-compas architecture

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

- Interactive diagram: https://gitdiagram.com/tangcyu/gen-compas
- Repository: https://github.com/tangcyu/gen-compas

## Overview

Gen-COMPAS orchestrates iterative, committor-guided protein rare-event sampling: it trains and samples diffusion models, optionally filters samples with a learned committor, selects structures, runs targeted and unbiased MD, then reweights trajectories and estimates free-energy landscapes. The README documents the stage schedule; sampled source confirms the workflow orchestrator, model training, RiteWeight processing, and NAMD execution. Some stage wiring is represented from README documentation because its implementation was not sampled.

Main entry points: [`workflow.py`](https://github.com/tangcyu/gen-compas/blob/main/workflow.py) (Iteration scheduler), [`tools/riteweight.py`](https://github.com/tangcyu/gen-compas/blob/main/tools/riteweight.py) (Trajectory reweighting), [`common/diffusion_sample.py`](https://github.com/tangcyu/gen-compas/blob/main/common/diffusion_sample.py) (Sample structures), [`common/vcn_slice.py`](https://github.com/tangcyu/gen-compas/blob/main/common/vcn_slice.py) (Committor slicing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow orchestration"]
  node_workflow["Iteration scheduler<br/>[workflow.py]"]
  node_config["Config loading<br/>[config.py]"]
end

subgraph group_generation["Structure generation"]
  node_difftrain["Train diffusion<br/>[diffusion_train.py]"]
  node_diffmodel["Diffusion network<br/>[model.py]"]
  node_diffsample["Sample structures"]
end

subgraph group_selection["Committor and targets"]
  node_vcntrain["Train committor<br/>[vcn_train.py]"]
  node_vcnmodel["Committor network<br/>[model.py]"]
  node_slice["Committor slicing<br/>[vcn_slice.py]"]
  node_cluster["Cluster targets<br/>[clustering.py]"]
  node_targetselect["Target selection"]
  node_occupancy["Set occupancy<br/>[occupancy.py]"]
end

subgraph group_simulation["Molecular simulation"]
  node_namd["Targeted and unbiased MD<br/>[namd.py]"]
end

subgraph group_analysis["Reweighting and analysis"]
  node_riteweight["Trajectory reweighting<br/>[riteweight.py]"]
  node_vcnoutput["VCN training data<br/>[tensor_table.py]"]
  node_diffusiontraj["Aligned training trajectory<br/>[riteweight.py]"]
  node_fel["Free-energy landscape<br/>[felestimate.py]"]
  node_landscape["Weighted FEL result"]
end

node_scientist(("Researcher"))
node_initialdata[("Initial MD data")]
node_namdengine["NAMD engine"]

node_scientist -->|"starts run"| node_workflow
node_workflow -->|"loads config"| node_config
node_workflow -->|"dispatches stage"| node_difftrain
node_workflow -->|"dispatches stage"| node_diffsample
node_workflow -->|"dispatches stage"| node_vcntrain
node_workflow -->|"dispatches stage"| node_slice
node_workflow -->|"dispatches stage"| node_cluster
node_workflow -->|"dispatches stage"| node_occupancy
node_workflow -->|"dispatches stage"| node_namd
node_workflow -->|"dispatches stage"| node_riteweight
node_workflow -->|"dispatches stage"| node_fel
node_initialdata -->|"trains from"| node_difftrain
node_initialdata -.->|"trains from"| node_vcntrain
node_difftrain -->|"optimizes"| node_diffmodel
node_diffmodel -->|"generates conformations"| node_diffsample
node_vcntrain -->|"optimizes"| node_vcnmodel
node_vcnmodel -->|"scores structures"| node_slice
node_diffsample -.->|"filters generated frames"| node_slice
node_diffsample -->|"clusters generated frames"| node_cluster
node_slice -->|"provides candidates"| node_targetselect
node_cluster -->|"provides representatives"| node_targetselect
node_targetselect -->|"prepares targets"| node_occupancy
node_occupancy -->|"supplies structures"| node_namd
node_namd -->|"runs simulations"| node_namdengine
node_namdengine -->|"produces trajectories"| node_riteweight
node_riteweight -->|"emits training data"| node_vcnoutput
node_riteweight -->|"emits aligned trajectory"| node_diffusiontraj
node_riteweight -->|"provides weighted results"| node_fel
node_fel -->|"projects landscape"| node_landscape

click node_workflow "https://github.com/tangcyu/gen-compas/blob/main/workflow.py"
click node_config "https://github.com/tangcyu/gen-compas/blob/main/common/config.py"
click node_difftrain "https://github.com/tangcyu/gen-compas/blob/main/common/diffusion_train.py"
click node_diffmodel "https://github.com/tangcyu/gen-compas/blob/main/utils/model.py"
click node_diffsample "https://github.com/tangcyu/gen-compas/blob/main/common/diffusion_sample.py"
click node_vcntrain "https://github.com/tangcyu/gen-compas/blob/main/common/vcn_train.py"
click node_vcnmodel "https://github.com/tangcyu/gen-compas/blob/main/vcn/model.py"
click node_slice "https://github.com/tangcyu/gen-compas/blob/main/common/vcn_slice.py"
click node_cluster "https://github.com/tangcyu/gen-compas/blob/main/tools/clustering.py"
click node_targetselect "https://github.com/tangcyu/gen-compas/blob/main/common/target_selection.py"
click node_occupancy "https://github.com/tangcyu/gen-compas/blob/main/tools/occupancy.py"
click node_namd "https://github.com/tangcyu/gen-compas/blob/main/tools/namd.py"
click node_riteweight "https://github.com/tangcyu/gen-compas/blob/main/tools/riteweight.py"
click node_vcnoutput "https://github.com/tangcyu/gen-compas/blob/main/tools/tensor_table.py"
click node_diffusiontraj "https://github.com/tangcyu/gen-compas/blob/main/tools/riteweight.py"
click node_fel "https://github.com/tangcyu/gen-compas/blob/main/tools/felestimate.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_workflow,node_config toneBlue
class node_difftrain,node_diffmodel,node_diffsample,node_initialdata toneAmber
class node_vcntrain,node_vcnmodel,node_slice,node_cluster,node_targetselect,node_occupancy toneMint
class node_namd toneRose
class node_riteweight,node_vcnoutput,node_diffusiontraj,node_fel,node_landscape,node_scientist,node_namdengine toneIndigo
```

## Components

### Workflow orchestration

- [Iteration scheduler](https://github.com/tangcyu/gen-compas/blob/main/workflow.py): `workflow.py`
- [Config loading](https://github.com/tangcyu/gen-compas/blob/main/common/config.py): `common/config.py`

### Structure generation

- [Train diffusion](https://github.com/tangcyu/gen-compas/blob/main/common/diffusion_train.py): `common/diffusion_train.py`
- [Diffusion network](https://github.com/tangcyu/gen-compas/blob/main/utils/model.py): `utils/model.py`
- [Sample structures](https://github.com/tangcyu/gen-compas/blob/main/common/diffusion_sample.py): `common/diffusion_sample.py`

### Committor and targets

- [Train committor](https://github.com/tangcyu/gen-compas/blob/main/common/vcn_train.py): `common/vcn_train.py`
- [Committor network](https://github.com/tangcyu/gen-compas/blob/main/vcn/model.py): `vcn/model.py`
- [Committor slicing](https://github.com/tangcyu/gen-compas/blob/main/common/vcn_slice.py): `common/vcn_slice.py`
- [Cluster targets](https://github.com/tangcyu/gen-compas/blob/main/tools/clustering.py): `tools/clustering.py`
- [Target selection](https://github.com/tangcyu/gen-compas/blob/main/common/target_selection.py): `common/target_selection.py`
- [Set occupancy](https://github.com/tangcyu/gen-compas/blob/main/tools/occupancy.py): `tools/occupancy.py`

### Molecular simulation

- [Targeted and unbiased MD](https://github.com/tangcyu/gen-compas/blob/main/tools/namd.py): `tools/namd.py`

### Reweighting and analysis

- [Trajectory reweighting](https://github.com/tangcyu/gen-compas/blob/main/tools/riteweight.py): `tools/riteweight.py`
- [VCN training data](https://github.com/tangcyu/gen-compas/blob/main/tools/tensor_table.py): `tools/tensor_table.py`
- [Aligned training trajectory](https://github.com/tangcyu/gen-compas/blob/main/tools/riteweight.py): `tools/riteweight.py`
- [Free-energy landscape](https://github.com/tangcyu/gen-compas/blob/main/tools/felestimate.py): `tools/felestimate.py`
- **Weighted FEL result**

### Other components

- **Researcher**
- **Initial MD data**
- **NAMD engine**

## Connections

- Researcher → Iteration scheduler: starts run
- Iteration scheduler → Config loading: loads config
- Iteration scheduler → Train diffusion: dispatches stage
- Iteration scheduler → Sample structures: dispatches stage
- Iteration scheduler → Train committor: dispatches stage
- Iteration scheduler → Committor slicing: dispatches stage
- Iteration scheduler → Cluster targets: dispatches stage
- Iteration scheduler → Set occupancy: dispatches stage
- Iteration scheduler → Targeted and unbiased MD: dispatches stage
- Iteration scheduler → Trajectory reweighting: dispatches stage
- Iteration scheduler → Free-energy landscape: dispatches stage
- Initial MD data → Train diffusion: trains from
- Initial MD data → Train committor: trains from
- Train diffusion → Diffusion network: optimizes
- Diffusion network → Sample structures: generates conformations
- Train committor → Committor network: optimizes
- Committor network → Committor slicing: scores structures
- Sample structures → Committor slicing: filters generated frames
- Sample structures → Cluster targets: clusters generated frames
- Committor slicing → Target selection: provides candidates
- Cluster targets → Target selection: provides representatives
- Target selection → Set occupancy: prepares targets
- Set occupancy → Targeted and unbiased MD: supplies structures
- Targeted and unbiased MD → NAMD engine: runs simulations
- NAMD engine → Trajectory reweighting: produces trajectories
- Trajectory reweighting → VCN training data: emits training data
- Trajectory reweighting → Aligned training trajectory: emits aligned trajectory
- Trajectory reweighting → Free-energy landscape: provides weighted results
- Free-energy landscape → Weighted FEL result: projects landscape