checking units strings

[prjemian]

The NeXus standard defines unit types such as NX_LENGTH and NX_TEMPERATURE. Each of these unit types has an enumeration of (1 or more) typical values.

The manual could accept an addition that shows how to use this information to check that any supplied units can be converted into any of the unit types enumerated for that field.

[prjemian]

Here's a python example using the pint package:

import pint

def check_units(self, expected, supplied):
    """
    Test if supplied units string can be converted into expected units.

    PARAMETERS

    expected *str*: expected units example
    supplied *str*: units string that was given

    RETURNS

    *bool*: `True` if units conversion is possible
    """
    ureg = pint.UnitRegistry()
    # print(f"{expected = }")
    # print(f"{supplied = }")

    if expected not in ureg:
        raise pint.UndefinedUnitError(
            f"Expected units '{expected}' not defined in unit registry."
        )
    if supplied not in ureg:
        raise pint.UndefinedUnitError(
            f"Supplied units '{supplied}' not defined in unit registry."
        )

    try:
        v = ureg(supplied).to(expected)
        # print(f"{v = }")
        return True
    except pint.DimensionalityError:
        return False

[prjemian]

Examples:

>>> check_units(None, "erg", "dyne*cm")
True
>>> check_units(None, "hectare", "acre")
True
>>> check_units(None, "foot", "K")
False
>>> check_units(None, "K/s", "hands")
False
>>> check_units(None, "hands", "cm")
True
>>> check_units(None, "femtoparsec", "furlong")
>>> try:
...     check_units(None, "blarney", "horseshoes")
... except pint.UndefinedUnitError as exc:
...     print(exc)
'Expected units 'blarney' not defined in unit registry.' is not defined in the unit registry
>>> try:
...     check_units(None, "nF", "horseshoes")
... except pint.UndefinedUnitError as exc:
...     print(exc)
'Supplied units 'horseshoes' not defined in unit registry.' is not defined in the unit registry

[prjemian]

We need an easy way to get the enumerated examples for each unit type from nxdlTypes.xsd.

[prjemian]

Won't be completed for upcoming release, kicking it down the road to next milestone.

[prjemian]

Looks as if this will be accomplished by the results of #1435, approved at NIAC2024.

• complex units, like eV/mm #1435

[prjemian]

Stated above:

We need an easy way to get ...

We now have examples available for each unit category. Here is are a couple examples:

definitions/nxdlTypes.xsd

Line 173 in 56e3ce5

<xs:element name="example">nm*rad</xs:element>

definitions/nxdlTypes.xsd

Lines 183 to 184 in 56e3ce5

	<xs:element name="example">J</xs:element>
	<xs:element name="example">keV</xs:element>

[prjemian]

Here, this work to be done (as stated above):

The manual could accept an addition ...