# nyelidl/pacs-q architecture

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

- Interactive diagram: https://gitdiagram.com/nyelidl/pacs-q
- Repository: https://github.com/nyelidl/pacs-q

## Overview

PaCS-Q runs parallel-cascade molecular-dynamics simulations: users provide structures, topology, reference/selection criteria and run settings; candidate trajectories are generated, scored, and selected to seed later cycles. The package supports AMBER and OpenMM workflows, reruns, distance- or RMSD-based selection, and trajectory analysis. Relationships among sampled modules are shown where excerpts or the source index establish them; analysis capabilities are documented in the README, but their runtime wiring was not sampled.

Main entry points: [`pacsq_toolkit/pacs_q_md.py`](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacs_q_md.py) (MD CLI), [`pacsq_toolkit/pacsrmsd.py`](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsrmsd.py) (Candidate scoring), [`pacsq_toolkit/pacsq_run.py`](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_run.py) (QM/MM sampling), [`pacsq_toolkit/pacsq_exq_run.py`](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_exq_run.py) (External QM run)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command interfaces"]
  node_pacsq_cli["QM/MM CLI<br/>[pacs_q.py]"]
  node_md_cli["MD CLI<br/>[pacs_q_md.py]"]
  node_input_discovery["Input discovery<br/>[file_find.py]"]
end

subgraph group_sampling["Cascade sampling"]
  node_standard_run["QM/MM sampling<br/>[pacsq_run.py]"]
  node_external_run["External QM run<br/>[pacsq_exq_run.py]"]
  node_rerun["QM/MM rerun<br/>[pacsq_rerun.py]"]
  node_pmemd_run["PMEMD sampling<br/>[pacsq_pmemd_run.py]"]
  node_pmemd_rerun["PMEMD rerun"]
  node_openmm_run["OpenMM sampling"]
  node_openmm_rerun["OpenMM rerun"]
  node_scoring["Candidate scoring<br/>[pacsrmsd.py]"]
  node_settings["Run settings<br/>[qmmm_setting.py]"]
end

subgraph group_engines["Simulation engines"]
  node_sander["Sander MPI<br/>[sander_run_mpi.py]"]
  node_sander_local["Sander runner<br/>[sander_run.py]"]
  node_pmemd_engine["PMEMD runner<br/>[pmemd_run.py]"]
  node_openmm_engine["OpenMM engine<br/>[openmm_engine.py]"]
  node_amber["AMBER"]
  node_openmm["OpenMM runtime"]
end

subgraph group_analysis["Trajectory analysis"]
  node_analysis_collection["CV and PES"]
  node_analysis_mpi["Parallel CV/PES"]
  node_analysis_pca["PCA analysis"]
  node_analysis_qm["QM input export"]
  node_analysis_orca["ORCA input export"]
  node_analysis_para["Parameter analysis<br/>[pacsana_3_para.py]"]
  node_analysis_rmsd["RMSD analysis<br/>[pacsrmsd.py]"]
end

node_user(("Researcher"))
node_trajectory[("MD trajectories")]

node_user -->|"runs"| node_pacsq_cli
node_user -->|"runs"| node_md_cli
node_md_cli -->|"discovers inputs"| node_input_discovery
node_md_cli -->|"dispatches"| node_standard_run
node_md_cli -->|"dispatches"| node_external_run
node_md_cli -->|"dispatches"| node_rerun
node_md_cli -->|"dispatches"| node_pmemd_run
node_md_cli -->|"dispatches"| node_pmemd_rerun
node_md_cli -->|"dispatches"| node_openmm_run
node_md_cli -->|"dispatches"| node_openmm_rerun
node_standard_run -->|"scores candidates"| node_scoring
node_standard_run -->|"runs simulations"| node_sander
node_external_run -->|"scores candidates"| node_scoring
node_external_run -->|"runs simulations"| node_sander_local
node_rerun -->|"scores candidates"| node_scoring
node_rerun -->|"runs simulations"| node_sander
node_pmemd_run -->|"scores candidates"| node_scoring
node_pmemd_run -->|"runs simulations"| node_pmemd_engine
node_pmemd_rerun -->|"scores candidates"| node_scoring
node_pmemd_rerun -->|"runs simulations"| node_pmemd_engine
node_openmm_run -->|"scores candidates"| node_scoring
node_openmm_run -->|"runs simulations"| node_openmm_engine
node_openmm_rerun -->|"scores candidates"| node_scoring
node_openmm_rerun -->|"runs simulations"| node_openmm_engine
node_standard_run -->|"reads settings"| node_settings
node_external_run -->|"reads settings"| node_settings
node_sander -->|"invokes"| node_amber
node_sander_local -.->|"invokes"| node_amber
node_pmemd_engine -.->|"invokes"| node_amber
node_openmm_engine -->|"uses runtime"| node_openmm
node_standard_run -->|"writes trajectories"| node_trajectory
node_pmemd_run -->|"writes trajectories"| node_trajectory
node_openmm_run -->|"writes trajectories"| node_trajectory
node_trajectory -.->|"analyzed as CV/PES"| node_analysis_collection
node_trajectory -.->|"analyzed as CV/PES"| node_analysis_mpi
node_trajectory -.->|"analyzed"| node_analysis_pca
node_trajectory -.->|"exports QM inputs"| node_analysis_qm
node_trajectory -.->|"exports QM inputs"| node_analysis_orca
node_trajectory -.->|"analyzed"| node_analysis_para
node_trajectory -.->|"scored"| node_analysis_rmsd

