ontology-mapper

本体映射器

目标

将真实世界的材料科学描述转换为标准化的本体注释。给定“FCC copper”之类的术语，或 {"material": "iron", "structure": "BCC", "lattice_a": 2.87} 之类的结构化数据，为任意已注册的本体生成相应的本体类和属性。

要求

• Python 3.10+
• 无外部依赖（仅使用 Python 标准库）
• 需要 ontology-explorer 的摘要 JSON 和 ontology_registry.json
• 每个本体对应的映射配置（<name>_mappings.json），用于设置本体专属的同义词和标签

需要收集的输入

输入	描述	示例
本体	注册表中的本体名称	cmso、asmo
术语	自然语言材料概念	"unit cell"、"FCC,copper,lattice"
晶系	7 种晶系之一	cubic、hexagonal
布拉菲点阵	点阵类型（符号或常用名称）	FCC、cF、BCC
空间群	空间群编号（1-230）	225
晶格参数	a、b、c 的单位为埃；alpha、beta、gamma 的单位为度	a=3.615
样品描述	包含材料属性的 JSON 字典	{"material":"copper","structure":"FCC"}

决策指南

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"

本体范围 — 晶体/样品注释仅适用于 CMSO。 crystal_mapper.py 和 sample_annotator.py 会输出晶体结构词汇（Crystalline Material、 Crystal Structure、Unit Cell、Space Group、晶格属性）。这些词汇由 CMSO 定义。ASMO 是模拟方法本体，不定义任何晶体/样品类——因此，对 ASMO 应仅使用 概念映射路径（concept_mapper.py，它会将 DFT、NPT、timestep、PBE 等术语解析为真实的 ASMO 类）。如果使用缺少所需类的本体运行 sample_annotator.py/crystal_mapper.py（例如 --ontology asmo），每个无法解析的术语都会在 results.validation_warnings 中标记，并被赋予 confidence: 0.0，而不会悄然输出无效术语。

脚本输出（JSON 字段）

脚本	主要输出
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

工作流

1. 如果用户提供自然语言术语，使用 concept_mapper.py 查找匹配的本体类。
2. 如果用户描述了晶体结构参数，使用 crystal_mapper.py 进行映射并验证约束。
3. 对于完整的样品描述，使用 sample_annotator.py 生成完整的本体注释。
4. 查看所有验证警告（例如，晶系对应的晶格参数不匹配）。
5. 检查 unmapped_fields 和 suggested_properties，确保内容完整。

对话工作流示例

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 示例

# 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

添加新本体

如需支持新本体，请在 references/ 中创建一个 <name>_mappings.json：

{
  "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": [...], ... }
}

然后在 ontology_registry.json 中该本体对应的条目里添加 "mappings_file": "myonto_mappings.json"。无需修改代码。

只有当 sample_schema、crystal_output、material_type_rules 和 annotation_routing 块中提到的每个类／属性都确实存在于该本体的摘要中时，才应包含这些块。 sample_annotator.py 会根据已加载的摘要验证输出的术语，并标记未定义的术语（results.validation_warnings，confidence: 0.0）。 例如，asmo_mappings.json 有意只包含 synonyms 和 property_synonyms，因为 ASMO 是模拟方法本体，不包含晶体／样品词汇——其概念术语（DFT、NPT、timestep、PBE）都能解析，但晶体／样品配置会输出无法解析的术语。

错误处理

错误	原因	解决方法
space_group must be between 1 and 230	空间群编号无效	使用有效的空间群编号
a must be positive	晶格参数为非正数	提供以埃为单位的正值
Unrecognized Bravais lattice '<x>'	布拉菲符号／名称不在可识别集合中	使用常见名称（FCC、BCC、HCP）或皮尔逊符号（cF、cI、hP、……）
Term exceeds maximum length of 200 characters	--term／--terms 条目过长	缩短术语
Too many terms (max 100)	提供的术语超过 100 个	拆分为较小批次
Sample must be a non-empty dict	样品数据为空或缺失	提供有效的 JSON 样品字典
Sample has too many keys (max 100)	样品字典过大	减少样品键的数量
晶格验证警告	晶格参数与晶系不一致	检查立方晶系是否满足 a=b=c 等条件
results.validation_warnings（术语）	输出的类／属性未定义于所选本体中（例如，ASMO 中的晶体术语）	使用 CMSO 进行晶体／样品标注；仅将 ASMO 用于概念映射

