MEGNet

Overview

MEGNet implements MatErials Graph Networks for learning properties of molecules and crystals. Developed by the Materials Virtual Lab, the repository combines pretrained predictive models with tools for training and customizing graph networks. It is now deprecated: the README states that it will receive no further updates and is retained as a reference for the original TensorFlow implementation, with matgl identified as its successor.

The workflow represents structures through atom features, bond features, connectivity, and global state attributes. Stacked MEGNet blocks exchange information among these components, and a set2set readout maps the representation to scalar or vector properties. Prediction examples accept pymatgen Structure or Molecule objects; molecular examples also describe conversion from SMILES and loading XYZ files. Pretrained models are distributed as HDF5+JSON files for QM9 molecular targets and Materials Project crystal targets, including orbital energies, formation energy, band gap, and logarithmic elastic moduli.

For model development, MEGNetModel supports training from structures and corresponding target values, or from validated graphs. Lower-level MEGNetLayer and Set2Set components support custom architectures. The repository also provides multi-fidelity examples and elemental embeddings extracted from formation-energy models for transfer-learning workflows.

Important constraints affect its use as a research baseline. The README discourages applying QM9 models to molecules outside that dataset because training coverage is limited. Crystal graph conversion can fail when the selected neighbor cutoff leaves isolated atoms. Large-dataset training is described as computationally intensive, with dedicated GPUs recommended. These constraints and the repository’s deprecated status should guide any intended evaluation.

Key Features

• Loads serialized HDF5+JSON pretrained models through MEGNetModel.from_file, with models for QM9 molecular properties and Materials Project crystal properties.
• Accepts pymatgen crystal and molecule objects for prediction, with documented molecular workflows for SMILES conversion and XYZ loading.
• Trains MEGNetModel instances from structures and targets, or uses train_from_graphs after filtering invalid structure graphs.
• Updates atom, bond, and global state attributes through stacked graph-network blocks, with set2set readout for scalar or vector predictions.
• Exposes MEGNetLayer and Set2Set components for constructing customized TensorFlow/Keras graph-network architectures.
• Provides pretrained elemental embeddings, a transfer-learning notebook, and examples for multi-fidelity graph-network training.

Use Cases

• Intended evaluation: assess pretrained formation-energy, band-gap, or elastic-modulus models as historical baselines on representative crystal structures, checking graph validity and target units.
• Intended evaluation: explore QM9 molecular-property prediction on in-domain molecules, rather than assuming applicability to unrelated molecular chemistry.
• Intended evaluation: train a property model on labeled crystal structures and compare a model using transferred elemental embeddings with one trained without them.
• Intended evaluation: study how global state features and multi-fidelity training could fit a materials-property modeling workflow using the supplied examples.

How to Use

1. Read the official README, especially its deprecation notice. Decide whether the original TensorFlow reference implementation is needed or whether to investigate the linked matgl successor.
2. Follow the README’s installation guidance in a separate evaluation environment. Treat installation and runtime compatibility as checks to perform, not as established facts for your system.
3. Select a pretrained target from mvl_models and inspect its model details. Follow the README’s crystal or QM9 notebook references to prepare pymatgen inputs and load the model through the documented API.
4. Check input coverage, neighbor cutoffs, and output units before interpreting predictions. In particular, the bulk-modulus example converts a log10 prediction to GPa; QM9 models carry an explicit coverage warning.
5. For custom training, pair structures with target values, validate graph conversion, and use the documented training workflow. Evaluate held-out predictions separately; consult the transfer-learning and multifidelity examples when relevant.