Possible deprecation and removal of node injection output

[mgovers]

Dear community,

We would like to hear your input on the topic of removal of the node injection output. Both objections and approvals are useful input to us, so feel free to leave a reply, even if only to let us know that you have no objections.

In short

Node injection output does not map directly to a physical quantity. Instead, the relevant quantities relating to injection are usually at the level of injections. Combined with the fact that node injection output comes at a significant maintainability cost, we seek to remove it altogether. The full rationale is explained below.

Impact

Breaking change

The new behavior would mean that the following expressions will result in a KeyError:

• output_data[ComponentType.node][AttributeType.p]
• output_data[ComponentType.node][AttributeType.q]

Typical alternative

In most cases, the actual relevant quantity is not the injection on the node but the injection of the appliance connected to that node. Hence, using that quantity directly, instead, should be the sustainable solution.

• output_data[ComponentType.source][AttributeType.p]
• output_data[ComponentType.source][AttributeType.q]
• output_data[ComponentType.sym_load][AttributeType.p]
• output_data[ComponentType.sym_load][AttributeType.q]
• output_data[ComponentType.sym_gen][AttributeType.p]
• output_data[ComponentType.sym_gen][AttributeType.q]
• output_data[ComponentType.asym_load][AttributeType.p]
• output_data[ComponentType.asym_load][AttributeType.q]
• output_data[ComponentType.asym_gen][AttributeType.p]
• output_data[ComponentType.asym_gen][AttributeType.q]

This is especially true if no explicit topological search is required to obtain the desired quantity, or if the user models the grid such that there is at most one appliance per node.

User alternative to original behavior

If the user really intents to aggregate injections per node, the total injection on a node can still be obtained using a calculation similar to the following.

node_ids = input_data[ComponentType.node][AttributeType.id]
node_p = dict.fromkeys(node_ids, 0.0)
node_q = dict.fromkeys(node_ids, 0.0)

for appliance, sign in (
    (ComponentType.source, +1),
    (ComponentType.sym_gen, +1),
    (ComponentType.asym_gen, +1),
    (ComponentType.sym_load, -1),
    (ComponentType.asym_load, -1),
):
    if appliance not in input_data or appliance not in output_data:
        continue
    nodes = input_data[appliance][AttributeType.node]
    p = output_data[appliance][AttributeType.p]
    q = output_data[appliance][AttributeType.q]

    for nid in node_ids:
        mask = nodes == nid
        node_p[nid] += sign * p[mask].sum()
        node_q[nid] += sign * q[mask].sum()

If desirable, we may be able to provide such a utility function from the power_grid_model.utils module.

Rationale

Why it is probably OK to remove for users

Node injection output has no direct usability.

• Usually, limits will be determined at the level of appliances:
  • Either there is only one appliance connected to a node, in which case the node injection is equivalent to the appliance injection;
  • Or there are more appliances connected to the same node, in which case the node injection does not map directly onto a physical quantity.

Why it was originally added and why its original purpose is no longer relevant

Obtaining node injection from appliances may be cumbersome. From the PGM core side, it could be obtained fairly easily using Kirchoff's law, which is (up to error tolerances in iterative solvers and truncation errors) equivalent to a sum over all appliance injections.

This node injection output could then be compared with the original sum of all appliances on the same node to obtain some information about the accuracy of the calculation result. But this was never documented, and therefore never considered stable. In addition, the sustainable way would obtain this information not using such a hack but directly from the calculation core using a logger (under active development). This logger could also be much more detailed and accurate than this type of user output could ever be. Therefore, even the original purpose is lost.

Why it would be nice to remove from the PGM implementation side

With PowerGridModel/power-grid-model#35 coming up, node injection obtained from Kirchoff's law no longer directly maps onto nodes as defined by users, so the trick initially used is no longer relevant. Removal of this feature would mean a significant improvement in maintainability, meaning we can deliver new features and other improvements, better and faster.

[Berend-Visser]

I agree that it can be removed. In my mind, nodes are points in the grid, which register a voltage value and nothing else. Injection and removal of current from the grid is the responsibility of the loads and sources, meaning that injected/removed power should be reported at that level as well.

For this reason, having p and q values at the level of nodes feels artificial to me, and we have never used this feature in our team. Aggregating the injected power of all appliances connected to a node does not feel particularly complex to me, and I think it's something that can be safely left to the user (or perhaps as you say, as a utility function you provide, if others do feel the need to have one).

[francisca-mestre]

I agree that it can be removed.

[SteffanWullems]

Good plan to remove this