A Julia research package for predicting intermolecular transfer integrals in organic molecular dimers using Atomic Cluster Expansion (ACE) machine-learning potentials.
Transfer integrals (electronic coupling matrix elements) determine charge- and exciton-transport rates in organic semiconductors. This project replaces expensive quantum-chemistry calculations with fast ACE surrogate models trained on dimer geometry libraries.
ACE-TransferInts.jl/
│
├── src/ # Julia library — importable functions
│ ├── ACE-TransferInts.jl # Module entry point (ACETransferInts)
│ ├── dimer.jl # rot_x/y/z, centroid, construct_dimer
│ ├── fitting.jl # extract_energies, rmse, mae, sign_accuracy
│ └── io.jl # read_J, write_xyz, read_lc_csv
│
├── experiments/ # One folder per molecule
│ ├── ethylene/
│ │ ├── datagen/ # Scripts that generate training structures
│ │ ├── fitting/ # ACE fit scripts and hyperparameter sweeps
│ │ └── results/ # CSV learning curves, plots
│ ├── thiophene/
│ │ ├── datagen/
│ │ ├── fitting/
│ │ └── results/
│ └── naphthalene/
│ ├── datagen/
│ ├── fitting/
│ ├── results/
│ ├── heavy_atom/ # All-heavy-atom representation
│ │ ├── datagen/
│ │ ├── fitting/
│ │ └── results/
│ └── bead/ # Coarse-grained bead representation
│ ├── datagen/
│ ├── fitting/
│ └── results/
│
├── notebooks/ # Exploratory and publication notebooks
│ ├── learning_curves.jl # Interactive learning-curve exploration
│ ├── learning_curves_paper.jl # Final paper figures (multi-molecule)
│ └── ACE_Package.jl # Environment setup helper
│
├── data/
│ ├── reference/ # Si_dataset.xyz and other reference data
│ ├── raw/ # Original extxyz from quantum chemistry
│ │ ├── ethylene/
│ │ ├── thiophene/
│ │ └── naphthalene/
│ └── processed/ # Train/test splits, modified structures
│
├── archive/
│ └── Notebook_2024-2025/ # Chronological research notebooks (read-only)
│
├── test/
│ └── runtests.jl
├── docs/
│ ├── make.jl
│ └── src/index.md
│
├── Project.toml
├── Manifest.toml
└── LICENSE
Atomic Cluster Expansion (ACE) builds a systematically improvable, many-body descriptor for atomic environments from rotationally invariant polynomials of interatomic distances and angles. Fitting an ACE model to reference transfer-integral data gives a fast surrogate that:
- is invariant to translation, rotation, and permutation of equivalent atoms;
- scales with body order (ν) and polynomial degree (td) so accuracy is controllable;
- requires only atomic positions at inference time.
| Molecule | Atom types in model | rcut (Å) | RMSE at convergence | Sign accuracy |
|---|---|---|---|---|
| Ethylene (C₂H₄) | Si, C | 7.5 | ~2.85 μeV/mol | ~86% |
| Thiophene (C₄H₄S) | Si, C, S, O | 9.0 | ~1.95 μeV/mol | ~86% |
| Naphthalene (C₁₀H₈) | Si, C (heavy atom) | 13.6 | ~12 meV/atom | ~97% |
| Naphthalene (bead) | Si, C (4-bead CG) | 13.6 | ~18 meV/bead | ~97% |
H atoms are replaced by heavier pseudo-Si atoms so the ACE radial basis covers the relevant interatomic distances cleanly. A coarse-grained bead model of naphthalene is also studied as a more compact representation. All models use ν=2, td=10 with 8,000 randomly sampled training structures; convergence is reached at ~1,500–2,000 structures.
using ACETransferInts
# Dimer geometry
R = rot_y(π/3) # 3×3 rotation matrix
c = centroid(atoms.X) # centre of geometry
construct_dimer("mol.extxyz", "dimer.extxyz", params, π/3, J)
# Metrics
rmse(predicted, reference)
mae(predicted, reference)
sign_accuracy(predicted, reference) # fraction with correct sign
# I/O
params, J, logJ = read_J("out.dat")
write_xyz("mol.xyz", atoms)
n, rmse_v, mae_v, sign_acc = read_lc_csv("LC_Ethylene.csv")| Parameter | Meaning | Small molecules | Large molecules |
|---|---|---|---|
ν (order) |
Body order (2 = pair, 3 = 3-body, …) | 2 | 2 |
td (total degree) |
Maximum polynomial degree | 10 | 10 |
rcut |
Cutoff radius (Å) | 7.5 – 9.0 | 13.6 |
r₀ |
Reference radius (Å) | 6.625 | 12.0 |
p |
Agnesi transform (numerator) | 19 | 19 |
q |
Agnesi transform (denominator) | 45 | 43 |
The canonical values above were fixed through systematic sweeps in April 2025 (rcut, p, q, td each varied independently) and validated across all three molecules. Fitting scripts and per-molecule sweep results live in experiments/<molecule>/fitting/.
Learning-curve data are stored as row-keyed CSV files:
n_train, 10, 50, 100, 200, 500, 1000
rmse, ...
mae, ...
sign_acc, ...
Final paper plots (RMSE, MAE, and sign accuracy on log–log axes for all molecules) are in notebooks/learning_curves_paper.jl and the per-molecule PNGs in experiments/*/results/.
Training labels are effective transfer integrals computed with xTB via the --dipro flag (GFN1-xTB level). Raw DIPRO output gives J and the overlap integral S; the effective coupling is:
J_eff = (J × 1928 − S × E_avg) / (1 − S²)
where E_avg is the average site energy (meV). The Python script script.py in each datagen/ directory batch-processes dimer XYZ files and attaches energy_eff to each extxyz frame.
- Convergence is fast. All systems reach diminishing returns by ~1,500–2,000 training structures; 5,000 structures yield only marginal improvement.
- Sign accuracy is the practical target. Models achieve 80–97% correct sign prediction depending on system, which is sufficient to rank dimer orientations for transport calculations.
- Including real heteroatoms helps. For thiophene, using Si, C, S, O (4-element model) reduces RMSE by ~35% compared to a 2-element Si, C proxy at large training set sizes.
- Larger molecules need larger cutoffs but are easier to learn. Naphthalene's sign accuracy (~97%) exceeds ethylene's (~86%) because its π–π stacking geometry is more regular and predictable.
- The bead model is fragile at small N. The 4-bead coarse-grained naphthalene representation needs >900 training structures to stabilise; below that, RMSE diverges.
import Pkg
Pkg.develop(path="path/to/ACE-TransferInts.jl")The main external dependency is ACEpotentials.jl (requires the ACEsuit registry). All other dependencies are in Project.toml.
archive/Notebook_2024-2025/ preserves the original chronological research notebooks (July 2024 – April 2026) exactly as written. These are the historical record; new work should go in experiments/ or notebooks/.
MIT — see LICENSE.
Copyright © Jarvist Moore Frost and contributors.