Migration guide v2.6.0

Nodes consistency

The creation of a business object like a case involves several low level operations in the storage layer like: create node, add data, add dependency ...

We can have a consistency issue if another process query a node when its data update is in progress.

In this revision we've added a new concept called node consistency. From now, nodes are created inconsistent by default. User should call the appStorage method setConsistent(String nodeId) to mark a node as consistent. That allows us to activate 'business objects' when all updates on the node are done.

As a result of this evolution, the sequence of operations for business objects creation is: create node, (add/update) data then mark node as consistent.

Impact : before this version, the getChildNodes(String nodeId) method in AppStorage returns all child nodes, now that method returns only consistent nodes, if the parentNode is inconsistent a AfsStorageException will be thrown. Same logic for getTimeSeriesNames(String nodeId), getTimeSeriesDataVersions(String nodeId) ...

Exemple taken from ImportedCaseBuilder, At the end of the following operations setConsistent(String nodeId) should be called to mark the node as consistent (ready for use).

...
 // create project file
NodeInfo info = context.getStorage().createNode(context.getFolderInfo().getId(), name, ImportedCase.PSEUDO_CLASS, "", ImportedCase.VERSION, new NodeGenericMetadata()
// store case data
importer.copy(dataSource, new AppStorageDataSource(context.getStorage(), info.getId(), info.getName()));
// mark the node as consistent
context.getStorage().setConsistent(info.getId());
...

NB : some new commands have been added for migration purpose, see here

IIDM network creation

Previously an empty IIDM network could be created using NetworkFactory static method:

Network network = NetworkFactory.create("test", "code");

This method has been deprecated and has to be replaced by following code:

Network network = Network.create("test", "code");

WARNING: Network.create now always use default in memory implementation of IIDM even if another IIDM implementation is present in the classpath (through NetworkFactoryService).

ZipHelper

Previously we get zip bytes by using ZipHelper.archiveFilesToZipBytes():

byte[] bytes = ZipHelper.archiveFilesToZipBytes(baseDir, f1, f2);

This class is now deprecated and has to be replaced by ZipPackager:

byte[] bytes = ZipPackager.archiveFilesToZipBytes(baseDir, f1, f2);

Add target deadband in IIDM tap changers

targetDeadband has been added as an optional new attribute for IIDM RatioTapChanger and PhaseTapChanger. This is a deadband used with discrete control to avoid excessive update of tap changers while regulating. The units of those appropriate for the mode.

Hence, new generated XIIDM files may contain this attribute and will not be readable by XMLImporter from an older version. Therefore, be careful to update the version of your importer if you chose to update the version of XMLExporter.

MPI

All the modules relatives to MPI computation have been moved to the new powsybl-hpc repository. This introduces some breaking changes:

itools-packager

The itools-packager plugin aims to create a distribution based on the itools script. The parameters mpiTasks and mpiHosts are not supported anymore and should be removed from pom.xml files.

itools

The --parallel option of itools has been removed. To run MPI program, you should use itools-mpi script, available in powsybl-hpc repository. The MPI configuration should be moved from itools.conf to the new itools-mpi.conf file.

iTools distribution

To create a complete iTools distribution (core + mpi), you have to compile and install both projects to the same installation directory:

$> cd powsybl-core
$> ./install --prefix=<INSTALL_DIR>
$> cd ../powsybl-hpc
$> ./install --prefix=<INSTALL_DIR>

If you prefer, you can also do it manually using maven:

$> cd powsybl-core
$> mvn install
$> cp -rp distribution-core/target/powsybl <INSTALL_DIR>
$> cd ../powsybl-hpc
$> mvn package
$> cp -rp distribution-hpc/target/powsybl <INSTALL_DIR>

IIDM NetworkListener

In order to optimize computation, it will be decided to replace String by Supplier<String> in AbstractConnectable.notifyUpdate methods.
Indeed, no need to build attribut parameter if no listener is present.
As example in AbstractTerminal.setP(double p):

getConnectable().notifyUpdate(() -> "p" + (num != -1 ? num : ""), oldValue, p);

The string concatanation take time for nothing if no listener has been add.

AbstractConnectable

Currently we notify changes by using methods:

void notifyUpdate(String attribute, Object oldValue, Object newValue) {
void notifyUpdate(String attribute, String variantId, Object oldValue, Object newValue)

New methods are available now:

void notifyUpdate(Supplier<String> attribute, Object oldValue, Object newValue) {
void notifyUpdate(Supplier<String> attribute, String variantId, Object oldValue, Object newValue)

NetworkListenerList