Bump matgl from 3.0.2 to 3.0.3

[dependabot]

Bumps matgl from 3.0.2 to 3.0.3.

Release notes

Sourced from matgl's releases.

v3.0.3

• GRACE (PyG) interatomic potential. New matgl.models.GRACE (beta) joins TensorNet / M3GNet / MEGNet / QET / CHGNet / SO3Net on the PyG backend. (#779)
• matgl.utils.training.MGLPotentialTrainer + MGLDatasetLoader (new, PyG-only). First dataset-level Hugging Face integration in matgl: a configure-once / fit-when-asked trainer paired with a small dataset-factory class that hoists HF auth / cache config to one place. __init__ stores hyperparameters; nothing heavy runs until fit(dataset=...). (#782)
  • MGLDatasetLoader (defaults to HF materialyze/matpes): loader = MGLDatasetLoader() then loader.matpes_dataset(version="r2SCAN-2025.2") and loader.matpes_element_refs(version="r2SCAN-2025.2", element_types=...). Override repo_id / revision / token / cache_dir in the constructor to point at a fork or a private mirror. Element references are reorderable to the caller's element_types. Stresses in the on-disk MatPES JSON (kbar, VASP compressive-positive) are converted to matgl's GPa compressive-negative convention automatically; pass stress_unit="GPa" to skip the conversion.
  • MGLPotentialTrainer: MGLPotentialTrainer(model, accelerator="auto", max_epochs=100, ...) accepts the full Lightning placement vocabulary ("auto" / "cpu" / "gpu" / "cuda" / "mps" / "tpu"). trainer.fit(dataset, *, atomrefs=None, save_path=None) is a small focused entry point:
    • dataset is a pre-built MGLDataset (random split inside _build_dataloaders via frac_list / shuffle / random_state) or a {"train", "valid", "test"} mapping of pre-built splits. Use MGLDatasetLoader above to build one.
    • atomrefs accepts np.ndarray / AtomRef instance / None. Use MGLDatasetLoader().matpes_element_refs(...) to download or fit_element_refs(...) to fit locally.
    • Loss-term toggling follows the constructor weights: set stress_weight=0 for datasets without stress labels (cluster / dimer extxyz), and magmom_weight / charge_weight > 0 only when the dataset carries those labels.
    • After fit, trainer.potential / trainer.lit_module / trainer.trainer / trainer.loaders / trainer.dataset / trainer.atomrefs are populated. Defaults: Huber loss with stress weight 0.1, batch size 32, lr 1e-3, 100 epochs, CosineAnnealingLR (decay_steps=1000, decay_alpha=0.01).
• MGLDataLoader collate auto-detect (PyG). When collate_fn is omitted, the loader now picks one from the training dataset's label keys (collate_fn_graph for property prediction, collate_fn_pes with stress / magmom / charge flags toggled to match labels), mirroring the DGL path. Subset (post-split_dataset) is peeled to reach the underlying MGLDataset.labels. Explicit collate_fn= always wins. (#782)
• fit_element_refs training helper. Convenience function that fits per-element energy offsets from pymatgen Structures + energies via np.linalg.lstsq, returning an array that drops directly into PotentialLightningModule(element_refs=...) or Potential(element_refs=...). (#780)
• Performance speedups (no checkpoint or public-API changes).
  • Cache spherical-Bessel basis constants (zeros, normalization factors) in __init__ instead of recomputing them in every forward. (#787)
  • Lower-overhead Potential and AtomRef forward paths on PyG: hoist .to(device) / shape work out of the hot path, avoid redundant tensor allocations. (#783)
  • Port the same Potential / AtomRef speedups to DGL. (#786)
  • Opt-in torch.compile flag on Potential (PyG) for further inference speedups. (#784)
  • Low-risk speedups across Structure2Graph / Molecule2Graph converters, the training loop, and the ASE PESCalculator. (#781)
• Bug fix (PyG): Potential.forward no longer mutates the input graph. Previously the autograd pos.requires_grad_(True) / cell.requires_grad_(True) toggles were applied in place on the caller's Data object, which leaked grad-tracking state across reuses. The forward now operates on a shallow clone of the relevant tensors. (#785)
• Fleshed out module-level docstrings for matgl.apps and matgl.layers, and the Potential wrapper docstring (energy / force / stress / charge contract, stress unit, magmom / charge head gating).

Changelog

Sourced from matgl's changelog.

3.0.3

• GRACE (PyG) interatomic potential. New matgl.models.GRACE (beta) joins TensorNet / M3GNet / MEGNet / QET / CHGNet / SO3Net on the PyG backend. (#779)
• matgl.utils.training.MGLPotentialTrainer + MGLDatasetLoader (new, PyG-only). First dataset-level Hugging Face integration in matgl: a configure-once / fit-when-asked trainer paired with a small dataset-factory class that hoists HF auth / cache config to one place. __init__ stores hyperparameters; nothing heavy runs until fit(dataset=...). (#782)
  • MGLDatasetLoader (defaults to HF materialyze/matpes): loader = MGLDatasetLoader() then loader.matpes_dataset(version="r2SCAN-2025.2") and loader.matpes_element_refs(version="r2SCAN-2025.2", element_types=...). Override repo_id / revision / token / cache_dir in the constructor to point at a fork or a private mirror. Element references are reorderable to the caller's element_types. Stresses in the on-disk MatPES JSON (kbar, VASP compressive-positive) are converted to matgl's GPa compressive-negative convention automatically; pass stress_unit="GPa" to skip the conversion. For datasets (MatPES forks, custom DFT runs) already on disk, loader.from_json("/path/to/file.json", ...) skips the HF round trip entirely. The JSON file must use the same per-record schema as the MatPES dataset — structure (pymatgen-serialisable) + energy / forces / stress PES keys; any extra metadata fields are ignored. stress_unit defaults to "kbar" (MatPES on-disk convention) and is applied consistently with the HF path. The loader returns a raw MGLDataset; splitting + MGLDataLoader wrapping is the trainer's job (see MGLPotentialTrainer's frac_list / shuffle / random_state loader_kwargs).
  • MGLPotentialTrainer: MGLPotentialTrainer(model, accelerator="auto", max_epochs=100, ...) accepts the full Lightning placement vocabulary ("auto" / "cpu" / "gpu" / "cuda" / "mps" / "tpu"). trainer.fit(dataset, *, atomrefs=None, save_path=None) is a small focused entry point:
    • dataset is a pre-built MGLDataset (random split inside _build_dataloaders via frac_list / shuffle / random_state) or a {"train", "valid", "test"} mapping of pre-built splits. Use MGLDatasetLoader above to build one.
    • atomrefs accepts np.ndarray / AtomRef instance / None. Use MGLDatasetLoader().matpes_element_refs(...) to download or fit_element_refs(...) to fit locally.
    • Loss-term toggling follows the constructor weights: set stress_weight=0 for datasets without stress labels (cluster / dimer extxyz), and magmom_weight / charge_weight > 0 only when the dataset carries those labels.
    • After fit, trainer.potential / trainer.lit_module / trainer.trainer / trainer.loaders / trainer.dataset / trainer.atomrefs are populated. Defaults: Huber loss with stress weight 0.1, batch size 32, lr 1e-3, 100 epochs, CosineAnnealingLR (decay_steps=1000, decay_alpha=0.01).
• MGLDataLoader collate auto-detect (PyG). When collate_fn is omitted, the loader now picks one from the training dataset's label keys (collate_fn_graph for property prediction, collate_fn_pes with stress / magmom / charge flags toggled to match labels), mirroring the DGL path. Subset (post-split_dataset) is peeled to reach the underlying MGLDataset.labels. Explicit collate_fn= always wins. (#782)
• fit_element_refs training helper. Convenience function that fits per-element energy offsets from pymatgen Structures + energies via np.linalg.lstsq, returning an array that drops directly into PotentialLightningModule(element_refs=...) or Potential(element_refs=...). (#780)
• Performance speedups (no checkpoint or public-API changes).
  • Cache spherical-Bessel basis constants (zeros, normalization factors) in __init__ instead of recomputing them in every forward. (#787)
  • Lower-overhead Potential and AtomRef forward paths on PyG: hoist .to(device) / shape work out of the hot path, avoid redundant tensor allocations. (#783)
  • Port the same Potential / AtomRef speedups to DGL. (#786)
  • Opt-in torch.compile flag on Potential (PyG) for further inference speedups. (#784)
  • Low-risk speedups across Structure2Graph / Molecule2Graph converters, the training loop, and the ASE PESCalculator. (#781)
• Bug fix (PyG): Potential.forward no longer mutates the input graph. Previously the autograd pos.requires_grad_(True) / cell.requires_grad_(True) toggles were applied in place on the caller's Data object, which leaked grad-tracking state across reuses. The forward now operates on a shallow clone of the relevant tensors. (#785)
• Fleshed out module-level docstrings for matgl.apps and matgl.layers, and the Potential wrapper docstring (energy / force / stress / charge contract, stress unit, magmom / charge head gating).

Commits

• 361b8df Update uv.lock.
• 38f6849 docs: fix README MGLPotentialTrainer API and round out 3.0.3 changelog
• 8ffbb4a feat(training): add MatGLPotentialTrainer + MGLDataLoader collate auto-detect...
• 2559e6d Fix warning.
• bd22309 docs(apps, layers): flesh out module and Potential docstrings
• 8180eb5 perf: cache spherical-Bessel basis constants in init (#787)
• c5b4da8 fix(pyg): Potential.forward no longer mutates the input graph (#785)
• c5c9b70 perf(dgl): port Potential and AtomRef speedups from #783 to DGL (#786)
• 3b255b2 feat(pyg): opt-in torch.compile flag on Potential (#784)
• 78b6100 perf(pyg): lower-overhead Potential and AtomRef forward paths (#783)
• Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

---

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)