Bump matgl from 3.0.2 to 4.0.0

[dependabot]

Bumps matgl from 3.0.2 to 4.0.0.

Release notes

Sourced from matgl's releases.

v4.0.0

• DGL backend removed. All DGL implementations have been deleted. matgl now targets PyTorch Geometric exclusively. The MATGL_BACKEND env var and the ensure_backend() helper have been removed. matgl.set_backend() is retained as a no-op stub for backwards compatibility and emits a DeprecationWarning when "DGL" is requested. Private _*_pyg.py modules have been renamed to drop the _pyg suffix. If you wish to use DGL, please install matgl<=4.
• Optional JAX inference backend (matgl.ext.jax, experimental). New subpackage that reimplements the inference path (energy + forces + stress) of the TensorNet and QET models in JAX. A pre-trained PyTorch potential is converted to a JAX parameter tree and JIT-compiled by XLA into one fused program, giving a portable (CPU / CUDA / Apple-Silicon) ~2-3.5x speedup over eager PyTorch for the MD / relaxation inner loop, with no NVIDIA-Warp dependency. JAXPESCalculator is a drop-in twin of matgl.ext.ase.PESCalculator. Outputs match the PyTorch reference to float64 precision. Requires the optional jax extra (pip install matgl[jax]); inference-only.
• Bug fix: QET no longer crashes on single-atom structures. Bare torch.squeeze() calls in QET.forward collapsed the size-1 node dimension of a one-atom input to a 0-d scalar, raising IndexError inside ElectrostaticPotential. These now use .reshape(-1), which drops only trailing feature dimensions and never the node dimension.
• Bug fix: TensorNet / QET no longer crash with the non-smooth SphericalBessel radial basis. With rbf_type="SphericalBessel" and use_smooth=False, the basis emits max_l * max_n features, but the embedding / interaction input Linear layers were sized for only max_n, raising a shape-mismatch RuntimeError in the forward pass. The radial-basis width fed to those layers now correctly accounts for max_l in the non-smooth case (the smooth SphericalBessel and Gaussian bases are unaffected).

v3.0.5

• Bug fix: QET no longer crashes on single-atom structures. Bare torch.squeeze() calls in QET.forward (and in the DGL LinearQeq QEq solver) collapsed the size-1 node dimension of a one-atom input to a 0-d scalar, raising IndexError inside the PyG ElectrostaticPotential and a node-feature shape error on the DGL backend. These now use .reshape(-1), which drops only trailing feature dimensions and never the node dimension.

v3.0.4

• PyG SO3Net. New matgl.models._so3net_pyg.SO3Net is the PyG counterpart of the existing DGL SO3Net and is now the implementation selected on the default PyG backend. The full public surface is preserved (target_property in {atomwise, dipole_moment, polarizability, graph}, readout_type in {set2set, weighted_atom, reduce_atom}, correct_charges, predict_dipole_magnitude, use_vector_representation, return_vector_representation). Forward now takes a PyG Data/Batch and aggregates per-graph via scatter_add / bincount instead of dgl.readout_nodes / batch_num_nodes.
• DGL backend deprecated. The DGL backend (MATGL_BACKEND=DGL) is deprecated and will be removed in v4.0.0. PyG is now the only supported backend for new work. ensure_backend("DGL") (called at import time when MATGL_BACKEND=DGL, and from matgl.set_backend("DGL")) now emits a DeprecationWarning.

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.

4.0.0

• DGL backend removed. All DGL implementations have been deleted. matgl now targets PyTorch Geometric exclusively. The MATGL_BACKEND env var and the ensure_backend() helper have been removed. matgl.set_backend() is retained as a no-op stub for backwards compatibility and emits a DeprecationWarning when "DGL" is requested. Private _*_pyg.py modules have been renamed to drop the _pyg suffix. If you wish to use DGL, please install matgl<=4.
• Optional JAX inference backend (matgl.ext.jax, experimental). New subpackage that reimplements the inference path (energy + forces + stress) of the TensorNet and QET models in JAX. A pre-trained PyTorch potential is converted to a JAX parameter tree and JIT-compiled by XLA into one fused program, giving a portable (CPU / CUDA / Apple-Silicon) ~2-3.5x speedup over eager PyTorch for the MD / relaxation inner loop, with no NVIDIA-Warp dependency. JAXPESCalculator is a drop-in twin of matgl.ext.ase.PESCalculator. Outputs match the PyTorch reference to float64 precision. Requires the optional jax extra (pip install matgl[jax]); inference-only.
• Bug fix: QET no longer crashes on single-atom structures. Bare torch.squeeze() calls in QET.forward collapsed the size-1 node dimension of a one-atom input to a 0-d scalar, raising IndexError inside ElectrostaticPotential. These now use .reshape(-1), which drops only trailing feature dimensions and never the node dimension.
• Bug fix: TensorNet / QET no longer crash with the non-smooth SphericalBessel radial basis. With rbf_type="SphericalBessel" and use_smooth=False, the basis emits max_l * max_n features, but the embedding / interaction input Linear layers were sized for only max_n, raising a shape-mismatch RuntimeError in the forward pass. The radial-basis width fed to those layers now correctly accounts for max_l in the non-smooth case (the smooth SphericalBessel and Gaussian bases are unaffected).

3.0.4

• PyG SO3Net. New matgl.models._so3net_pyg.SO3Net is the PyG counterpart of the existing DGL SO3Net and is now the implementation selected on the default PyG backend. The full public surface is preserved (target_property in {atomwise, dipole_moment, polarizability, graph}, readout_type in {set2set, weighted_atom, reduce_atom}, correct_charges, predict_dipole_magnitude, use_vector_representation, return_vector_representation). Forward now takes a PyG Data/Batch and aggregates per-graph via scatter_add / bincount instead of dgl.readout_nodes / batch_num_nodes.
• DGL backend deprecated. The DGL backend (MATGL_BACKEND=DGL) is deprecated and will be removed in v4.0.0. PyG is now the only supported backend for new work. ensure_backend("DGL") (called at import time when MATGL_BACKEND=DGL, and from matgl.set_backend("DGL")) now emits a DeprecationWarning.

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

• c783125 Update tasks.
• da972ea Update uv.lock.
• 5c40eb1 Updated changelog.
• 40eee88 Updated changelog.
• c8636ad Remove DGL support; rename _pyg modules to drop suffix (#792)
• 537e7e4 ci: GPU runner matrix for warp vs eager vs JAX TensorNet benchmark (#795)
• 98c2d6a JAX inference-path prototype for TensorNet / QET (PyG) (#794)
• ffef5fc fix: size TensorNet RBF layers correctly for non-smooth SphericalBessel (#793)
• fcf19dc Update version.
• bd4b13d Document QET single-atom bug fix in changelog
• 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)

[dependabot]

Superseded by #1489.