# pdynamo/pdynamo3 architecture

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

- Interactive diagram: https://gitdiagram.com/pdynamo/pdynamo3
- Repository: https://github.com/pdynamo/pdynamo3

## Overview

pDynamo is a Python/C molecular simulation library for building molecular systems and evaluating QC, MM, or hybrid QC/MM potentials, with simulation, optimization, analysis, and file-format support. The principal use is to prepare molecular input, assign a model, calculate energies or properties, and run a study whose outputs are analyzed or written. The graph preserves major README capabilities and add-ons; many links are documented at capability level or inferred from the product workflow, since their invoking code was not sampled.

Main entry points: [`pMolecule/EnergyModel.py`](https://github.com/pdynamo/pdynamo3/blob/main/pMolecule/EnergyModel.py) (Energy models), [`pMolecule`](https://github.com/pdynamo/pdynamo3/tree/main/pMolecule) (Molecular system), [`pMolecule/MMModel/MMModel.py`](https://github.com/pdynamo/pdynamo3/blob/main/pMolecule/MMModel/MMModel.py) (MM force fields), [`pMolecule/QCModel`](https://github.com/pdynamo/pdynamo3/tree/main/pMolecule/QCModel) (QC methods)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_io["Molecular input/output"]
  node_formats["Molecular formats"]
  node_system["Molecular system"]
  node_output["File and trajectory output"]
end

subgraph group_model["Molecular models"]
  node_core["Core services"]
  node_arrays["Numerical arrays"]
  node_mm["MM force fields<br/>[MMModel.py]"]
  node_qc["QC methods"]
  node_hybrid["QC/MM coupling"]
  node_energy["Energy models<br/>[EnergyModel.py]"]
end

subgraph group_workflows["Simulation workflows"]
  node_optimization["Geometry optimization"]
  node_transition["Transition states"]
  node_dynamics["Molecular dynamics"]
  node_montecarlo["Monte Carlo"]
  node_normalmodes["Normal modes<br/>[NormalModes.py]"]
end

subgraph group_extensions["Analysis and add-ons"]
  node_properties["Properties and analysis"]
  node_pcetk["Proton energetics<br/>[CEModel.py]"]
  node_pm6ml["PM6 delta learning<br/>[QCDeltaMLModel.py]"]
  node_pyscf["PySCF integration<br/>[QCModelPySCF.py]"]
end

node_user(("Researcher"))

node_user -.->|"provides input"| node_formats
node_formats -.->|"builds system"| node_system
node_system -.->|"receives structure"| node_mm
node_system -.->|"receives structure"| node_qc
node_mm -.->|"evaluates potential"| node_energy
node_qc -.->|"evaluates potential"| node_energy
node_hybrid -.->|"couples potentials"| node_energy
node_mm -->|"uses utilities"| node_core
node_mm -->|"uses arrays"| node_arrays
node_optimization -.->|"optimizes energy"| node_energy
node_transition -.->|"searches surface"| node_energy
node_dynamics -.->|"uses potential"| node_energy
node_montecarlo -.->|"uses potential"| node_energy
node_normalmodes -.->|"analyzes potential"| node_energy
node_system -.->|"yields properties"| node_properties
node_energy -.->|"writes results"| node_output
node_pcetk -->|"models protonation"| node_system
node_pcetk -->|"uses foundations"| node_core
node_pcetk -->|"uses sampling model"| node_montecarlo
node_pm6ml -.->|"corrects PM6"| node_qc
node_pyscf -.->|"provides QC backend"| node_qc

click node_formats "https://github.com/pdynamo/pdynamo3/tree/main/pBabel"
click node_system "https://github.com/pdynamo/pdynamo3/tree/main/pMolecule"
click node_output "https://github.com/pdynamo/pdynamo3/tree/main/pBabel"
click node_core "https://github.com/pdynamo/pdynamo3/tree/main/pCore"
click node_arrays "https://github.com/pdynamo/pdynamo3/tree/main/pScientific/Arrays"
click node_mm "https://github.com/pdynamo/pdynamo3/blob/main/pMolecule/MMModel/MMModel.py"
click node_qc "https://github.com/pdynamo/pdynamo3/tree/main/pMolecule/QCModel"
click node_hybrid "https://github.com/pdynamo/pdynamo3/tree/main/pMolecule/NBModel"
click node_energy "https://github.com/pdynamo/pdynamo3/blob/main/pMolecule/EnergyModel.py"
click node_optimization "https://github.com/pdynamo/pdynamo3/tree/main/pScientific/ObjectiveFunctionIterators"
click node_transition "https://github.com/pdynamo/pdynamo3/blob/main/addOns/pyCPR/CPRSaddlePointRefinement.py"
click node_dynamics "https://github.com/pdynamo/pdynamo3/tree/main/pSimulation"
click node_montecarlo "https://github.com/pdynamo/pdynamo3/tree/main/pSimulation"
click node_normalmodes "https://github.com/pdynamo/pdynamo3/blob/main/pSimulation/NormalModes.py"
click node_properties "https://github.com/pdynamo/pdynamo3/tree/main/pMolecule"
click node_pcetk "https://github.com/pdynamo/pdynamo3/blob/main/addOns/pcetk/CEModel.py"
click node_pm6ml "https://github.com/pdynamo/pdynamo3/blob/main/addOns/PM6ML/QCDeltaMLModel.py"
click node_pyscf "https://github.com/pdynamo/pdynamo3/blob/main/addOns/pySCF/QCModelPySCF.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_formats,node_system,node_output toneBlue
class node_core,node_arrays,node_mm,node_qc,node_hybrid,node_energy toneAmber
class node_optimization,node_transition,node_dynamics,node_montecarlo,node_normalmodes toneMint
class node_properties,node_pcetk,node_pm6ml,node_pyscf toneRose
class node_user toneIndigo
```

## Components

### Molecular input/output

- [Molecular formats](https://github.com/pdynamo/pdynamo3/tree/main/pBabel): `pBabel`
- [Molecular system](https://github.com/pdynamo/pdynamo3/tree/main/pMolecule): `pMolecule`
- [File and trajectory output](https://github.com/pdynamo/pdynamo3/tree/main/pBabel): `pBabel`

### Molecular models

- [Core services](https://github.com/pdynamo/pdynamo3/tree/main/pCore): `pCore`
- [Numerical arrays](https://github.com/pdynamo/pdynamo3/tree/main/pScientific/Arrays): `pScientific/Arrays`
- [MM force fields](https://github.com/pdynamo/pdynamo3/blob/main/pMolecule/MMModel/MMModel.py): `pMolecule/MMModel/MMModel.py`
- [QC methods](https://github.com/pdynamo/pdynamo3/tree/main/pMolecule/QCModel): `pMolecule/QCModel`
- [QC/MM coupling](https://github.com/pdynamo/pdynamo3/tree/main/pMolecule/NBModel): `pMolecule/NBModel`
- [Energy models](https://github.com/pdynamo/pdynamo3/blob/main/pMolecule/EnergyModel.py): `pMolecule/EnergyModel.py`

### Simulation workflows

- [Geometry optimization](https://github.com/pdynamo/pdynamo3/tree/main/pScientific/ObjectiveFunctionIterators): `pScientific/ObjectiveFunctionIterators`
- [Transition states](https://github.com/pdynamo/pdynamo3/blob/main/addOns/pyCPR/CPRSaddlePointRefinement.py): `addOns/pyCPR/CPRSaddlePointRefinement.py`
- [Molecular dynamics](https://github.com/pdynamo/pdynamo3/tree/main/pSimulation): `pSimulation`
- [Monte Carlo](https://github.com/pdynamo/pdynamo3/tree/main/pSimulation): `pSimulation`
- [Normal modes](https://github.com/pdynamo/pdynamo3/blob/main/pSimulation/NormalModes.py): `pSimulation/NormalModes.py`

### Analysis and add-ons

- [Properties and analysis](https://github.com/pdynamo/pdynamo3/tree/main/pMolecule): `pMolecule`
- [Proton energetics](https://github.com/pdynamo/pdynamo3/blob/main/addOns/pcetk/CEModel.py): `addOns/pcetk/CEModel.py`
- [PM6 delta learning](https://github.com/pdynamo/pdynamo3/blob/main/addOns/PM6ML/QCDeltaMLModel.py): `addOns/PM6ML/QCDeltaMLModel.py`
- [PySCF integration](https://github.com/pdynamo/pdynamo3/blob/main/addOns/pySCF/QCModelPySCF.py): `addOns/pySCF/QCModelPySCF.py`

### Other components

- **Researcher**

## Connections

- Researcher → Molecular formats: provides input
- Molecular formats → Molecular system: builds system (evidence: `pBabel/GromacsTopologyFileReader.py`)
- Molecular system → MM force fields: receives structure (evidence: `pMolecule/MMModel/MMModel.py`)
- Molecular system → QC methods: receives structure (evidence: `pMolecule/QCModel/GaussianBases/__extensions__/csource/BlockStorage.c`)
- MM force fields → Energy models: evaluates potential (evidence: `pMolecule/MMModel/MMModel.py`)
- QC methods → Energy models: evaluates potential
- QC/MM coupling → Energy models: couples potentials
- MM force fields → Core services: uses utilities (evidence: `pMolecule/MMModel/MMModel.py`)
- MM force fields → Numerical arrays: uses arrays (evidence: `pMolecule/MMModel/MMModel.py`)
- Geometry optimization → Energy models: optimizes energy
- Transition states → Energy models: searches surface
- Molecular dynamics → Energy models: uses potential
- Monte Carlo → Energy models: uses potential
- Normal modes → Energy models: analyzes potential
- Molecular system → Properties and analysis: yields properties
- Energy models → File and trajectory output: writes results
- Proton energetics → Molecular system: models protonation (evidence: `addOns/pcetk/CEModel.py`)
- Proton energetics → Core services: uses foundations (evidence: `addOns/pcetk/CEModel.py`)
- Proton energetics → Monte Carlo: uses sampling model (evidence: `addOns/pcetk/CEModel.py`)
- PM6 delta learning → QC methods: corrects PM6
- PySCF integration → QC methods: provides QC backend