解读指南

• 置信度分数：1.0 = 标签完全匹配，0.9 = 同义词表匹配，0.7 = 子串匹配，0.5 = 描述匹配。注意：每个本体的同义词表会在精确标签匹配之前进行查询，因此，如果某个术语既是同义词键又是类标签（例如 space group、unit cell、atom），即使它与类标签完全一致，也会报告为 0.9 的同义词匹配——匹配到的类和 IRI 仍然正确。
• sample_annotator.py 验证警告：系统会根据已加载的本体摘要检查每个输出的类／属性。未在该本体中定义的术语会标记在 results.validation_warnings 中（相应标注还会包含 validation_warning 字段，且 confidence: 0.0）。这表示标注器检测到晶体／样品术语无法在所选本体中解析为 IRI（例如，对晶态样品运行 --ontology asmo——见下文）。
• 验证警告：表示可能存在错误（例如，为立方晶系指定 a!=b）。这些是警告，不是错误——映射仍会继续。
• 未映射字段：标注器无法识别的输入键。这些字段可能需要手动映射。
• 建议属性：可使标注更完整的其他本体属性。

验证清单

• 确认 results.validation_warnings 为空（或已解释每条内容）——列表非空意味着某个输出的类／属性未在所选本体中定义，并被赋予了 confidence: 0.0；不要将此类术语报告为有效标注。
• 记录每个概念匹配的 match_type 和 confidence，并确认所选术语符合其匹配等级（1.0 精确匹配，0.9 同义词，0.7 子字符串，0.5 描述）；对于任何 substring_* 或 description_class 匹配，请确认匹配到的类确实是预期概念，而非偶然的字符串命中。
• 对于晶体映射，记录 results.effective_system 和 results.bravais_lattice（解析后的 Pearson 符号，例如 cF／cI），并确认输入的 Bravais 晶格／空间群／晶系彼此一致（validation_warnings 中没有“空间群 N 表示 X，但指定了 Y”警告）。
• 根据 effective_system 检查晶格参数约束——确认没有“立方晶系要求 a=b”／角度为 90° 等警告，或明确说明每条警告的理由（警告仅供参考，映射仍会继续）。
• 列出 results.unmatched（概念）和 results.unmapped_fields（样本），并确认没有重要内容被悄然丢弃；对于任何本应成功解析但未匹配的术语，运行输出的 class_browser.py 建议。
• 检查 results.suggested_properties，并记录哪些缺失字段（elements、space_group、lattice_a 等）是有意省略的，哪些应在标注被视为完整之前补上。

常见陷阱与错误推断

