Add complete atomization energy MLP pipeline from scratch

[Copilot]

Repository was a bare stub (only .gitignore + a two-line README.md). Implements the full project structure and end-to-end ML pipeline for predicting molecular atomization energies via Coulomb-matrix descriptors and an MLP ensemble.

New files

• requirements.txt — six dependencies: numpy, pandas, requests, matplotlib, scikit-learn, tensorflow>=2.0.0
• src/main.py — self-contained pipeline (download → parse → featurise → train → evaluate → plot)

src/main.py pipeline stages

• Download — streams ANI-1E ZIP from Zenodo with progress bar; no-ops if data already present
• XYZ parsing — handles single- and multi-frame XYZ files; extracts elements, Å-coordinates, and DFT energy from comment line
• Coulomb matrix — M_ii = 0.5·Z^2.4, M_ij = Z_i·Z_j / r_ij
• Features — BoB descriptor (per-pair Coulomb values sorted ↓, zero-padded to dataset-global max) concatenated with sorted eigenvalue vector (padded to MAX_ATOMS=26), then z-score normalised
• Split — 70 / 15 / 15 (train / val / test)
• Model — 1024→512→256→128→1, GELU + BatchNorm + Dropout (0.20/0.15), linear skip connection from raw input concatenated before output head
• Training — AdamW (lr=1e-4, wd=1e-5), Huber loss (δ=0.1), ReduceLROnPlateau (factor=0.3, patience=15), EarlyStopping (patience=40); 5 independently-seeded models averaged at inference
• Outputs — parity_plot.png, residual_distribution.png, learning_curves.png

.gitignore

Appended project-specific patterns: /ani1e/, *.keras, *.h5, *.hdf5, *.png, *.pdf, macOS/

README.md

Replaced stub with full documentation: theory (Schrödinger equation, Coulomb matrix formulas), feature engineering, model architecture, training config, and reported results (MAE 3.36 kcal/mol, R²=0.9996).

Original prompt

Here is what I want you to build: Repository Structure
Plaintext
atomization-energy-mlp/
├── .gitignore
├── requirements.txt
├── README.md
└── src/
└── main.py
.gitignore
Plaintext

Environments

.env
.venv
env/
venv/
ENV/
env.bak/
macOS/

Python

pycache/
*.py[cod]
*$py.class

Data and Models

/ani1e/
*.keras
*.h5
*.hdf5

Output

*.png
*.pdf

Jupyter Notebook

.ipynb_checkpoints
requirements.txt
Plaintext
numpy
pandas
requests
matplotlib
scikit-learn
tensorflow>=2.0.0
README.md
Markdown

Multi-layer Perceptrons for Molecular Atomization Energies

Author: D.H. (John) Kim
Course: SPC707P Deep Learning
Date: 15/04/2026

Abstract

This repository contains a rigorous study and implementation of molecular atomization energy prediction using Coulomb-matrix-derived descriptors and multi-layer perceptrons (MLPs). Working with 57,462 equilibrium organic molecules from the ANI-1E dataset ($\omega$B97x/6-31G(d) level of theory), we develop and evaluate a progression of molecular representations—Coulomb matrix eigenvalues, sorted Coulomb matrices, and the Bag of Bonds descriptor. These are grounded in the nuclear Coulomb interaction operator from the molecular Hamiltonian.

Our best model, a 5-member ensemble of MLPs operating on concatenated Bag of Bonds and eigenvalue features (564 dimensions), achieves a test MAE of 3.36 kcal/mol (0.15 eV, $R^2 = 0.9996$) on an unseen test set of 8,620 molecules.

Theory & Fundamentals

Predicting molecular energies from atomic coordinates requires solving the time-independent Schrödinger equation:

$$\hat{H} \Psi = E \Psi$$

Solving this exactly is intractable for large systems. This project leverages machine learning to approximate the energy mapping directly from atomic coordinates and nuclear charges.

Molecular Representation

We utilize the Coulomb Matrix ($M$), which encodes nuclear charges ($Z$) and interatomic distances ($R$) into a symmetric matrix:

• Off-diagonal elements represent pairwise nuclear repulsions:
  $$M_{ij} = \frac{Z_i Z_j}{|R_i - R_j|}$$
• Diagonal elements approximate isolated-atom energies:
  $$M_{ii} = 0.5 Z_i^{2.4}$$

Feature Engineering

To ensure the neural network receives fixed-size, permutation-invariant inputs, two complementary descriptors are extracted from $M$:

1. Eigenvalues: Eigenvalue decomposition of $M$ yields a sorted vector $v_{\text{eig}}$ invariant to atom permutation.
2. Bag of Bonds (BoB): Groups off-diagonal elements by element pair (e.g., H-C, C-O), sorts each bag in descending order, and pads to a fixed length, producing $v_{\text{BoB}}$.

The final feature vector is the concatenation of both, $x = v_{\text{BoB}} \oplus v_{\text{eig}}$, resulting in 564 dimensions. Features are z-score normalized per dimension.

Model Architecture

The regression model is a five-layer MLP mapping the 564-dimensional input to a single atomization energy value.

• Topology: 1024 $\rightarrow$ 512 $\rightarrow$ 256 $\rightarrow$ 128 $\rightarrow$ 1
• Regularization: Batch Normalization and Dropout (0.15 - 0.20) at each hidden layer.
• Activation: GELU
• Skip Connection: A linear projection of the raw input is concatenated with the final hidden representation before the output head.

To improve robustness, an ensemble of 5 independently seeded models is trained. Predictions are averaged at inference.

Training & Results

• Optimizer: AdamW (initial LR: 1e-4, weight decay: 1e-5)
• Loss Function: Huber Loss ($\delta = 0.1$)
• Scheduling: ReduceLROnPlateau (factor: 0.3, patience: 15)

The dataset is split 70/15/15 into train (40,223), validation (8,619), and test (8,620) subsets.

Test Performance:

• MAE: 3.36 kcal/mol (0.15 eV, 0.0053 Hartree)
• RMSE: 4.88 kcal/mol
• $R^2$: 0.9996

Usage

1. Install dependencies:

   pip install -r requirements.txt

Run the pipeline:

Bash
python src/main.py
Note: The script will automatically download the ANI-1E dataset from Zenodo (~1GB) to a local ani1e directory, parse the XYZ files, engineer the BoB features, train the 5-model ensemble, and output the diagnostic evaluation plots.