matthew-j-liu/amber-ff

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.