科研 Skill
MatGL图神经网络框架
matgl-framework
Covers building, applying, validating, and fine-tuning MatGL graph-neural-network models for property prediction and interatomic potentials. Use for pretrained GNN workflows via MatGL.
SKILL.md
MatGL Framework
Description
Use this skill when building, applying, validating, or fine-tuning MatGL models for materials property prediction, learned interatomic potentials, and graph-based materials workflows. MatGL is most useful when a workflow needs pretrained graph neural network models, pymatgen-compatible structure handling, periodic crystal graph construction, or a bridge between materials databases, DFT datasets, and learned potential deployment.
MatGL should not be treated as a black-box replacement for DFT. Pretrained models can be extremely useful for screening, relaxation preconditioning, or baseline predictions, but their reliability depends on the training domain, target definition, element coverage, structure type, and validation protocol.
Domain Context
MatGL sits in the materials graph-learning ecosystem alongside M3GNet-style universal potentials, MEGNet-style property models, CHGNet-style charge-informed workflows, and newer pretrained materials models. In practice, it often appears in workflows that start from pymatgen Structure objects, convert periodic structures into graph representations, apply a pretrained model, and then validate predictions against DFT or experiment.
Useful MatGL tasks include:
- Predicting crystal properties from periodic structures.
- Loading pretrained models for formation energy, band gap, or potential-energy-surface inference where available.
- Relaxing structures using learned energy/force/stress models.
- Fine-tuning pretrained models on project-specific DFT datasets.
- Preparing graph-learning baselines for high-throughput screening.
- Comparing universal-potential relaxations against VASP, Quantum ESPRESSO, or CP2K reference calculations.
When to Use This Skill
- Use when applying MatGL pretrained models to crystal property prediction, screening, relaxation preconditioning, or potential-energy-surface inference.
- Use when converting pymatgen structures into periodic graph-learning inputs with explicit control over cell representation, cutoffs, neighbor lists, and metadata.
- Use when fine-tuning MatGL or M3GNet-style models on project-specific DFT datasets with energy, force, stress, or scalar property labels.
- Use when comparing MatGL predictions against DFT, high-throughput DFT, universal potentials, or other graph neural network baselines.
When Not to Use This Skill
MatGL is not automatically appropriate when:
- The chemistry, charge state, defect type, surface, molecule, or pressure/temperature regime is outside the model training distribution.
- The target requires strict DFT-level accuracy for final publication claims.
- The dataset is too small to fine-tune without leakage-resistant validation.
- The structure contains unsupported elements, unusual oxidation states, partial occupancies, disorder, molecular crystals, charged defects, or nonperiodic species that the model was not designed to handle.
- Uncertainty estimates are required but the deployed model does not provide calibrated uncertainty.
Core Concepts
Graph Construction From Structures
MatGL workflows usually begin with periodic structures from pymatgen or ASE. Crystal graphs encode atoms as nodes and neighbor relationships as edges, usually with distances, periodic image offsets, and sometimes angular or three-body features depending on the model architecture.
Check these details before trusting predictions:
- Whether the input cell, species, occupancies, oxidation states, and site properties survived file conversion.
- Whether the graph cutoff is appropriate for the model family and target.
- Whether the neighbor list includes the intended periodic images.
- Whether disordered or partially occupied structures were filtered, ordered, or otherwise transformed.
- Whether the structure was standardized to a primitive, conventional, or model-specific cell consistently across the dataset.
Small changes in graph construction can change predictions. For benchmarking, record the MatGL version, model name, graph converter settings, cutoff, and preprocessing code.
Pretrained Models
Pretrained MatGL models can provide fast screening estimates or initial relaxations. They are most defensible when the query structures resemble the training data and the output is used as a candidate-ranking or preconditioning signal.
Treat model metadata as part of the scientific input:
- Model identifier and checkpoint version.
- Training dataset, if documented.
- Element coverage.
- Target definition and units.
- Whether energies are absolute, per-atom, formation-like, corrected, or referenced to a particular convention.
- Whether forces and stresses were included in training.
- Known benchmark set and reported errors.
[EXPERT REVIEW NEEDED] Public model names, default checkpoints, and loader APIs can change across MatGL releases. Pin versions and save the resolved model metadata with every production run.
M3GNet, CHGNet, and Related Workflows
M3GNet-style models commonly use graph representations to predict energy, forces, stresses, and sometimes related materials properties for periodic structures. CHGNet-style workflows also use graph neural networks for materials, with charge-informed representations and pretrained potentials in adjacent tooling. These models are related in purpose but not interchangeable: training data, target definitions, graph construction, element coverage, and stress conventions can differ.
When comparing MatGL, CHGNet-style, MACE-style, and classical potentials:
- Compare on the same structures and target definitions.
- Use the same DFT reference settings when possible.
- Separate energy, force, stress, relaxation, and downstream-property metrics.
- Inspect failure cases by chemistry, coordination, volume, and structural motif.
- Avoid calling a model "universal" without stating the validation domain.
Key Workflows
Workflow 1: Pretrained Inference
Use pretrained inference for rapid triage, sanity checks, or baseline predictions.
- Load structures with pymatgen and validate species, lattice, occupancies, and units.
- Load the intended MatGL pretrained model and record the exact model identifier.
- Run predictions on a small known reference set before processing a full dataset.
- Check output units and target definitions.
- Compare a sample of predictions against DFT, experiment, or trusted literature values.
- Save inputs, model metadata, predictions, and environment information.
Minimal example pattern:
import matgl
from pymatgen.core import Structure
structure = Structure.from_file("POSCAR")
model = matgl.load_model("M3GNet-MP-2021.2.8-PES") # verify name for your MatGL version
prediction = model.predict_structure(structure)
print(prediction)
Before adapting this pattern, verify the current MatGL API and whether the loaded model expects a structure, graph, state attributes, or an ASE calculator wrapper. [EXPERT REVIEW NEEDED]
Workflow 2: Structure Relaxation With Learned Potentials
Use MatGL relaxations when screening many candidates, pre-relaxing structures before DFT, or comparing learned-potential geometries against DFT references.
Recommended protocol:
- Start from well-defined structures with valid lattice vectors and periodic boundary conditions.
- Filter unsupported elements, partial occupancies, and obviously invalid geometries.
- Run a short test relaxation on representative structures.
- Track energy, force, stress, volume, and symmetry changes.
- Compare final structures against DFT relaxations for a chemically diverse subset.
- Re-run suspicious relaxations with stricter settings or DFT.
Important diagnostics:
- Large volume collapse or expansion.
- Abrupt coordination changes.
- Unphysical short bonds after relaxation.
- Stress sign or unit inconsistencies.
- Relaxed structures that leave the intended phase, composition, or coordination environment.
- Systematic bias by chemistry or oxidation state.
For publication-quality workflows, learned-potential relaxations should be labeled as such and validated against the DFT setup used for downstream conclusions.
Workflow 3: Custom Dataset Preparation
MatGL fine-tuning and training require stricter dataset hygiene than one-off inference.
Each record should preserve:
- Structure in a reproducible format.
- Composition, chemical system, formula, and source identifier.
- Energy target with units and reference convention.
- Forces with units and atom ordering.
- Stress tensor with units and sign convention.
- Property labels, task definitions, and uncertainty if available.
- DFT code, functional, pseudopotentials, cutoffs, k-point density, smearing, convergence thresholds, and relaxation state.
- Provenance fields linking back to database entries, workflow IDs, or calculation directories.
Before training:
- Deduplicate structures with a structure-matching method appropriate for the chemistry.
- Split by chemical system, structure family, time, or source when testing extrapolation.
- Keep polymorphs distinct when their target values differ.
- Remove failed or unconverged DFT calculations unless explicitly modeling failure states.
- Check that train, validation, and test sets do not share near-duplicate structures.
Random splits are often too optimistic for materials datasets because related compositions, prototypes, or relaxation trajectories can leak across splits.
Workflow 4: Fine-Tuning and Transfer Learning
Use fine-tuning when a pretrained model is close to the target domain but systematically biased for a project-specific chemistry, functional, pressure range, defect class, or property definition.
Fine-tuning checklist:
- Start with a documented pretrained checkpoint.
- Freeze or unfreeze model components deliberately.
- Use a validation split that reflects the intended deployment domain.
- Tune learning rates conservatively; small datasets overfit quickly.
- Monitor energy, force, stress, and property losses separately.
- Compare against a non-fine-tuned baseline and a simple descriptor-based baseline.
- Retain the original test set if claiming transfer improvement.
- Save all training configuration, data split files, checkpoints, and environment metadata.
When fine-tuning on forces and stresses, confirm that every structure has consistent atom ordering, cell units, force units, and stress conventions. A single silent conversion error can dominate training behavior.
Workflow 5: Validation
Validate MatGL workflows at the level of the scientific claim.
For property prediction:
- Report MAE/RMSE and residual distributions by chemistry, structure family, and target range.
- Include parity plots, calibration checks if uncertainty is available, and high-error outlier inspection.
- Compare against baseline descriptors, simple regressors, and other pretrained models where appropriate.
For learned potentials:
- Validate energies, forces, and stresses separately.
- Compare relaxed structures to DFT relaxations.
- Test equation-of-state curves, defect formation trends, surface energies, phonon stability, or MD stability when relevant.
- Use short NVE or thermostat-sensitivity checks before trusting MD trajectories.
For high-throughput screening:
- Recompute top candidates and uncertain regions with DFT.
- Track which predictions came from pretrained inference, fine-tuned models, and DFT.
- Avoid mixing corrected DFT energies and raw model predictions without explicit reference alignment.
Common Failure Modes
| Failure mode | Symptom | Mechanical check |
|---|---|---|
| Pretrained model outside domain | Confident-looking predictions for unsupported chemistry | Check element coverage, training data, and nearest known compositions |
| Unit mismatch | Energies, forces, or stresses off by large factors | Record and test all unit conversions on reference examples |
| Stress convention mismatch | Relaxation expands when it should compress, or vice versa | Confirm tensor order, sign convention, and pressure units |
| Broken periodic graph construction | Missing neighbors, isolated atoms, or unrealistic coordination | Inspect neighbor counts and periodic image offsets |
| Duplicate leakage | Excellent test metrics but poor external performance | Run structure matching and split by chemistry/prototype |
| Overfit fine-tuning | Validation improves briefly, then degrades or fails out-of-domain | Use small learning rates, early stopping, and external tests |
| Unsupported elements | Loader, graph builder, or embedding lookup fails | Pre-filter compositions and log excluded structures |
| Treating predictions as DFT-quality | Screening claims do not survive recomputation | Recompute representative and top-ranked candidates with DFT |
| Missing model metadata | Results cannot be reproduced later | Save model ID, checkpoint, package versions, and code commit |
| Wrong target interpretation | Formation energy, total energy, and property labels mixed | Audit target definitions before training or ranking |
Best Practices
- Pin MatGL, pymatgen, DGL, PyTorch, and CUDA versions for production runs.
- Store train/validation/test split files as explicit artifacts.
- Use pymatgen or ASE readers consistently; do not mix silently converted structures without checking.
- Validate on chemically meaningful held-out sets, not only random splits.
- Log excluded structures and unsupported elements.
- Keep DFT reference settings attached to every training and validation record.
- Use scientific visualization to inspect residuals, outliers, relaxation paths, and chemical coverage.
- Use high-throughput DFT to confirm top candidates, boundary cases, and model disagreement regions.
- Treat pretrained uncertainty as unavailable unless the model and workflow explicitly provide calibrated uncertainty.
Integration with Other Skills
- crystal-property-gnn: Crystal graph construction, periodic materials targets, and dataset splitting.
- molecular-property-gnn: Related graph-learning concepts for molecular property prediction.
- universal-potentials: Deployment and validation expectations for pretrained interatomic potentials.
- fine-tuning-mlp: Model adaptation strategies for domain-specific datasets.
- mlp-validation: Energy, force, stress, relaxation, and MD validation protocols.
- mace-training: Comparison point for equivariant learned potentials and dataset preparation.
- active-learning-mlp: Selecting DFT queries to improve model coverage.
- materials-featurization: Descriptor baselines and feature-audit practices.
- pymatgen-analysis: Structure handling, transformations, parsing, and structure matching.
- materials-databases-access: Database-derived structures, labels, and provenance.
- high-throughput-dft: DFT recomputation for screening validation.
- dft-convergence: Reference-quality DFT settings for validation datasets.
- scientific-visualization: Parity plots, residuals, coverage maps, and relaxation diagnostics.
- reproducibility-workflow: Environment pinning, provenance tracking, and artifact management.
Key References
- Chen, C. and Ong, S. P. "A universal graph deep learning interatomic potential for the periodic table." Nature Computational Science 2, 718-728 (2022).
- Chen, C. et al. "Graph Networks as a Universal Machine Learning Framework for Molecules and Crystals." Chemistry of Materials 31, 3564-3572 (2019).
- Deng, B. et al. "CHGNet as a pretrained universal neural network potential for charge-informed atomistic modelling." Nature Machine Intelligence 5, 1031-1041 (2023).
- Xie, T. and Grossman, J. C. "Crystal Graph Convolutional Neural Networks for an Accurate and Interpretable Prediction of Material Properties." Physical Review Letters 120, 145301 (2018).
- Dunn, A. et al. "Benchmarking materials property prediction methods: the Matbench test set and Automatminer reference algorithm." npj Computational Materials 6, 138 (2020).
示例提示词
我想用MatGL加载预训练图神经网络模型预测这个晶体的力学性质。
所属插件
安装该插件会一并获得同领域的 35 个 Skill / MCP。
同插件的其他科研 Skill
- 主动学习构建机器学习势训练集Runs active-learning workflows for ML interatomic potentials: uncertainty-guided MD exploration, DFT oracle labeling, query strategy. Use when expanding an MLP training set.
- AiiDA计算工作流管理Covers AiiDA, a provenance-first Python workflow engine for computational materials science: calculation input generation, remote submission. Use when orchestrating reproducible DFT/MD campaigns.
- ASE原子模拟环境Covers the Atomic Simulation Environment (ASE) as an atomistic workflow hub: Atoms objects, calculators, optimizers, trajectories. Use when scripting or converting structures across DFT/MD codes.
- 粗粒化分子动力学模拟Covers coarse-grained molecular dynamics: mapping atomistic structures to CG beads, parameterizing Martini/IBI/force-matching force fields. Use when atomistic timescales are too short.
- CP2K第一性原理分子动力学Covers end-to-end DFT, AIMD, and atomistic workflows with CP2K using the Gaussian-and-plane-waves method: input construction, convergence testing. Use for CP2K-based simulations.
- 扩散模型生成晶体结构Covers de novo crystal structure generation with score-based diffusion and flow-matching models (MatterGen, DiffCSP, CDVAE). Use when generating candidate structures, not analyzing existing ones.
- 晶体图神经网络性质预测Covers graph neural networks for crystal and periodic-material property prediction: crystal graph construction, periodic neighbor finding. Use when building GNN property predictors for crystals.
- 平面波DFT收敛性测试Covers systematic convergence testing for plane-wave DFT: cutoff energy, k-point mesh density, smearing. Use before trusting DFT energies, forces, or derived properties as converged.
- 机器学习势DFT数据集生成Covers generating DFT-labeled datasets for training ML interatomic potentials: configuration-space coverage. Use when building an MLP training dataset from scratch.
- 点缺陷第一性原理计算Covers first-principles point-defect modeling: vacancy/interstitial/antisite/substitutional construction, charge-state calculations. Use for defect thermodynamics studies.
- 第一性原理声子谱计算Covers lattice dynamics from first principles: phonon dispersion, phonon DOS. Use when computing vibrational or thermodynamic properties from DFT.
- 表面模型DFT计算Covers surface slab model construction and DFT calculation: Miller-index generation, termination selection, slab/vacuum convergence. Use for surface science and catalysis DFT studies.
- 弹性常数计算工作流Computes single-crystal and polycrystalline elastic constants from DFT or MD stress-strain data and checks mechanical stability. Use when deriving stiffness tensors or bulk/shear modulus.
- 增强采样自由能计算Covers enhanced sampling methods for atomistic MD (metadynamics, umbrella sampling. Use for rare-event or slow-transition sampling.
- 状态方程拟合Covers equation-of-state fitting from DFT/ML-potential energy-volume data: Birch-Murnaghan, Vinet, and Murnaghan forms. Use when fitting an EOS to compression data.
- 机器学习势微调迁移训练Covers fine-tuning pretrained universal ML interatomic potentials on system-specific DFT data. Use when adapting a universal MLP to a new system.
- 分子动力学自由能计算Covers quantitative free-energy calculations from MD: alchemical FEP/TI/BAR/MBAR, umbrella-sampling PMF. Use when computing thermodynamic free energies from simulation.
- GROMACS分子动力学工作流Covers end-to-end MD simulations with GROMACS: topology/.mdp construction, energy minimization, NVT/NPT equilibration. Use for GROMACS-based biomolecular or materials MD.
- 高通量DFT自动化筛选Covers automated large-scale DFT screening: workflow graphs with atomate2/jobflow/AiiDA, input-set standardization, custodian error handling. Use for high-throughput DFT screening campaigns.
- LAMMPS分子动力学工作流Covers end-to-end MD simulations with LAMMPS: input script anatomy, force-field deployment, ensemble control, equilibration. Use for LAMMPS-based classical molecular dynamics.
- MACE机器学习势训练Covers training MACE machine-learned interatomic potentials: extxyz dataset preparation, isolated-atom energies, train/val/test splitting. Use for MACE-specific MLP training workflows.
- 分子动力学轨迹后处理分析Covers quantitative post-processing of atomistic MD trajectories: loading LAMMPS/GROMACS/ASE trajectories and computing RDF, coordination numbers. Use for structural MD trajectory analysis.
- 分子动力学平衡过程设计Covers bringing an atomistic simulation from its initial configuration to a representative equilibrium state before production statistics: ensemble. Use before collecting production MD data.
- 分子动力学力场选型验证Covers selection, validation, and deployment of classical interatomic force fields for MD: physical basis and transferability limits of EAM, MEAM, Tersoff. Use when choosing a force field.
常见问题
MatGL图神经网络框架能做什么?
Covers building, applying, validating, and fine-tuning MatGL graph-neural-network models for property prediction and interatomic potentials. Use for pretrained GNN workflows via MatGL。
如何安装MatGL图神经网络框架?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「MatGL图神经网络框架」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
MatGL图神经网络框架需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
MatGL图神经网络框架经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。