Merge pull request #30 from Simon-McIntosh/main

Carry the steradian in the name, not only in the unit

Author: Simon-McIntosh

imas_standard_names/grammar/constants.py

@@ -391,6 +391,7 @@ class SegmentRule:
     "fourier_coefficient",
     "gyroaveraged",
     "moment",
+    "per_solid_angle",
     "reference_waveform",
     "waveform",
 )
@@ -446,6 +447,7 @@ class SegmentRule:
     "fourier_coefficient",
     "gyroaveraged",
     "moment",
+    "per_solid_angle",
     "reference_waveform",
     "waveform",
 )

imas_standard_names/grammar/model_types.py

@@ -687,6 +687,7 @@ class Transformation(StrEnum):
     FOURIER_COEFFICIENT = "fourier_coefficient"
     GYROAVERAGED = "gyroaveraged"
     MOMENT = "moment"
+    PER_SOLID_ANGLE = "per_solid_angle"
     REFERENCE_WAVEFORM = "reference_waveform"
     WAVEFORM = "waveform"
 
@@ -737,6 +738,7 @@ class Decomposition(StrEnum):
     FOURIER_COEFFICIENT = "fourier_coefficient"
     GYROAVERAGED = "gyroaveraged"
     MOMENT = "moment"
+    PER_SOLID_ANGLE = "per_solid_angle"
     REFERENCE_WAVEFORM = "reference_waveform"
     WAVEFORM = "waveform"
 

imas_standard_names/grammar/vocabularies/advisory_aliases.yml

@@ -17,6 +17,11 @@ segments:
       reason: >-
         Retired duplicate spelling of the per-time derivative; the registered
         operator says what it does without a meteorological reading.
+    per_steradian:
+      canonical: per_solid_angle
+      reason: >-
+        Names the steradian rather than the quantity it measures; the
+        registered operator reads as the physical division it performs.
   physical_base:
     strain_tensor:
       canonical: strain

imas_standard_names/grammar/vocabularies/operators.yml

@@ -307,6 +307,17 @@ operators:
     precedence: 10
     returns: scalar
 
+  # Division by the solid angle the quantity is emitted into, adding sr^-1 to
+  # the unit (a volumetric source rate m^-3.s^-1 becomes m^-3.s^-1.sr^-1).
+  # Postfix so the per-unit normalization reads after the quantity it divides,
+  # as it does in physics prose ("source rate per solid angle"), and one token
+  # serves every quantity rather than a base per emitted species.
+  per_solid_angle:
+    kind: unary_postfix
+    precedence: 15
+    returns: scalar_or_vector
+    dimension_transforming: true
+
   reference_waveform:
     kind: unary_postfix
     precedence: 5

tests/grammar/test_advisory_alias_contract.py

@@ -15,6 +15,7 @@
     ("position", "annulus_centre"): "annulus_center",
     ("physical_base", "strain_tensor"): "strain",
     ("transformation", "tendency"): "time_derivative",
+    ("transformation", "per_steradian"): "per_solid_angle",
 }
 
 CONTEXTUAL_REWRITES = {

tests/grammar/test_solid_angle_normalization.py

@@ -0,0 +1,57 @@
+"""The per-solid-angle spelling: one operator token, every quantity.
+
+A volumetric emission rate resolved into direction carries sr^-1 in its unit
+(m^-3.s^-1.sr^-1). ``per_solid_angle`` is what carries that steradian in the
+name, so the unit string is not the only place the per-solid-angle character
+survives, and it composes onto any quantity rather than needing a base per
+emitted species.
+"""
+
+import pytest
+
+from imas_standard_names import compose, parse
+from imas_standard_names.grammar import parse_name
+from imas_standard_names.grammar.vocab_loaders import load_operators
+
+_PER_SOLID_ANGLE_NAMES = [
+    "source_rate_per_solid_angle",
+    "hard_xray_source_rate_per_solid_angle",
+    "electron_energy_source_rate_per_solid_angle",
+    "radiance_per_solid_angle",
+]
+
+
+@pytest.mark.parametrize("name", _PER_SOLID_ANGLE_NAMES)
+def test_per_solid_angle_names_parse_strictly(name: str) -> None:
+    parse(name, strict=True)
+
+
+@pytest.mark.parametrize("name", _PER_SOLID_ANGLE_NAMES)
+def test_per_solid_angle_names_round_trip(name: str) -> None:
+    assert compose(parse(name, strict=True).ir) == name
+
+
+@pytest.mark.parametrize("name", _PER_SOLID_ANGLE_NAMES)
+def test_the_operator_leaves_the_base_intact(name: str) -> None:
+    """The token normalizes the quantity; it never becomes part of the base."""
+    without = name.removesuffix("_per_solid_angle")
+    assert parse_name(name).physical_base == parse_name(without).physical_base
+
+
+def test_the_token_is_a_dimension_transforming_postfix_operator() -> None:
+    """sr^-1 joins the unit, so base-implies-unit inference must be suppressed."""
+    operator = load_operators().operators["per_solid_angle"]
+
+    assert operator.kind == "unary_postfix"
+    assert operator.dimension_transforming is True
+
+
+def test_one_token_serves_every_emitted_quantity() -> None:
+    """No base spelled '<base>_per_solid_angle' — the operator replaces them."""
+    from imas_standard_names.grammar.vocab_loaders import load_physical_bases
+
+    assert not [
+        token
+        for token in load_physical_bases().bases
+        if token.endswith("_per_solid_angle") or token.endswith("_per_steradian")
+    ]