# matthew-j-liu/amber-ff architecture

> Architecture diagram of the GitHub repository matthew-j-liu/amber-ff, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/matthew-j-liu/amber-ff
- Repository: https://github.com/matthew-j-liu/amber-ff

## Overview

1. **Repository purpose**
   This is a C++17 molecular mechanics project centered on computing AMBER/GAFF-style force-field energies for small organic molecules. The current implementation is strongest for saturated hydrocarbons, with partial support extended to additional molecule classes through atom typing and parameter expansion.

2. **Top-level data model**
   The core input is an annotated `.xyz` file: coordinates plus an explicit bond list appended after the atom block. That bond information is used to build a molecule as a graph rather than inferring connectivity only from geometry. The parameter side is a reduced AMBER parameter file format, specialized into `hydrocarbons.dat` and `selected_atoms.dat` for the subset of atom types the code can handle.

3. **Parsing boundary**
   `src/read_xyz.cpp` and `src/read_params.cpp` are the main ingestion layer, with `src/parsing.hpp` consolidating the public parse interface. Their job is to convert file-based chemistry data into in-memory structures: a molecule graph plus force-field parameter maps.

4. **Molecule representation**
   `src/molecule.hpp/.cpp` defines the molecular graph abstraction: atoms as nodes, bonds as edges, and neighbor lists used throughout the rest of the pipeline. `src/mol_utils.cpp/.hpp` appears to own chemistry-specific graph utilities such as bond detection and AMBER atom-type assignment.

5. **Atom typing as a separate stage**
   Atom typing is explicitly separated from parsing and energy evaluation. The README shows the typing logic is rule-based: halogens first, then carbon backbone by coordination, then oxygen/nitrogen, then hydrogens based on attachment. This stage is important because the force-field parameters are keyed by atom types, not just element symbols.

6. **Geometry computation**
   `src/geom_util.cpp/.hpp` provides the low-level measurements needed by the force field: bond lengths, bond angles, and dihedral angles derived from coordinates and graph connectivity. This is the bridge between the molecule graph and the energy formulas.

7. **Force-field engine**
   `src/ff.cpp/.hpp` is the energy core. It computes the bonded and nonbonded terms used in the project’s AMBER-style model: bonds, angles, dihedrals, and van der Waals. Parameter lookup is done through force-field maps populated from the parsed parameter file. The README notes that electrostatics are not implemented and the explicit hydrogen-bond term is omitted for simplicity.

8. **Parameter format and scope**
   `params/gaff2.dat` is the source parameter archive, while `params/hydrocarbons.dat` is a reduced, easier-to-parse subset. `params/selected_atoms.dat` expands coverage to more molecules while keeping the same parser contract. `params/param_file_format.md` documents the expected sectioned file structure, which matters because the parser depends on those bracketed section boundaries.

9. **Execution entry points**
   `src/main.cpp` is the general driver for loading one molecule and one parameter set, then printing/using the parsed structures and computed values. `src/dihedral_scan_main.cpp` supports a more specialized workflow for scanning a torsion and generating result data for one molecule.

10. **Analysis and benchmarking layer**
   The `benchmarks/` directory is a separate evaluation subsystem. It contains scripts to run parity checks against reference outputs, and plotting code to visualize error distributions and class-based comparisons. This is the repo’s main validation boundary against AMBER outputs rather than a production runtime feature.

11. **Dihedral-scan workflow**
   `dihedral_scan/scan_dihedral.py` and the `dihedral_scan/results/` CSV output form a small analysis pipeline for torsion energy curves. That workflow is likely used to compare the project’s dihedral term against known reference behavior for a specific molecule such as but-1-ene.

12. **Tests and confidence boundaries**
   The `tests/` directory mixes C++ unit tests and a Python test, covering parameter loading, XYZ parsing, force-field calculations, and a basic smoke test. This shows the repo’s confidence model is split across file parsing correctness, chemistry typing correctness, and numeric energy correctness.

13. **Build and run infrastructure**
   The repo uses CMake plus shell wrappers (`build_and_run.sh`, `interactive.sh`, `run_AMBER_benchmarking.sh`, `run_AMBER_custom.sh`, `test.sh`) to simplify compilation and comparison workflows. The code also links against Armadillo, so linear-algebra and vector math are part of the runtime dependencies.