click node_pacsq_cli "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacs_q.py"
click node_md_cli "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacs_q_md.py"
click node_input_discovery "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/file_find.py"
click node_standard_run "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_run.py"
click node_external_run "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_exq_run.py"
click node_rerun "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_rerun.py"
click node_pmemd_run "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_pmemd_run.py"
click node_pmemd_rerun "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_pmemd_rerun.py"
click node_openmm_run "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_openmm_run.py"
click node_openmm_rerun "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_openmm_rerun.py"
click node_scoring "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsrmsd.py"
click node_settings "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/qmmm_setting.py"
click node_sander "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/sander_run_mpi.py"
click node_sander_local "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/sander_run.py"
click node_pmemd_engine "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pmemd_run.py"
click node_openmm_engine "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/openmm_engine.py"
click node_analysis_collection "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_dis_collection.py"
click node_analysis_mpi "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_dis_collection_mpi.py"
click node_analysis_pca "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_procupine.py"
click node_analysis_qm "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_traj2g16.py"
click node_analysis_orca "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_traj2orca.py"
click node_analysis_para "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_3_para.py"
click node_analysis_rmsd "https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsrmsd.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_pacsq_cli,node_md_cli,node_input_discovery toneBlue
class node_standard_run,node_external_run,node_rerun,node_pmemd_run,node_pmemd_rerun,node_openmm_run,node_openmm_rerun,node_scoring,node_settings,node_trajectory toneAmber
class node_sander,node_sander_local,node_pmemd_engine,node_openmm_engine,node_amber,node_openmm toneMint
class node_analysis_collection,node_analysis_mpi,node_analysis_pca,node_analysis_qm,node_analysis_orca,node_analysis_para,node_analysis_rmsd toneRose
class node_user toneIndigo
```

## Components

### Command interfaces

- [QM/MM CLI](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacs_q.py): `pacsq_toolkit/pacs_q.py`
- [MD CLI](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacs_q_md.py): `pacsq_toolkit/pacs_q_md.py`
- [Input discovery](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/file_find.py): `pacsq_toolkit/file_find.py`

### Cascade sampling

- [QM/MM sampling](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_run.py): `pacsq_toolkit/pacsq_run.py`
- [External QM run](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_exq_run.py): `pacsq_toolkit/pacsq_exq_run.py`
- [QM/MM rerun](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_rerun.py): `pacsq_toolkit/pacsq_rerun.py`
- [PMEMD sampling](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_pmemd_run.py): `pacsq_toolkit/pacsq_pmemd_run.py`
- [PMEMD rerun](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_pmemd_rerun.py): `pacsq_toolkit/pacsq_pmemd_rerun.py`
- [OpenMM sampling](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_openmm_run.py): `pacsq_toolkit/pacsq_openmm_run.py`
- [OpenMM rerun](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsq_openmm_rerun.py): `pacsq_toolkit/pacsq_openmm_rerun.py`
- [Candidate scoring](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsrmsd.py): `pacsq_toolkit/pacsrmsd.py`
- [Run settings](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/qmmm_setting.py): `pacsq_toolkit/qmmm_setting.py`

### Simulation engines

- [Sander MPI](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/sander_run_mpi.py): `pacsq_toolkit/sander_run_mpi.py`
- [Sander runner](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/sander_run.py): `pacsq_toolkit/sander_run.py`
- [PMEMD runner](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pmemd_run.py): `pacsq_toolkit/pmemd_run.py`
- [OpenMM engine](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/openmm_engine.py): `pacsq_toolkit/openmm_engine.py`
- **AMBER**
- **OpenMM runtime**

### Trajectory analysis

- [CV and PES](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_dis_collection.py): `pacsq_toolkit/pacsana_dis_collection.py`
- [Parallel CV/PES](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_dis_collection_mpi.py): `pacsq_toolkit/pacsana_dis_collection_mpi.py`
- [PCA analysis](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_procupine.py): `pacsq_toolkit/pacsana_procupine.py`
- [QM input export](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_traj2g16.py): `pacsq_toolkit/pacsana_traj2g16.py`
- [ORCA input export](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_traj2orca.py): `pacsq_toolkit/pacsana_traj2orca.py`
- [Parameter analysis](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsana_3_para.py): `pacsq_toolkit/pacsana_3_para.py`
- [RMSD analysis](https://github.com/nyelidl/pacs-q/blob/main/pacsq_toolkit/pacsrmsd.py): `pacsq_toolkit/pacsrmsd.py`

### Other components

- **Researcher**
- **MD trajectories**

## Connections

- Researcher → QM/MM CLI: runs (evidence: `README.md`)
- Researcher → MD CLI: runs (evidence: `README.md`)
- MD CLI → Input discovery: discovers inputs (evidence: `pacsq_toolkit/pacs_q_md.py`)
- MD CLI → QM/MM sampling: dispatches (evidence: `pacsq_toolkit/pacs_q_md.py`)
- MD CLI → External QM run: dispatches (evidence: `pacsq_toolkit/pacs_q_md.py`)
- MD CLI → QM/MM rerun: dispatches (evidence: `pacsq_toolkit/pacs_q_md.py`)
- MD CLI → PMEMD sampling: dispatches (evidence: `pacsq_toolkit/pacs_q_md.py`)
- MD CLI → PMEMD rerun: dispatches (evidence: `pacsq_toolkit/pacs_q_md.py`)
- MD CLI → OpenMM sampling: dispatches (evidence: `pacsq_toolkit/pacs_q_md.py`)
- MD CLI → OpenMM rerun: dispatches (evidence: `pacsq_toolkit/pacs_q_md.py`)
- QM/MM sampling → Candidate scoring: scores candidates (evidence: `pacsq_toolkit/pacsq_run.py`)
- QM/MM sampling → Sander MPI: runs simulations (evidence: `pacsq_toolkit/pacsq_run.py`)
- External QM run → Candidate scoring: scores candidates (evidence: `pacsq_toolkit/pacsq_exq_run.py`)
- External QM run → Sander runner: runs simulations (evidence: `pacsq_toolkit/pacsq_exq_run.py`)
- QM/MM rerun → Candidate scoring: scores candidates (evidence: `pacsq_toolkit/pacsq_rerun.py`)
- QM/MM rerun → Sander MPI: runs simulations (evidence: `pacsq_toolkit/pacsq_rerun.py`)
- PMEMD sampling → Candidate scoring: scores candidates (evidence: `pacsq_toolkit/pacsq_pmemd_run.py`)
- PMEMD sampling → PMEMD runner: runs simulations (evidence: `pacsq_toolkit/pacsq_pmemd_run.py`)
- PMEMD rerun → Candidate scoring: scores candidates (evidence: `pacsq_toolkit/pacsq_pmemd_rerun.py`)
- PMEMD rerun → PMEMD runner: runs simulations (evidence: `pacsq_toolkit/pacsq_pmemd_rerun.py`)
- OpenMM sampling → Candidate scoring: scores candidates (evidence: `pacsq_toolkit/pacsq_openmm_run.py`)
- OpenMM sampling → OpenMM engine: runs simulations (evidence: `pacsq_toolkit/pacsq_openmm_run.py`)
- OpenMM rerun → Candidate scoring: scores candidates (evidence: `pacsq_toolkit/pacsq_openmm_rerun.py`)
- OpenMM rerun → OpenMM engine: runs simulations (evidence: `pacsq_toolkit/pacsq_openmm_rerun.py`)
- QM/MM sampling → Run settings: reads settings (evidence: `pacsq_toolkit/pacsq_run.py`)
- External QM run → Run settings: reads settings (evidence: `pacsq_toolkit/pacsq_exq_run.py`)
- Sander MPI → AMBER: invokes (evidence: `pacsq_toolkit/sander_run_mpi.py`)
- Sander runner → AMBER: invokes
- PMEMD runner → AMBER: invokes
- OpenMM engine → OpenMM runtime: uses runtime (evidence: `pacsq_toolkit/openmm_engine.py`)
- QM/MM sampling → MD trajectories: writes trajectories (evidence: `pacsq_toolkit/pacsq_run.py`)
- PMEMD sampling → MD trajectories: writes trajectories (evidence: `pacsq_toolkit/pacsq_pmemd_run.py`)
- OpenMM sampling → MD trajectories: writes trajectories
- MD trajectories → CV and PES: analyzed as CV/PES (evidence: `README.md`)
- MD trajectories → Parallel CV/PES: analyzed as CV/PES (evidence: `README.md`)
- MD trajectories → PCA analysis: analyzed (evidence: `README.md`)
- MD trajectories → QM input export: exports QM inputs (evidence: `README.md`)
- MD trajectories → ORCA input export: exports QM inputs (evidence: `README.md`)
- MD trajectories → Parameter analysis: analyzed
- MD trajectories → RMSD analysis: scored