# qtchem/ffprime architecture

> Architecture diagram of the GitHub repository qtchem/ffprime, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qtchem/ffprime
- Repository: https://github.com/qtchem/ffprime

## Overview

FFprime derives molecular bonded and nonbonded force-field parameters from electronic-structure data and AIM partitioning. The primary nonbonded workflow loads a molecule, partitions its density, derives atomic volumes and multipoles, then computes dispersion and Lennard-Jones parameters; the bonded workflow extracts connectivity and uses a molecular Hessian to calculate force constants. The electrostatics package also offers Cartesian and spherical potential/field evaluation. Sampled source supports the principal nonbonded and bonded calls; other documented capabilities are shown conservatively where implementation detail was not sampled.

Main entry points: [`ffprime/nb.py`](https://github.com/qtchem/ffprime/blob/main/ffprime/nb.py) (Nonbonded workflow), [`ffprime/bond.py`](https://github.com/qtchem/ffprime/blob/main/ffprime/bond.py) (Bonded workflow), [`ffprime/electrostatics/utils.py`](https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/utils.py) (Atomic moments), [`ffprime/utils/connectivity.py`](https://github.com/qtchem/ffprime/blob/main/ffprime/utils/connectivity.py) (Connectivity parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_parameterization["Parameter derivation"]
  node_nonbonded["Nonbonded workflow<br/>[nb.py]"]
  node_partition["AIM partitioning<br/>[part.py]"]
  node_atomic_volumes["Atomic volumes<br/>[utils.py]"]
  node_ts_dispersion["TS dispersion<br/>[vdw.py]"]
  node_lj_parameters["Lennard-Jones parameters<br/>[parameters.py]"]
end

subgraph group_electrostatics["Electrostatics"]
  node_multipole_moments["Atomic moments<br/>[utils.py]"]
  node_cartesian_multipoles["Cartesian moments<br/>[cartesian.py]"]
  node_spherical_multipoles["Spherical moments<br/>[spherical.py]"]
  node_electrostatic_analysis["Electrostatic analysis<br/>[analysis.py]"]
  node_multipole_expansion["Multipole expansion<br/>[expansion.py]"]
end

subgraph group_bonding["Bonded parameters"]
  node_bonded["Bonded workflow<br/>[bond.py]"]
  node_connectivity["Connectivity parser<br/>[connectivity.py]"]
  node_bonding_notebook["Bonding analysis notebook<br/>[notebook.py]"]
  node_seminario["Seminario utilities<br/>[seminario.py]"]
end

subgraph group_analysis["Evaluation and analysis"]
  node_potential_tools["Potential evaluation<br/>[potentials.py]"]
  node_parameter_output["Parameter output<br/>[write.py]"]
end

node_user(("Force-field user"))
node_molecule_input["Electronic structure input"]
node_results["Derived parameters"]
node_qm_reference["Quantum reference energies"]

node_user -->|"requests derivation"| node_nonbonded
node_molecule_input -->|"loads molecule"| node_nonbonded
node_nonbonded -->|"partitions density"| node_partition
node_nonbonded -->|"computes volumes"| node_atomic_volumes
node_nonbonded -->|"computes moments"| node_multipole_moments
node_nonbonded -->|"derives dispersion"| node_ts_dispersion
node_nonbonded -->|"derives LJ values"| node_lj_parameters
node_nonbonded -->|"returns parameters"| node_results
node_multipole_moments -->|"converts components"| node_spherical_multipoles
node_user -->|"evaluates fields"| node_cartesian_multipoles
node_user -->|"evaluates fields"| node_spherical_multipoles
node_user -->|"requests derivation"| node_bonded
node_molecule_input -->|"loads Hessian"| node_bonded
node_bonded -->|"parses connectivity"| node_connectivity
node_bonded -.->|"computes force constants"| node_results
node_connectivity -->|"provides connectivity"| node_bonding_notebook
node_user -->|"evaluates potentials"| node_potential_tools
node_user -.->|"derives bonded terms"| node_seminario
node_results -.->|"writes parameters"| node_parameter_output
node_results -.->|"benchmarks against"| node_qm_reference
node_user -.->|"analyzes properties"| node_electrostatic_analysis
node_user -.->|"evaluates expansion"| node_multipole_expansion

click node_nonbonded "https://github.com/qtchem/ffprime/blob/main/ffprime/nb.py"
click node_partition "https://github.com/qtchem/ffprime/blob/main/ffprime/utils/part.py"
click node_atomic_volumes "https://github.com/qtchem/ffprime/blob/main/ffprime/nonbonding/utils.py"
click node_ts_dispersion "https://github.com/qtchem/ffprime/blob/main/ffprime/nonbonding/vdw.py"
click node_lj_parameters "https://github.com/qtchem/ffprime/blob/main/ffprime/nonbonding/parameters.py"
click node_multipole_moments "https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/utils.py"
click node_cartesian_multipoles "https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/cartesian.py"
click node_spherical_multipoles "https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/spherical.py"
click node_electrostatic_analysis "https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/analysis.py"
click node_multipole_expansion "https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/expansion.py"
click node_bonded "https://github.com/qtchem/ffprime/blob/main/ffprime/bond.py"
click node_connectivity "https://github.com/qtchem/ffprime/blob/main/ffprime/utils/connectivity.py"
click node_bonding_notebook "https://github.com/qtchem/ffprime/blob/main/ffprime/bonding/notebook.py"
click node_potential_tools "https://github.com/qtchem/ffprime/blob/main/ffprime/utils/potentials.py"
click node_seminario "https://github.com/qtchem/ffprime/blob/main/ffprime/utils/seminario.py"
click node_parameter_output "https://github.com/qtchem/ffprime/blob/main/ffprime/utils/write.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_nonbonded,node_partition,node_atomic_volumes,node_ts_dispersion,node_lj_parameters,node_user toneBlue
class node_multipole_moments,node_cartesian_multipoles,node_spherical_multipoles,node_electrostatic_analysis,node_multipole_expansion toneAmber
class node_bonded,node_connectivity,node_bonding_notebook,node_seminario toneMint
class node_potential_tools,node_parameter_output toneRose
class node_molecule_input,node_results,node_qm_reference toneIndigo
```

## Components

### Parameter derivation

- [Nonbonded workflow](https://github.com/qtchem/ffprime/blob/main/ffprime/nb.py): `ffprime/nb.py`
- [AIM partitioning](https://github.com/qtchem/ffprime/blob/main/ffprime/utils/part.py): `ffprime/utils/part.py`
- [Atomic volumes](https://github.com/qtchem/ffprime/blob/main/ffprime/nonbonding/utils.py): `ffprime/nonbonding/utils.py`
- [TS dispersion](https://github.com/qtchem/ffprime/blob/main/ffprime/nonbonding/vdw.py): `ffprime/nonbonding/vdw.py`
- [Lennard-Jones parameters](https://github.com/qtchem/ffprime/blob/main/ffprime/nonbonding/parameters.py): `ffprime/nonbonding/parameters.py`

### Electrostatics

- [Atomic moments](https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/utils.py): `ffprime/electrostatics/utils.py`
- [Cartesian moments](https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/cartesian.py): `ffprime/electrostatics/cartesian.py`
- [Spherical moments](https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/spherical.py): `ffprime/electrostatics/spherical.py`
- [Electrostatic analysis](https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/analysis.py): `ffprime/electrostatics/analysis.py`
- [Multipole expansion](https://github.com/qtchem/ffprime/blob/main/ffprime/electrostatics/expansion.py): `ffprime/electrostatics/expansion.py`

### Bonded parameters

- [Bonded workflow](https://github.com/qtchem/ffprime/blob/main/ffprime/bond.py): `ffprime/bond.py`
- [Connectivity parser](https://github.com/qtchem/ffprime/blob/main/ffprime/utils/connectivity.py): `ffprime/utils/connectivity.py`
- [Bonding analysis notebook](https://github.com/qtchem/ffprime/blob/main/ffprime/bonding/notebook.py): `ffprime/bonding/notebook.py`
- [Seminario utilities](https://github.com/qtchem/ffprime/blob/main/ffprime/utils/seminario.py): `ffprime/utils/seminario.py`

### Evaluation and analysis

- [Potential evaluation](https://github.com/qtchem/ffprime/blob/main/ffprime/utils/potentials.py): `ffprime/utils/potentials.py`
- [Parameter output](https://github.com/qtchem/ffprime/blob/main/ffprime/utils/write.py): `ffprime/utils/write.py`

### Other components

- **Force-field user**
- **Electronic structure input**
- **Derived parameters**
- **Quantum reference energies**

## Connections

- Force-field user → Nonbonded workflow: requests derivation (evidence: `README.md`)
- Electronic structure input → Nonbonded workflow: loads molecule (evidence: `ffprime/nb.py`)
- Nonbonded workflow → AIM partitioning: partitions density (evidence: `ffprime/nb.py`)
- Nonbonded workflow → Atomic volumes: computes volumes (evidence: `ffprime/nb.py`)
- Nonbonded workflow → Atomic moments: computes moments (evidence: `ffprime/nb.py`)
- Nonbonded workflow → TS dispersion: derives dispersion (evidence: `ffprime/nb.py`)
- Nonbonded workflow → Lennard-Jones parameters: derives LJ values (evidence: `ffprime/nb.py`)
- Nonbonded workflow → Derived parameters: returns parameters (evidence: `README.md`)
- Atomic moments → Spherical moments: converts components (evidence: `ffprime/electrostatics/utils.py`)
- Force-field user → Cartesian moments: evaluates fields (evidence: `ffprime/electrostatics/cartesian.py`)
- Force-field user → Spherical moments: evaluates fields (evidence: `ffprime/electrostatics/spherical.py`)
- Force-field user → Bonded workflow: requests derivation (evidence: `ffprime/bond.py`)
- Electronic structure input → Bonded workflow: loads Hessian (evidence: `ffprime/bond.py`)
- Bonded workflow → Connectivity parser: parses connectivity (evidence: `ffprime/bond.py`)
- Bonded workflow → Derived parameters: computes force constants
- Connectivity parser → Bonding analysis notebook: provides connectivity (evidence: `ffprime/bonding/notebook.py`)
- Force-field user → Potential evaluation: evaluates potentials (evidence: `README.md`)
- Force-field user → Seminario utilities: derives bonded terms
- Derived parameters → Parameter output: writes parameters
- Derived parameters → Quantum reference energies: benchmarks against
- Force-field user → Electrostatic analysis: analyzes properties
- Force-field user → Multipole expansion: evaluates expansion