14. **Representative project flow**
   The end-to-end data path is: annotated molecule file and parameter file in → parsing → graph construction → atom typing → geometry extraction → force-field term evaluation → output/benchmark comparison. The repo’s structure is aligned around that pipeline, with datasets, parsing, chemistry logic, energy computation, and validation kept in distinct folders.

Main entry points: [`src/ff.cpp`](https://github.com/matthew-j-liu/amber-ff/blob/main/src/ff.cpp) (Energy core), [`src/read_xyz.cpp`](https://github.com/matthew-j-liu/amber-ff/blob/main/src/read_xyz.cpp) (Read XYZ), [`src/read_params.cpp`](https://github.com/matthew-j-liu/amber-ff/blob/main/src/read_params.cpp) (Read params), [`src/main.cpp`](https://github.com/matthew-j-liu/amber-ff/blob/main/src/main.cpp) (Main driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_src["Core engine"]
  node_n_parsing["Parsing API<br/>C++ interface<br/>[parsing.hpp]"]
  node_n_read_xyz["Read XYZ<br/>parser<br/>[read_xyz.cpp]"]
  node_n_read_params["Read params<br/>parser<br/>[read_params.cpp]"]
  node_n_molecule(("Molecule graph<br/>graph model<br/>[molecule.hpp]"))
  node_n_mol_utils["Chem utils<br/>chemistry helpers<br/>[mol_utils.cpp]"]
  node_n_geom["Geometry<br/>measurements<br/>[geom_util.cpp]"]
  node_n_ff_params[("FF params<br/>parameter maps<br/>[ff_params.hpp]")]
  node_n_ff["Energy core<br/>force field<br/>[ff.cpp]"]
  node_n_main["Main driver<br/>CLI runtime<br/>[main.cpp]"]
  node_n_dihedral_main["Torsion driver<br/>CLI runtime"]
end

subgraph group_grp_params["Parameter data"]
  node_n_gaff2["GAFF2 archive<br/>parameter source<br/>[gaff2.dat]"]
  node_n_hc_params["Hydrocarbon set<br/>parameter subset<br/>[hydrocarbons.dat]"]
  node_n_selected_params["Selected atoms<br/>parameter subset<br/>[selected_atoms.dat]"]
  node_n_param_format["Format spec<br/>docs"]
end

subgraph group_grp_data["Molecule datasets"]
  node_n_inputs["Molecule set<br/>input corpora"]
end

subgraph group_grp_analysis["Analysis"]
  node_n_benchmarks["Benchmarks<br/>evaluation"]
  node_n_scan["Dihedral scan<br/>analysis pipeline"]
end

subgraph group_grp_tests["Validation"]
  node_n_tests["Tests<br/>test suite"]
end

node_n_read_xyz -->|"builds"| node_n_molecule
node_n_read_params -->|"populates"| node_n_ff_params
node_n_parsing -->|"exposes"| node_n_read_xyz
node_n_parsing -->|"exposes"| node_n_read_params
node_n_molecule -->|"used by"| node_n_mol_utils
node_n_mol_utils -->|"atom types"| node_n_ff
node_n_molecule -->|"feeds"| node_n_geom
node_n_geom -->|"measures"| node_n_ff
node_n_ff_params -->|"lookups"| node_n_ff
node_n_main -->|"loads"| node_n_parsing
node_n_main -->|"types"| node_n_mol_utils
node_n_main -->|"computes"| node_n_ff
node_n_dihedral_main -->|"drives"| node_n_scan
node_n_gaff2 -.->|"derives"| node_n_hc_params
node_n_gaff2 -.->|"derives"| node_n_selected_params
node_n_param_format -->|"specifies"| node_n_read_params
node_n_inputs -->|"sample data"| node_n_read_xyz
node_n_benchmarks -->|"validates"| node_n_ff
node_n_scan -->|"analyzes"| node_n_ff
node_n_tests -->|"covers"| node_n_read_xyz
node_n_tests -->|"covers"| node_n_read_params
node_n_tests -->|"covers"| node_n_ff

click node_n_parsing "https://github.com/matthew-j-liu/amber-ff/blob/main/src/parsing.hpp"
click node_n_read_xyz "https://github.com/matthew-j-liu/amber-ff/blob/main/src/read_xyz.cpp"
click node_n_read_params "https://github.com/matthew-j-liu/amber-ff/blob/main/src/read_params.cpp"
click node_n_molecule "https://github.com/matthew-j-liu/amber-ff/blob/main/src/molecule.hpp"
click node_n_mol_utils "https://github.com/matthew-j-liu/amber-ff/blob/main/src/mol_utils.cpp"
click node_n_geom "https://github.com/matthew-j-liu/amber-ff/blob/main/src/geom_util.cpp"
click node_n_ff_params "https://github.com/matthew-j-liu/amber-ff/blob/main/src/ff_params.hpp"
click node_n_ff "https://github.com/matthew-j-liu/amber-ff/blob/main/src/ff.cpp"
click node_n_main "https://github.com/matthew-j-liu/amber-ff/blob/main/src/main.cpp"
click node_n_dihedral_main "https://github.com/matthew-j-liu/amber-ff/blob/main/src/dihedral_scan_main.cpp"
click node_n_gaff2 "https://github.com/matthew-j-liu/amber-ff/blob/main/params/gaff2.dat"
click node_n_hc_params "https://github.com/matthew-j-liu/amber-ff/blob/main/params/hydrocarbons.dat"
click node_n_selected_params "https://github.com/matthew-j-liu/amber-ff/blob/main/params/selected_atoms.dat"
click node_n_param_format "https://github.com/matthew-j-liu/amber-ff/blob/main/params/param_file_format.md"
click node_n_inputs "https://github.com/matthew-j-liu/amber-ff/tree/main/input_molecules_copy"
click node_n_benchmarks "https://github.com/matthew-j-liu/amber-ff/tree/main/benchmarks"
click node_n_scan "https://github.com/matthew-j-liu/amber-ff/tree/main/dihedral_scan"
click node_n_tests "https://github.com/matthew-j-liu/amber-ff/tree/main/tests"

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_n_parsing,node_n_read_xyz,node_n_read_params,node_n_molecule,node_n_mol_utils,node_n_geom,node_n_ff_params,node_n_ff,node_n_main,node_n_dihedral_main toneBlue
class node_n_gaff2,node_n_hc_params,node_n_selected_params,node_n_param_format toneAmber
class node_n_inputs toneMint
class node_n_benchmarks,node_n_scan toneRose
class node_n_tests toneIndigo
```

## Components

### Core engine

C++17 parsing, molecule modeling, geometry, and force-field evaluation.

- [Parsing API](https://github.com/matthew-j-liu/amber-ff/blob/main/src/parsing.hpp): C++ interface · Public parse boundary that exposes XYZ and parameter ingestion. · `src/parsing.hpp`
- [Read XYZ](https://github.com/matthew-j-liu/amber-ff/blob/main/src/read_xyz.cpp): parser · Loads annotated coordinates and appended bond lists into molecule data. · `src/read_xyz.cpp`
- [Read params](https://github.com/matthew-j-liu/amber-ff/blob/main/src/read_params.cpp): parser · Loads reduced AMBER-style parameter sections into lookup maps. · `src/read_params.cpp`
- [Molecule graph](https://github.com/matthew-j-liu/amber-ff/blob/main/src/molecule.hpp): graph model · Atom-and-bond representation with neighbor lists used across the pipeline. · `src/molecule.hpp`
- [Chem utils](https://github.com/matthew-j-liu/amber-ff/blob/main/src/mol_utils.cpp): chemistry helpers · Graph utilities for connectivity handling and atom typing support. · `src/mol_utils.cpp`
- [Geometry](https://github.com/matthew-j-liu/amber-ff/blob/main/src/geom_util.cpp): measurements · Computes bond lengths, angles, and dihedrals from coordinates and connectivity. · `src/geom_util.cpp`
- [FF params](https://github.com/matthew-j-liu/amber-ff/blob/main/src/ff_params.hpp): parameter maps · In-memory force-field tables keyed by atom types and interaction classes. · `src/ff_params.hpp`
- [Energy core](https://github.com/matthew-j-liu/amber-ff/blob/main/src/ff.cpp): force field · Evaluates AMBER-style bonded and nonbonded terms for a molecule. · `src/ff.cpp`
- [Main driver](https://github.com/matthew-j-liu/amber-ff/blob/main/src/main.cpp): CLI runtime · General entry point for loading one molecule and one parameter set. · `src/main.cpp`
- [Torsion driver](https://github.com/matthew-j-liu/amber-ff/blob/main/src/dihedral_scan_main.cpp): CLI runtime · Specialized entry point for dihedral scan workflows. · `src/dihedral_scan_main.cpp`

### Parameter data

Force-field archives and the file-format contract they follow.

- [GAFF2 archive](https://github.com/matthew-j-liu/amber-ff/blob/main/params/gaff2.dat): parameter source · Primary source parameter set used to derive supported subsets. · `params/gaff2.dat`
- [Hydrocarbon set](https://github.com/matthew-j-liu/amber-ff/blob/main/params/hydrocarbons.dat): parameter subset · Reduced parameter file for the simpler supported chemistry class. · `params/hydrocarbons.dat`
- [Selected atoms](https://github.com/matthew-j-liu/amber-ff/blob/main/params/selected_atoms.dat): parameter subset · Expanded subset that broadens molecule coverage while keeping parser compatibility. · `params/selected_atoms.dat`
- [Format spec](https://github.com/matthew-j-liu/amber-ff/blob/main/params/param_file_format.md): docs · Sectioned parameter-file format contract consumed by the parser. · `params/param_file_format.md`

### Molecule datasets

Annotated input molecules used by the runtime and benchmarks.

- [Molecule set](https://github.com/matthew-j-liu/amber-ff/tree/main/input_molecules_copy): input corpora · Annotated XYZ examples spanning alkanes, functional groups, and benchmark molecules. · `input_molecules_copy`

### Analysis

Benchmarking, parity plots, and dihedral scan workflow.

- [Benchmarks](https://github.com/matthew-j-liu/amber-ff/tree/main/benchmarks): evaluation · Parity scripts and plots comparing outputs against reference behavior. · `benchmarks`
- [Dihedral scan](https://github.com/matthew-j-liu/amber-ff/tree/main/dihedral_scan): analysis pipeline · Scripted torsion-energy sweep and resulting CSV data. · `dihedral_scan`

### Validation

Unit and smoke tests spanning parsing, typing, and energy evaluation.

- [Tests](https://github.com/matthew-j-liu/amber-ff/tree/main/tests): test suite · C++ and Python tests for parsing, typing, and force-field calculations. · `tests`

## Connections

- Read XYZ → Molecule graph: builds · Converts annotated coordinates into a molecule graph.
- Read params → FF params: populates · Creates parameter maps from the reduced AMBER-style file.
- Parsing API → Read XYZ: exposes · Public parsing interface for XYZ ingestion.
- Parsing API → Read params: exposes · Public parsing interface for parameter ingestion.
- Molecule graph → Chem utils: used by · Graph utilities operate on the molecular representation.
- Chem utils → Energy core: atom types · Provides typing and connectivity information needed by the energy engine.
- Molecule graph → Geometry: feeds · Geometry routines consume coordinates and bond connectivity.
- Geometry → Energy core: measures · Supplies lengths, angles, and dihedrals to energy formulas.
- FF params → Energy core: lookups · Force-field terms are evaluated from parsed parameter tables.
- Main driver → Parsing API: loads · Main runtime starts by reading molecule and parameter inputs.
- Main driver → Chem utils: types · Performs atom typing before energy evaluation.
- Main driver → Energy core: computes · Runs the force-field energy calculation.
- Torsion driver → Dihedral scan: drives · Specialized executable supports torsion scanning workflows.
- GAFF2 archive → Hydrocarbon set: derives · Reduced subset is derived from the broader GAFF2 archive.
- GAFF2 archive → Selected atoms: derives · Expanded selected-atom coverage is based on the source archive.
- Format spec → Read params: specifies · Parser depends on the bracketed section structure.
- Molecule set → Read XYZ: sample data · Annotated XYZ molecules are the primary runtime inputs.
- Benchmarks → Energy core: validates · Parity and plots assess energy-output agreement.
- Dihedral scan → Energy core: analyzes · Dihedral scan workflow evaluates torsion energy behavior.
- Tests → Read XYZ: covers · Tests parsing of annotated XYZ inputs.
- Tests → Read params: covers · Tests parameter loading behavior.
- Tests → Energy core: covers · Tests force-field numeric calculations.