Package com.powsybl.iidm.network

Interface VoltageLevel

All Superinterfaces:
Container<VoltageLevel>, Extendable<VoltageLevel>, Identifiable<VoltageLevel>
public interface VoltageLevel extends Container<VoltageLevel>
A voltage level is a collection of equipments located in the same substation and at the same base voltage.

A voltage level contains a topology model, i.e. an object that describes how equipments are connected together.

Topology model:

A voltage level may have two kinds of topology model depending on what level of detail we want to have (getTopologyKind()):
  • node/breaker model: this is the most detailed way to describe a topology. All elements are physical ones: busbar sections, breakers and disconnectors. A node in a node/breaker context means "connection node" and not topological node or bus.
  • bus/breaker model: this is an aggregated form of the topology made of buses and breakers. A bus is the aggregation of busbar sections and closed switches.

Topology view:

A topology model can be managed through the 3 following views ordered from the most detailed to the less detailed:
  • node/breaker view
  • bus/breaker view
  • bus only view

Depending on the topology model kind of the voltage level a view can have the status:

  • N/A, it doesn't make sense to take view that is more detailed than the model. An exception is thrown when a method is called on an N/A view
  • modifiable, when the view has the same level of detail than the model
  • readable only, because the view is a result of a computation on the topology model

The view status is summarized in the following table:

Topology model
node/breaker bus/breaker
Topology view node/breaker modifiable N/A
bus/breaker readable modifiable
bus readable readable

Characteristics

Attribute Type Unit Required Defaut value Description
Id String - yes - Unique identifier of the voltage level
Name String - yes - Human-readable name of the voltage level
NominalV double kV yes - The nominal voltage
LowVoltageLimit double kV no - The low voltage limit
HighVoltageLimit double kV no - The high voltage limit
TopologyKind TopologyKind - yes - The kind of topology

Creating a substation with a node/breaker topology model:

The substation of the example has two voltage levels VL1 and VL2 described by a node/breaker topology model. The first voltage level VL1 has 2 busbar sections BBS1 and BBS2 , a generator GN, a load LD and a coupler BR3 between busbar section BBS1 and BBS2. The second voltage level VL2 has a single busbar section BBS3 a line LN and is connected to voltage level VL1 through transformer TR.

Here is a diagram of the substation:

The node/breaker topology model is stored inside the voltage level as a graph where connection nodes are the vertices and switches are the edges.

The next diagram shows how to map the subtation topology to a graph.

Each voltage level has its own topology graph. Voltage level VL1 has 8 connection nodes. Generator GN is connected to node 1, load LD to node 5, busbar sections BBS1 and BBS2 to node 3 and 4. 2, 6 and 7 are internal connection nodes. Voltage level VL2 has 3 nodes, line LN is connected to node 1, busbar section BBS3 to node 2. Transformer TR is connected to node 8 of voltage level 400Kv and node 3 of voltage level 225Kv. Plain edges represent closed switches. Dashed edges reprensent opened switches. Green edges will disappear during the bus/breaker topology computation whereas pink edges (like in this case 3<->4) will be retained whatever their position are (see Switch.isRetained()).

