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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

imas_standard_names-0.8.0.tar.gz (1.3 MB view details)

Uploaded Sep 1, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

imas_standard_names-0.8.0-py3-none-any.whl (351.0 kB view details)

Uploaded Sep 1, 2026 Python 3

File details

Details for the file imas_standard_names-0.8.0.tar.gz.

File metadata

Download URL: imas_standard_names-0.8.0.tar.gz
Upload date: Sep 1, 2026
Size: 1.3 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for imas_standard_names-0.8.0.tar.gz
Algorithm	Hash digest
SHA256	`ecc87c870ebffc85859805615216b4c1f4b0210ce2e425331b2ec6732533aaf5`
MD5	`aa384082ab8b237cd11af0549d5c7d49`
BLAKE2b-256	`8f372ad3e04b5cde540d0d784834ef17bd1333656ffdcafa4b66346a1c89a641`

See more details on using hashes here.

Provenance

The following attestation bundles were made for imas_standard_names-0.8.0.tar.gz:

Publisher: release.yml on iterorganization/IMAS-Standard-Names

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: imas_standard_names-0.8.0.tar.gz
- Subject digest: ecc87c870ebffc85859805615216b4c1f4b0210ce2e425331b2ec6732533aaf5
- Sigstore transparency entry: 2674884762
- Sigstore integration time: Sep 1, 2026
Source repository:
- Permalink: iterorganization/IMAS-Standard-Names@49fe54b41a9311b38eca525bd90d4a2385080bc9
- Branch / Tag: refs/tags/v0.8.0
- Owner: https://github.com/iterorganization
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@49fe54b41a9311b38eca525bd90d4a2385080bc9
- Trigger Event: push