科研 Skill

材料结构特征化

materials-featurization

Covers converting structures, compositions, and trajectories into ML feature vectors: Magpie-style elemental statistics. Use when building inputs for materials ML models.

发布者 Codar安全审核通过v0.1.0更新于 2026-11-18

SKILL.md

Materials Featurization

Description

This skill covers the conversion of atomic structures, compositions, and trajectories into numerical feature vectors for physical-science ML: composition featurizers (Magpie-style elemental statistics, oxidation-state features), structure featurizers (SOAP, Coulomb matrix, Voronoi, radial distribution functions, bond orientational order), site-level featurizers with structure-level aggregation, and descriptor selection for crystals, molecules, surfaces, defects, amorphous structures, and MD trajectories. Covers matminer, pymatgen, ASE, DScribe, and RDKit. Invoke this skill when building a feature matrix for regression or classification on materials datasets, when selecting between hand-crafted descriptors and learned graph representations, or when auditing a feature pipeline for leakage, NaN patterns, or physical inconsistencies.

Domain Context

Materials featurization is the translation of atomic structures and compositions into vectors of numbers that a statistical model can process. Unlike image or text data where pixels and tokens have a natural numerical representation, materials structures have no canonical encoding: a crystal can be described by its unit cell (arbitrary choice of conventional vs. primitive cell), its composition (continuous or categorical species fractions), its local environments (per-site descriptors aggregated to structure level), or its global topology (graph connectivity). Each encoding captures different physical information and has different sensitivity to symmetry operations, cell conventions, and disorder.

Hand-crafted descriptors vs. learned representations. Composition-based descriptors (Magpie, CGCNN input) require only element symbols and fractions — cheap to compute, insensitive to structural details, and appropriate for screening or when structures are unavailable. Structure-based descriptors (SOAP, Voronoi, Coulomb matrix) use full atomic positions but are O(N²) or worse for global descriptors. Learned graph neural network representations (CGCNN, MEGNet, MatFormer) jointly learn the featurization and the regression, but require training data, are less interpretable, and cannot be used as feature vectors for arbitrary downstream models without fine-tuning. The choice between them depends on data quantity, interpretability requirements, computational budget, and whether the target property is dominated by local chemistry (SOAP is then sufficient) or long-range interactions (learned models with long-range attention are preferable).

Featurization is not neutral. The descriptor encodes assumptions about what physical information is relevant for the target property. SOAP captures local bonding environments up to a cutoff radius; it is blind to long-range electrostatics and topological features. Coulomb matrix eigenvalues capture intermolecular distances but are sensitive to the molecular geometry in ways that may not correlate with the property of interest. Magpie features average elemental properties by composition and are entirely blind to the crystal structure. Using the wrong descriptor class for a property introduces systematic prediction errors that cannot be fixed by model tuning.

Leakage is the primary failure mode in materials ML. Target leakage occurs when a feature encodes information that would not be available at prediction time — for example, including the DFT-computed band gap as a feature for predicting another DFT-computed property where the band gap is also the target or strongly correlated with it. Feature leakage occurs when preprocessing steps (scaling, imputation, feature selection) are fit on the combined train+test set rather than only the train set, making test performance optimistic. Materials datasets have additional structure: many crystals sharing a prototype differ only in lattice parameters, so a random train/test split may put near-duplicates on both sides. All of these require explicit mitigation.

Missing values and physical invalidity. Matminer featurizers can return NaN for structures where a required property is undefined — for example, OxidationStateDecorator fails on structures with ambiguous charge balance, and CrystalNNFingerprint can fail on structures with unusual coordination environments. A feature matrix with 20% NaN in a critical column that is imputed by mean produces a model that silently degrades for those structures without any warning.

When to Use This Skill

  • Building composition- or structure-based feature matrices for surrogate property models (formation energy, band gap, thermal conductivity, defect formation energy).
  • Constructing diversity metrics and coverage maps for active learning or dataset curation (see active-learning-mlp): selecting which structures to label with DFT.
  • Featurizing trajectories for per-frame property prediction, structure classification, or change-point detection in MD or active learning.
  • Auditing an inherited feature matrix for leakage, NaN patterns, duplicate structures, or descriptor inconsistencies before using it for modeling.
  • Comparing the information content of different descriptor families on a new chemical space.