The following code shows how to create the substation with a node/breaker topology model. 

    Network n = ...
    Substation s = ...
    VoltageLevel vl1 = s.newVoltageLevel()
        .setId("VL1")
        .setTopologyKind(TopologyKind.NODE_BREAKER)
        .add();
    vl1.getNodeBreakerView().setNodeCount(8);
    // create busbar sections BBS1 and BBS2
    vl1.getNodeBreakerView().newBusbarSection()
        .setId("BBS1")
        .add();
    vl1.getNodeBreakerView().newBusbarSection()
        .setId("BBS2")
        .add();
    // create generator GN
    vl1.newGenerator()
        .setId("GN")
        .setNode(1)
        ...
        .add();
    // create load LD
    vl1.newLoad()
        .setId("LD")
        .setNode(5)
        ...
        .add();
    // connect generator GN by creating breaker BR1 and disconnectors DI1 and DI2
    vl1.getNodeBreakerView().newBreaker()
        .setId("BR1")
        .setOpen(false)
        .setNode1(1)
        .setNode1(2)
        .add();
    vl1.getNodeBreakerView().newDisconnector()
        .setId("DI1")
        .setOpen(false)
        .setNode1(2)
        .setNode1(3)
        .add();
    vl1.getNodeBreakerView().newDisconnector()
        .setId("DI2")
        .setOpen(true)
        .setNode1(2)
        .setNode1(4)
        .add();
    // connect load LD
    ...
    // create busbar coupler BR3
    vl1.getNodeBreakerView().newBreaker()
        .setId("BR3")
        .setOpen(false)
        .setRetained(true) // retain this breaker in the bus/breaker topology!!!
        .setNode1(3)
        .setNode2(4)
        .add();

    VoltageLevel vl2 = s.newVoltageLevel()
        .setId("VL2")
        .setTopologyKind(TopologyKind.NODE_BREAKER)
        .add();
    vl2.getNodeBreakerView().setNodeCount(3);
    // create busbar section BBS3
    vl2.getNodeBreakerView().newBusbarSection()
        .setId("BBS3")
        .add();
    // create line LN
    n.newLine()
        .setId("LN")
        .setVoltageLevel1("VL2")
        .setNode1(1)
        .setVoltageLevel2(...)
        .setNode2(...)
        ...
        .add();

    // create transformer TR
    s.newTwoWindingsTransformer()
        .setId("TR")
        .setVoltageLevel1("VL1")
        .setNode1(8)
        .setVoltageLevel2("VL2")
        .setNode2(3)
        ...
        .add();

The following diagram shows computed bus/breaker topology. Compared to node/breaker topology, only remains equipements (GN, LD, TR, LN), and switches flagged as retained (BR3). Equipments are now connected through buses (B1 and B2).

To get a bus/breaker view on the substation voltage level VL1 use getBusBreakerView(). The following code shows how to get buses and breakers of the bus/breaker view in voltage level VL1. 

    // VL1 contains 2 buses in the bus/breaker view
    Iterator<Bus> itB = vl1.getBusBreakerView().getBuses().iterator();

    // first bus connects nodes 1, 2, 3, 5, 6
    Bus b1 = itB.next();
    // ... and consequently generator GN and load LD
    Generator gn = b1.getGenerators().iterator().next();
    Load ld = b1.getLoads().iterator().next();

    // bus/breaker view can also be accessed from an equipment
    Bus alsoB1 = gn.getTerminal().getBusBreakerView.getBus();

    // second bus connects nodes 4, 7, 8
    Bus b2 = itB.next();
    TwoWindingsTransformer tr = b2.getTwoWindingsTransformer().iterator().next();

    // VL1 contains 1 switch in the bus/breaker view
    Iterator<Switch> itS = vl1.getBusBreakerView().getSwitches().iterator();
    Switch br3 = itS.next();

The following diagram shows computed bus topology. Compared to bus/breaker topology, there is no switches anymore. Only remains equipements (GN, LD, TR, LN) connected through buses.

To get a bus view one the substation voltage level VL1 use getBusView(). The following code shows how to get buses of the bus view in voltage level VL1. 

    // VL1 contains 1 buses in the bus view
    Iterator<Bus> itB = vl1.getBusView().getBuses();

    // the bus connects all the equipements of voltage level VL1
    Bus b1 = itB.next();

Creating a substation with a bus/breaker topology model:

Instead of creating VL1 and VL3 with a node/breaker topology model, we can directly create them in a simpler bus/breaker topology model. It can be very useful when data source only contains bus/branch data link in DEF or CIM format.

