科研 Skill
材料术语本体映射
ontology-mapper
Maps materials science terms, crystal structures, and sample descriptions to standardized ontology classes with confidence scores. Use when annotating data for ontology interoperability.
SKILL.md
Ontology Mapper
Goal
Translate real-world materials science descriptions into standardized ontology annotations. Given terms like "FCC copper" or structured data like {"material": "iron", "structure": "BCC", "lattice_a": 2.87}, produce the corresponding ontology classes and properties for any registered ontology.
Requirements
- Python 3.10+
- No external dependencies (Python standard library only)
- Requires ontology-explorer's summary JSON and
ontology_registry.json - Per-ontology mapping config (
<name>_mappings.json) for ontology-specific synonyms and labels
Inputs to Gather
| Input | Description | Example |
|---|---|---|
| Ontology | Ontology name from registry | cmso, asmo |
| Term(s) | Natural-language materials concept(s) | "unit cell", "FCC,copper,lattice" |
| Crystal system | One of the 7 crystal systems | cubic, hexagonal |
| Bravais lattice | Lattice type (symbol or common name) | FCC, cF, BCC |
| Space group | Space group number (1-230) | 225 |
| Lattice parameters | a, b, c in angstroms; alpha, beta, gamma in degrees | a=3.615 |
| Sample description | JSON dict with material properties | {"material":"copper","structure":"FCC"} |
Decision Guidance
What do you need to map?
├── A concept or term to find its ontology class
│ └── concept_mapper.py --ontology <name> --term "<term>"
├── Crystal structure parameters to ontology terms
│ └── crystal_mapper.py --ontology <name> --bravais <type> --space-group <N> --a <val>
├── A full sample description to ontology annotations
│ └── sample_annotator.py --ontology <name> --sample '<json>'
└── Multiple terms at once
└── concept_mapper.py --ontology <name> --terms "term1,term2,term3"
Ontology scope — crystal/sample annotation is CMSO-only.
crystal_mapper.pyandsample_annotator.pyemit crystal-structure vocabulary (Crystalline Material, Crystal Structure, Unit Cell, Space Group, lattice properties). This vocabulary is defined by CMSO. ASMO is a simulation-methods ontology and does not define any crystal/sample classes — so for ASMO use the concept-mapping path (concept_mapper.py, which resolves terms like DFT, NPT, timestep, PBE to real ASMO classes) only. Ifsample_annotator.py/crystal_mapper.pyis run with an ontology whose summary lacks the required classes (e.g.--ontology asmo), each unresolvable term is flagged inresults.validation_warningsand givenconfidence: 0.0rather than silently emitting an invalid term.
Script Outputs (JSON Fields)
| Script | Key Outputs |
|---|---|
scripts/concept_mapper.py | results.matches, results.unmatched, results.suggestions |
scripts/crystal_mapper.py | results.ontology_classes, results.ontology_properties, results.effective_system, results.bravais_lattice, results.validation_warnings |
scripts/sample_annotator.py | results.annotations, results.sample_type, results.material_type, results.unmapped_fields, results.suggested_properties, results.validation_warnings |
Workflow
- If the user provides natural-language terms, use
concept_mapper.pyto find matching ontology classes. - If the user describes crystal structure parameters, use
crystal_mapper.pyto map them and validate constraints. - For a complete sample description, use
sample_annotator.pyto produce full ontology annotations. - Review any validation warnings (e.g., lattice parameter mismatches for the crystal system).
- Check
unmapped_fieldsandsuggested_propertiesfor completeness.
Conversational Workflow Example
User: I'm setting up an MD simulation of BCC iron with lattice parameter 2.87 angstroms.
What CMSO terms should I use?
Agent: Let me map your iron sample to CMSO ontology terms.
[Runs: sample_annotator.py --ontology cmso --sample '{"material":"iron","structure":"BCC","lattice_a":2.87,"space_group":229}' --json]
Your BCC iron simulation maps to these CMSO annotations:
- **Sample**: Atomic Scale Sample (subclass of Computational Sample)
- **Material**: Crystalline Material
- **Unit Cell**: Bravais lattice = "cI" (body-centered cubic)
- **Space Group**: number = 229 (Im-3m)
- **Lattice**: a = 2.87 Å
- **Element**: Fe
Suggested additions:
- Number of atoms in the simulation cell
- Simulation cell vectors and angles
CLI Examples
# Map a single concept
python3 skills/ontology/ontology-mapper/scripts/concept_mapper.py \
--ontology cmso --term "space group" --json
# Map multiple terms
python3 skills/ontology/ontology-mapper/scripts/concept_mapper.py \
--ontology cmso --terms "FCC,copper,lattice constant" --json
# Map crystal parameters (with ontology-specific labels)
python3 skills/ontology/ontology-mapper/scripts/crystal_mapper.py \
--ontology cmso --bravais FCC --space-group 225 --a 3.615 --json
# Map crystal parameters (generic labels, no ontology specified)
python3 skills/ontology/ontology-mapper/scripts/crystal_mapper.py \
--bravais FCC --space-group 225 --a 3.615 --json
# Annotate a full sample
python3 skills/ontology/ontology-mapper/scripts/sample_annotator.py \
--ontology cmso \
--sample '{"material":"copper","structure":"FCC","space_group":225,"lattice_a":3.615}' \
--json
Adding a New Ontology
To support a new ontology, create a <name>_mappings.json in references/:
{
"ontology": "myonto",
"synonyms": { "simulation method": "Simulation Method", ... },
"property_synonyms": { "timestep": "has timestep", ... },
"material_type_rules": { "keyword_rules": [...], "default": "Material" },
"sample_schema": { "sample_class": "Simulation", ... },
"crystal_output": { "base_classes": [...], "property_map": {...} },
"annotation_routing": { "unit_cell_indicators": [...], ... }
}
Then add "mappings_file": "myonto_mappings.json" to the ontology's entry in ontology_registry.json. No code changes needed.
Only include the sample_schema, crystal_output, material_type_rules and
annotation_routing blocks if every class/property they name actually exists in that
ontology's summary. sample_annotator.py validates emitted terms against the loaded
summary and flags any that are undefined (results.validation_warnings, confidence: 0.0).
For example, asmo_mappings.json deliberately ships only synonyms and
property_synonyms because ASMO is a simulation-methods ontology with no crystal/sample
vocabulary — its concept terms (DFT, NPT, timestep, PBE) all resolve, but a crystal/sample
config would emit unresolvable terms.
Error Handling
| Error | Cause | Resolution |
|---|---|---|
space_group must be between 1 and 230 | Invalid space group number | Use a valid space group number |
a must be positive | Non-positive lattice parameter | Provide positive values in angstroms |
Unrecognized Bravais lattice '<x>' | Bravais symbol/name not in the recognized set | Use a common name (FCC, BCC, HCP) or a Pearson symbol (cF, cI, hP, ...) |
Term exceeds maximum length of 200 characters | A --term/--terms entry is too long | Shorten the term |
Too many terms (max 100) | More than 100 terms supplied | Split into smaller batches |
Sample must be a non-empty dict | Empty or missing sample data | Provide a valid JSON sample dict |
Sample has too many keys (max 100) | Oversized sample dict | Reduce the number of sample keys |
| Validation warnings (lattice) | Lattice parameters inconsistent with crystal system | Check that a=b=c for cubic, etc. |
results.validation_warnings (terms) | Emitted class/property not defined in the chosen ontology (e.g. crystal terms for ASMO) | Use CMSO for crystal/sample annotation; use ASMO only for concept mapping |
Interpretation Guidance
- Confidence scores: 1.0 = exact label match, 0.9 = synonym-table match, 0.7 = substring match, 0.5 = description match. Note: the per-ontology synonym table is consulted before exact-label matching, so a term that is both a synonym key and a class label (e.g.
space group,unit cell,atom) is reported as a 0.9 synonym match even though it coincides exactly with a class label — the matched class and IRI are still correct. sample_annotator.pyvalidation warnings: every emitted class/property is checked against the loaded ontology summary. Terms not defined in that ontology are flagged inresults.validation_warnings(and the corresponding annotation gets avalidation_warningfield withconfidence: 0.0). This is how the annotator signals that a crystal/sample term cannot resolve to an IRI in the chosen ontology (e.g. running--ontology asmoon a crystalline sample — see below).- Validation warnings: indicate potential mistakes (e.g., specifying a!=b for cubic). These are warnings, not errors — the mapping still proceeds.
- Unmapped fields: input keys that the annotator doesn't recognize. These may need manual mapping.
- Suggested properties: additional ontology properties that would make the annotation more complete.
Verification checklist
- Confirmed
results.validation_warningsis empty (or every entry is explained) — a non-empty list means an emitted class/property is not defined in the chosen ontology and was givenconfidence: 0.0; do not report such terms as valid annotations. - Recorded the
match_typeandconfidencefor each concept match and confirmed the chosen term is acceptable for its tier (1.0 exact, 0.9 synonym, 0.7 substring, 0.5 description); for anysubstring_*ordescription_classmatch, verified the matched class is actually the intended concept and not an incidental string hit. - For crystal mappings, recorded
results.effective_systemandresults.bravais_lattice(the resolved Pearson symbol, e.g.cF/cI), and confirmed the input Bravais/space-group/system are mutually consistent (no "space group N implies X but Y was specified" warning invalidation_warnings). - Checked lattice-parameter constraints against
effective_system— confirmed no warnings such as "Cubic requires a=b" / angle-90 violations, or explicitly justified each one (warnings are advisory, the mapping still proceeds). - Listed
results.unmatched(concept) andresults.unmapped_fields(sample) and confirmed nothing materially important was silently dropped; ran the emittedclass_browser.pysuggestion for any unmatched term that should have resolved. - Reviewed
results.suggested_propertiesand recorded which missing fields (elements, space_group, lattice_a, ...) are intentionally omitted vs. should be added before the annotation is considered complete.
Common pitfalls & rationalizations
| Tempting shortcut | Why it's wrong / what to do |
|---|---|
| "The script printed annotations, so the sample is correctly annotated." | Emission is not validation. sample_annotator.py will emit a term and then flag it with validation_warning / confidence: 0.0 if it is not in the ontology — always read results.validation_warnings before trusting the output. |
"I'll annotate this crystalline sample with --ontology asmo." | ASMO is a simulation-methods ontology with no crystal/sample vocabulary; every crystal term comes back at confidence: 0.0. Use CMSO for crystal/sample annotation; use ASMO only via the concept-mapping path. |
| "It matched the term, so the mapping is high-confidence." | A match can be a 0.7 substring or 0.5 description hit (e.g. an incidental substring inside an unrelated label). Check confidence/match_type; treat anything below an exact/synonym match as a candidate to verify, not a fact. |
"space group matched a class label, so that's a 1.0 exact match." | The per-ontology synonym table is consulted before exact-label matching, so synonym-key terms (space group, unit cell, atom) report as 0.9 synonym matches even when they equal a class label. The matched class/IRI is still correct — do not "correct" the confidence. |
| "The space group is valid (1–230), so my crystal system is fine." | A valid space group can still contradict an explicitly given --system or Bravais lattice. Read effective_system and check for a "space group N implies X but Y was specified" entry in validation_warnings. |
"My sample has a structure field, so the Bravais lattice resolved." | In the sample path strict_bravais=False: free-text structures (e.g. rocksalt, perovskite) are passed through unmapped with a warning, leaving bravais_lattice null. Verify results.bravais_lattice is the expected Pearson symbol, or supply FCC/BCC/HCP/a Pearson code. |
Security
Input Validation
--ontologyis validated against registered ontology names inontology_registry.json(fixed allowlist)--termand--termsare length-limited and used only for substring matching against pre-processed synonym tables (never interpolated into code)--bravaisis validated against a fixed set of recognized lattice type symbols--space-groupis validated as an integer between 1 and 230- Lattice parameters (
--a,--b,--c,--alpha,--beta,--gamma) are validated as finite positive numbers --sampleJSON is parsed withjson.loads()and validated as a non-empty dict; keys and values are type-checked
File Access
- Scripts read pre-processed JSON files from the
references/directory:ontology_registry.json,*_mappings.json,*_summary.json,crystal_systems.json,element_data.json(all read-only) - No scripts write to the filesystem; all output goes to stdout
- No network access is required
Tool Restrictions
- Read: Used to inspect script source, reference files, and ontology data
- Grep: Used to search reference files for mapping patterns or ontology terms
- Glob: Used to locate reference files and ontology data
- Notably, this skill has no Bash or Write access, giving it the lowest attack surface of all skills
Safety Measures
- No
eval(),exec(), or dynamic code generation - No subprocess calls of any kind; all logic runs within Python scripts invoked by the agent
- No file writes; the skill is purely read-only and analytical
- Minimal tool surface (Read, Grep, Glob only) means the agent cannot execute arbitrary commands or modify the filesystem
Limitations
- Concept mapping uses string matching and a per-ontology synonym table; it does not understand arbitrary natural language
- Crystal system validation checks basic constraints only (not all crystallographic rules)
- The element resolver recognizes common element names and symbols but may miss unusual spellings
- Bravais lattice aliases cover common usage (FCC, BCC, HCP) but not all crystallographic notation variants
References
- Mapping Patterns — common mapping examples
- Crystal Systems — crystal system definitions and Bravais lattices
- Element Data — periodic table data
- CMSO Mappings — CMSO-specific synonym tables and annotation config
- CMSO Guide — CMSO ontology overview
- Ontology Explorer — sibling skill;
scripts/class_browser.py --ontology <name> --search <term>browses classes when a concept is unmatched
Version History
- v1.2.3 (2026-10-19): Validate lattice geometry and Bravais/space-group consistency with a licensed reference table and explicit evidence semantics.
| Date | Version | Changes |
|---|---|---|
| 2026-06-23 | 1.2 | Validate emitted terms against the loaded ontology (ASMO crystal/sample terms now flagged, not silently emitted); document ASMO is concept-mapping only; clarify synonym-vs-exact confidence precedence; self-contained class_browser suggestion; harden input validation (term/sample size caps, Bravais allowlist) |
| 2026-02-25 | 1.1 | Refactored for multi-ontology support: externalized CMSO-specific knowledge to config |
| 2026-02-25 | 1.0 | Initial release with CMSO mapping support |
Numerical and evidence limits
When explaining crystal results, keep the declared lattice and the space-group
requirement separate. BCC always maps to cI; FCC maps to cF. Space group 225
requires cF in its standard setting, whereas 229 requires cI. Thus BCC with
225 is a conflict, not a reason to rename BCC as cF. Use the distinct fields in
bravais_evidence and the tool's scientific_interpretation in the final answer.
standard_setting_match checks only this pair of declarations; inspect all
validation warnings too. A null match means insufficient declarations. Cubic
cell lengths and angles do not determine centering or prove atomic symmetry.
Retain these constraints during answer synthesis, not only tool selection.
The deterministic explanation renderer
can produce the final scientific text directly from trusted, input-verified
crystal_mapper JSON. Do not substitute unrestricted model prose for that text
when a grounded report is required.
Crystal checks reject or warn on impossible metrics and compare Bravais type with the canonical space-group setting from spglib 2.8.0 (reference and license bundled). This does not verify atomic positions, arbitrary setting transformations or actual symmetry operations.
示例提示词
帮我把这个样品的布拉维格子和空间群映射成本体兼容的标注。
所属插件
安装该插件会一并获得同领域的 23 个 Skill / MCP。
同插件的其他科研 Skill
- 制造解法验证与基准测试规划Plans verification and validation campaigns using manufactured solutions, canonical benchmarks. Use when an agent must prove a solver is correct before trusting results.
- 数值解空间时间收敛性分析Performs spatial/temporal convergence analysis for solution verification: observed order, Richardson extrapolation. Use when checking that a simulation result is grid/timestep independent.
- PDE数值微分格式选择Selects and applies numerical differentiation schemes for PDE/ODE discretization: finite-difference stencils. Use when choosing a spatial discretization scheme.
- 仿真结果FAIR归档打包Creates FAIR-minded reproducibility bundles for simulations: file inventories, hashes, units, engine versions. Use before publishing or archiving a simulation dataset.
- HPC作业运行诊断Diagnoses HPC runtime and scheduler problems for materials simulations: MPI/OpenMP/GPU layout, modules, scratch paths, walltime. Use when a cluster job fails, hangs, or underperforms.
- 线性方程组求解器选型Selects and configures linear solvers for Ax=b systems: direct (LU, Cholesky) versus iterative (CG, GMRES, BiCGSTAB) methods, sparsity. Use when choosing a linear solver for a simulation.
- 分子动力学分析方案规划Plans molecular dynamics post-processing for materials simulations: RDF, MSD/diffusion, VACF/VDOS, coordination numbers. Use when deciding which MD analysis to run and in what order.
- 数值模拟网格生成规划Plans and evaluates mesh generation for numerical simulations: grid resolution from physics scales, aspect ratio/skewness checks. Use when designing or auditing a simulation mesh.
- 非线性方程组求解器选型Selects and configures nonlinear solvers for root-finding, optimization, and least-squares problems: Newton, quasi-Newton, Broyden, Anderson acceleration. Use when choosing a nonlinear solver.
- 时间积分方法选择Selects and configures time-integration methods for ODE/PDE simulations: explicit Runge-Kutta, BDF, Rosenbrock. Use when choosing a time-stepping scheme for a solver.
- 偏微分方程数值稳定性分析Analyzes numerical stability for time-dependent PDE simulations: CFL/Fourier criteria, von Neumann analysis. Use when a simulation blows up or to check a scheme’s stability limits.
- 材料科学本体浏览查询Parses, navigates, and queries materials science ontology structures: class hierarchies, property domain/range lookup. Use when exploring an unfamiliar materials ontology.
- 本体标注一致性校验Validates material sample annotations against ontology constraints: class/property existence, domain/range consistency. Use before publishing ontology-annotated materials data.
- 仿真参数优化与敏感性分析Explores and optimizes simulation parameters via design of experiments, sensitivity analysis, and optimizer selection: Latin Hypercube, quasi-random. Use when calibrating simulation parameters.
- 仿真计算性能剖析Identifies computational bottlenecks, parallel scaling, and memory requirements for materials simulations: parses timing logs for dominant phases. Use when a simulation is slow or scales poorly.
- 仿真输出数据后处理Extracts, analyzes, and summarizes simulation output data: spatial fields at timesteps, time-series trends, steady-state detection. Use when turning raw simulation output into summary statistics.
- 多代码仿真故障分诊Provides first-response triage for cross-code LAMMPS/VASP/QE/MOOSE simulation failures: classifies nonconvergence, NaN/Inf. Use when a simulation crashes and the cause is unclear.
- 多任务仿真批量编排Orchestrates multi-simulation campaigns: generates parameter sweeps (grid, linspace, Latin Hypercube), tracks batch job status. Use when running and managing many related simulation jobs.
- 仿真三阶段有效性校验Validates simulations across three stages: pre-flight config checks, runtime log monitoring for NaN/Inf and residual growth. Use to catch simulation errors before, during, and after a run.
- SLURM作业脚本生成Generates correct SLURM sbatch job scripts and sanity-checks HPC resource requests: nodes, MPI/OpenMP layout, memory, GPUs, walltime. Use when writing or debugging a SLURM submission script.
- 瞬态仿真时间步策略Plans and controls time-step policies for transient simulations: CFL and physics-based stability limits, adaptive stepping. Use when setting up a time-stepping strategy for a solver.
- 计算材料工作流引擎选型Maps computational materials tasks onto workflow engines (atomate2, jobflow, AiiDA, pyiron) or a one-off script. Use when deciding how to structure a reproducible campaign or DAG.
常见问题
材料术语本体映射能做什么?
Maps materials science terms, crystal structures, and sample descriptions to standardized ontology classes with confidence scores. Use when annotating data for ontology interoperability。
如何安装材料术语本体映射?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「材料术语本体映射」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
材料术语本体映射需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
材料术语本体映射经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。