容易采取的捷径	错误原因／正确做法
“脚本输出了标注，所以样本已经正确标注。”	输出不等于验证。若某术语不在本体中，sample_annotator.py 会先输出该术语，然后通过 validation_warning／confidence: 0.0 将其标记出来——信任输出之前，务必先查看 results.validation_warnings。
“我会用 --ontology asmo 标注这个晶体样本。”	ASMO 是一种模拟方法本体，不包含晶体／样本词汇；所有晶体术语的 confidence 都会是 0.0。晶体／样本标注请使用 CMSO；ASMO 仅用于概念映射路径。
“术语匹配上了，所以映射的置信度很高。”	匹配结果可能是 0.7 的子字符串匹配或 0.5 的描述匹配（例如无关标签中的偶然子字符串）。请检查 confidence／match_type；低于精确匹配／同义词匹配的结果都应视为待核实的候选项，而非事实。
“space group 匹配到了类标签，所以这是 1.0 的精确匹配。”	每个本体的同义词表会在精确标签匹配之前进行查询，因此，同义词键术语（space group、unit cell、atom）即使与类标签完全相同，也会报告为 0.9 的同义词匹配。匹配到的类／IRI 仍然正确——不要“纠正”其置信度。
“空间群有效（1–230），所以我的晶系没有问题。”	即使空间群有效，也可能与明确给出的 --system 或 Bravais 晶格冲突。请查看 effective_system，并检查 validation_warnings 中是否有“空间群 N 表示 X，但指定了 Y”的内容。
“我的样本有 structure 字段，所以 Bravais 晶格已经解析出来了。”	在样本路径中，strict_bravais=False：自由文本结构（例如 rocksalt、perovskite）会原样传递，不进行映射，并附带警告，因此 bravais_lattice 仍为 null。请确认 results.bravais_lattice 是预期的 Pearson 符号，或提供 FCC／BCC／HCP／Pearson 符号代码。

安全

输入验证

• --ontology 会根据 ontology_registry.json 中注册的本体名称进行验证（固定允许列表）
• --term 和 --terms 有长度限制，且仅用于与预处理后的同义词表进行子串匹配（绝不会插入代码）
• --bravais 会根据一组固定的已识别晶格类型符号进行验证
• --space-group 会验证为 1 到 230 之间的整数
• 晶格参数（--a、--b、--c、--alpha、--beta、--gamma）会验证为有限的正数
• --sample JSON 会使用 json.loads() 解析，并验证为非空字典；键和值都会进行类型检查

文件访问

• 脚本从 references/ 目录读取预处理后的 JSON 文件：ontology_registry.json、*_mappings.json、*_summary.json、crystal_systems.json、element_data.json（均为只读）
• 所有脚本均不会写入文件系统；所有输出都发送到标准输出
• 无需网络访问

工具限制

• Read：用于检查脚本源代码、参考文件和本体数据
• Grep：用于在参考文件中搜索映射模式或本体术语
• Glob：用于定位参考文件和本体数据
• 值得注意的是，此技能没有 Bash 或 Write 访问权限，因此其攻击面在所有技能中最低

安全措施

• 不使用 eval()、exec() 或动态代码生成
• 不进行任何子进程调用；所有逻辑均在 Agent 调用的 Python 脚本中运行
• 不写入文件；此技能纯粹是只读和分析性的
• 最小化的工具范围（仅 Read、Grep、Glob）意味着 Agent 无法执行任意命令或修改文件系统

局限性

• 概念映射使用字符串匹配和每个本体各自的同义词表；无法理解任意自然语言
• 晶系验证仅检查基本约束（并非所有晶体学规则）
• 元素解析器可识别常见元素名称和符号，但可能无法识别不常见的拼写
• 布拉维晶格别名涵盖常见用法（FCC、BCC、HCP），但不包括所有晶体学符号变体

参考资料

• 映射模式 — 常见映射示例
• 晶系 — 晶系定义和布拉维晶格
• 元素数据 — 元素周期表数据
• CMSO 映射 — CMSO 专属同义词表和注释配置
• CMSO 指南 — CMSO 本体概览
• 本体浏览器 — 同级技能；当概念未匹配时，可使用 scripts/class_browser.py --ontology <name> --search <term> 浏览类

版本历史

日期	版本	变更
2026-06-23	1.2	根据已加载的本体验证输出术语（ASMO 晶体/样本术语现在会被标记，而非静默输出）；说明 ASMO 仅支持概念映射；明确同义词置信度与精确匹配置信度的优先级；提供独立的 class_browser 建议；强化输入验证（term/sample 大小上限、Bravais 允许列表）
2026-02-25	1.1	重构以支持多本体：将 CMSO 专属知识外置到配置中
2026-02-25	1.0	初始版本，支持 CMSO 映射