complex units, like eV/mm

[sanbrock]

• Neither NX_ENERGY nor NX_PER_LENGTH is the correct choice for eV/mm as monochromator disperion is reported at FLASH
• NeXus doc states "However, any field must have a units attribute which describes the units." but hardly anybody does this via adding an attribute named "units" to all fields, i.e. also fields NX_CHAR must have a units attribute, feels that this is too tight of being a useful constraint.
• Suggestion: sharpen semantics of NeXus documentation #1487

[prjemian]

Is it appropriate to define a new type of units for this purpose? Here is where they are defined.
https://github.com/nexusformat/definitions/blob/main/nxdlTypes.xsd

[phyy-nx]

Proposal:

For complex types that are not currently in the list NeXus unit categories, allow the attribute, units, to in addition to being NX_ANGLE, NX_AREA, etc, be a vector of fractional SI dimensions. Example,

<field name="mega_unit" type="NX_FLOAT" units="0,1,2,3,4,0,0">

This means the user needs to include the attribute units, and the string they provide needs to have dimensionality of mass * time^2 * electric current^3 * temperature^4

The vector is:
length
mass
time
electric current
thermodynamic temperature
amount of substance
luminous intensity

This is the same order as in UDunits (link)

The HTML rendering won't show the numbers, but instead will use the SI defaults and the exponents to be more human readable. For example, g * s^2 * A^3 * K^4. The XML will have the vector. Whenever this convention is used, it is highly encouraged to proved the common name for these units in the doc string of the field.

This is a supplement to the list of allowed NeXus unit categories, and can be considered for complex types not in the list.

(the NIAC will return to this tomorrow)

[tacaswell]

' '.join(__ for __ in (f'{_}^{v}' if v != 0 else '' for _, v in zip(('s', 'm', 'kg', 'A', 'K', 'mol', 'cd'), (1, 0, 0, 3, -1, 0))) if __)

[prjemian]

A sequence of seven numbers (in the NXDL file) is hard to embrace as a person who is coaching people to write new application definitions. This is a code that must be remembered. I foresee continual challenges about the proper order of the numbers, for example.

Perhaps there is another, more natural, way to implement this idea?

The problem to be solved here is that a pre-defined a list of units categories might not be bounded. To allow the NeXus standard to be flexible to our community, we need a more robust system to describe expected units as our community's needs expand.

We could add a unit_example="ev/mm" attribute for the monochromator disperion cited above. In general, the unit_example would have a human readable expression that is convertible with UDunits, pint, whatever. This type of expression satisfies the list of numbers with a human readable text. The expression is comparable to the examples already provided in nxdlTypes.xsd. Could it eventually replace the unit categories altogether?

[prjemian]

The second example above (units="0,1,2,3,4,0,0") could be expressed
unit_example="g * s^2 * A^3 * K^4". It could also be expressed in other variations which evaluate to the same units.

[tacaswell]

n [24]: {**dict.fromkeys(('s', 'm', 'kg', 'A', 'K', 'mol', 'cd'), 0), **{k:int(v) for k, v in (g.split('^') for g in 's^1 A^3 K^-1'.split())}}
Out[24]: {'s': 1, 'm': 0, 'kg': 0, 'A': 3, 'K': -1, 'mol': 0, 'cd': 0}

is also pretty straight forward (modulo details like supporting ^1 implicitly).

Maybe instead of trying to write a "nice" string we have to parse, we instead make it a json object as:

<field name="mega_unit" type="NX_FLOAT" units="{'s': 1, 'm': 0, 'kg': 0, 'A': 3, 'K': -1, 'mol': 0, 'cd': 0}">

It is a bit verbose, but it is unambiguous to both humans and computers. Dropping the keys who's value is 0 is likely reasonable.

[phyy-nx]

Of these I prefer the vector representation, but only because the user would never see it. The HTML for the documentation would be rendered as g * s^2 * A^3 * K^4, and we would recommend that developers put in their doc strings the more conventional name for their units. Only the XML would contain the more machine-readable vector.

The unit_example attribute is worth considering though.

[phyy-nx]

Note this is literally #1325, with the addition of extra HTML rendering code to smooth out the non-human readable unit vector.

[phyy-nx]

Alternate proposal:

• If a unit is not provided by the list of NeXus unit categories, instead of providing a category, the field statement can include an example of the units directly.
• The example does not constrain the scale of the units. For example, if the unit is eV/mm, they user could specify in a data file eV/cm, or any other unit that is convertible to the example given.

Example:

<field name="monochromator_dispersion" units="eV/mm">

It is recommended that users and application developers check if their units and their unit examples adhere to the UDUNITS standard.

This proposal is accepted by NIAC vote as part of NIAC2024

[prjemian]

The PR should close these related issues:

• checking units strings #918
• Proposal: Adopt unitsSI from openPMD #1325

[prjemian]

Probably needs a modification to the NXDL Schema.