Add CHGNet PyG PBE model and model card

README.md

@@ -0,0 +1,91 @@
+---
+library_name: matgl
+tags:
+- matgl
+- materials-science
+- graph-neural-network
+---
+
+# Description
+
+This model is a CHGNet universal potential for the **PyTorch Geometric (PyG) backend** of
+[MatGL](https://github.com/materialyzeai/matgl).  The weights were **directly transferred**
+from the DGL checkpoint
+[materialyze/CHGNet-PES-MatPES-PBE-2025.2.10](https://huggingface.co/materialyze/CHGNet-PES-MatPES-PBE-2025.2.10)
+— no retraining was performed.
+
+The architecture is a faithful PyG port of the original DGL CHGNet implementation.
+The DGL implementation has a slight modification from the original PyTorch implementation
+by adding directed edge updates; this PyG port preserves that modification.
+
+# Training dataset
+
+MatPES-PBE-2024.11: Materials Energy Surface dataset that contains off-equilibrium PBE static calculations.
+- Train-Val-Test splitting with mp-id: 0.9 - 0.5 - 0.5
+- Train set size: 391241
+- Validation set size: 21736
+- Test set size: 21735
+
+# Performance metrics
+## Training and validation errors
+
+Identical to the source DGL checkpoint (weights are the same):
+
+| partition  | Energy (meV/atom) | Force (meV/Å) | stress (GPa) | magmom (μB) |
+| ---------- |-------------------|---------------|--------------|-------------|
+| Train      | 26.54             | 81.4          | 0.375        | 0.066       |
+| Validation | 32.02             | 123.8         | 0.617        | 0.067       |
+| Test       | 30.70             | 136.0         | 0.642        | 0.066       |
+
+## PyG vs DGL prediction parity
+
+Evaluated on 10 structures spanning diverse chemistries (MoS, Fe, Mo, Al, NaCl, BaTiO₃,
+Li₂O, MgO, and their perturbed variants) with both the PyG and DGL models running
+independently.
+
+| Quantity | Max |ΔPyG − ΔDGL| |
+|---|---|
+| Energy/atom (eV) | 0 (exact) |
+| Forces (eV/Å) | 1.5 × 10⁻⁷ |
+| Stress (GPa) | 4.1 × 10⁻⁶ |
+| Magnetic moment (μB) | 0 (exact) |
+
+Non-zero force/stress differences arise from floating-point summation order differences
+between DGL and PyG message-passing kernels, not from any model divergence.
+All differences are more than two orders of magnitude below the `atol = 1e-5` threshold
+of the automated parity test.
+
+# Usage
+
+```python
+import matgl
+from matgl.ext.pymatgen import Structure2Graph
+import torch
+
+pot = matgl.load_model("BowenD-UCB/CHGNet-PyG-MatPES-PBE-2025.2.10")
+pot.eval()
+```
+
+# References
+
+```txt
+Deng, B. et al. CHGNet as a pretrained universal neural network potential for charge-informed atomistic modelling.
+Nat. Mach. Intell. 1–11 (2023) doi:10.1038/s42256-023-00716-3.
+```
+
+#### Date: 2025.2.10
+#### Author: Bowen Deng
+
+## Metadata
+
+```json
+{
+  "tags": [
+    "matgl",
+    "materials-science",
+    "graph-neural-network"
+  ],
+  "license": "BSD-3-Clause",
+  "author": "Bowen Deng"
+}
+```

model.json

@@ -0,0 +1,159 @@
+{
+    "@class": "Potential",
+    "@module": "matgl.apps._pes_pyg",
+    "@model_version": 3,
+    "metadata": null,
+    "kwargs": {
+        "model": {
+            "@class": "CHGNet",
+            "@module": "matgl.models._chgnet_pyg",
+            "@model_version": 1,
+            "init_args": {
+                "element_types": [
+                    "H",
+                    "He",
+                    "Li",
+                    "Be",
+                    "B",
+                    "C",
+                    "N",
+                    "O",
+                    "F",
+                    "Ne",
+                    "Na",
+                    "Mg",
+                    "Al",
+                    "Si",
+                    "P",
+                    "S",
+                    "Cl",
+                    "Ar",
+                    "K",
+                    "Ca",
+                    "Sc",
+                    "Ti",
+                    "V",
+                    "Cr",
+                    "Mn",
+                    "Fe",
+                    "Co",
+                    "Ni",
+                    "Cu",
+                    "Zn",
+                    "Ga",
+                    "Ge",
+                    "As",
+                    "Se",
+                    "Br",
+                    "Kr",
+                    "Rb",
+                    "Sr",
+                    "Y",
+                    "Zr",
+                    "Nb",
+                    "Mo",
+                    "Tc",
+                    "Ru",
+                    "Rh",
+                    "Pd",
+                    "Ag",
+                    "Cd",
+                    "In",
+                    "Sn",
+                    "Sb",
+                    "Te",
+                    "I",
+                    "Xe",
+                    "Cs",
+                    "Ba",
+                    "La",
+                    "Ce",
+                    "Pr",
+                    "Nd",
+                    "Pm",
+                    "Sm",
+                    "Eu",
+                    "Gd",
+                    "Tb",
+                    "Dy",
+                    "Ho",
+                    "Er",
+                    "Tm",
+                    "Yb",
+                    "Lu",
+                    "Hf",
+                    "Ta",
+                    "W",
+                    "Re",
+                    "Os",
+                    "Ir",
+                    "Pt",
+                    "Au",
+                    "Hg",
+                    "Tl",
+                    "Pb",
+                    "Bi",
+                    "Ac",
+                    "Th",
+                    "Pa",
+                    "U",
+                    "Np",
+                    "Pu"
+                ],
+                "dim_state_feats": null,
+                "non_linear_bond_embedding": false,
+                "non_linear_angle_embedding": false,
+                "cutoff": 6.0,
+                "threebody_cutoff": 3.0,
+                "cutoff_exponent": 5,
+                "max_f": 32,
+                "learn_basis": false,
+                "num_blocks": 5,
+                "shared_bond_weights": "both",
+                "final_mlp_type": "mlp",
+                "final_hidden_dims": [
+                    128,
+                    128
+                ],
+                "final_dropout": 0.0,
+                "pooling_operation": "sum",
+                "readout_field": "atom_feat",
+                "activation_type": "swish",
+                "is_intensive": false,
+                "num_targets": 1,
+                "num_site_targets": 1,
+                "task_type": "regression",
+                "angle_update_hidden_dims": [],
+                "atom_conv_hidden_dims": [
+                    128
+                ],
+                "bond_conv_hidden_dims": [
+                    128
+                ],
+                "bond_update_hidden_dims": [
+                    128
+                ],
+                "conv_dropout": 0.0,
+                "dim_angle_embedding": 128,
+                "dim_atom_embedding": 128,
+                "dim_bond_embedding": 128,
+                "dim_state_embedding": null,
+                "layer_bond_weights": null,
+                "max_n": 63,
+                "normalization": "layer",
+                "normalize_hidden": false
+            }
+        },
+        "data_mean": "tensor(0.)",
+        "data_std": "tensor(3.2515)",
+        "element_refs": "tensor([ -3.6867,  -1.9978,  -3.7186,  -3.3643,  -6.6234,  -8.4499,  -5.5657,\n         -6.9965,  -4.9662,  -0.0187,  -1.5531,  -1.6896,  -4.4992,  -6.0153,\n         -6.3834,  -4.9390,  -2.6428,  -0.0427,  -1.7198,  -5.0344,  -7.1726,\n         -9.6275,  -9.8038,  -9.5224,  -9.3022,  -7.7307,  -6.3933,  -4.3683,\n         -3.1376,  -0.9442,  -3.3615,  -4.5886,  -4.4786,  -4.1130,  -2.3407,\n          7.9289,  -1.5689,  -3.9607,  -8.6393,  -9.3327, -10.5867, -10.7636,\n         -8.6914,  -8.1344,  -6.6219,  -4.7359,  -1.0682,  -0.7805,  -2.6786,\n         -3.9057,  -3.9473,  -3.1972,  -1.8243,  11.1554,  -1.7597,  -5.2027,\n         -7.8053,  -7.3150,  -7.9745,  -8.8961,  -7.8314, -11.5431, -13.3298,\n        -15.1617, -11.3405, -10.4704,  -8.9142,  -8.1105,  -6.9612,  -4.9349,\n         -6.2312, -10.3309, -12.0231, -12.5809, -10.7719,  -9.5070,  -7.7026,\n         -5.5023,  -2.7198,   0.8658,  -1.7361,  -3.2330,  -3.5141,  -3.2480,\n         -8.0818,  -8.3339, -11.9343, -11.9106, -13.3325])",
+        "calc_forces": true,
+        "calc_stresses": true,
+        "calc_hessian": false,
+        "calc_magmom": true,
+        "calc_charge": false,
+        "calc_repuls": false,
+        "zbl_trainable": false,
+        "debug_mode": false
+    }
+}

model.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4485f0c99472de4672ad5f0cb84c2e89679137708b397cf927f94269a4019715
+size 3974

state.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d9bb47085b0395c8c19de76f15432feaafb81a9cebe22f65e7b13b444bf59b63
+size 11099906