# aobeng-comp-chem/nbotools architecture

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

- Interactive diagram: https://gitdiagram.com/aobeng-comp-chem/nbotools
- Repository: https://github.com/aobeng-comp-chem/nbotools

## Overview

NBOTools is an interactive Python toolkit for analyzing NBO calculation outputs. Users provide NBO plot files and a `.47` basis description; `main.py` dispatches menu choices to matrix transformations, orbital localization, bond-order analysis, valence–core work, and NLMO partition analysis. Matrix extraction and basis interpretation support those analyses, while separate scripts reconstruct/visualize PNAOs and check `.47` basis conventions. The README documents capabilities beyond the sampled excerpts; edges below are limited to documented or indexed relationships.

Main entry points: [`packages/main.py`](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/main.py) (Interactive menu), [`packages/sep_mat.py`](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/sep_mat.py) (Matrix transforms), [`packages/val_core_ortho.py`](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/val_core_ortho.py) (Valence–core solver), [`packages/pm_localization.py`](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/pm_localization.py) (Pipek–Mezey localization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Input and basis"]
  node_extractor["NBO data extraction"]
  node_basis["Basis interpretation<br/>[basis_info.py]"]
end

subgraph group_matrix["Matrix processing"]
  node_matrices["Matrix transforms<br/>[sep_mat.py]"]
  node_matrix_ui["Matrix selection and export<br/>[my_func.py]"]
end

subgraph group_analysis["Orbital analysis"]
  node_menu["Interactive menu<br/>[main.py]"]
  node_localization["Pipek–Mezey localization<br/>[pm_localization.py]"]
  node_population["Population analysis<br/>[pop_analys.py]"]
  node_bond["Bond-order analysis<br/>[bond_indices.py]"]
  node_nlmo["NLMO partition analysis<br/>[nlmo_partition.py]"]
  node_valcore["Valence–core solver<br/>[val_core_ortho.py]"]
  node_promolecule["Promolecule density"]
end

subgraph group_utilities["Supporting utilities"]
  node_visualizer["Orbital data output<br/>[visualizer.py]"]
  node_pnao_script["PNAO reconstruction viewer<br/>[nao2pnao.py]"]
  node_namelist_converter[".47 namelist converter"]
  node_namelist_checker["Basis convention checker"]
end

node_user(("Analyst"))
node_nbo_files["NBO plot files"]
node_basis_file[".47 basis file"]

node_user -->|"provides"| node_nbo_files
node_user -->|"provides"| node_basis_file
node_user -->|"selects analysis"| node_menu
node_nbo_files -->|"parsed from"| node_extractor
node_extractor -->|"supplies matrices"| node_matrices
node_basis_file -->|"describes basis"| node_basis
node_menu -->|"dispatches matrix actions"| node_matrix_ui
node_menu -->|"dispatches matrix actions"| node_matrices
node_menu -->|"dispatches"| node_localization
node_menu -->|"dispatches"| node_bond
node_menu -->|"dispatches"| node_nlmo
node_menu -->|"dispatches"| node_valcore
node_matrices -->|"uses basis mapping"| node_basis
node_bond -->|"uses basis data"| node_basis
node_bond -->|"uses matrices"| node_matrices
node_bond -->|"uses promolecule data"| node_promolecule
node_nlmo -->|"uses basis data"| node_basis
node_nlmo -->|"uses matrices"| node_matrices
node_localization -->|"uses selection helpers"| node_matrix_ui
node_localization -->|"uses population analysis"| node_population
node_localization -->|"uses output routines"| node_visualizer
node_valcore -->|"uses input helpers"| node_matrix_ui
node_valcore -->|"uses matrix data"| node_matrices
node_valcore -->|"uses localization"| node_localization
node_valcore -->|"uses population analysis"| node_population
node_user -->|"runs separately"| node_pnao_script
node_user -->|"runs checker workflow"| node_namelist_converter
node_namelist_converter -->|"creates checker input"| node_namelist_checker

click node_menu "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/main.py"
click node_extractor "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/extract_nbo_files.py"
click node_basis "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/basis_info.py"
click node_matrices "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/sep_mat.py"
click node_matrix_ui "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/my_func.py"
click node_localization "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/pm_localization.py"
click node_population "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/pop_analys.py"
click node_bond "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/bond_indices.py"
click node_nlmo "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/nlmo_partition.py"
click node_valcore "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/val_core_ortho.py"
click node_promolecule "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/generate_promolecule.py"
click node_visualizer "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/visualizer.py"
click node_pnao_script "https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/nao2pnao.py"
click node_namelist_converter "https://github.com/aobeng-comp-chem/nbotools/blob/main/tools/convert-47-to-namelists.py"
click node_namelist_checker "https://github.com/aobeng-comp-chem/nbotools/tree/main/tools/parse-namelists"

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_extractor,node_basis toneBlue
class node_matrices,node_matrix_ui toneAmber
class node_menu,node_localization,node_population,node_bond,node_nlmo,node_valcore,node_promolecule toneMint
class node_visualizer,node_pnao_script,node_namelist_converter,node_namelist_checker toneRose
class node_user,node_nbo_files,node_basis_file toneIndigo
```

## Components

### Input and basis

- [NBO data extraction](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/extract_nbo_files.py): `packages/extract_nbo_files.py`
- [Basis interpretation](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/basis_info.py): `packages/basis_info.py`

### Matrix processing

- [Matrix transforms](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/sep_mat.py): `packages/sep_mat.py`
- [Matrix selection and export](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/my_func.py): `packages/my_func.py`

### Orbital analysis

- [Interactive menu](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/main.py): `packages/main.py`
- [Pipek–Mezey localization](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/pm_localization.py): `packages/pm_localization.py`
- [Population analysis](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/pop_analys.py): `packages/pop_analys.py`
- [Bond-order analysis](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/bond_indices.py): `packages/bond_indices.py`
- [NLMO partition analysis](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/nlmo_partition.py): `packages/nlmo_partition.py`
- [Valence–core solver](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/val_core_ortho.py): `packages/val_core_ortho.py`
- [Promolecule density](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/generate_promolecule.py): `packages/generate_promolecule.py`

### Supporting utilities

- [Orbital data output](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/visualizer.py): `packages/visualizer.py`
- [PNAO reconstruction viewer](https://github.com/aobeng-comp-chem/nbotools/blob/main/packages/nao2pnao.py): `packages/nao2pnao.py`
- [.47 namelist converter](https://github.com/aobeng-comp-chem/nbotools/blob/main/tools/convert-47-to-namelists.py): `tools/convert-47-to-namelists.py`
- [Basis convention checker](https://github.com/aobeng-comp-chem/nbotools/tree/main/tools/parse-namelists): `tools/parse-namelists`

### Other components

- **Analyst**
- **NBO plot files**
- **.47 basis file**

## Connections

- Analyst → NBO plot files: provides (evidence: `README.md`)
- Analyst → .47 basis file: provides (evidence: `README.md`)
- Analyst → Interactive menu: selects analysis (evidence: `packages/main.py`)
- NBO plot files → NBO data extraction: parsed from (evidence: `README.md`)
- NBO data extraction → Matrix transforms: supplies matrices (evidence: `packages/sep_mat.py`)
- .47 basis file → Basis interpretation: describes basis (evidence: `README.md`)
- Interactive menu → Matrix selection and export: dispatches matrix actions (evidence: `packages/main.py`)
- Interactive menu → Matrix transforms: dispatches matrix actions (evidence: `packages/main.py`)
- Interactive menu → Pipek–Mezey localization: dispatches (evidence: `packages/main.py`)
- Interactive menu → Bond-order analysis: dispatches (evidence: `packages/main.py`)
- Interactive menu → NLMO partition analysis: dispatches (evidence: `packages/main.py`)
- Interactive menu → Valence–core solver: dispatches (evidence: `packages/main.py`)
- Matrix transforms → Basis interpretation: uses basis mapping (evidence: `packages/sep_mat.py`)
- Bond-order analysis → Basis interpretation: uses basis data (evidence: `packages/bond_indices.py`)
- Bond-order analysis → Matrix transforms: uses matrices (evidence: `packages/bond_indices.py`)
- Bond-order analysis → Promolecule density: uses promolecule data (evidence: `packages/bond_indices.py`)
- NLMO partition analysis → Basis interpretation: uses basis data (evidence: `packages/nlmo_partition.py`)
- NLMO partition analysis → Matrix transforms: uses matrices (evidence: `packages/nlmo_partition.py`)
- Pipek–Mezey localization → Matrix selection and export: uses selection helpers (evidence: `packages/pm_localization.py`)
- Pipek–Mezey localization → Population analysis: uses population analysis (evidence: `packages/pm_localization.py`)
- Pipek–Mezey localization → Orbital data output: uses output routines (evidence: `packages/pm_localization.py`)
- Valence–core solver → Matrix selection and export: uses input helpers (evidence: `packages/val_core_ortho.py`)
- Valence–core solver → Matrix transforms: uses matrix data (evidence: `packages/val_core_ortho.py`)
- Valence–core solver → Pipek–Mezey localization: uses localization (evidence: `packages/val_core_ortho.py`)
- Valence–core solver → Population analysis: uses population analysis (evidence: `packages/val_core_ortho.py`)
- Analyst → PNAO reconstruction viewer: runs separately (evidence: `README.md`)
- Analyst → .47 namelist converter: runs checker workflow (evidence: `README.md`)
- .47 namelist converter → Basis convention checker: creates checker input (evidence: `README.md`)
