# gqcg/gqcp architecture

> Architecture diagram of the GitHub repository gqcg/gqcp, 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/gqcg/gqcp
- Repository: https://github.com/gqcg/gqcp

## Overview

GQCP is a C++ domain-specific library for developing electronic-structure methods in spinor bases, with Python bindings. A typical calculation represents a molecule and basis, obtains one- and two-electron integrals, forms operators and applies a selected quantum-chemical method; property and response modules support downstream analysis. The tree also shows distinct method families, orbital optimization and configuration-interaction basis machinery. The README establishes the product scope, while sampled source confirms integral-engine construction and operator storage; some method-level wiring is inferred from the module organization.

Main entry points: [`gqcp/include/Operator/SecondQuantized/SQHamiltonian.hpp`](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Operator/SecondQuantized/SQHamiltonian.hpp) (Quantized operators), [`gqcp/include/QCMethod/HF/RHF/RHFSCFSolver.hpp`](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/HF/RHF/RHFSCFSolver.hpp) (Hartree–Fock), [`gqcp/include/QCMethod/CC/CCSDSolver.hpp`](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/CC/CCSDSolver.hpp) (Correlated methods), [`gqcp/include/QCMethod/NOCI/NOCI.hpp`](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/NOCI/NOCI.hpp) (CI and NOCI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_molecular["Molecular model"]
  node_molecule["Molecule<br/>[Molecule.hpp]"]
end

subgraph group_integrals["Basis and integrals"]
  node_basis["Gaussian basis<br/>[GTOBasisSet.hpp]"]
  node_spinor["Spinor basis<br/>[GSpinorBasis.hpp]"]
  node_integral_factory["Integral factory<br/>[IntegralEngine.hpp]"]
  node_primitive_engines["Primitive engines"]
  node_backend_engines["Libint / Libcint"]
  node_one_electron["One-electron integrals"]
  node_two_electron["Two-electron integrals"]
end

subgraph group_operators["Operators and states"]
  node_operators["Quantized operators<br/>[SQHamiltonian.hpp]"]
  node_operator_storage["Operator storage"]
  node_density["Density matrices<br/>[G1DM.hpp]"]
  node_onv["ONV bases"]
end

subgraph group_methods["Electronic structure"]
  node_hf["Hartree–Fock<br/>[RHFSCFSolver.hpp]"]
  node_correlated["Correlated methods<br/>[CCSDSolver.hpp]"]
  node_ci_noci["CI and NOCI<br/>[NOCI.hpp]"]
  node_geminals["Geminal methods<br/>[AP1roG.hpp]"]
  node_orbital_opt["Orbital optimization"]
end

subgraph group_analysis["Analysis and bindings"]
  node_properties["Properties and response<br/>[properties.hpp]"]
  node_python["Python bindings"]
end

node_scientist(("Research user"))

node_scientist -->|"defines system"| node_molecule
node_scientist -->|"chooses basis"| node_basis
node_molecule -->|"centers basis"| node_basis
node_basis -->|"supports orbitals"| node_spinor
node_scientist -->|"requests integrals"| node_integral_factory
node_integral_factory -->|"creates engines"| node_primitive_engines
node_integral_factory -.->|"creates backend"| node_backend_engines
node_primitive_engines -->|"evaluates integrals"| node_one_electron
node_primitive_engines -->|"evaluates integrals"| node_two_electron
node_backend_engines -.->|"evaluates integrals"| node_one_electron
node_backend_engines -.->|"evaluates integrals"| node_two_electron
node_one_electron -->|"supplies matrix elements"| node_operators
node_two_electron -->|"supplies matrix elements"| node_operators
node_operators -->|"stores parameters"| node_operator_storage
node_scientist -->|"selects method"| node_hf
node_hf -->|"uses Hamiltonian"| node_operators
node_hf -->|"forms density"| node_density
node_scientist -->|"selects method"| node_correlated
node_correlated -->|"uses Hamiltonian"| node_operators
node_correlated -->|"uses densities"| node_density
node_scientist -->|"selects method"| node_ci_noci
node_ci_noci -->|"uses configurations"| node_onv
node_ci_noci -->|"uses Hamiltonian"| node_operators
node_scientist -->|"selects method"| node_geminals
node_geminals -->|"uses Hamiltonian"| node_operators
node_scientist -->|"requests optimization"| node_orbital_opt
node_orbital_opt -->|"rotates orbitals"| node_spinor
node_hf -->|"enables analysis"| node_properties
node_correlated -->|"enables analysis"| node_properties
node_ci_noci -->|"enables analysis"| node_properties
node_geminals -->|"enables analysis"| node_properties
node_scientist -.->|"uses bindings"| node_python

click node_molecule "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Molecule/Molecule.hpp"
click node_basis "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/ScalarBasis/GTOBasisSet.hpp"
click node_spinor "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/SpinorBasis/GSpinorBasis.hpp"
click node_integral_factory "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/Integrals/IntegralEngine.hpp"
click node_primitive_engines "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/Integrals/Primitive/PrimitiveCoulombRepulsionIntegralEngine.hpp"
click node_backend_engines "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/Integrals/Interfaces/LibcintOneElectronIntegralEngine.hpp"
click node_one_electron "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/Integrals/OneElectronIntegralEngine.hpp"
click node_two_electron "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/Integrals/TwoElectronIntegralEngine.hpp"
click node_operators "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Operator/SecondQuantized/SQHamiltonian.hpp"
click node_operator_storage "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Operator/SecondQuantized/SQOperatorStorage.hpp"
click node_density "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/DensityMatrix/G1DM.hpp"
click node_onv "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/ONVBasis/SpinResolvedONVBasis.hpp"
click node_hf "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/HF/RHF/RHFSCFSolver.hpp"
click node_correlated "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/CC/CCSDSolver.hpp"
click node_ci_noci "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/NOCI/NOCI.hpp"
click node_geminals "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/Geminals/AP1roG.hpp"
click node_orbital_opt "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/OrbitalOptimization/NewtonOrbitalOptimizer.hpp"
click node_properties "https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Processing/Properties/properties.hpp"
click node_python "https://github.com/gqcg/gqcp/blob/develop/gqcpy/src/Basis/Integrals/FunctionalOneElectronPrimitiveIntegralEngine_bindings.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_molecule,node_scientist toneBlue
class node_basis,node_spinor,node_integral_factory,node_primitive_engines,node_backend_engines,node_one_electron,node_two_electron toneAmber
class node_operators,node_operator_storage,node_density,node_onv toneMint
class node_hf,node_correlated,node_ci_noci,node_geminals,node_orbital_opt toneRose
class node_properties,node_python toneIndigo
```

## Components

### Molecular model

- [Molecule](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Molecule/Molecule.hpp): `gqcp/include/Molecule/Molecule.hpp`

### Basis and integrals

- [Gaussian basis](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/ScalarBasis/GTOBasisSet.hpp): `gqcp/include/Basis/ScalarBasis/GTOBasisSet.hpp`
- [Spinor basis](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/SpinorBasis/GSpinorBasis.hpp): `gqcp/include/Basis/SpinorBasis/GSpinorBasis.hpp`
- [Integral factory](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/Integrals/IntegralEngine.hpp): `gqcp/include/Basis/Integrals/IntegralEngine.hpp`
- [Primitive engines](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/Integrals/Primitive/PrimitiveCoulombRepulsionIntegralEngine.hpp): `gqcp/include/Basis/Integrals/Primitive/PrimitiveCoulombRepulsionIntegralEngine.hpp`
- [Libint / Libcint](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/Integrals/Interfaces/LibcintOneElectronIntegralEngine.hpp): `gqcp/include/Basis/Integrals/Interfaces/LibcintOneElectronIntegralEngine.hpp`
- [One-electron integrals](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/Integrals/OneElectronIntegralEngine.hpp): `gqcp/include/Basis/Integrals/OneElectronIntegralEngine.hpp`
- [Two-electron integrals](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Basis/Integrals/TwoElectronIntegralEngine.hpp): `gqcp/include/Basis/Integrals/TwoElectronIntegralEngine.hpp`

### Operators and states

- [Quantized operators](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Operator/SecondQuantized/SQHamiltonian.hpp): `gqcp/include/Operator/SecondQuantized/SQHamiltonian.hpp`
- [Operator storage](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Operator/SecondQuantized/SQOperatorStorage.hpp): `gqcp/include/Operator/SecondQuantized/SQOperatorStorage.hpp`
- [Density matrices](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/DensityMatrix/G1DM.hpp): `gqcp/include/DensityMatrix/G1DM.hpp`
- [ONV bases](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/ONVBasis/SpinResolvedONVBasis.hpp): `gqcp/include/ONVBasis/SpinResolvedONVBasis.hpp`

### Electronic structure

- [Hartree–Fock](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/HF/RHF/RHFSCFSolver.hpp): `gqcp/include/QCMethod/HF/RHF/RHFSCFSolver.hpp`
- [Correlated methods](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/CC/CCSDSolver.hpp): `gqcp/include/QCMethod/CC/CCSDSolver.hpp`
- [CI and NOCI](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/NOCI/NOCI.hpp): `gqcp/include/QCMethod/NOCI/NOCI.hpp`
- [Geminal methods](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/Geminals/AP1roG.hpp): `gqcp/include/QCMethod/Geminals/AP1roG.hpp`
- [Orbital optimization](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/QCMethod/OrbitalOptimization/NewtonOrbitalOptimizer.hpp): `gqcp/include/QCMethod/OrbitalOptimization/NewtonOrbitalOptimizer.hpp`

### Analysis and bindings

- [Properties and response](https://github.com/gqcg/gqcp/blob/develop/gqcp/include/Processing/Properties/properties.hpp): `gqcp/include/Processing/Properties/properties.hpp`
- [Python bindings](https://github.com/gqcg/gqcp/blob/develop/gqcpy/src/Basis/Integrals/FunctionalOneElectronPrimitiveIntegralEngine_bindings.cpp): `gqcpy/src/Basis/Integrals/FunctionalOneElectronPrimitiveIntegralEngine_bindings.cpp`

### Other components

- **Research user**

## Connections

- Research user → Molecule: defines system
- Research user → Gaussian basis: chooses basis
- Molecule → Gaussian basis: centers basis
- Gaussian basis → Spinor basis: supports orbitals
- Research user → Integral factory: requests integrals
- Integral factory → Primitive engines: creates engines
- Integral factory → Libint / Libcint: creates backend
- Primitive engines → One-electron integrals: evaluates integrals
- Primitive engines → Two-electron integrals: evaluates integrals
- Libint / Libcint → One-electron integrals: evaluates integrals
- Libint / Libcint → Two-electron integrals: evaluates integrals
- One-electron integrals → Quantized operators: supplies matrix elements
- Two-electron integrals → Quantized operators: supplies matrix elements
- Quantized operators → Operator storage: stores parameters
- Research user → Hartree–Fock: selects method
- Hartree–Fock → Quantized operators: uses Hamiltonian
- Hartree–Fock → Density matrices: forms density
- Research user → Correlated methods: selects method
- Correlated methods → Quantized operators: uses Hamiltonian
- Correlated methods → Density matrices: uses densities
- Research user → CI and NOCI: selects method
- CI and NOCI → ONV bases: uses configurations
- CI and NOCI → Quantized operators: uses Hamiltonian
- Research user → Geminal methods: selects method
- Geminal methods → Quantized operators: uses Hamiltonian
- Research user → Orbital optimization: requests optimization
- Orbital optimization → Spinor basis: rotates orbitals
- Hartree–Fock → Properties and response: enables analysis
- Correlated methods → Properties and response: enables analysis
- CI and NOCI → Properties and response: enables analysis
- Geminal methods → Properties and response: enables analysis
- Research user → Python bindings: uses bindings