The following code shows how to create the substation with a bus/breaker topology model. 

    VoltageLevel vl1 = s.newVoltageLevel()
        .setId("VL1")
        .setTopologyKind(TopologyKind.BUS_BREAKER)
        .add();
    // create busbar sections BBS1 and BBS2
    vl1.getBusBreakerView().newBus()
        .setId("B1")
        .add();
    vl1.getBusBreakerView().newBus()
        .setId("B2")
        .add();
    // create generator GN
    vl1.newGenerator()
        .setId("GN")
        .setBus("B1")
        ...
        .add();
    // create load LD
    vl1.newLoad()
        .setId("LD")
        .setBus("B1")
        ...
        .add();
     // create busbar coupler BR3
     vl1.getBusBreakerView().newBreaker()
        .setId("BR3")
        .setOpen(false)
        .setBus1("B1")
        .setBus2("B2")
        .add();

    VoltageLevel vl2 = s.newVoltageLevel()
        .setId("VL2")
        .setTopologyKind(TopologyKind.BUS_BREAKER)
        .add();
    vl2.getBusBreakerView().newBus()
        .setId("B3")
        .add();
    // create line LN
    n.newLine()
        .setId("LN")
        .setVoltageLevel1("VL2");
        .setBus1("B3")
        .setVoltageLevel2(...);
        .setBus2(...)
        ...
        .add();

    // create transformer TR
    s.newTwoWindingsTransformer()
        .setId("TR")
        .setVoltageLevel1("VL1");
        .setBus1("B2")
        .setVoltageLevel2("VL2");
        .setBus2("B3")
        ...
        .add();

Warning: in that case the node/breaker view status on voltage level VL1 and VL2 is N/A.

To create a voltage level, see VoltageLevelAdder

