# adicksonlab/wepy architecture

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

- Interactive diagram: https://gitdiagram.com/adicksonlab/wepy
- Repository: https://github.com/adicksonlab/wepy

## Overview

wepy is a modular framework for weighted-ensemble molecular-dynamics simulations. The principal workflow assembles a simulation from a snapshot and configuration, advances walker dynamics, applies boundary conditions and resampling, then reports results for persistent storage and analysis. OpenMM and multiprocessing are supported runtime integrations; WExplore and REVO are documented resampling choices. The excerpts show the simulation manager’s cycle and reporting responsibilities and orchestration’s call into it. Several important subsystems are represented from the README and source tree, but their internal connections are omitted where sampled evidence does not establish them.

Main entry points: [`src/wepy/sim_manager.py`](https://github.com/adicksonlab/wepy/blob/master/src/wepy/sim_manager.py) (Simulation manager), [`src/wepy_tools/sim_makers`](https://github.com/adicksonlab/wepy/tree/master/src/wepy_tools/sim_makers) (System makers), [`src/wepy/runners/openmm.py`](https://github.com/adicksonlab/wepy/blob/master/src/wepy/runners/openmm.py) (Dynamics runner), [`src/wepy/resampling/resamplers/resampler.py`](https://github.com/adicksonlab/wepy/blob/master/src/wepy/resampling/resamplers/resampler.py) (Resampling interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Simulation setup"]
  node_makers["System makers"]
  node_config["Configuration<br/>[configuration.py]"]
  node_snapshot["Simulation snapshot<br/>[snapshot.py]"]
  node_orchestrator["Orchestrator<br/>[orchestrator.py]"]
end

subgraph group_runtime["Simulation runtime"]
  node_manager["Simulation manager<br/>[sim_manager.py]"]
  node_walker["Walkers and state<br/>[walker.py]"]
  node_runner["Dynamics runner<br/>[openmm.py]"]
  node_boundary["Boundary conditions<br/>[boundary.py]"]
  node_resampler["Resampling interface<br/>[resampler.py]"]
  node_wexplore["WExplore<br/>[wexplore.py]"]
  node_revo["REVO<br/>[revo.py]"]
  node_mapper["Work mapper<br/>[mapper.py]"]
  node_worker["Task mapper<br/>[task_mapper.py]"]
  node_openmm(("OpenMM engine"))
end

subgraph group_storage["Reporting and storage"]
  node_reporter["Reporter interface<br/>[reporter.py]"]
  node_hdf5reporter["HDF5 reporter<br/>[hdf5.py]"]
  node_hdf5[("HDF5 datasets<br/>[hdf5.py]")]
  node_cli["HDF5 and run CLI<br/>[cli.py]"]
end

subgraph group_analysis["Analysis and monitoring"]
  node_analysis["Trajectory analysis<br/>[parents.py]"]
  node_network["Network analysis<br/>[network.py]"]
  node_dashboard["Run dashboards<br/>[dashboard.py]"]
  node_monitor["Prometheus monitoring<br/>[prometheus.py]"]
end

node_user(("Simulation user"))

node_user -->|"configures"| node_makers
node_makers -->|"assembles"| node_config
node_makers -->|"creates"| node_snapshot
node_makers -->|"uses"| node_orchestrator
node_makers -->|"constructs"| node_runner
node_orchestrator -->|"runs cycles"| node_manager
node_manager -->|"advances dynamics"| node_runner
node_manager -->|"applies boundaries"| node_boundary
node_manager -->|"resamples walkers"| node_resampler
node_manager -->|"reports cycle"| node_reporter
node_runner -->|"maps work"| node_mapper
node_mapper -->|"dispatches tasks"| node_worker
node_wexplore -->|"implements"| node_resampler
node_revo -->|"implements"| node_resampler
node_hdf5reporter -->|"extends"| node_reporter
node_hdf5reporter -->|"writes"| node_hdf5
node_cli -.->|"queries datasets"| node_hdf5
node_analysis -.->|"reads datasets"| node_hdf5
node_dashboard -->|"extends"| node_reporter
node_user -.->|"selects engine"| node_openmm
node_manager -.->|"emits metrics"| node_monitor

click node_makers "https://github.com/adicksonlab/wepy/tree/master/src/wepy_tools/sim_makers"
click node_config "https://github.com/adicksonlab/wepy/blob/master/src/wepy/orchestration/configuration.py"
click node_snapshot "https://github.com/adicksonlab/wepy/blob/master/src/wepy/orchestration/snapshot.py"
click node_orchestrator "https://github.com/adicksonlab/wepy/blob/master/src/wepy/orchestration/orchestrator.py"
click node_manager "https://github.com/adicksonlab/wepy/blob/master/src/wepy/sim_manager.py"
click node_walker "https://github.com/adicksonlab/wepy/blob/master/src/wepy/walker.py"
click node_runner "https://github.com/adicksonlab/wepy/blob/master/src/wepy/runners/openmm.py"
click node_boundary "https://github.com/adicksonlab/wepy/blob/master/src/wepy/boundary_conditions/boundary.py"
click node_resampler "https://github.com/adicksonlab/wepy/blob/master/src/wepy/resampling/resamplers/resampler.py"
click node_wexplore "https://github.com/adicksonlab/wepy/blob/master/src/wepy/resampling/resamplers/wexplore.py"
click node_revo "https://github.com/adicksonlab/wepy/blob/master/src/wepy/resampling/resamplers/revo.py"
click node_mapper "https://github.com/adicksonlab/wepy/blob/master/src/wepy/work_mapper/mapper.py"
click node_worker "https://github.com/adicksonlab/wepy/blob/master/src/wepy/work_mapper/task_mapper.py"
click node_reporter "https://github.com/adicksonlab/wepy/blob/master/src/wepy/reporter/reporter.py"
click node_hdf5reporter "https://github.com/adicksonlab/wepy/blob/master/src/wepy/reporter/hdf5.py"
click node_hdf5 "https://github.com/adicksonlab/wepy/blob/master/src/wepy/hdf5.py"
click node_cli "https://github.com/adicksonlab/wepy/blob/master/src/wepy/orchestration/cli.py"
click node_analysis "https://github.com/adicksonlab/wepy/blob/master/src/wepy/analysis/parents.py"
click node_network "https://github.com/adicksonlab/wepy/blob/master/src/wepy/analysis/network.py"
click node_dashboard "https://github.com/adicksonlab/wepy/blob/master/src/wepy/reporter/dashboard.py"
click node_monitor "https://github.com/adicksonlab/wepy/blob/master/src/wepy_tools/monitoring/prometheus.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_makers,node_config,node_snapshot,node_orchestrator,node_user toneBlue
class node_manager,node_walker,node_runner,node_boundary,node_resampler,node_wexplore,node_revo,node_mapper,node_worker,node_openmm toneAmber
class node_reporter,node_hdf5reporter,node_hdf5,node_cli toneMint
class node_analysis,node_network,node_dashboard,node_monitor toneRose
```

## Components

### Simulation setup

- [System makers](https://github.com/adicksonlab/wepy/tree/master/src/wepy_tools/sim_makers): `src/wepy_tools/sim_makers`
- [Configuration](https://github.com/adicksonlab/wepy/blob/master/src/wepy/orchestration/configuration.py): `src/wepy/orchestration/configuration.py`
- [Simulation snapshot](https://github.com/adicksonlab/wepy/blob/master/src/wepy/orchestration/snapshot.py): `src/wepy/orchestration/snapshot.py`
- [Orchestrator](https://github.com/adicksonlab/wepy/blob/master/src/wepy/orchestration/orchestrator.py): `src/wepy/orchestration/orchestrator.py`

### Simulation runtime

- [Simulation manager](https://github.com/adicksonlab/wepy/blob/master/src/wepy/sim_manager.py): `src/wepy/sim_manager.py`
- [Walkers and state](https://github.com/adicksonlab/wepy/blob/master/src/wepy/walker.py): `src/wepy/walker.py`
- [Dynamics runner](https://github.com/adicksonlab/wepy/blob/master/src/wepy/runners/openmm.py): `src/wepy/runners/openmm.py`
- [Boundary conditions](https://github.com/adicksonlab/wepy/blob/master/src/wepy/boundary_conditions/boundary.py): `src/wepy/boundary_conditions/boundary.py`
- [Resampling interface](https://github.com/adicksonlab/wepy/blob/master/src/wepy/resampling/resamplers/resampler.py): `src/wepy/resampling/resamplers/resampler.py`
- [WExplore](https://github.com/adicksonlab/wepy/blob/master/src/wepy/resampling/resamplers/wexplore.py): `src/wepy/resampling/resamplers/wexplore.py`
- [REVO](https://github.com/adicksonlab/wepy/blob/master/src/wepy/resampling/resamplers/revo.py): `src/wepy/resampling/resamplers/revo.py`
- [Work mapper](https://github.com/adicksonlab/wepy/blob/master/src/wepy/work_mapper/mapper.py): `src/wepy/work_mapper/mapper.py`
- [Task mapper](https://github.com/adicksonlab/wepy/blob/master/src/wepy/work_mapper/task_mapper.py): `src/wepy/work_mapper/task_mapper.py`
- **OpenMM engine**

### Reporting and storage

- [Reporter interface](https://github.com/adicksonlab/wepy/blob/master/src/wepy/reporter/reporter.py): `src/wepy/reporter/reporter.py`
- [HDF5 reporter](https://github.com/adicksonlab/wepy/blob/master/src/wepy/reporter/hdf5.py): `src/wepy/reporter/hdf5.py`
- [HDF5 datasets](https://github.com/adicksonlab/wepy/blob/master/src/wepy/hdf5.py): `src/wepy/hdf5.py`
- [HDF5 and run CLI](https://github.com/adicksonlab/wepy/blob/master/src/wepy/orchestration/cli.py): `src/wepy/orchestration/cli.py`

### Analysis and monitoring

- [Trajectory analysis](https://github.com/adicksonlab/wepy/blob/master/src/wepy/analysis/parents.py): `src/wepy/analysis/parents.py`
- [Network analysis](https://github.com/adicksonlab/wepy/blob/master/src/wepy/analysis/network.py): `src/wepy/analysis/network.py`
- [Run dashboards](https://github.com/adicksonlab/wepy/blob/master/src/wepy/reporter/dashboard.py): `src/wepy/reporter/dashboard.py`
- [Prometheus monitoring](https://github.com/adicksonlab/wepy/blob/master/src/wepy_tools/monitoring/prometheus.py): `src/wepy_tools/monitoring/prometheus.py`

### Other components

- **Simulation user**

## Connections

- Simulation user → System makers: configures
- System makers → Configuration: assembles (evidence: `src/wepy_tools/sim_makers/openmm/sim_maker.py`)
- System makers → Simulation snapshot: creates (evidence: `src/wepy_tools/sim_makers/openmm/sim_maker.py`)
- System makers → Orchestrator: uses (evidence: `src/wepy_tools/sim_makers/openmm/sim_maker.py`)
- System makers → Dynamics runner: constructs (evidence: `src/wepy_tools/sim_makers/openmm/sim_maker.py`)
- Orchestrator → Simulation manager: runs cycles (evidence: `src/wepy/orchestration/orchestrator.py`)
- Simulation manager → Dynamics runner: advances dynamics (evidence: `src/wepy/sim_manager.py`)
- Simulation manager → Boundary conditions: applies boundaries (evidence: `src/wepy/sim_manager.py`)
- Simulation manager → Resampling interface: resamples walkers (evidence: `src/wepy/sim_manager.py`)
- Simulation manager → Reporter interface: reports cycle (evidence: `src/wepy/sim_manager.py`)
- Dynamics runner → Work mapper: maps work (evidence: `src/wepy/runners/openmm.py`)
- Work mapper → Task mapper: dispatches tasks (evidence: `src/wepy/work_mapper/task_mapper.py`)
- WExplore → Resampling interface: implements (evidence: `src/wepy/resampling/resamplers/wexplore.py`)
- REVO → Resampling interface: implements (evidence: `src/wepy/resampling/resamplers/revo.py`)
- HDF5 reporter → Reporter interface: extends (evidence: `src/wepy/reporter/hdf5.py`)
- HDF5 reporter → HDF5 datasets: writes (evidence: `src/wepy/reporter/hdf5.py`)
- HDF5 and run CLI → HDF5 datasets: queries datasets
- Trajectory analysis → HDF5 datasets: reads datasets
- Run dashboards → Reporter interface: extends (evidence: `src/wepy/reporter/dashboard.py`)
- Simulation user → OpenMM engine: selects engine
- Simulation manager → Prometheus monitoring: emits metrics
