科研 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.
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_cutusing radial basis functions and spherical harmonics. Invariant to rotation, reflection, and translation. Produces a per-site vector of lengthn_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
ElementPropertyfeaturizer withpreset="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
VoronoiFingerprintcomputes 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
OxidationStateDecoratoruses 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:
- Workflow 1: Composition featurizers — Magpie-style descriptors with matminer —
references/key-workflows/01-workflow-1-composition-featurizers-magpie-style.md: Generate composition-level feature matrices. These require only chemical formulas; no structural information is needed. The fastest featurizer class and the only option when structures are unavailable. - Workflow 2: Structure featurizers — SOAP descriptors with DScribe —
references/key-workflows/02-workflow-2-structure-featurizers-soap-descriptor.md: SOAP is the workhorse descriptor for structure-based materials ML. Used for surrogate models, FPS-based diversity filtering, and MLP active learning. - Workflow 3: Structure-level featurization with matminer —
references/key-workflows/03-workflow-3-structure-level-featurization-with-ma.md: matminer provides a large library of site-level and structure-level featurizers. Site-level featurizers produce per-atom features that must be aggregated to structure-level. - Workflow 4: Feature matrix assembly, preprocessing, and NaN handling —
references/key-workflows/04-workflow-4-feature-matrix-assembly-preprocessing.md: Combining multiple featurizers, scaling, and preparing the feature matrix for a downstream model. - Workflow 5: Train/test splitting and leakage prevention —
references/key-workflows/05-workflow-5-train-test-splitting-and-leakage-prev.md: Materials datasets have structural redundancy that makes random splits misleading. Use materials-aware splits. - Workflow 6: Featurization for trajectories, surfaces, and amorphous structures —
references/key-workflows/06-workflow-6-featurization-for-trajectories-surfac.md: Applying featurizers consistently to non-equilibrium structures, MD trajectories, and disordered systems.
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 sklearnPipelineandGridSearchCVwithfit_transform(X_train)andtransform(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(seereproducibility-workflow). - Standardize cell conventions before structure featurization. Always apply either
get_primitive_standard_structure()orget_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-workflowfor 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_metadatain 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.cellandatoms.positionsare 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.jsonshared 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
- 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
- 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
- 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
- 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
- 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描述符用于后续机器学习建模。
所属插件
安装该插件会一并获得同领域的 42 个 Skill / MCP。
同插件的其他科研 Skill
- 贝叶斯优化材料发现Covers Bayesian optimization for materials and chemistry design: surrogate models, acquisition functions, batch/constrained BO. Use when planning sample-efficient experiments or simulations.
- CALPHAD热力学计算工作流Covers CALPHAD computational thermodynamics: database selection, equilibrium/metastable calculations, binary/ternary phase diagrams. Use when predicting phase stability or solidification paths.
- 材料第一性原理与分子动力学模拟Routes first-principles and classical materials simulation (DFT, MD, ML potentials) to the right specialized workflow. Use as an entry point for any simulation-based materials task.
- 蠕变力学建模与验证Selects, calibrates, and validates creep deformation and rupture models under sustained thermomechanical load, covering rate prediction. Use when assessing long-term high-temperature components.
- 晶体塑性有限元建模Covers crystal plasticity and CPFE modeling of metals: slip systems for FCC/BCC/HCP, Schmid factors. Use when simulating texture- and orientation-dependent plastic deformation.
- 衍射结构表征Covers diffraction-based structure characterization (XRD, neutron, SAED): space group determination, Rietveld refinement, phase identification. Use for any diffraction-pattern analysis technique.
- EBSD织构分析Analyzes EBSD orientation maps for grain size, misorientation, phase, and texture, with pole figures and twin-boundary identification. Use for electron backscatter diffraction workflows.
- 电化学性能测试分析Covers electrochemical characterization: cyclic voltammetry, battery cycling analysis, EIS. Use for electrochemistry-specific data analysis distinct from general materials characterization.
- 金属疲劳寿命评估Builds, calibrates, and validates fatigue assessments for metals and components: stress-life, strain-life, multiaxial critical-plane. Use when predicting fatigue life or crack growth.
- 多物理场有限元建模Covers finite element modeling for coupled materials, mechanics, and transport problems: weak-form construction, boundary conditions, mesh choice. Use for multiphysics FEM simulations.
- 连续尺度有限元力学建模Covers continuum-scale mechanical, thermal, and multiphysics simulation with Abaqus/COMSOL conventions, mesh generation. Use for macroscale FEM consuming measured or computed material properties.
- 断裂力学评估与建模Selects, constructs, and validates fracture-mechanics assessments: LEFM checks, elastic-plastic fracture mechanics. Use when assessing cracked materials or components.
- 高斯过程材料回归建模Covers Gaussian process regression for materials and chemistry datasets: descriptor selection, kernel design. Use when a probabilistic surrogate model with uncertainty is needed.
- 自驱动实验室闭环材料发现Covers combinatorial synthesis, robotic experimentation. Use for autonomous or robotics-driven experimental campaigns, a less standardized domain.
- 材料数据库可复现访问Covers reproducible API access to materials databases (Materials Project, AFLOW, OQMD, NOMAD, COD, ICSD-style sources): authentication. Use when programmatically querying these databases.
- 材料数据库跨库查询Covers querying public materials databases beyond Materials Project: AFLOW, OQMD, NOMAD, JARVIS. Use when pulling or comparing data from these live, API-integrated resources.
- 材料数据标准与互操作Covers data interoperability standards for materials science: CIF crystal files, the OPTIMADE query API. Use when structuring or exchanging materials data between tools.
- 材料科学图表绘制规范Covers publication-quality figure conventions for materials science plots: phase diagrams, pole figures, stress-strain curves. Use when the deliverable is a figure, not just an analysis result.
- 材料信息学性质预测Covers ML for materials property prediction and generative design: descriptor-based models, crystal GNNs (CGCNN/MEGNet-class). Use for materials informatics distinct from interatomic potentials.
- 材料生命周期评估Covers life-cycle assessment for materials and manufacturing routes: goal/scope definition, functional units, inventory construction. Use for environmental-impact studies of materials.
- 材料科学文献检索Covers formulating literature search queries for materials science questions and synthesizing/citing results responsibly. Requires a web search tool; it cannot substitute for one.
- 工程材料选型设计Selects engineering materials via material indices and Ashby charts, ranking candidates by performance per cost or mass. Use when picking a material class for a design constraint.
- 材料统计方法与实验设计Covers statistics shared across materials characterization and simulation: design of experiments. Use for cross-cutting statistical treatment of materials data.
- 材料结构与成分核心分析Covers core structure and composition analysis: reading/writing crystal structures, composition handling, symmetry analysis, phase diagrams. Use as a general-purpose structure-analysis toolkit.
常见问题
材料结构特征化能做什么?
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 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。