EOSNet: Embedded Overlap Structures for Graph Neural Networks

EOSNet uses atomic-centered Gaussian Overlap Matrix (GOM) fingerprints as node features in a graph neural network to predict material properties from crystal structures.

Key idea: GOM eigenvalues encode orbital overlap information — a physics-motivated representation that captures chemical bonding character beyond simple distance-based descriptors.

Models

EOSNet provides two backbone architectures:

Model	Backbone	Description
EOSNet v1 (CGCNN)	Crystal graph convolution	GOM fingerprints + CGCNN message passing
EOSNet v2 (e3nn)	Equivariant tensor products	GOM fingerprints + e3nn spherical harmonics

Select with --model-type e3nn (default) or --model-type cgcnn.

Installation

Prerequisites

• Python 3.10+
• PyTorch >= 2.0
• e3nn

GOM fingerprints are computed natively in PyTorch (eosnet/fp/) — no external C library needed.

Setup

conda create -n eosnet python=3.10 pip
conda activate eosnet

# Install dependencies
pip install numpy scipy ase scikit-learn pymatgen
pip install torch torchvision
pip install e3nn

Data Format

EOSNet supports two input formats:

POSCAR format (default)

Create a directory with:

root_dir/
├── id_prop.csv      # ID, target_value (one per line)
├── id0.vasp         # POSCAR files
├── id1.vasp
└── ...

Extended XYZ format

root_dir/
├── id_prop.csv      # ID, target_value
└── structures.xyz   # All structures in extended XYZ

Use convert_to_extxyz.py to convert POSCAR directories to extended XYZ.

Training

# Train with e3nn backbone (default)
python train.py root_dir

# Train with CGCNN backbone (v1)
python train.py root_dir --model-type cgcnn

# Full example with recommended settings
python train.py root_dir \
    --task regression \
    --epochs 500 \
    --batch-size 64 \
    --optim Adam \
    --lr 1e-3 \
    --warmup-epochs 20 \
    --lr-milestones 100 200 400 \
    --train-ratio 0.8 \
    --val-ratio 0.1 \
    --test-ratio 0.1 \
    --n-conv 3 \
    --n-h 1 \
    | tee train_log.txt

Key options

Flag	Default	Description
--model-type	e3nn	Model backbone: e3nn or cgcnn
--task	regression	regression or classification
--epochs	200	Number of training epochs
--batch-size	64	Mini-batch size
--optim	SGD	Optimizer: SGD or Adam
--lr	0.01	Initial learning rate
--n-conv	3	Number of convolution layers
--nx	256	Max neighbors for GOM fingerprint
--lmax	0	0 for s-orbitals only, 1 for s+p
--radius	8.0	Neighbor cutoff radius (Å)
--save_to_disk	False	Pre-process and cache data to disk
--fine-tune	—	Path to pre-trained model for fine-tuning
--resume	—	Path to checkpoint for resuming training
--data-format	auto	Input format: auto, extxyz, or vasp

e3nn-specific options:

Flag	Default	Description
--irreps-hidden	32x0e+16x1o+8x2e	Hidden irreducible representations
--max-ell	2	Max spherical harmonic order
--num-radial-basis	16	Number of radial basis functions

Run python train.py -h for all options.

Output files

• model_best.pth.tar — Best model (by validation MAE or AUC)
• checkpoint.pth.tar — Latest checkpoint
• train_results.csv / test_results.csv — Predictions (ID, target, predicted)

Prediction

python predict.py model_best.pth.tar --test root_dir

How to Cite

If you use EOSNet, please cite:

@article{taoEOSnetEmbeddedOverlap2025,
  title   = {EOSnet: Embedded Overlap Structures for Graph Neural Networks
             in Predicting Material Properties},
  author  = {Tao, Shuo and Zhu, Li},
  journal = {J. Phys. Chem. Lett.},
  volume  = {16},
  pages   = {717--724},
  year    = {2025},
  doi     = {10.1021/acs.jpclett.4c03179}
}

GOM fingerprint methodology:

@article{sadeghiMetricsMeasuringDistances2013,
  title   = {Metrics for Measuring Distances in Configuration Spaces},
  author  = {Sadeghi, Ali and Ghasemi, S. Alireza and Schaefer, Bastian
             and Mohr, Stephan and Lill, Markus A. and Goedecker, Stefan},
  journal = {J. Chem. Phys.},
  volume  = {139},
  pages   = {184118},
  year    = {2013},
  doi     = {10.1063/1.4828704}
}

Fingerprint library:

@article{zhuFingerprintBasedMetric2016,
  title   = {A Fingerprint Based Metric for Measuring Similarities
             of Crystalline Structures},
  author  = {Zhu, Li and Amsler, Maximilian and Fuhrer, Tobias and Schaefer, Bastian
             and Faraji, Somayeh and Rostami, Samare and Ghasemi, S. Alireza
             and Sadeghi, Ali and Grauzinyte, Migle and Wolverton, Chris
             and Goedecker, Stefan},
  journal = {J. Chem. Phys.},
  volume  = {144},
  pages   = {034203},
  year    = {2016},
  doi     = {10.1063/1.4940026}
}

CGCNN framework:

@article{PhysRevLett.120.145301,
  title     = {Crystal Graph Convolutional Neural Networks for an Accurate
               and Interpretable Prediction of Material Properties},
  author    = {Xie, Tian and Grossman, Jeffrey C.},
  journal   = {Phys. Rev. Lett.},
  volume    = {120},
  pages     = {145301},
  year      = {2018},
  doi       = {10.1103/PhysRevLett.120.145301}
}

License

The v1 (CGCNN) backbone is based on the CGCNN framework by Tian Xie.