When Not to Use This Skill

  • When a graph neural network trained on the same dataset is available and more accurate — learned representations from CGCNN, MEGNet, or CHGNet will typically outperform hand-crafted descriptors for the same training data if sufficient data (> 1,000 structures) is available. Use this skill when interpretability, speed, or small-data constraints favor fixed descriptors.
  • For properties requiring electron density or wavefunction information — local environment descriptors are blind to quantum chemical effects like Mott localization, charge transfer, or orbital hybridization. DFT-derived features (PDOS moments, Bader charges, orbital character) require DFT calculations and are a different class of featurizer.
  • For long-timescale dynamical properties (diffusion coefficients, viscosity, glass transition) — these require MD trajectories, not static structure features. Featurizing only the equilibrium structure for predicting dynamical properties will produce unreliable models. [EXPERT REVIEW NEEDED]
  • For molecular systems where topology matters more than geometry — RDKit fingerprints (Morgan, MACCS, topological torsion) encode graph-based connectivity and are more appropriate than SOAP or Coulomb matrices for drug-like molecules. Use RDKit for molecules with known connectivity; use DScribe for periodic systems or molecules where only coordinates are available.

Core Concepts

  • Featurizer: A function that maps a material (as a pymatgen Structure/Composition, ASE Atoms, or RDKit Mol) to a fixed-length numerical vector. Featurizers can be composition-level (require only species and fractions), site-level (one vector per atom, then aggregated), or structure-level (require full atomic positions and cell).
  • SOAP (Smooth Overlap of Atomic Positions): An atom-centered descriptor that encodes the local chemical environment within a cutoff radius r_cut using radial basis functions and spherical harmonics. Invariant to rotation, reflection, and translation. Produces a per-site vector of length n_max × (l_max+1)² × (n_species+1)×n_species/2. Averaged across sites to produce a structure-level vector. The most widely used descriptor for MLP active learning and structure similarity metrics.
  • Magpie descriptors: A set of 145 composition-level features introduced in the Materials Agnostic Platform for Informatics and Exploration (Ward et al. 2016). Each feature is a statistical aggregate (mean, std, min, max, range, mode) of an elemental property (atomic number, electronegativity, atomic radius, cohesive energy, melting point, etc.) weighted by composition. Available via matminer's ElementProperty featurizer with preset="magpie".
  • Coulomb matrix: A pairwise matrix M_ij = Z_i Z_j / |r_i - r_j| (i ≠ j), M_ii = 0.5 Z_i^2.4. Encodes all pairwise distances weighted by nuclear charges. Not invariant to atom ordering — requires eigenvalue sorting or random rotation averaging. Scales as O(N²) in system size. Suited for molecules; less practical for large crystals.
  • Sine matrix (periodic Coulomb matrix): Extension of the Coulomb matrix to periodic systems using the minimum image convention for distances. Avoids the vacuum problem of the Coulomb matrix for crystals. Implemented in DScribe.
  • Voronoi tessellation descriptors: Partitions space into Voronoi cells; each atom's cell encodes its coordination geometry. matminer's VoronoiFingerprint computes statistics of the Voronoi polyhedron (n_faces, volume, area ratios). Robust to disordered structures; less sensitive to cutoff radius than SOAP.
  • CrystalNNFingerprint: matminer featurizer that uses the CrystalNN neighbor-finding algorithm (distance + angle heuristics) to assign coordination environments and compute a fingerprint encoding the local geometry. More expensive than Voronoi but captures bond angle information. Can fail on unusual coordination environments (returns NaN).
  • Bond orientational order (BOO): Steinhardt order parameters Q_l measuring the orientational symmetry of the nearest-neighbor shell. Q_6 ≈ 0.574 for FCC, ≈ 0.510 for BCC, ≈ 0.485 for HCP. Useful for detecting crystalline vs. amorphous environments in MD trajectories. Implemented in freud and OVITO.
  • Oxidation state assignment: pymatgen's OxidationStateDecorator uses a bond-valence-based heuristic to assign formal charges to sites. Required for featurizers that encode oxidation-state-specific properties. Fails for metallic systems (cannot distribute charges) and for ambiguous mixed-valence systems. Always check the success rate before including oxidation-state features.
  • Feature leakage: A feature that inadvertently encodes the target variable or is preprocessed using target-set information. Examples: including DFT formation energy as a feature for a model predicting DFT formation energy from composition; fitting a StandardScaler on train+test data; using the target property to select the most predictive features before splitting.
  • Train/test leakage in materials datasets: Two structures that share a crystal prototype (e.g., both are rocksalt AB compounds differing only in composition) or that are related by a small structural perturbation will have nearly identical descriptor vectors. A random split assigns them to different folds, producing over-optimistic test error. Materials-aware splitting (by composition family, by crystal prototype, or by descriptor-space distance) is required for honest evaluation.

