# aobeng-comp-chem/cheminsight3d architecture

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

## Overview

ChemInsight3D is a desktop molecular-orbital and electron-density viewer. The primary workflow is to open a supported wavefunction or cube file, parse and normalize its molecular data, compute orbital or density grids, then visualize and inspect them. The graph also includes localization, overlap/basis support, and source caching. Some viewer and native-extension wiring is only documented or indexed; those links are marked accordingly rather than inferred as direct calls.

Main entry points: [`ChemInsight3D.py`](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/ChemInsight3D.py) (Viewer application), [`grid_utils.py`](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/grid_utils.py) (Orbital grids), [`fchk_read.py`](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/fchk_read.py) (Gaussian reader), [`read_molden.py`](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/read_molden.py) (Molden reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_viewer["Viewer and inspection"]
  node_viewer_app["Viewer application<br/>[ChemInsight3D.py]"]
  node_chemview["Chemview interface<br/>[chemview.py]"]
end

subgraph group_chemistry["Input and localization"]
  node_fchk_reader["Gaussian reader<br/>[fchk_read.py]"]
  node_molden_reader["Molden reader<br/>[read_molden.py]"]
  node_nbo_reader["NBO reader<br/>[nbo_read.py]"]
  node_localization["Pipek-Mezey localization<br/>[localization_io.py]"]
  node_native_localization["Native localization"]
end

subgraph group_compute["Grid computation"]
  node_density["Density analysis"]
  node_grid["Orbital grids<br/>[grid_utils.py]"]
  node_native_grid["Native grid engine"]
end

subgraph group_support["Shared numerical support"]
  node_overlap["AO overlap<br/>[overlap_matrix.py]"]
  node_basis["Basis definitions<br/>[bas_dict.py]"]
  node_angular["Angular functions<br/>[angular_funct.py]"]
  node_cache[("Source cache<br/>[source_cache.py]")]
  node_native_overlap["Native overlap<br/>[overlap_matrix.cpp]"]
end

node_user(("Desktop user"))
node_cube_files["Cube files"]
node_wavefunction_files["Wavefunction files"]

node_user -->|"opens viewer"| node_viewer_app
node_viewer_app -->|"opens cubes"| node_cube_files
node_user -->|"loads source"| node_wavefunction_files
node_viewer_app -->|"loads Gaussian"| node_fchk_reader
node_viewer_app -->|"loads Molden"| node_molden_reader
node_viewer_app -->|"loads NBO"| node_nbo_reader
node_viewer_app -->|"runs localization"| node_localization
node_viewer_app -->|"requests density grids"| node_density
node_fchk_reader -->|"evaluates orbital grids"| node_grid
node_molden_reader -->|"evaluates orbital grids"| node_grid
node_nbo_reader -->|"evaluates orbital grids"| node_grid
node_density -->|"builds grid"| node_grid
node_density -->|"gets occupations"| node_localization
node_grid -->|"evaluates angular parts"| node_angular
node_fchk_reader -->|"computes overlap"| node_overlap
node_molden_reader -->|"computes overlap"| node_overlap
node_nbo_reader -.->|"computes overlap"| node_overlap
node_fchk_reader -.->|"uses basis definitions"| node_basis
node_molden_reader -.->|"uses basis definitions"| node_basis
node_nbo_reader -->|"uses basis definitions"| node_basis
node_fchk_reader -->|"caches parsed data"| node_cache
node_molden_reader -->|"caches parsed data"| node_cache
node_nbo_reader -->|"caches parsed data"| node_cache
node_grid -.->|"optionally accelerates"| node_native_grid
node_localization -.->|"optionally accelerates"| node_native_localization
node_overlap -.->|"optionally accelerates"| node_native_overlap

click node_viewer_app "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/ChemInsight3D.py"
click node_chemview "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/chemview.py"
click node_fchk_reader "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/fchk_read.py"
click node_molden_reader "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/read_molden.py"
click node_nbo_reader "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/nbo_read.py"
click node_localization "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/localization_io.py"
click node_density "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/density_analysis.py"
click node_grid "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/grid_utils.py"
click node_overlap "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/overlap_matrix.py"
click node_basis "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/bas_dict.py"
click node_angular "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/angular_funct.py"
click node_cache "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/source_cache.py"
click node_native_grid "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/electron_density_opt_omp.cpp"
click node_native_localization "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/localization_native.cpp"
click node_native_overlap "https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/overlap_matrix.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_viewer_app,node_chemview,node_user toneBlue
class node_fchk_reader,node_molden_reader,node_nbo_reader,node_localization,node_native_localization toneAmber
class node_density,node_grid,node_native_grid toneMint
class node_overlap,node_basis,node_angular,node_cache,node_native_overlap toneRose
class node_cube_files,node_wavefunction_files toneIndigo
```

## Components

### Viewer and inspection

- [Viewer application](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/ChemInsight3D.py): `ChemInsight3D.py`
- [Chemview interface](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/chemview.py): `chemview.py`

### Input and localization

- [Gaussian reader](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/fchk_read.py): `fchk_read.py`
- [Molden reader](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/read_molden.py): `read_molden.py`
- [NBO reader](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/nbo_read.py): `nbo_read.py`
- [Pipek-Mezey localization](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/localization_io.py): `localization_io.py`
- [Native localization](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/localization_native.cpp): `localization_native.cpp`

### Grid computation

- [Density analysis](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/density_analysis.py): `density_analysis.py`
- [Orbital grids](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/grid_utils.py): `grid_utils.py`
- [Native grid engine](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/electron_density_opt_omp.cpp): `electron_density_opt_omp.cpp`

### Shared numerical support

- [AO overlap](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/overlap_matrix.py): `overlap_matrix.py`
- [Basis definitions](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/bas_dict.py): `bas_dict.py`
- [Angular functions](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/angular_funct.py): `angular_funct.py`
- [Source cache](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/source_cache.py): `source_cache.py`
- [Native overlap](https://github.com/aobeng-comp-chem/cheminsight3d/blob/main/overlap_matrix.cpp): `overlap_matrix.cpp`

### Other components

- **Desktop user**
- **Cube files**
- **Wavefunction files**

## Connections

- Desktop user → Viewer application: opens viewer (evidence: `README.md`)
- Viewer application → Cube files: opens cubes (evidence: `README.md`)
- Desktop user → Wavefunction files: loads source (evidence: `README.md`)
- Viewer application → Gaussian reader: loads Gaussian (evidence: `ChemInsight3D.py`)
- Viewer application → Molden reader: loads Molden (evidence: `ChemInsight3D.py`)
- Viewer application → NBO reader: loads NBO (evidence: `ChemInsight3D.py`)
- Viewer application → Pipek-Mezey localization: runs localization (evidence: `ChemInsight3D.py`)
- Viewer application → Density analysis: requests density grids (evidence: `ChemInsight3D.py`)
- Gaussian reader → Orbital grids: evaluates orbital grids (evidence: `fchk_read.py`)
- Molden reader → Orbital grids: evaluates orbital grids (evidence: `read_molden.py`)
- NBO reader → Orbital grids: evaluates orbital grids (evidence: `nbo_read.py`)
- Density analysis → Orbital grids: builds grid (evidence: `density_analysis.py`)
- Density analysis → Pipek-Mezey localization: gets occupations (evidence: `density_analysis.py`)
- Orbital grids → Angular functions: evaluates angular parts (evidence: `grid_utils.py`)
- Gaussian reader → AO overlap: computes overlap (evidence: `fchk_read.py`)
- Molden reader → AO overlap: computes overlap (evidence: `read_molden.py`)
- NBO reader → AO overlap: computes overlap (evidence: `nbo_read.py`)
- Gaussian reader → Basis definitions: uses basis definitions (evidence: `fchk_read.py`)
- Molden reader → Basis definitions: uses basis definitions (evidence: `read_molden.py`)
- NBO reader → Basis definitions: uses basis definitions (evidence: `nbo_read.py`)
- Gaussian reader → Source cache: caches parsed data (evidence: `fchk_read.py`)
- Molden reader → Source cache: caches parsed data (evidence: `read_molden.py`)
- NBO reader → Source cache: caches parsed data (evidence: `nbo_read.py`)
- Orbital grids → Native grid engine: optionally accelerates (evidence: `README.md`)
- Pipek-Mezey localization → Native localization: optionally accelerates (evidence: `README.md`)
- AO overlap → Native overlap: optionally accelerates (evidence: `README.md`)
