Generalise Restart Representation of UDQs

[bska]

This PR reimplements the RestartIO::RstUDQ type with a view towards introducing support for restarting simulation runs containing user defined quantities (UDQs) associated to the segments of multi-segmented wells. In particular, we replace the current value container with a back-end based on the CSRGraphFromCoordinates helper class. This, in turn, enables supporting UDQ values at the sub-entity level of a top-level entity such as the segments of a multi-segmented well.

We more clearly distinguish the producing side–i.e., the layer which loads information from a restart file–from the consuming side–i.e., the client code which forms UDQConfig and UDQState objects based on the restart file information, and require the producing side to signal when the restart information has been fully loaded. To this end, the producing side is expected to

1. Call member function prepareValues() to signal that new values are being loaded
2. Call member function addValue(), typically in a loop, to include new UDQ values from the restart file
3. Call member function commitValues() to signal that all values have been loaded.

As an alternative to step 2, the producing side may call member function addScalarValue() if the quantity in question is scalar–typically a field level UDQ.

The producing should also include any relevant entity names, usually well or group names, by calling the addEntityName() member function.

The consuming side is expected to interact with the information through operator[]() which returns a specialised ValueRange type that supports forward iteration, for instance in a range-for() loop.

This new interface begets a significant update to the UDQAssign class. In particular, we no longer need the rst_selector and instead add new constructor and add_record interfaces which take a RestartIO::RstUDQ object and a report step index. The previous interface based on the rst_selector implicitly assumed that all assignment statements applied a constant value to a collection of wells or groups, but this assumption does not generally hold when we load information from a restart file. The
n ew interface removes this assumption. While here, also make the AssignRecord into a private data type since client code does not generally need to know how we represent the assignment information.

Finally, add Doxygen-style documentation to the types

• RestartIO::RstUDQ
• UDQAssign
• UDQConfig

While not much, this may help future maintainers understand the relationships between these types a little better.

[bska]

I am creating this PR in draft mode because it depends on, and contains, the earlier PR #4224. I will keep the PR in a draft state until such time as it is ready for review and merging. That may be after we've created the release branches for the 2024.10 OPM release, since it's not clear to me that this is ready to go into a release version quite yet.

[bska]

jenkins build this please