# zheyuanlai/abf-fisher-rao architecture

> Architecture diagram of the GitHub repository zheyuanlai/abf-fisher-rao, 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/zheyuanlai/abf-fisher-rao
- Repository: https://github.com/zheyuanlai/abf-fisher-rao

## Overview

This is a computational research repository evaluating when Fisher–Rao resampling helps Adaptive Biasing Force free-energy estimation across model and molecular systems. The main workflow is to run a benchmark simulation, analyze paired methods and diagnostics, then assemble cross-case findings into the report. The map emphasizes documented study entry points and sampled runtime engines; many other benchmark and analysis modules are visible only in the tree, so their internal wiring is omitted.

Main entry points: [`scripts/build_closure_inventory.py`](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/build_closure_inventory.py) (Closure inventory), [`scripts/run_abf_fr_grid.py`](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_abf_fr_grid.py) (Metastability runner), [`scripts/run_entropic_bottleneck_study.py`](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_entropic_bottleneck_study.py) (Entropic runner), [`scripts/run_wca_production.py`](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_wca_production.py) (WCA production)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_study["ABF-FR studies"]
  node_metastability["Metastability runner<br/>[run_abf_fr_grid.py]"]
  node_entropic["Entropic runner"]
  node_wca_runner["WCA production"]
  node_phase_runner["WCA phase study"]
end

subgraph group_systems["System models"]
  node_abf_engine["2D GPU sampler"]
  node_entropic_core["Entropic core<br/>[eb_abffr_core.py]"]
  node_wca_core["WCA ABF-FR core<br/>[wca_abffr_core.py]"]
  node_alanine_core["Alanine sampler<br/>[core2d_ala.py]"]
  node_alkane_core["Alkane distance sampler<br/>[core_dist.py]"]
  node_lta_core["LTA model<br/>[core_lta.py]"]
  node_cha_core["CHA model<br/>[core_cha.py]"]
  node_zif8_core["ZIF-8 model<br/>[core_zif8.py]"]
end

subgraph group_analysis["Analysis"]
  node_wca_analysis["WCA analysis"]
  node_entropy_analysis["Entropy analysis"]
  node_analysis_suite["Cross-case analysis"]
  node_inventory["Closure inventory"]
end

subgraph group_reporting["Reporting"]
  node_report_assets["Report assets"]
  node_report_numbers["Report checks"]
end

node_researcher(("Researcher"))

node_researcher -->|"starts study"| node_metastability
node_researcher -->|"starts study"| node_entropic
node_researcher -->|"starts study"| node_wca_runner
node_researcher -->|"starts study"| node_phase_runner
node_metastability -->|"runs sampler"| node_abf_engine
node_entropic -->|"runs core"| node_entropic_core
node_wca_runner -->|"runs core"| node_wca_core
node_phase_runner -->|"runs core"| node_wca_core
node_researcher -->|"analyzes runs"| node_wca_analysis
node_researcher -->|"analyzes sweep"| node_entropy_analysis
node_researcher -->|"analyzes cases"| node_analysis_suite
node_researcher -->|"builds inventory"| node_inventory
node_researcher -->|"builds assets"| node_report_assets
node_researcher -->|"checks numbers"| node_report_numbers
node_analysis_suite -.->|"summarizes evidence"| node_inventory
node_inventory -.->|"supplies results"| node_report_assets

