§1 — Problem and origin

Edge and divertor codes — SOLPS above all — track molecular and compound species: molecular deuterium D₂, and the hydrocarbon families (CD₄, C₂D₆, …) produced by chemical erosion of carbon plasma-facing components. The ITER Data Dictionary models these as an ion[]/element[] and neutral[]/element[] array in which each element carries nuclear charge Z, mass number A, and a multiplicity field — the number of atoms of that element in the species (the DD cluster "Species Multiplicity Atomic Data": edge_profiles/…/neutral/element/multiplicity, …/ion/element/multiplicity). D₂ is a neutral species with one element (D) at multiplicity 2; CD₄ is two elements (C×1, D×4).

The ISN grammar cannot express this today. It has molecular as a population token (energy/molecularity class) but no way to name which molecule — D₂ vs CD₄ are indistinguishable. A handful of specific molecular subject tokens have already crept into subjects.yml ad-hoc (methane, deuterated_methane, ethane, ethylene, propane, silane, ammonia, ammonia_deuterated, methane_carbon_13) — a combinatorial anti-pattern (one subject token per molecule, no compositional structure), which is exactly the mistake this plan should replace with a principled construction. This surfaced while shipping the state segment (see systematic-review-remediation, f-srr-010); the lead asked to scope compound species as its own design task.

§2 — Three distinct species-grouping constructions (do not conflate)

The imas-dd investigation showed the intuitive "paired group" actually splits three ways. Only the third is this plan's subject; the figure fixes the boundaries.

§3 — Scope and requirements

• Self-describing composition. A name must convey which molecule is resolved (D₂ vs CD₄) without external lookup — mirroring the self-describing goal of the state rework.
• Compositional, not combinatorial. Replace the ad-hoc per-molecule subject tokens with a construction that composes from elements + counts, so a new molecule needs no new hand-added subject token.
• DD-anchored. The construction must map cleanly to element[]+multiplicity so codex can generate compound-species names directly from the DD path (SOLPS-provided data).
• Orthogonal to the shipped axes. Compound identity must compose with population (molecular), the state segment (a molecular ion has a charge state), component/aggregation, and the channel/base — without re-introducing a compound-subject anti-pattern.
• Retire the ad-hoc molecular subjects (methane/ethane/… listed in §1) by migrating them onto the new construction, if the design supports it.

§4 — Candidate directions (for the brainstorm — not yet decided)

This plan is a design task: the construction is undecided and needs a brainstorm (and likely a Fable design critique, as the state rework had) before any implementation plan. Directions to weigh:

• A — Composition qualifier / molecule vocabulary. A closed molecule vocabulary (d2, cd4, …) as a first-class segment or subject-adjacent token. Simple, but still enumerative (a token per molecule) unless the tokens encode composition.
• B — Structured formula construction. A compositional spelling built from element + multiplicity (e.g. an <element><count> pattern), so arbitrary molecules compose without new tokens. Most faithful to the DD; hardest to fit the greedy-longest-prefix grammar and canonical-one-spelling contract.
• C — Element + multiplicity as grammar sub-structure. Model the DD element[]/multiplicity directly as a repeatable segment group. Most general; largest grammar change; must not break round-trip.

Open questions the brainstorm must answer: does composition belong in the subject axis or a new axis? how does a molecular ion (compound identity + charge_state) render? is isotopic labelling (D vs H, ¹³C in methane_carbon_13) part of this axis or separate? how many real SOLPS species must be expressible (bounded set vs open formula)?

§5 — Relationship to other work

• Informs / follows systematic-review-remediation — spun out of the state-segment work (f-srr-010); shares the self-describing, DD-anchored, anti-compound-subject principles.
• Distinct from the state segment (shipped): state resolves a state of a species; this resolves the species identity as a molecule. A molecular ion could carry both.
• Distinct from reaction channels (deuterium_tritium, already atomic subjects): those are reactant pairs, not bound compounds.

Project: imas-standard-names
Plan:    sn-compound-species-naming (http://localhost:8765/imas-standard-names/sn-compound-species-naming.html)
Section: design
Tier:    opus

Context
  SOLPS tracks molecular/compound species (D2, CD4 hydrocarbons from carbon erosion); the DD models them as element[]+multiplicity. ISN has no compositional construction — only ad-hoc per-molecule subject tokens (methane, ethane, ...). Spun out of the state-segment work (systematic-review-remediation f-srr-010). Honour the live decisions shown above; do not re-list them.

State to read  (CODE / FILES / DATA)
  docs/sn-compound-species-naming.html (this plan) for the three-construction framing.
  imas_standard_names/grammar/vocabularies/subjects.yml — the ad-hoc molecular tokens to retire (methane, deuterated_methane, ethane, ethylene, propane, silane, ammonia, ammonia_deuterated, methane_carbon_13).
  imas-dd tools: edge_profiles ion/element + neutral/element + multiplicity; species_reference_identifier; the 'Species Multiplicity Atomic Data' cluster. Enumerate the real SOLPS species set.
  The shipped state segment (grammar/vocabularies/states.yml, model.py _check_state_gate) as the precedent for adding a subject-refinement construction.

Scope locks / constraints  (non-decision)
  Self-describing + compositional (not one-token-per-molecule) + DD-anchored to element[]/multiplicity. Must compose orthogonally with population(molecular), the state segment, component/aggregation. Greedy longest-prefix + canonical-one-spelling contract must hold; full-catalog round-trip must stay green. ISN owns all vocabulary (no codex hardcoding).

Done-when
  1. Construction + scope decisions locked (the two decisions in this plan)
  2. Fable design critique captured; before/after examples across molecular ion / neutral / isotopic cases
  3. Implementation plan written (writing-plans); this followup resolved