Key Workflows

Full steps for each part are in references/key-workflows/; open the one you need:

Common Failure Modes

Moved to references/common-failure-modes.md to keep this file short; read it when this part is needed.

Best Practices

  • Choose the featurizer class that matches the physical information relevant to the target property. For properties dominated by local bonding (formation energy, band gap of simple materials), SOAP or Voronoi is appropriate. For properties requiring long-range information (Madelung energy, piezoelectricity in polar materials), global descriptors or learned representations are needed. Mismatched featurizer–property pairs cannot be rescued by hyperparameter tuning.
  • Always check the NaN fraction per feature before any preprocessing. A feature with 25% NaN that is imputed by median creates a bimodal distribution: real values and imputed values. This is tolerable only if the imputed rows are physically similar to the median row. For structure featurizers that fail on unusual environments, NaN is a diagnostic, not noise — it tells you the featurizer does not understand the structure.
  • Fit all preprocessing (imputation, scaling, feature selection) exclusively on the training set. Every .fit() call that uses test data inflates test performance. Use sklearn Pipeline and GridSearchCV with fit_transform(X_train) and transform(X_test) to enforce this.
  • Report SOAP descriptor hyperparameters (r_cut, n_max, l_max, sigma, average) as part of the model card. A SOAP vector computed with r_cut=5.0 is not the same feature as r_cut=6.0; models trained on one are not transferable to the other. Include these in the feature_metadata.json (see reproducibility-workflow).
  • Standardize cell conventions before structure featurization. Always apply either get_primitive_standard_structure() or get_conventional_standard_structure() uniformly across the entire dataset. Mixing conventions produces multiple descriptor vectors for the same crystal.
  • Use prototype-aware or descriptor-space splitting for honest model evaluation on materials datasets. Random splitting overestimates generalization to new chemical spaces because it leaks correlated structures. The harder but more informative splits reveal whether the model extrapolates to new crystal prototypes or new composition families.
  • Document and version the exact set of feature names alongside the model checkpoint. Feature names can change silently when matminer or pymatgen versions change their featurizer output ordering or add/remove features. See reproducibility-workflow for how to record this.
  • For oxidation-state features, always validate the assignment success rate before including them. An oxide-specific featurizer (e.g., cation field strength, anion charge) trained on a mixed dataset where only 60% of structures have valid oxidation states will learn from an imputed majority that is not physically meaningful.

