Network reduction
The network reduction is relying on a NetworkPredicate
instance, to define an area of interest (i.e. a list of equipments to keep in the network after the reduction). The equipments outside this area will be removed and the lines, transformers and HVDC lines connecting voltage levels inside and outside this area will be replaced by injections (loads or dangling lines, depending on the implementation).
Define an area of interest
Before doing the reduction, one has to define the area of interest, using the com.powsybl.iidm.reducer.NetworkPredicate
interface. This interface declares two methods:
public interface NetworkPredicate {
boolean test(Substation substation);
boolean test(VoltageLevel voltageLevel);
}
These two methods must return true
when the given parameter (a substation or a voltage level) is in the area of interest and should still be in the network after the reduction.
PowSyBl provides two implementations of this interface:
- the
IdentifierNetworkPredicate
implementation defines an area of interest using a list of voltage levels or substation IDs - the
NominalVoltageNetworkPredicate
implementation defines an area of interest using a range of nominal voltages
You can also provide your own implementation.
By IDs
The com.powsybl.iidm.reducer.IdentifierNetworkPredicate
class is an implementation of the NetworkPredicate
interface that contains a set of substations’ or voltage levels’ IDs.
The boolean test(Substation substation)
method returns true if the ID of the given substation is contained in the set of IDs, or at least one of the voltage levels IDs of the given substation is found in the set of IDs.
The boolean test(VoltageLevel voltageLevel)
method returns true if the ID of the given voltage level or the ID of its substation is found in the set of IDs.
Examples
The following example shows how to create new IdentifierNetworkPredicate
instances:
IdentifierNetworkPredicate p1 = new IdentifierNetworkPredicate(Arrays.asList("VL1", "VL2", "S1"));
IdentifierNetworkPredicate p2 = new IdentifierNetworkPredicate(Collections.singleton("VL1"));
There is also a more convenient way to create an instance of IdentifierNetworkPredicate
, using the of(String...)
static method:
NetworkPredicate p1 = IdentifierNetworkPredicate.of("VL1", "VL2", "S1");
NetworkPredicate p2 = IdentifierNetworkPredicate.of("VL1");
The list of voltage levels IDs can also be the result of a query:
NetworkPredicate p3 = new IdentifierNetworkPredicate(
network.getVoltageLevelStream()
.filter(vl -> vl.getNominalV() >= 225.0)
.filter(vl -> vl.getNominalV() <= 400.0)
.map(VoltageLevel::getId)
.collect(Collectors.toList()));
By nominal voltages
The com.powsybl.iidm.reducer.NominalVoltageNetworkPredicate
class is an implementation of the NetworkPredicate
interface that contains two double values that define a range of nominal voltages.
The boolean test(Substation substation)
method returns true if at least one of the voltage levels of the given substation has its nominal voltage inside the range.
The boolean test(Voltage substation)
method returns true if the given voltage level has its nominal voltage inside the range.
Examples
The following example shows how to create a new NominalVoltageNetworkPredicate
instance:
NetworkPredicate p1 = new NominalVoltageNetworkPredicate(0.0, Double.MAX_VALUE);
NetworkPredicate p2 = new NominalVoltageNetworkPredicate(225.0, 400.0);
Network reduction
The com.powsybl.iidm.reducer.NetworkReducer
interface provides one method, in charge of the reduction of the network:
public interface NetworkReducer {
void reduce(Network network);
}
PowSyBl provides a default implementation of this interface, but you can provide your own.
Default implementation
The com.powsybl.iidm.reducer.DefaultNetworkReducer
class is the PowSyBl implementation of the NetworkReducer
interface that replaces the lines in the border group by loads or dangling lines depending on the options, the two windings transformers and the HVDC lines by loads.
The three windings transformers are replaced by a load if only one connected voltage level is kept. If two out of three connected voltage levels are kept, the third one is automatically added by the DefaultNetworkReducer
to the voltage levels to keep.
Options
The network reduction can be configured by passing a com.powsybl.iidm.reducer.ReductionOptions
instance to the DefaultNetworkReducer
constructor.
withDanglingLines
This option defines whether the equipments in the border group are replaced by dangling lines or by loads. If this option is set to false
, which is the default value, the equipments are exclusively replaced by loads.
Examples
The following example shows how to create a new ReductionOptions
instance to do replacements by dangling lines.
ReductionOptions options = new ReductionOptions();
options.withDanglingLines(true);
Note that the ReductionOptions
class offers a fluent API that allows you to write code like this:
ReductionOptions options = new ReductionOptions()
.withDanglingLines(true);
Observers
The com.powsybl.iidm.reducer.NetworkReducerObserver
is an interface that allows to be notified each time an Identifiable
is removed or replaced. This interface provides several methods, one per Identifiable
sub class managed by the DefaultNetworkReducer
implementation. There are 2 types of events:
- a replace event, when an AC line, a two or three windings transformer or an HVDC line is replaced by a load or a danging line
- a remove event, when a substation, a voltage level, a line, a two or three windings transformer or an HVDC line is removed.
public interface NetworkReducerObserver {
void substationRemoved(Substation substation);
void voltageLevelRemoved(VoltageLevel voltageLevel);
void lineReplaced(Line line, Injection injection);
void lineRemoved(Line line);
void transformerReplaced(TwoWindingsTransformer transformer, Injection injection);
void transformerRemoved(TwoWindingsTransformer transformer);
void transformerReplaced(ThreeWindingsTransformer transformer, Injection injection);
void transformerRemoved(ThreeWindingsTransformer transformer);
void hvdcLineReplaced(HvdcLine hvdcLine, Injection injection);
void hvdcLineRemoved(HvdcLine hvdcLine);
}
PowSyBl provides a default implementation of the NetworkReducerObserver
that does nothing. Use it as a base class of your own implementation.
Examples
The following Java code shows how to reduce a network, using the default implementation:
Network network = Importers.loadNetwork("network.xiidm");
NetworkReducer reducer = NetworkReducer.builder()
.withNetworkPredicate(new NominalVoltageNetworkPredicate(225.0, 400.0))
.withDanglingLines(true)
.build();
reducer.reduce(network);
Groovy scripting
This example shows how to do a network reduction, using the run-script command.
First, we need a groovy script to do the reduction:
import com.powsybl.iidm.network.Network;
import com.powsybl.iidm.reducer.IdentifierNetworkPredicate;
import com.powsybl.iidm.reducer.NetworkReducer;
network = loadNetwork(args[0])
reducer = NetworkReducer.builder()
.withNetworkPredicate(IdentifierNetworkPredicate.of("P1"))
.build()
reducer.reduce(network)
saveNetwork("XIIDM", network, null, args[1])
See the groovy scripts documentation page for more information about loadNetwork
and saveNetwork
functions.
Then, we run the groovy-script command to apply the previous script to the network.xiidm
file, and then export the modified network to the network2.xiidm
file.
$> ./itools run-script --file extraction.groovy network.xiidm network2.xiidm
Import post-processor
This example shows how to automatically reduce networks when they are loaded, using the groovy post-processors with the same script as above. Note that the script will be applied each time a case file will be loaded. If you want to do it only once, use the previous method.
The script is a little different from the previous one:
import com.powsybl.iidm.reducer.IdentifierNetworkPredicate;
import com.powsybl.iidm.reducer.NetworkReducer;
reducer = NetworkReducer.builder()
.withNetworkPredicate(IdentifierNetworkPredicate.of("P1"))
.build()
reducer.reduce(network)
We have to configure the groovy post-processor in your configuration file:
import:
postProcessors: groovyScript
groovy-post-processor:
script: /home/user/network-reduction.groovy
For more information about the configuration of the groovy post-processor, please refer to this documentation page.
Then, we run the convert-network command:
$> ./itools convert-network --input-file /home/user/input.xiidm
--output-file /home/user/output.xiidm --output-format XIIDM
Observers
This example shows how to implement the NetworkReducerObserver
and log information each time an equipment is replaced.
NetworkReducerObserver observer = new DefaultNetworkReducerObserver() {
private static final Logger LOGGER = LoggerFactory.getLogger(NetworkReducerObserver.class);
@Override
public void lineReplaced(Line line, Injection injection) {
LOGGER.info("Line " + line.getId() + " has be replaced by a " + injection.getType());
}
@Override
public void transformerReplaced(TwoWindingsTransformer transformer, Injection injection) {
LOGGER.info("Transformer " + transformer.getId() + " has be replaced by a " + injection.getType());
}
@Override
public void transformerReplaced(ThreeWindingsTransformer transformer, Injection injection) {
LOGGER.info("Transformer " + transformer.getId() + " has be replaced by a " + injection.getType());
}
@Override
public void hvdcLineReplaced(HvdcLine hvdcLine, Injection injection) {
LOGGER.info("HVDC line " + hvdcLine.getId() + " has be replaced by a " + injection.getType());
}
};
NetworkReducer reducer = NetworkReducer.builder()
.withNetworkPredicate(new NominalVoltageNetworkPredicate(225.0, 400.0))
.withDanglingLines(true)
.withObservers(observer)
.build();
reducer.reduce(network);