# aobeng-comp-chem/nbo2cube architecture

> Architecture diagram of the GitHub repository aobeng-comp-chem/nbo2cube, 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/nbo2cube
- Repository: https://github.com/aobeng-comp-chem/nbo2cube

## Overview

nbo2cube is a command-line molecular-orbital volume generator: users provide basis and NBO orbital files, choose orbitals and a grid, then calculate orbital values and write Gaussian cube files. The main Python entry point coordinates parsing, grid setup, and serial/parallel calculation; an optimized C++ mode is also documented. The graph reflects relationships shown in the excerpts, SOURCE INDEX, or README; implementation details for some documented calculation modes are not fully sampled.

Main entry points: [`nbo2cube.py`](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/nbo2cube.py) (Calculation coordinator), [`readbasis.py`](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/readbasis.py) (Basis parsing), [`angular_funct.py`](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/angular_funct.py) (Angular functions), [`read_orb_file.py`](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/read_orb_file.py) (Orbital selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Input processing"]
  node_basis["Basis parsing<br/>[readbasis.py]"]
  node_basisdict["Basis term data<br/>[bas_dict.py]"]
  node_normalization["Basis normalization<br/>[readbasis.py]"]
  node_orbitalinput["Orbital selection<br/>[read_orb_file.py]"]
end

subgraph group_setup["Grid setup"]
  node_grid["Grid configuration<br/>[nbo2cube.py]"]
end

subgraph group_calculation["Orbital calculation"]
  node_coordinator["Calculation coordinator<br/>[nbo2cube.py]"]
  node_angular["Angular functions<br/>[angular_funct.py]"]
  node_serial["Serial evaluation<br/>[nbo2cube.py]"]
  node_parallel["Parallel evaluation<br/>[nbo2cube.py]"]
  node_optimized["Optimized C++"]
end

subgraph group_output["Cube output"]
  node_cube["Cube files"]
end

node_user(("User"))

node_user -->|"provides inputs"| node_coordinator
node_coordinator -->|"loads basis"| node_basis
node_basis -->|"uses term data"| node_basisdict
node_coordinator -->|"loads orbitals"| node_orbitalinput
node_orbitalinput -->|"reads basis size"| node_basis
node_basis -->|"normalizes coefficients"| node_normalization
node_coordinator -->|"configures grid"| node_grid
node_coordinator -->|"evaluates serially"| node_serial
node_coordinator -->|"dispatches workers"| node_parallel
node_coordinator -->|"uses C++ mode"| node_optimized
node_coordinator -->|"evaluates angular terms"| node_angular
node_serial -->|"calls"| node_angular
node_parallel -->|"calls"| node_angular
node_coordinator -->|"writes cube files"| node_cube

click node_basis "https://github.com/aobeng-comp-chem/nbo2cube/blob/main/readbasis.py"
click node_basisdict "https://github.com/aobeng-comp-chem/nbo2cube/blob/main/bas_dict.py"
click node_normalization "https://github.com/aobeng-comp-chem/nbo2cube/blob/main/readbasis.py"
click node_orbitalinput "https://github.com/aobeng-comp-chem/nbo2cube/blob/main/read_orb_file.py"
click node_grid "https://github.com/aobeng-comp-chem/nbo2cube/blob/main/nbo2cube.py"
click node_coordinator "https://github.com/aobeng-comp-chem/nbo2cube/blob/main/nbo2cube.py"
click node_angular "https://github.com/aobeng-comp-chem/nbo2cube/blob/main/angular_funct.py"
click node_serial "https://github.com/aobeng-comp-chem/nbo2cube/blob/main/nbo2cube.py"
click node_parallel "https://github.com/aobeng-comp-chem/nbo2cube/blob/main/nbo2cube.py"
click node_optimized "https://github.com/aobeng-comp-chem/nbo2cube/blob/main/electron_density_opt_omp.cpp"

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_basis,node_basisdict,node_normalization,node_orbitalinput,node_user toneBlue
class node_grid toneAmber
class node_coordinator,node_angular,node_serial,node_parallel,node_optimized toneMint
class node_cube toneRose
```

## Components

### Input processing

- [Basis parsing](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/readbasis.py): `readbasis.py`
- [Basis term data](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/bas_dict.py): `bas_dict.py`
- [Basis normalization](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/readbasis.py): `readbasis.py`
- [Orbital selection](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/read_orb_file.py): `read_orb_file.py`

### Grid setup

- [Grid configuration](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/nbo2cube.py): `nbo2cube.py`

### Orbital calculation

- [Calculation coordinator](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/nbo2cube.py): `nbo2cube.py`
- [Angular functions](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/angular_funct.py): `angular_funct.py`
- [Serial evaluation](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/nbo2cube.py): `nbo2cube.py`
- [Parallel evaluation](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/nbo2cube.py): `nbo2cube.py`
- [Optimized C++](https://github.com/aobeng-comp-chem/nbo2cube/blob/main/electron_density_opt_omp.cpp): `electron_density_opt_omp.cpp`

### Cube output

- **Cube files**

### Other components

- **User**

## Connections

- User → Calculation coordinator: provides inputs (evidence: `README.md`)
- Calculation coordinator → Basis parsing: loads basis (evidence: `nbo2cube.py`)
- Basis parsing → Basis term data: uses term data (evidence: `readbasis.py`)
- Calculation coordinator → Orbital selection: loads orbitals (evidence: `nbo2cube.py`)
- Orbital selection → Basis parsing: reads basis size (evidence: `read_orb_file.py`)
- Basis parsing → Basis normalization: normalizes coefficients (evidence: `readbasis.py`)
- Calculation coordinator → Grid configuration: configures grid (evidence: `nbo2cube.py`)
- Calculation coordinator → Serial evaluation: evaluates serially (evidence: `README.md`)
- Calculation coordinator → Parallel evaluation: dispatches workers (evidence: `nbo2cube.py`)
- Calculation coordinator → Optimized C++: uses C++ mode (evidence: `README.md`)
- Calculation coordinator → Angular functions: evaluates angular terms (evidence: `nbo2cube.py`)
- Serial evaluation → Angular functions: calls (evidence: `nbo2cube.py`)
- Parallel evaluation → Angular functions: calls (evidence: `nbo2cube.py`)
- Calculation coordinator → Cube files: writes cube files (evidence: `nbo2cube.py`)