click node_metastability "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_abf_fr_grid.py"
click node_entropic "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_entropic_bottleneck_study.py"
click node_wca_runner "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_wca_production.py"
click node_phase_runner "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_wca_phase_diagram.py"
click node_abf_engine "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/abffr/simulation_torch.py"
click node_entropic_core "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/eb_abffr_core.py"
click node_wca_core "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/wca_abffr_core.py"
click node_alanine_core "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/alanine/core2d_ala.py"
click node_alkane_core "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/alkanes/core_dist.py"
click node_lta_core "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/lta/core_lta.py"
click node_cha_core "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/cha/core_cha.py"
click node_zif8_core "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/zif8/core_zif8.py"
click node_wca_analysis "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/analyze_wca_production.py"
click node_entropy_analysis "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/experiments/entropy_dominant_bottleneck/analyze_entropy_dominant_bottleneck.py"
click node_analysis_suite "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/analyze_convergence_atlas.py"
click node_inventory "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/build_closure_inventory.py"
click node_report_assets "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/report/scripts/build_report_assets.py"
click node_report_numbers "https://github.com/zheyuanlai/abf-fisher-rao/blob/main/report/scripts/check_report_numbers.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_metastability,node_entropic,node_wca_runner,node_phase_runner toneBlue
class node_abf_engine,node_entropic_core,node_wca_core,node_alanine_core,node_alkane_core,node_lta_core,node_cha_core,node_zif8_core toneAmber
class node_wca_analysis,node_entropy_analysis,node_analysis_suite,node_inventory toneMint
class node_report_assets,node_report_numbers toneRose
class node_researcher toneIndigo
```

## Components

### ABF-FR studies

- [Metastability runner](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_abf_fr_grid.py): `scripts/run_abf_fr_grid.py`
- [Entropic runner](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_entropic_bottleneck_study.py): `scripts/run_entropic_bottleneck_study.py`
- [WCA production](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_wca_production.py): `scripts/run_wca_production.py`
- [WCA phase study](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/run_wca_phase_diagram.py): `scripts/run_wca_phase_diagram.py`

### System models

- [2D GPU sampler](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/abffr/simulation_torch.py): `src/abffr/simulation_torch.py`
- [Entropic core](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/eb_abffr_core.py): `src/eb_abffr_core.py`
- [WCA ABF-FR core](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/wca_abffr_core.py): `src/wca_abffr_core.py`
- [Alanine sampler](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/alanine/core2d_ala.py): `src/alanine/core2d_ala.py`
- [Alkane distance sampler](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/alkanes/core_dist.py): `src/alkanes/core_dist.py`
- [LTA model](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/lta/core_lta.py): `src/lta/core_lta.py`
- [CHA model](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/cha/core_cha.py): `src/cha/core_cha.py`
- [ZIF-8 model](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/src/zif8/core_zif8.py): `src/zif8/core_zif8.py`

### Analysis

- [WCA analysis](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/analyze_wca_production.py): `scripts/analyze_wca_production.py`
- [Entropy analysis](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/experiments/entropy_dominant_bottleneck/analyze_entropy_dominant_bottleneck.py): `experiments/entropy_dominant_bottleneck/analyze_entropy_dominant_bottleneck.py`
- [Cross-case analysis](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/analyze_convergence_atlas.py): `scripts/analyze_convergence_atlas.py`
- [Closure inventory](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/scripts/build_closure_inventory.py): `scripts/build_closure_inventory.py`

### Reporting

- [Report assets](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/report/scripts/build_report_assets.py): `report/scripts/build_report_assets.py`
- [Report checks](https://github.com/zheyuanlai/abf-fisher-rao/blob/main/report/scripts/check_report_numbers.py): `report/scripts/check_report_numbers.py`

### Other components

- **Researcher**

## Connections

- Researcher → Metastability runner: starts study
- Researcher → Entropic runner: starts study
- Researcher → WCA production: starts study
- Researcher → WCA phase study: starts study
- Metastability runner → 2D GPU sampler: runs sampler
- Entropic runner → Entropic core: runs core
- WCA production → WCA ABF-FR core: runs core
- WCA phase study → WCA ABF-FR core: runs core
- Researcher → WCA analysis: analyzes runs
- Researcher → Entropy analysis: analyzes sweep
- Researcher → Cross-case analysis: analyzes cases
- Researcher → Closure inventory: builds inventory
- Researcher → Report assets: builds assets
- Researcher → Report checks: checks numbers
- Cross-case analysis → Closure inventory: summarizes evidence
- Closure inventory → Report assets: supplies results