A Boolean for control by allocation

[visr]

Implement a Boolean for control by allocation as opposed to the magic "Ribasim.allocation", as suggested in #2527 (comment).

When we do this, we should directly validate that it is only used for Outlet or Pump, and not other unsupported node types, otherwise users may expect it to do something. Came up in #2883.

[verheem]

This needs some refinement. I understand the objection to the "magic string value", but it is very much in line with the feature to be able to switch between control state allocation and a discrete controlled state.

If we want to switch to a boolean value "control_by_allocation=true", how do you want to still support this switching behaviour without a special value?

The only option I see is that the user then must define its own special named value. The control_by_allocation option must be of type tuple, "control_by_allocation=(true, "special_control_state_name").

And then make sure that in an outlet.

    model.outlet.add(
        Node(4, Point(2, 0), subnetwork_id=1),
        [outlet.Static(
        flow_rate=[3e-3], max_flow_rate=3.0, controlled_by_allocation=(true, "allocation_state"), control_state=["allocation_state", "discrete_state"])
        ],
    )

And in a discrete control

    discrete_control2 = model.discrete_control.add(
        Node(2, Point(1.0, 1.0), name="Control Node"),
        [
            discrete_control.Variable(
                compound_variable_id=[1],
                listen_node_id=[1],
                variable=["level"],
            ),
            discrete_control.Condition(
                compound_variable_id=[1],
                condition_id=[1],
                threshold_high=[1.0],
            ),
            discrete_control.Logic(
                control_state=["allocation_state", "discrete_state"],
                truth_state=["F", "T"],
            ),
        ],
    )

However, the boolean is then redundant so we should make it a allocation_control_state = "special_control_state_name"
This can then be different for each node which gives some interesting freedom for a ribasim modeler.

    model.outlet.add(
        Node(1, Point(2, 0), subnetwork_id=1),
        [outlet.Static(
        flow_rate=[3e-3], max_flow_rate=3.0, allocation_control_state=("allocation_state_1"), control_state=["allocation_state_1", "allocation_state_2" "discrete_state"])
        ],
    )

    model.outlet.add(
        Node(2, Point(3, 0), subnetwork_id=1),
        [outlet.Static(
        flow_rate=[3e-3], max_flow_rate=3.0, allocation_control_state=("allocation_state_2"), control_state=["allocation_state_1", "allocation_state_2" "discrete_state"])
        ],
    )

And in a discrete control

    discrete_control2 = model.discrete_control.add(
        Node(2, Point(1.0, 1.0), name="Control Node"),
        [
            discrete_control.Variable(
                compound_variable_id=[1],
                listen_node_id=[1],
                variable=["level"],
            ),
            discrete_control.Condition(
                compound_variable_id=[1],
                condition_id=[1],
                threshold_high=[1.0, 1.2],
            ),
            discrete_control.Logic(
                control_state=["allocation_state_1", "allocation_state_2", "discrete_state"],
                truth_state=["FF", "TF", "TT"],
            ),
        ],
    )

However this feels a bit user unfriendly if you need to specify for each node its allocation_control_state to turn on allocation, and then repeat that in the control_state table so in the end, in my opinion our current implementation is cleanest, unless we see a good use case for the multi allocation state situation

[verheem]

After discussion with @evetion, we will implement the following (old vs new):

OLD

    outlet_old = model.outlet.add(
        Node(4, Point(-1.0, 0.0)),
        [
            outlet.Static(
                flow_rate=[None, 1],
                max_flow_rate=[1, 0],
                control_state=["Ribasim.allocation", "prescribed"],
            )
        ],
    )

NEW

    outlet_new = model.outlet.add(
        Node(3, Point(1.0, 0.0)),
        [
            outlet.Static(
                flow_rate=[None, None, 1],
                max_flow_rate=[0.08, 0.02, 0.05],
                control_state=["something", "something2", "prescribed"],
                allocation_controlled=[True, True, False],
            )
        ],
    )

This way we will have multiple different behaving allocation states and no magic strings anymore.

[evetion]

Refined with @simulutions today.

Apart from the "ugly" magic values in control states, the current behavior:

• prevents switching control states for allocation itself (a new max flow bound for allocation)
• prevents any new extension on the value (a new type of allocation that you also want to enable concurrently).
• prevents an explanation of the state

Allocation controlled is just a boolean for specific nodes (and the number of nodetypes that can be allocation controlled is increasing). Splitting it from the control state itself, it could land in:

• The global Node table (but invalid for some node types, and no control state)
• The Discrete control Logic table (but then allocation can't function without control)
• The Static tables (grows all tables a bit, especially if time also gets control state)
• A new ControlMap table (but no such concepts exist yet)

I feel only the latter two are feasible, and while I like a global table (as it fully spells out all control states, properly defining control state as an id (foreign key), it also separates it from the Nodes themselves, introducing some duplication. It also forces a control state to always be allocation controlled or not, foregoing finer-control per node. Adding a boolean check to some static tables feels very much inline with our current approach, and places it next to the control state in the Python API. It is therefore our preferred approach.