# eipgen/deepatb architecture

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

- Interactive diagram: https://gitdiagram.com/eipgen/deepatb
- Repository: https://github.com/eipgen/deepatb

## Overview

DeePaTB is a machine-learning correction to the semi-empirical Amesp quantum-chemistry method. Its main workflow prepares molecular examples and Amesp baseline results, derives projected-density descriptors and energy/force correction labels, trains a DeePKS model, then combines model corrections with Amesp results for prediction. The repository also supports single-XYZ evaluation, frozen-density analytic forces, an experimental Amesp response path, and finite-difference force checks. The graph follows README workflows and sampled scripts; unsampled training internals and several preparation steps are represented only at their documented boundaries.

Main entry points: [`job/03_force/evaluate_xyz.py`](https://github.com/eipgen/deepatb/blob/main/job/03_force/evaluate_xyz.py) (XYZ evaluation), [`Amesp/Bin/amesp`](https://github.com/eipgen/deepatb/blob/main/Amesp/Bin/amesp) (Amesp calculations), [`deepatb/model_io.py`](https://github.com/eipgen/deepatb/blob/main/deepatb/model_io.py) (Model loading), [`deepatb/dataset.py`](https://github.com/eipgen/deepatb/blob/main/deepatb/dataset.py) (Dataset validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Data preparation"]
  node_prepare["Prepare examples"]
  node_amesp["Amesp calculations"]
  node_descriptors["Descriptor generation"]
  node_force_labels["Force labels"]
  node_energydata["Energy labels"]
end

subgraph group_learning["Model learning"]
  node_datasets["Dataset validation<br/>[dataset.py]"]
  node_trainer["DeePKS training"]
  node_model["Trained model<br/>[model.pth]"]
end

subgraph group_runtime["Prediction and forces"]
  node_energy_eval["Energy prediction<br/>[get_deepatb_ene.py]"]
  node_force_eval["Dataset forces"]
  node_singlepoint["XYZ evaluation<br/>[evaluate_xyz.py]"]
  node_fdcheck["Finite-difference check"]
end

subgraph group_core["DeePaTB core"]
  node_parse["Amesp parsers<br/>[amesp.py]"]
  node_descriptorcore["Projected descriptors<br/>[descriptor.py]"]
  node_modelio["Model loading<br/>[model_io.py]"]
  node_forcecore["Force correction<br/>[force.py]"]
  node_runner["Amesp runner<br/>[amesp_runner.py]"]
  node_response["Post-SCF response<br/>[amesp_response.py]"]
  node_selfconsistent["Correction potential<br/>[self_consistent.py]"]
end

node_user(("Researcher"))
node_xyz["XYZ molecules"]

node_user -->|"provides"| node_xyz
node_xyz -->|"supplies geometries"| node_prepare
node_prepare -->|"runs calculations"| node_amesp
node_amesp -->|"writes output"| node_parse
node_parse -->|"provides density"| node_descriptors
node_descriptors -->|"computes"| node_descriptorcore
node_descriptorcore -->|"saves descriptors"| node_datasets
node_amesp -->|"supplies base forces"| node_force_labels
node_force_labels -->|"saves force targets"| node_datasets
node_energydata -->|"saves energy targets"| node_datasets
node_datasets -->|"provides training data"| node_trainer
node_trainer -->|"trains"| node_model
node_model -->|"loaded by"| node_modelio
node_modelio -->|"loads model"| node_energy_eval
node_energy_eval -->|"evaluates model"| node_modelio
node_energy_eval -->|"combines baseline energy"| node_amesp
node_modelio -->|"loads model"| node_force_eval
node_force_eval -->|"computes correction"| node_forcecore
node_force_eval -->|"combines base results"| node_amesp
node_user -->|"requests evaluation"| node_singlepoint
node_xyz -->|"provides geometry"| node_singlepoint
node_singlepoint -->|"runs Amesp"| node_runner
node_runner -->|"invokes"| node_amesp
node_runner -->|"parses results"| node_parse
node_singlepoint -->|"builds descriptor"| node_descriptorcore
node_singlepoint -->|"loads model"| node_modelio
node_singlepoint -->|"computes frozen force"| node_forcecore
node_singlepoint -.->|"optionally requests response"| node_response
node_response -.->|"runs response jobs"| node_amesp
node_forcecore -.->|"provides correction potential"| node_selfconsistent
node_user -->|"requests validation"| node_fdcheck
node_fdcheck -->|"evaluates displaced geometries"| node_singlepoint

click node_prepare "https://github.com/eipgen/deepatb/tree/main/job/01_prepare"
click node_amesp "https://github.com/eipgen/deepatb/blob/main/Amesp/Bin/amesp"
click node_parse "https://github.com/eipgen/deepatb/blob/main/deepatb/amesp.py"
click node_descriptors "https://github.com/eipgen/deepatb/blob/main/job/01_prepare/03_get_aTB_decriptor.py"
click node_descriptorcore "https://github.com/eipgen/deepatb/blob/main/deepatb/descriptor.py"
click node_force_labels "https://github.com/eipgen/deepatb/blob/main/job/01_prepare/05_get_delta_force.py"
click node_datasets "https://github.com/eipgen/deepatb/blob/main/deepatb/dataset.py"
click node_trainer "https://github.com/eipgen/deepatb/tree/main/job/02_train"
click node_model "https://github.com/eipgen/deepatb/blob/main/job/02_train/model.pth"
click node_modelio "https://github.com/eipgen/deepatb/blob/main/deepatb/model_io.py"
click node_energy_eval "https://github.com/eipgen/deepatb/blob/main/job/02_train/get_deepatb_ene.py"
click node_force_eval "https://github.com/eipgen/deepatb/blob/main/job/02_train/get_deepatb_force.py"
click node_forcecore "https://github.com/eipgen/deepatb/blob/main/deepatb/force.py"
click node_singlepoint "https://github.com/eipgen/deepatb/blob/main/job/03_force/evaluate_xyz.py"
click node_runner "https://github.com/eipgen/deepatb/blob/main/deepatb/amesp_runner.py"
click node_response "https://github.com/eipgen/deepatb/blob/main/deepatb/amesp_response.py"
click node_selfconsistent "https://github.com/eipgen/deepatb/blob/main/deepatb/self_consistent.py"
click node_fdcheck "https://github.com/eipgen/deepatb/blob/main/job/03_force/check_force_finite_difference.py"
click node_energydata "https://github.com/eipgen/deepatb/blob/main/job/01_prepare/04_get_delta_energy.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_prepare,node_amesp,node_descriptors,node_force_labels,node_energydata toneBlue
class node_datasets,node_trainer,node_model toneAmber
class node_energy_eval,node_force_eval,node_singlepoint,node_fdcheck toneMint
class node_parse,node_descriptorcore,node_modelio,node_forcecore,node_runner,node_response,node_selfconsistent toneRose
class node_user,node_xyz toneIndigo
```

## Components

### Data preparation

- [Prepare examples](https://github.com/eipgen/deepatb/tree/main/job/01_prepare): `job/01_prepare`
- [Amesp calculations](https://github.com/eipgen/deepatb/blob/main/Amesp/Bin/amesp): `Amesp/Bin/amesp`
- [Descriptor generation](https://github.com/eipgen/deepatb/blob/main/job/01_prepare/03_get_aTB_decriptor.py): `job/01_prepare/03_get_aTB_decriptor.py`
- [Force labels](https://github.com/eipgen/deepatb/blob/main/job/01_prepare/05_get_delta_force.py): `job/01_prepare/05_get_delta_force.py`
- [Energy labels](https://github.com/eipgen/deepatb/blob/main/job/01_prepare/04_get_delta_energy.py): `job/01_prepare/04_get_delta_energy.py`

### Model learning

- [Dataset validation](https://github.com/eipgen/deepatb/blob/main/deepatb/dataset.py): `deepatb/dataset.py`
- [DeePKS training](https://github.com/eipgen/deepatb/tree/main/job/02_train): `job/02_train`
- [Trained model](https://github.com/eipgen/deepatb/blob/main/job/02_train/model.pth): `job/02_train/model.pth`

### Prediction and forces

- [Energy prediction](https://github.com/eipgen/deepatb/blob/main/job/02_train/get_deepatb_ene.py): `job/02_train/get_deepatb_ene.py`
- [Dataset forces](https://github.com/eipgen/deepatb/blob/main/job/02_train/get_deepatb_force.py): `job/02_train/get_deepatb_force.py`
- [XYZ evaluation](https://github.com/eipgen/deepatb/blob/main/job/03_force/evaluate_xyz.py): `job/03_force/evaluate_xyz.py`
- [Finite-difference check](https://github.com/eipgen/deepatb/blob/main/job/03_force/check_force_finite_difference.py): `job/03_force/check_force_finite_difference.py`

### DeePaTB core

- [Amesp parsers](https://github.com/eipgen/deepatb/blob/main/deepatb/amesp.py): `deepatb/amesp.py`
- [Projected descriptors](https://github.com/eipgen/deepatb/blob/main/deepatb/descriptor.py): `deepatb/descriptor.py`
- [Model loading](https://github.com/eipgen/deepatb/blob/main/deepatb/model_io.py): `deepatb/model_io.py`
- [Force correction](https://github.com/eipgen/deepatb/blob/main/deepatb/force.py): `deepatb/force.py`
- [Amesp runner](https://github.com/eipgen/deepatb/blob/main/deepatb/amesp_runner.py): `deepatb/amesp_runner.py`
- [Post-SCF response](https://github.com/eipgen/deepatb/blob/main/deepatb/amesp_response.py): `deepatb/amesp_response.py`
- [Correction potential](https://github.com/eipgen/deepatb/blob/main/deepatb/self_consistent.py): `deepatb/self_consistent.py`

### Other components

- **Researcher**
- **XYZ molecules**

## Connections

- Researcher → XYZ molecules: provides
- XYZ molecules → Prepare examples: supplies geometries
- Prepare examples → Amesp calculations: runs calculations
- Amesp calculations → Amesp parsers: writes output
- Amesp parsers → Descriptor generation: provides density
- Descriptor generation → Projected descriptors: computes
- Projected descriptors → Dataset validation: saves descriptors
- Amesp calculations → Force labels: supplies base forces
- Force labels → Dataset validation: saves force targets
- Energy labels → Dataset validation: saves energy targets
- Dataset validation → DeePKS training: provides training data
- DeePKS training → Trained model: trains
- Trained model → Model loading: loaded by
- Model loading → Energy prediction: loads model
- Energy prediction → Model loading: evaluates model
- Energy prediction → Amesp calculations: combines baseline energy
- Model loading → Dataset forces: loads model
- Dataset forces → Force correction: computes correction
- Dataset forces → Amesp calculations: combines base results
- Researcher → XYZ evaluation: requests evaluation
- XYZ molecules → XYZ evaluation: provides geometry
- XYZ evaluation → Amesp runner: runs Amesp
- Amesp runner → Amesp calculations: invokes
- Amesp runner → Amesp parsers: parses results
- XYZ evaluation → Projected descriptors: builds descriptor
- XYZ evaluation → Model loading: loads model
- XYZ evaluation → Force correction: computes frozen force
- XYZ evaluation → Post-SCF response: optionally requests response
- Post-SCF response → Amesp calculations: runs response jobs
- Force correction → Correction potential: provides correction potential
- Researcher → Finite-difference check: requests validation
- Finite-difference check → XYZ evaluation: evaluates displaced geometries