IMAS Standard Names

Grammar library for IMAS Standard Names — a controlled vocabulary for fusion data variables.

This repository owns the grammar: the controlled vocabulary, the parser and renderer, catalog validation, and the documentation site. AI-assistant tools over standard names are served by imas-codex.

Quick Start

pip install imas-standard-names

Python Library

from imas_standard_names import StandardNameIR, compose, parse
from imas_standard_names.repository import StandardNameCatalog

catalog = StandardNameCatalog()
entry = catalog.get("electron_temperature")
print(f"{entry.name}: {entry.unit} — {entry.description}")

# Strict parsing is the validity oracle for both flat names and recursive
# operator expressions.
result = parse("square_of_inverse_of_pressure", strict=True)
assert isinstance(result.ir, StandardNameIR)
assert [operator.op for operator in result.ir.operators] == ["square", "inverse"]
assert compose(result.ir) == "square_of_inverse_of_pressure"

Installation

The tools and catalog are distributed separately:

Package	Purpose
imas-standard-names	Grammar library, parser, validation
imas-standard-names-catalog	Standard names catalog (YAML + SQLite)

Basic Installation

# Tools + catalog (recommended)
pip install imas-standard-names[catalog]

# Tools only
pip install imas-standard-names

Catalog Options

The catalog can be accessed in several ways:

# Option 1: Install catalog package (recommended)
pip install imas-standard-names-catalog

# Option 2: Download pre-built database
wget https://github.com/iterorganization/imas-standard-names-catalog/releases/latest/download/catalog.db
export STANDARD_NAMES_CATALOG_DB=./catalog.db

# Option 3: Clone catalog repository (for development)
git clone https://github.com/iterorganization/imas-standard-names-catalog.git
export STANDARD_NAMES_CATALOG_ROOT=./imas-standard-names-catalog/standard_names

Development Setup

git clone https://github.com/iterorganization/imas-standard-names.git
cd imas-standard-names
uv sync

Architecture

This project uses a two-repository architecture:

• imas-standard-names (this repo): Grammar library, parser, validation, Python API
• imas-standard-names-catalog: YAML source files and pre-built SQLite database

Name generation is handled by imas-codex, which uses ISN's grammar API to mint candidates.

This separation allows independent versioning — catalog content, tooling, and generation logic evolve separately.

Documentation

Full documentation: iterorganization.github.io/IMAS-Standard-Names

• Grammar Reference — naming rules and vocabulary
• Guidelines — patterns and conventions
• Quick Start — getting started
• Architecture — project boundary and API contract

Python API

Entry point	Purpose
imas_standard_names.parse(name, strict=True)	Authoritative validation for flat and recursively ordered grammar
imas_standard_names.parse(name)	Diagnostic parse into a lossless StandardNameIR
imas_standard_names.compose	Render a StandardNameIR into its canonical spelling
imas_standard_names.StandardNameIR	Public recursive representation; operator lists are outermost first
imas_standard_names.grammar.model.parse_standard_name	Strict-validating projection into the flat StandardName facade; may reject a valid ordered tree it cannot represent
imas_standard_names.validate_round_trip	Diagnostic parse/render drift check; not a validity test
imas_standard_names.grammar.context.get_grammar_context	Grammar rules and vocabulary for LLM pipelines
imas_standard_names.repository.StandardNameCatalog	Query the catalog
imas_standard_names.canonical_unit	Canonical unit authority
standard-names (CLI)	Build, search, and serve the catalog site
validate_catalog (CLI)	Check catalog integrity and grammar compliance

Tools that expose these over the Model Context Protocol live in imas-codex.

License

MIT