Author:
Geoffroy Jamgotchian <geoffroy.jamgotchian at rte-france.com>
See Also:

  • Method Details

    • getSubstation

      Optional<Substation> getSubstation()

    • getNullableSubstation

      default Substation getNullableSubstation()

    • getNominalV

      double getNominalV()
      Get the nominal voltage in KV.

    • setNominalV

      VoltageLevel setNominalV(double nominalV)

    • getLowVoltageLimit

      double getLowVoltageLimit()
      Get the low voltage limit in KV.
      Returns:
      the low voltage limit or NaN if undefined

    • setLowVoltageLimit

      VoltageLevel setLowVoltageLimit(double lowVoltageLimit)
      Set the low voltage limit in KV.
      Parameters:
      lowVoltageLimit - the low voltage limit in KV

    • getHighVoltageLimit

      double getHighVoltageLimit()
      Get the high voltage limit in KV.
      Returns:
      the high voltage limit or NaN if undefined

    • setHighVoltageLimit

      VoltageLevel setHighVoltageLimit(double highVoltageLimit)
      Set the high voltage limit in KV.
      Parameters:
      highVoltageLimit - the high voltage limit in KV

    • getConnectable

      <T extends Connectable> T getConnectable(String id, Class<T> aClass)
      Get an equipment connected to this substation voltage level.
      Parameters:
      id - the equipment id
      aClass -
      Returns:
      the equipment

    • getConnectables

      <T extends Connectable> Iterable<T> getConnectables(Class<T> clazz)
      Get an Iterable on all the equipments connected to this substation voltage level for a given type.
      Parameters:
      clazz - equipments type
      Returns:
      all the equipments of the given type

    • getConnectableStream

      <T extends Connectable> Stream<T> getConnectableStream(Class<T> clazz)
      Get a Stream on all the equipments connected to this substation voltage level for a given type.
      Parameters:
      clazz - equipments type
      Returns:
      all the equipments of the given type

    • getConnectableCount

      <T extends Connectable> int getConnectableCount(Class<T> clazz)
      Count the equipments connected to this substation voltage level for a given type.
      Parameters:
      clazz - equipments type
      Returns:
      all the equipment of the given type

    • getConnectables

      Iterable<Connectable> getConnectables()
      Get an Iterable on all the equipments connected to this substation voltage level.
      Returns:
      all the equipments

    • getConnectableStream

      Stream<Connectable> getConnectableStream()
      Get a Stream on all the equipments connected to this substation voltage level.
      Returns:
      all the equipments

    • getConnectableCount

      int getConnectableCount()
      Count the equipments connected to this substation voltage level.
      Returns:
      all the equipments

    • newGenerator

      GeneratorAdder newGenerator()
      Get a builder to create a new generator.

    • getGenerators

      Iterable<Generator> getGenerators()
      Get generators.

    • getGeneratorStream

      Stream<Generator> getGeneratorStream()
      Get generators.

    • getGeneratorCount

      int getGeneratorCount()
      Get generator count.

    • newBattery

      BatteryAdder newBattery()
      Get a builder to create a new battery.

    • getBatteries

      Iterable<Battery> getBatteries()
      Get batteries.

    • getBatteryStream

      Stream<Battery> getBatteryStream()
      Get batteries.

    • getBatteryCount

      int getBatteryCount()
      Get battery count.

    • newLoad

      LoadAdder newLoad()
      Get a builder to create a new load.

    • getLoads

      Iterable<Load> getLoads()
      Get loads.

    • getLoadStream

      Stream<Load> getLoadStream()
      Get loads.

    • getSwitches

      Iterable<Switch> getSwitches()
      Get switches.

    • getSwitchCount

      int getSwitchCount()
      Get switch count.

    • getLoadCount

      int getLoadCount()
      Get load count.

    • newShuntCompensator

      ShuntCompensatorAdder newShuntCompensator()

    • getShuntCompensators

      Iterable<ShuntCompensator> getShuntCompensators()
      Get compensator shunts.

    • getShuntCompensatorStream

      Stream<ShuntCompensator> getShuntCompensatorStream()
      Get compensator shunts.

    • getShuntCompensatorCount

      int getShuntCompensatorCount()
      Get shunt count.

    • newDanglingLine

      DanglingLineAdder newDanglingLine()
      Get a builder to create a new dangling line.

    • getDanglingLines

      Iterable<DanglingLine> getDanglingLines(DanglingLineFilter danglingLineFilter)
      Get the dangling lines in this voltage level which correspond to given filter.

    • getDanglingLines

      default Iterable<DanglingLine> getDanglingLines()
      Get all dangling lines in this voltage level.

    • getDanglingLineStream

      Stream<DanglingLine> getDanglingLineStream(DanglingLineFilter danglingLineFilter)
      Get the dangling lines in this voltage level which correspond to given filter.

    • getDanglingLineStream

      default Stream<DanglingLine> getDanglingLineStream()
      Get all dangling lines in this voltage level.

    • getDanglingLineCount

      int getDanglingLineCount()
      Get dangling line count.

    • newStaticVarCompensator

      StaticVarCompensatorAdder newStaticVarCompensator()
      Get a builder to create a new static var compensator.

    • getStaticVarCompensators

      Iterable<StaticVarCompensator> getStaticVarCompensators()
      Get static var compensators.

    • getStaticVarCompensatorStream

      Stream<StaticVarCompensator> getStaticVarCompensatorStream()
      Get static var compensators.

    • getStaticVarCompensatorCount

      int getStaticVarCompensatorCount()
      Get static var compensator count.

    • newVscConverterStation

      VscConverterStationAdder newVscConverterStation()
      Get a builder to create a new VSC converter station connected to this voltage level.
      Returns:
      a builder to create a new VSC converter

    • getVscConverterStations

      Iterable<VscConverterStation> getVscConverterStations()
      Get all VSC converter stations connected to this voltage level.
      Returns:
      all VSC converter stations connected to this voltage level

    • getVscConverterStationStream

      Stream<VscConverterStation> getVscConverterStationStream()
      Get all VSC converter stations connected to this voltage level.
      Returns:
      all VSC converter stations connected to this voltage level

    • getVscConverterStationCount

      int getVscConverterStationCount()
      Get VSC converter stations count connected to this voltage level.
      Returns:
      VSC converter stations count connected to this voltage level

    • newLccConverterStation

      LccConverterStationAdder newLccConverterStation()
      Get a builder to create a new LCC converter station connected to this voltage level.
      Returns:
      a builder to create a new LCC converter

    • getLccConverterStations

      Iterable<LccConverterStation> getLccConverterStations()
      Get all LCC converter stations connected to this voltage level.
      Returns:
      all LCC converter stations connected to this voltage level

    • getLccConverterStationStream

      Stream<LccConverterStation> getLccConverterStationStream()
      Get all LCC converter stations connected to this voltage level.
      Returns:
      all LCC converter stations connected to this voltage level

    • getLccConverterStationCount

      int getLccConverterStationCount()
      Get LCC converter stations count connected to this voltage level.
      Returns:
      LCC converter stations count connected to this voltage level

    • getLines

      Iterable<Line> getLines()
      Get all lines connected to this voltage level.
      Returns:
      all lines connected to this voltage level

    • getLineStream

      Stream<Line> getLineStream()
      Get all lines connected to this voltage level.
      Returns:
      all lines connected to this voltage level

    • getLineCount

      int getLineCount()
      Get line count connected to this voltage level.
      Returns:
      line count connected to this voltage level

    • getTwoWindingsTransformers

      Iterable<TwoWindingsTransformer> getTwoWindingsTransformers()
      Get all two windings transformers connected to this voltage level.
      Returns:
      all two windings transformers connected to this voltage level

    • getTwoWindingsTransformerStream

      Stream<TwoWindingsTransformer> getTwoWindingsTransformerStream()
      Get all two windings transformers connected to this voltage level.
      Returns:
      all two windings transformers connected to this voltage level

    • getTwoWindingsTransformerCount

      int getTwoWindingsTransformerCount()
      Get two windings transformer count connected to this voltage level.
      Returns:
      two windings transformer count connected to this voltage level

    • getThreeWindingsTransformers

      Iterable<ThreeWindingsTransformer> getThreeWindingsTransformers()
      Get all three windings transformers connected to this voltage level.
      Returns:
      all three windings transformers connected to this voltage level

    • getThreeWindingsTransformerStream

      Stream<ThreeWindingsTransformer> getThreeWindingsTransformerStream()
      Get all three windings transformers connected to this voltage level.
      Returns:
      all three windings transformers connected to this voltage level

    • getThreeWindingsTransformerCount

      int getThreeWindingsTransformerCount()
      Get three windings transformer count connected to this voltage level.
      Returns:
      three windings transformer count connected to this voltage level

    • newGround

      GroundAdder newGround()
      Get a builder to create a new ground.

    • getGrounds

      Iterable<Ground> getGrounds()
      Get grounds.

    • getGroundStream

      Stream<Ground> getGroundStream()
      Get grounds.

    • getGroundCount

      int getGroundCount()
      Get ground count.

    • remove

      default void remove()
      Remove this voltage level from the network.

    • visitEquipments

      void visitEquipments(TopologyVisitor visitor)
      Visit equipments of the voltage level.
      Parameters:
      visitor -

    • getTopologyKind

      TopologyKind getTopologyKind()
      Get the kind of topology.

    • getNodeBreakerView

      VoltageLevel.NodeBreakerView getNodeBreakerView()
      Get a node/breaker view of the topology.
      Returns:
      a node/breaker view of the topology

    • getBusBreakerView

      VoltageLevel.BusBreakerView getBusBreakerView()
      Get a bus/breaker view of the topology.
      Returns:
      a bus/breaker view of the topology

    • getBusView

      VoltageLevel.BusView getBusView()
      Get a bus view of the topology.
      Returns:
      a bus view of the topology

    • printTopology

      void printTopology()
      Print an ASCII representation of the topology on the standard ouput.

    • printTopology

      void printTopology(PrintStream out, ShortIdDictionary dict)
      Print an ASCII representation of the topology on a stream.
      Parameters:
      out - the stream

    • exportTopology

      void exportTopology(Path file) throws IOException
      Export in a file the topology in DOT format (Graphviz).
      Parameters:
      file - the file
      Throws:
      IOException

    • exportTopology

      void exportTopology(Writer writer, Random random) throws IOException
      Export in a file the topology in DOT format (Graphviz).
      Parameters:
      writer - a writer
      random - pseudo random number generator
      Throws:
      IOException

    • exportTopology

      void exportTopology(Writer writer) throws IOException
      Export the topology in DOT format (Graphviz).
      Parameters:
      writer - a writer
      Throws:
      IOException

    • getType

      default IdentifiableType getType()
      Description copied from interface: Identifiable
      Get identifiable type.
      Specified by:
      getType in interface Identifiable<VoltageLevel>
      Returns:
      the identifiable type