# mattatzb/rhf-from-scratch architecture

> Architecture diagram of the GitHub repository mattatzb/rhf-from-scratch, 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/mattatzb/rhf-from-scratch
- Repository: https://github.com/mattatzb/rhf-from-scratch

## Overview

This is an educational, from-scratch restricted Hartree–Fock (RHF) program for small molecules, with a two-electron full configuration interaction (FCI) extension and diatomic scan tools. The main workflow constructs molecular geometry, builds a Gaussian basis, evaluates integrals, and runs the RHF self-consistent-field loop to produce energies. Separate drivers scan geometries, optionally add FCI, or compare results with Psi4. Edges reflect calls visible in excerpts or capabilities documented in the README; unsampled internals are not assumed.

Main entry points: [`basis.py`](https://github.com/mattatzb/rhf-from-scratch/blob/main/basis.py) (Basis builder), [`scf.py`](https://github.com/mattatzb/rhf-from-scratch/blob/main/scf.py) (RHF SCF), [`run_ci.py`](https://github.com/mattatzb/rhf-from-scratch/blob/main/run_ci.py) (RHF plus FCI driver), [`run_ci_scan.py`](https://github.com/mattatzb/rhf-from-scratch/blob/main/run_ci_scan.py) (FCI scan)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_molecular_model["Molecular model"]
  node_molecule["Molecule geometry<br/>[mol.py]"]
  node_basis_builder["Basis builder<br/>[basis.py]"]
  node_basis_data["Bundled basis sets"]
end

subgraph group_electronic_structure["Electronic structure"]
  node_integrals["Gaussian integrals<br/>[integrals.py]"]
  node_rhf["RHF SCF<br/>[scf.py]"]
  node_fci["Two-electron FCI<br/>[ci.py]"]
end

subgraph group_scan_workflows["Scan workflows"]
  node_rhf_example["RHF example<br/>[main.py]"]
  node_rhf_scan["RHF diatomic scan<br/>[scan.py]"]
  node_fci_driver["RHF plus FCI driver<br/>[run_ci.py]"]
  node_fci_scan["FCI scan<br/>[run_ci_scan.py]"]
  node_psi4_scan["Psi4 comparison scan<br/>[run_psi4_scan.py]"]
end

subgraph group_results_integrations["Results and integrations"]
  node_psi4["Psi4"]
  node_run_logging["Run records<br/>[runlog.py]"]
end

node_user(("User"))

node_user -->|"runs example"| node_rhf_example
node_user -->|"runs scan"| node_rhf_scan
node_user -->|"runs driver"| node_fci_driver
node_user -->|"runs scan"| node_fci_scan
node_user -->|"runs comparison"| node_psi4_scan
node_rhf_example -->|"constructs"| node_molecule
node_rhf_example -->|"builds basis"| node_basis_builder
node_rhf_example -->|"runs SCF"| node_rhf
node_basis_builder -->|"reads geometry"| node_molecule
node_basis_builder -->|"loads basis data"| node_basis_data
node_rhf -->|"builds integrals"| node_integrals
node_rhf -->|"uses molecule"| node_molecule
node_rhf -->|"uses basis"| node_basis_builder
node_integrals -->|"uses nuclei"| node_molecule
node_integrals -->|"integrates functions"| node_basis_builder
node_rhf_scan -->|"constructs geometries"| node_molecule
node_rhf_scan -->|"builds basis"| node_basis_builder
node_rhf_scan -->|"runs SCF"| node_rhf
node_fci_driver -->|"uses geometry helper"| node_rhf_scan
node_fci_driver -->|"builds basis"| node_basis_builder
node_fci_driver -->|"runs SCF"| node_rhf
node_fci_driver -->|"builds ERIs"| node_integrals
node_fci_driver -->|"builds CI energy"| node_fci
node_fci_scan -->|"uses geometry helper"| node_rhf_scan
node_fci_scan -->|"builds basis"| node_basis_builder
node_fci_scan -->|"runs SCF"| node_rhf
node_fci_scan -->|"builds ERIs"| node_integrals
node_fci_scan -->|"computes FCI"| node_fci
node_psi4_scan -->|"requests energies"| node_psi4

click node_molecule "https://github.com/mattatzb/rhf-from-scratch/blob/main/mol.py"
click node_basis_builder "https://github.com/mattatzb/rhf-from-scratch/blob/main/basis.py"
click node_basis_data "https://github.com/mattatzb/rhf-from-scratch/tree/main/data"
click node_integrals "https://github.com/mattatzb/rhf-from-scratch/blob/main/integrals.py"
click node_rhf "https://github.com/mattatzb/rhf-from-scratch/blob/main/scf.py"
click node_fci "https://github.com/mattatzb/rhf-from-scratch/blob/main/ci.py"
click node_rhf_example "https://github.com/mattatzb/rhf-from-scratch/blob/main/main.py"
click node_rhf_scan "https://github.com/mattatzb/rhf-from-scratch/blob/main/scan.py"
click node_fci_driver "https://github.com/mattatzb/rhf-from-scratch/blob/main/run_ci.py"
click node_fci_scan "https://github.com/mattatzb/rhf-from-scratch/blob/main/run_ci_scan.py"
click node_psi4_scan "https://github.com/mattatzb/rhf-from-scratch/blob/main/run_psi4_scan.py"
click node_run_logging "https://github.com/mattatzb/rhf-from-scratch/blob/main/runlog.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_molecule,node_basis_builder,node_basis_data,node_user toneBlue
class node_integrals,node_rhf,node_fci toneAmber
class node_rhf_example,node_rhf_scan,node_fci_driver,node_fci_scan,node_psi4_scan toneMint
class node_psi4,node_run_logging toneRose
```

## Components

### Molecular model

- [Molecule geometry](https://github.com/mattatzb/rhf-from-scratch/blob/main/mol.py): `mol.py`
- [Basis builder](https://github.com/mattatzb/rhf-from-scratch/blob/main/basis.py): `basis.py`
- [Bundled basis sets](https://github.com/mattatzb/rhf-from-scratch/tree/main/data): `data`

### Electronic structure

- [Gaussian integrals](https://github.com/mattatzb/rhf-from-scratch/blob/main/integrals.py): `integrals.py`
- [RHF SCF](https://github.com/mattatzb/rhf-from-scratch/blob/main/scf.py): `scf.py`
- [Two-electron FCI](https://github.com/mattatzb/rhf-from-scratch/blob/main/ci.py): `ci.py`

### Scan workflows

- [RHF example](https://github.com/mattatzb/rhf-from-scratch/blob/main/main.py): `main.py`
- [RHF diatomic scan](https://github.com/mattatzb/rhf-from-scratch/blob/main/scan.py): `scan.py`
- [RHF plus FCI driver](https://github.com/mattatzb/rhf-from-scratch/blob/main/run_ci.py): `run_ci.py`
- [FCI scan](https://github.com/mattatzb/rhf-from-scratch/blob/main/run_ci_scan.py): `run_ci_scan.py`
- [Psi4 comparison scan](https://github.com/mattatzb/rhf-from-scratch/blob/main/run_psi4_scan.py): `run_psi4_scan.py`

### Results and integrations

- **Psi4**
- [Run records](https://github.com/mattatzb/rhf-from-scratch/blob/main/runlog.py): `runlog.py`

### Other components

- **User**

## Connections

- User → RHF example: runs example (evidence: `README.md`)
- User → RHF diatomic scan: runs scan (evidence: `README.md`)
- User → RHF plus FCI driver: runs driver (evidence: `README.md`)
- User → FCI scan: runs scan (evidence: `README.md`)
- User → Psi4 comparison scan: runs comparison (evidence: `README.md`)
- RHF example → Molecule geometry: constructs (evidence: `main.py`)
- RHF example → Basis builder: builds basis (evidence: `main.py`)
- RHF example → RHF SCF: runs SCF (evidence: `main.py`)
- Basis builder → Molecule geometry: reads geometry (evidence: `basis.py`)
- Basis builder → Bundled basis sets: loads basis data (evidence: `README.md`)
- RHF SCF → Gaussian integrals: builds integrals (evidence: `scf.py`)
- RHF SCF → Molecule geometry: uses molecule (evidence: `scf.py`)
- RHF SCF → Basis builder: uses basis (evidence: `scf.py`)
- Gaussian integrals → Molecule geometry: uses nuclei (evidence: `integrals.py`)
- Gaussian integrals → Basis builder: integrates functions (evidence: `integrals.py`)
- RHF diatomic scan → Molecule geometry: constructs geometries (evidence: `scan.py`)
- RHF diatomic scan → Basis builder: builds basis (evidence: `scan.py`)
- RHF diatomic scan → RHF SCF: runs SCF (evidence: `scan.py`)
- RHF plus FCI driver → RHF diatomic scan: uses geometry helper (evidence: `run_ci.py`)
- RHF plus FCI driver → Basis builder: builds basis (evidence: `run_ci.py`)
- RHF plus FCI driver → RHF SCF: runs SCF (evidence: `run_ci.py`)
- RHF plus FCI driver → Gaussian integrals: builds ERIs (evidence: `run_ci.py`)
- RHF plus FCI driver → Two-electron FCI: builds CI energy (evidence: `run_ci.py`)
- FCI scan → RHF diatomic scan: uses geometry helper (evidence: `run_ci_scan.py`)
- FCI scan → Basis builder: builds basis (evidence: `run_ci_scan.py`)
- FCI scan → RHF SCF: runs SCF (evidence: `run_ci_scan.py`)
- FCI scan → Gaussian integrals: builds ERIs (evidence: `run_ci_scan.py`)
- FCI scan → Two-electron FCI: computes FCI (evidence: `run_ci_scan.py`)
- Psi4 comparison scan → Psi4: requests energies (evidence: `run_psi4_scan.py`)
