heshamfs/materials-simulation-skills/ontology-explorer

Ontology Explorer

Goal

Enable an agent to understand, navigate, and query the structure of materials science ontologies without loading verbose OWL/XML files directly. Provides fast access to class hierarchies, property definitions, and domain-range relationships through pre-processed JSON summaries.

Requirements

• Python 3.10+
• No external dependencies (Python standard library only)
• Internet access required only for owl_parser.py and ontology_summarizer.py when fetching remote OWL files

Inputs to Gather

Decision Guidance

What do you need?
├── Understand overall ontology structure
│   └── class_browser.py --ontology cmso --list-roots
├── Inspect a specific class
│   └── class_browser.py --ontology cmso --class <name>
├── Find properties for a class
│   └── property_lookup.py --ontology cmso --class <name>
├── Look up a specific property
│   └── property_lookup.py --ontology cmso --property <name>
├── Search for a concept
│   ├── class_browser.py --ontology cmso --search <term>
│   └── property_lookup.py --ontology cmso --search <term>
├── Parse a new/updated OWL file
│   └── owl_parser.py --source <path-or-url>
└── Generate/refresh a summary JSON
    └── ontology_summarizer.py --source <url> --output <path>

Script Outputs (JSON Fields)

Workflow

1. Identify which ontology the user is working with (default: CMSO).
2. Use class_browser.py --list-roots to see the top-level concepts.
3. Drill into specific classes with class_browser.py --class <name> to see hierarchy, children, and applicable properties.
4. Look up individual properties with property_lookup.py --property <name>.
5. If the user mentions a concept but not its ontology name, use --search to find matching classes or properties.
6. For a new or updated ontology, run owl_parser.py to parse the raw OWL, then ontology_summarizer.py to generate a summary JSON.

Conversational Workflow Example

User: I have an FCC copper simulation. What CMSO classes should I use to describe it?
 
Agent: Let me explore the CMSO ontology to find the relevant classes. I'll run
a few targeted searches and property lookups (the answer below is synthesized
from several commands, per the Workflow section).
 
[Runs: class_browser.py --ontology cmso --search "crystal" --json]
  → Crystalline Material, Crystal Structure (among others)
[Runs: class_browser.py --ontology cmso --search "sample" --json]
  → Computational Sample, Atomic Scale Sample
[Runs: class_browser.py --ontology cmso --search "unit cell" --json]
  → Unit Cell
[Runs: class_browser.py --ontology cmso --search "space group" --json]
  → Space Group
[Runs: class_browser.py --ontology cmso --search "element" --json]
  → Chemical Element
[Runs: property_lookup.py --ontology cmso --property "has material" --json]
  → domain Computational Sample → range Material
[Runs: property_lookup.py --ontology cmso --property "has structure" --json]
  → domain Material → range Structure
[Runs: property_lookup.py --ontology cmso --property "has unit cell" --json]
  → domain Crystal Structure → range Unit Cell
 
For an FCC copper simulation, the relevant CMSO classes are:
 
- **Computational Sample** → **Atomic Scale Sample**: your simulation is an atomic-scale sample
- **Material** → **Crystalline Material**: copper is crystalline
- **Crystal Structure**: describes the FCC arrangement
- **Unit Cell**: the repeating FCC unit cell (a=b=c=3.615 Å, α=β=γ=90°)
- **Space Group**: FCC copper is space group 225 (Fm-3m)
- **Chemical Element**: Cu
 
The key relationship chain (from the property domains/ranges above):
  Computational Sample → has material → Material → has structure → Structure
  → (Crystal Structure) → has unit cell → Unit Cell
 
Shall I look up the specific properties for any of these classes?

CLI Examples

# List root classes in CMSO
python3 skills/ontology/ontology-explorer/scripts/class_browser.py \
  --ontology cmso --list-roots --json
 
# Inspect the Material class hierarchy
python3 skills/ontology/ontology-explorer/scripts/class_browser.py \
  --ontology cmso --class Material --json
 
# Search for crystal-related classes
python3 skills/ontology/ontology-explorer/scripts/class_browser.py \
  --ontology cmso --search crystal --json
 
# Find all properties for UnitCell
python3 skills/ontology/ontology-explorer/scripts/property_lookup.py \
  --ontology cmso --class UnitCell --json
 
# Look up a specific property
python3 skills/ontology/ontology-explorer/scripts/property_lookup.py \
  --ontology cmso --property "has space group" --json
 
# Parse a remote OWL file
python3 skills/ontology/ontology-explorer/scripts/owl_parser.py \
  --source https://raw.githubusercontent.com/OCDO/cmso/main/cmso.owl --json
 
# Generate a summary JSON from an OWL file
python3 skills/ontology/ontology-explorer/scripts/ontology_summarizer.py \
  --source https://raw.githubusercontent.com/OCDO/cmso/main/cmso.owl \
  --output summary.json --json

Error Handling

Interpretation Guidance

• Class hierarchy: root classes are the broadest concepts; leaf classes are the most specific. A class inherits all properties from its ancestors.
• Object properties: show how classes relate to each other (domain → range). A property with domain UnitCell and range Basis means a unit cell has a basis.
• Data properties: show what literal values a class carries. A property with domain ChemicalElement and range xsd:string means an element has a string-valued attribute.
• Union domains: a property can apply to more than one class. When it does, the domain is shown as the classes joined with a pipe, e.g. A | B. (The bundled CMSO/ASMO summaries currently contain no union-domain properties.)
• Search relevance: 1.0 = label match, 0.5 = description match only.

Verification checklist

Before presenting any class, property, or relationship as fact, confirm and record:

• [ ] Resolved the target via class_browser.py --class <name> (or property_lookup.py) and recorded the exact canonical label returned in results.class_info.label / results.property_info.name — do not quote a name the agent typed; quote the label the tool resolved (e.g. UnitCell → Unit Cell).
• [ ] For every relationship chain stated, cited the actual domain and range from a property_lookup.py --property <name> call (recorded results.property_info.domain and .range), rather than inferring the link from class names.
• [ ] When a property's domain contains a pipe (A | B), reported it as a union (applies to each listed class) and confirmed the class in question matches one normalized member — did not silently assume single-class domain.
• [ ] For --search results, recorded each match's relevance and stated whether it was a label match (1.0) or description-only match (0.5); did not present a 0.5 description hit as a confirmed term match.
• [ ] Identified the ontology by its registry key (cmso or asmo) and confirmed it exists in references/ontology_registry.json; did not query an unregistered ontology or conflate CMSO and ASMO terms.
• [ ] When relying on a generated/refreshed summary, recorded its metadata.source_url and metadata.generated_at and the statistics (num_classes, num_object_properties, num_data_properties) so the result is traceable to a specific OWL source.
• [ ] Treated absent parents, descriptions, or domain/range as missing data (not as "no such relationship"), since the parser extracts only simple rdfs:subClassOf and declared domains/ranges and does no reasoning.

Common pitfalls & rationalizations

Security

Input Validation

• --ontology is validated against registered ontology names in ontology_registry.json (fixed allowlist)
• --class and --property names are validated against a safe-character pattern to prevent injection
• --search terms are length-limited and used only for substring matching against pre-processed labels (never interpolated into queries or code)
• --source for owl_parser.py accepts file paths or URLs; URLs are validated against https:// scheme only