Integration with Other Skills

  • reproducibility-workflow: The featurizer hyperparameters (r_cut, n_max, l_max, sigma, preset name), the exact feature names output by each featurizer version, and the preprocessing pipeline parameters must all be recorded as provenance metadata. save_feature_metadata in Workflow 4 is the featurization layer of the general reproducibility framework described there.
  • dft-dataset-generation: Structural descriptors (SOAP, Voronoi) drive the FPS diversity filtering in that skill's Workflow 1. The descriptor hyperparameters used for FPS must be consistent with those used for the downstream surrogate model — computing FPS with r_cut=5.0 and training a surrogate with r_cut=6.0 may include structurally redundant training data. Use the same descriptor for both steps.
  • dft-convergence: DFT-derived features (band gap, formation energy, bulk modulus from DFT) are target variables, not input features — do not use them as features for models predicting those same quantities. However, DFT-derived structural relaxation outputs (lattice parameters, bond lengths) are valid input features for models predicting other DFT quantities computed at the same convergence level.
  • vasp-workflow: When VASP outputs (relaxed structures, OUTCAR-derived properties) are used as the basis for featurization, the pymatgen parser must be consistent with the VASP settings. Structures relaxed with different ENCUT or POTCAR may have systematically different bond lengths and volumes, which translate directly into different descriptor vectors.
  • quantum-espresso: QE-relaxed structures use Bohr or Angstrom depending on the output format; ASE handles the conversion, but verify that atoms.cell and atoms.positions are in Angstrom before passing to DScribe or matminer. A cell in Bohr produces descriptor vectors that are shifted in r-space by a factor of 1.89 relative to the expected range.
  • mlp-validation: SOAP descriptors are used in that skill's extrapolation detection workflow to compute distances between production MD frames and the training set. The descriptor parameters (r_cut, n_max, l_max) must be identical between the active learning FPS step, the MLP validation step, and any downstream surrogate — use a single descriptor_config.json shared across all pipelines.
  • active-learning-mlp: Descriptor-space diversity filtering (FPS with SOAP) is the primary redundancy-reduction step in that skill's Workflow 1. The SOAP cutoff must be at or above the second coordination shell to capture the full local environment that the MLP sees. Using a shorter cutoff for FPS than for the MLP training descriptor is inconsistent and may select redundant structures.
  • surrogate-validation: Surrogate model validation requires knowing which test structures are interpolation vs. extrapolation cases. The descriptor-space distances computed here (SOAP Euclidean distance to the nearest training structure) quantify extrapolation for any fixed-descriptor surrogate model. A test structure with no training neighbor within distance δ is an extrapolation candidate regardless of the model's predicted uncertainty.
  • gaussian-process-materials: Gaussian processes use the descriptor as the kernel input — the kernel function is the inner product or distance in descriptor space. The choice of descriptor defines the GP's inductive bias. SOAP-based kernels (dot-product kernel on normalized SOAP vectors) are a physically motivated choice for local property prediction; Matminer features with an RBF kernel are appropriate for composition-based screening where interpretability matters.
  • crystal-property-gnn: Graph neural networks jointly learn the featurization and the regression; they do not use a fixed descriptor. However, the same train/test leakage considerations apply: prototype-aware or composition-aware splits are required for honest evaluation. Fixed descriptors (SOAP, Voronoi) are useful as baselines against which GNN accuracy should be compared before committing to the more complex model.
  • molecular-property-gnn: For molecular systems, the featurization choice is between graph-based (atom-bond graph, as in GNNs), topology-based (Morgan/ECFP fingerprints from RDKit), geometry-based (SOAP, Coulomb matrix), or learned (e.g., ChemBERTa from SMILES). RDKit fingerprints are the most widely used fixed descriptors for drug-like molecules; SOAP is preferred for conformer-sensitive properties where 3D geometry matters.

Key References

  1. Ward, L., et al. (2016). A general-purpose machine learning framework for predicting properties of inorganic materials. npj Computational Materials, 2, 16028. https://doi.org/10.1038/npjcompumats.2016.28
  2. Bartók, A. P., et al. (2013). On representing chemical environments. Physical Review B, 87(18), 184115. https://doi.org/10.1103/PhysRevB.87.184115
  3. Himanen, L., et al. (2020). DScribe: Library of descriptors for machine learning in materials science. Computer Physics Communications, 247, 106949. https://doi.org/10.1016/j.cpc.2019.106949
  4. Dunn, A., et al. (2020). Benchmarking materials property prediction methods: the Matbench test set and Automatminer reference algorithm. npj Computational Materials, 6, 138. https://doi.org/10.1038/s41524-020-00406-3
  5. De, S., et al. (2016). Comparing molecules and solids across structural and alchemical space. Physical Chemistry Chemical Physics, 18(20), 13754–13769. https://doi.org/10.1039/C6CP00415F

示例提示词

我想把这批晶体结构转换成SOAP描述符用于后续机器学习建模。

所属插件

材料表征、性能与材料信息学面向实验与数据驱动的材料研究:XRD/电镜/谱学/热分析/力学测试等表征,合成与加工,电化学与半导体表征,相场、CALPHAD 与连续介质力学,材料数据库、特征工程、贝叶斯优化与主动学习,选材与生命周期评价。

安装该插件会一并获得同领域的 42 个 Skill / MCP。

同插件的其他科研 Skill

常见问题

材料结构特征化能做什么?

Covers converting structures, compositions, and trajectories into ML feature vectors: Magpie-style elemental statistics. Use when building inputs for materials ML models。

如何安装材料结构特征化?

在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「材料结构特征化」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。

材料结构特征化需要哪些权限?

该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。

材料结构特征化经过官方审核吗?

是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。