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

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.py and sample_annotator.py emit 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. If sample_annotator.py/crystal_mapper.py is run with an ontology whose summary lacks the required classes (e.g. --ontology asmo), each unresolvable term is flagged in results.validation_warnings and given confidence: 0.0 rather than silently emitting an invalid term.

Script Outputs (JSON Fields)

Workflow

1. If the user provides natural-language terms, use concept_mapper.py to find matching ontology classes.
2. If the user describes crystal structure parameters, use crystal_mapper.py to map them and validate constraints.
3. For a complete sample description, use sample_annotator.py to produce full ontology annotations.
4. Review any validation warnings (e.g., lattice parameter mismatches for the crystal system).
5. Check unmapped_fields and suggested_properties for 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

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.py` validation warnings: every emitted class/property is checked against the loaded ontology summary. Terms not defined in that ontology are flagged in results.validation_warnings (and the corresponding annotation gets a validation_warning field with confidence: 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 asmo on 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_warnings is empty (or every entry is explained) — a non-empty list means an emitted class/property is not defined in the chosen ontology and was given confidence: 0.0; do not report such terms as valid annotations.
• [ ] Recorded the match_type and confidence for 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 any substring_* or description_class match, verified the matched class is actually the intended concept and not an incidental string hit.
• [ ] For crystal mappings, recorded results.effective_system and results.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 in validation_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) and results.unmapped_fields (sample) and confirmed nothing materially important was silently dropped; ran the emitted class_browser.py suggestion for any unmatched term that should have resolved.
• [ ] Reviewed results.suggested_properties and 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

Security

Input Validation

• --ontology is validated against registered ontology names in ontology_registry.json (fixed allowlist)
• --term and --terms are length-limited and used only for substring matching against pre-processed synonym tables (never interpolated into code)
• --bravais is validated against a fixed set of recognized lattice type symbols
• --space-group is validated as an integer between 1 and 230
• Lattice parameters (--a, --b, --c, --alpha, --beta, --gamma) are validated as finite positive numbers
• --sample JSON is parsed with json.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.

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.