Repository navigation
Clarify the case(s) of "mixed" units #300
Description
Activity
First, there are some intructions about mixed units in the developer documentation here : https://imas-data-dictionary.readthedocs.io/en/latest/dm_rules_guidelines.html
Then you are right, there are essentially two cases where units are not determined in advance (so they can be "mixed").
- The node is a generic data container and it's physics content isn't pre-determined, so its units are not pre-determined either. A typical example of this is plasma_profils/covariance_matrix/data
- the reuse of a generic sub-structure in multiple contexts, for development reasons, creates cases where a field doesn't have pre-determined units. This is the case of your example here: https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/pulse_schedule.html#pulse_schedule-ec-power_launched-reference . We could solve that by creating more individual types (then losing the advantage of generic sub-structures), or by using the units="as_parent" mechanism (see below).
In most cases relevant to 2), we use the units="as_parent" tag to avoid putting mixed units. This is what is done in your second example https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/magnetics.html#magnetics-flux_loop-flux-data. Here we just put the only free units of the substructure at the parent level. This is fine from the XSD point of view, but to avoid confusion we should remove in the documentation the units from the structure level (makes no sense to display it at this level, since the "as_parent" mechanism copies them to the relevant leaves).
First, there are some intructions about mixed units in the developer documentation here : https://imas-data-dictionary.readthedocs.io/en/latest/dm_rules_guidelines.html
Indeed, but this clearly must be part of the glossary/user documentations, as long as [mixed] is being exposed in the final doc
In most cases relevant to 2), we use the units="as_parent" tag to avoid putting mixed units. This is what is done in your second example https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/magnetics.html#magnetics-flux_loop-flux-data. Here we just put the only free units of the substructure at the parent level. This is fine from the XSD point of view, but to avoid confusion we should remove in the documentation the units from the structure level (makes no sense to display it at this level, since the "as_parent" mechanism copies them to the relevant leaves).
I fully agree with this approach: trying to use more widely the "as_parent" mechanism wherever possible, and not listing units at the structure level.
In the documentation, we explain the case for dimensionless units (cf. https://imas-data-dictionary.readthedocs.io/en/latest/units.html) but not for mixed units.
There are, at least, two use-cases where we find "mixed" units:
grid/dim1andgrid/dim2depend ongrid_typesibling, see Define units for case-dependent quantities #118 )It should be explained in the glossary, and we should check if there are different use-cases in the DD that these two types.
ps: I also note that some other IDS have units in both structure and children node level (e.g. https://imas-data-dictionary.readthedocs.io/en/latest/generated/ids/magnetics.html#magnetics-flux_loop-flux-data) not clear why we have that case and 2. in other places, maybe the case 2 can be avoided?