Confusion between buses of bus view and bus-breaker view

[sylvlecl]

• Do you want to request a feature or report a bug?

API clarification.

• What is the current behavior?

The difference between calculated buses of the bus view and "configured" buses of the bus-breaker view can be confusing to users.
In the API, it's not always clear what kind of buses we are referring to.

For example, when you create buses, you actually create "configured" buses, which will not appear when calling get_buses, which returns buses from the bus view:

network.create_buses(id='MYBUS', voltage_level_id='MYVL')   # Creates a configured bus "MYBUS"
network.get_buses()  # Will not contain "MYBUS" but a calculated bus like "MYVL_0"

Another example, when you create an element, you can specify a "bus_id" to define where it should be connected. Here we expect a "configured" bus, not a bus from the get_buses method, which can be confusing:

network.create_loads(id='L', bus_id='MYVL_0', ...)  # will raise an error because MYVL_0 is not a "configured" bus
network.create_loads(id='L', bus_id='MYBUS', ...)  # OK

• What is the expected behavior?

We should clarify where "configured" buses are expected or returned, instead of buses from the bus view.

In order to achieve this, we will need in particular to agree on some wording.
Currently, in returned dataframes, we have both bus_id and bus_breaker_bus_id columns.

Therefore, we could use "bus_breaker_bus" wherever a configured bus is expected/returned, but:

• it's ugly
• it's not specific enough, because often you really need a "configured bus" of a bus-breaker voltage level, and not a bus from the bus-breaker view of a node-breaker voltage level

--> should we use configured_bus in those places instead ?

create_buses would become create_configured_buses, and bus_id in creation methods would be renamed to configured_bus_id
instead.
Columns in returned dataframes would remaine bus_breaker_bus_id, because it's more generic than configured_bus_id, although still ugly.

Slightly linked with design issue powsybl/powsybl-core#2168 in powsybl-core, where the "configured bus" does not exist in the API either.

[sylvlecl]

@annetill @EtienneLt @geofjamg
Any opinion about the renaming propositions ? This would promote the concept of "configured bus" from an implementation detail in java to the API level, which seems necessary to me for clarity.

[nicow-elia]

Also, it would be nice to have a mapping between the two. Right now, we have the function get_bus_breaker_view_buses():

and the function get_buses():

However, it's unclear which bus from the get_bus_breaker_view_buses() is referring to which bus in the get_buses(). To find out what the translation is, you would have to call get_bus_breaker_topology(voltage_level):

Here, we see that actually all the bus_breaker buses in the substation are referring to the same buses in get_buses().