Document how to make `Pump` and `Outlet` nodes allocation controlled

[SouthEndMusic]

They become allocation controlled by giving them the control state "Ribasim.allocation".

[evetion]

Will discuss with @visr @simulutions on this magic value.

[simulutions]

Here it is: https://ribasim.org/concept/allocation.html#control-by-allocation

[evetion]

I think my main concern (and something I already find very ugly in that control has to parse magic values like level/flow/concentration.X/concentration_external.X) is the "magic" of these values. They have a clear goal, but in very specific cases they do something completely different? Beside, having to put a specific value for a control state implies that we can trigger allocation control, and switch to other (non allocation) states as well. Not sure if that is what's intended. If not, I rather have a boolean field controlling this feature.

[visr]

It is intended that we can have control switch between Ribasim.allocation or other control states. An example is a reservoir that can release water based on downstream demand, but then switch to flood operation without any allocation when needed. I'm not sure this currently works, but it would be great to work out and document such an example.

You are right that it is a bit magic, but at the same time it aligns well in the existing concept of control_state. Having to introduce a separate concept can possibly also make things more difficult to grasp. We add the Ribasim. prefix to signify that this value has special meaning to Ribasim. If we don't do it already, we should error on any control states with that prefix that we don't know, to reserve it for our use.