Models documentation

dynawaltz-dsl/src/main/groovy/com/powsybl/dynawaltz/dsl/DynaWaltzDynamicModelGroovyExtension.groovy

@@ -38,18 +38,19 @@ class DynaWaltzDynamicModelGroovyExtension implements DynamicModelGroovyExtensio
 
     @Override
     List<String> getModelNames() {
-        builderConfigs.stream().flatMap { it -> it.libs}.toList() as List<String>
+        builderConfigs.stream().flatMap { it -> it.modelInfos.stream()}.map { i -> i.formattedInfo()}.toList() as List<String>
     }
 
 
     @Override
     void load(Binding binding, Consumer<DynamicModel> consumer, ReportNode reportNode) {
         builderConfigs.forEach {conf ->
-            conf.libs.forEach {lib ->
-                binding.setVariable(lib , { Closure<Void> closure ->
+            conf.modelInfos.forEach { modelInfo ->
+                def modelName = modelInfo.name()
+                binding.setVariable(modelName , { Closure<Void> closure ->
                     def cloned = closure.clone()
                     ModelBuilder<DynamicModel> builder = conf.builderConstructor
-                            .createBuilder(binding.getVariable("network") as Network, lib, DslReports.createModelBuilderReportNode(reportNode, lib))
+                            .createBuilder(binding.getVariable("network") as Network, modelName, DslReports.createModelBuilderReportNode(reportNode, modelName))
                     cloned.delegate = builder
                     cloned()
                     builder.build()?.tap {

dynawaltz-dsl/src/main/groovy/com/powsybl/dynawaltz/dsl/DynaWaltzEventModelGroovyExtension.groovy

@@ -37,17 +37,17 @@ class DynaWaltzEventModelGroovyExtension implements EventModelGroovyExtension {
     }
 
     List<String> getModelNames() {
-        builderConfigs.collect {it.tag}
+        builderConfigs.collect {it.eventModelInfo.formattedInfo()}
     }
 
     @Override
     void load(Binding binding, Consumer<EventModel> consumer, ReportNode reportNode) {
         builderConfigs.forEach {
-            binding.setVariable(it.tag, { Closure<Void> closure ->
+            binding.setVariable(it.eventModelInfo.name(), { Closure<Void> closure ->
                 def cloned = closure.clone()
                 ModelBuilder<EventModel> builder = it.builderConstructor.createBuilder(
                         binding.getVariable("network") as Network,
-                        DslReports.createModelBuilderReportNode(reportNode, it.tag))
+                        DslReports.createModelBuilderReportNode(reportNode, it.eventModelInfo.name()))
                 cloned.delegate = builder
                 cloned()
                 builder.build()?.tap {

dynawaltz-dsl/src/test/java/com/powsybl/dynawaltz/dsl/DynamicModelsSupplierTest.java

@@ -39,6 +39,7 @@
 import com.powsybl.iidm.network.test.FourSubstationsNodeBreakerFactory;
 import com.powsybl.iidm.network.test.HvdcTestNetwork;
 import com.powsybl.iidm.network.test.SvcTestCaseFactory;
+import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
 import org.junit.jupiter.params.provider.MethodSource;
@@ -56,6 +57,13 @@ class DynamicModelsSupplierTest extends AbstractModelSupplierTest {
 
     private static final List<DynamicModelGroovyExtension> EXTENSIONS = GroovyExtension.find(DynamicModelGroovyExtension.class, DynaWaltzProvider.NAME);
 
+    @Test
+    void testLibsInfo() {
+        for (DynamicModelGroovyExtension extension : EXTENSIONS) {
+            assertNotNull(extension.getModelNames());
+        }
+    }
+
     @ParameterizedTest(name = "{0}")
     @MethodSource("provideEquipmentModelData")
     void testEquipmentDynamicModels(String groovyScriptName, Class<? extends EquipmentBlackBoxModel> modelClass, Network network, String staticId, String dynamicId, String parameterId, String lib) {

dynawaltz-dsl/src/test/java/com/powsybl/dynawaltz/dsl/EventModelsSupplierTest.java

@@ -19,6 +19,7 @@
 import com.powsybl.iidm.network.test.EurostagTutorialExample1Factory;
 import com.powsybl.iidm.network.test.HvdcTestNetwork;
 import com.powsybl.iidm.network.test.SvcTestCaseFactory;
+import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
 import org.junit.jupiter.params.provider.MethodSource;
@@ -36,6 +37,13 @@ class EventModelsSupplierTest extends AbstractModelSupplierTest {
 
     protected static final List<EventModelGroovyExtension> EXTENSIONS = GroovyExtension.find(EventModelGroovyExtension.class, DynaWaltzProvider.NAME);
 
+    @Test
+    void testLibsInfo() {
+        for (EventModelGroovyExtension extension : EXTENSIONS) {
+            assertNotNull(extension.getModelNames());
+        }
+    }
+
     @ParameterizedTest(name = "{0}")
     @MethodSource("provideEventModelData")
     void testEventModels(String groovyScriptName, Class<? extends AbstractEvent> modelClass, Network network, String equipmentStaticId, String dynamicId, String lib, double startTime) {

dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/BuilderConfig.java

@@ -11,7 +11,7 @@
 import com.powsybl.dynamicsimulation.DynamicModel;
 import com.powsybl.iidm.network.Network;
 
-import java.util.Collection;
+import java.util.Set;
 import java.util.function.Supplier;
 
 /**
@@ -21,17 +21,17 @@ public class BuilderConfig {
 
     @FunctionalInterface
     public interface ModelBuilderConstructor {
-        ModelBuilder<DynamicModel> createBuilder(Network network, String lib, ReportNode reportNode);
+        ModelBuilder<DynamicModel> createBuilder(Network network, String modelName, ReportNode reportNode);
     }
 
     private final String category;
     private final ModelBuilderConstructor builderConstructor;
-    private final Supplier<Collection<String>> libsSupplier;
+    private final Supplier<Set<ModelInfo>> modelInfosSupplier;
 
-    public BuilderConfig(String category, ModelBuilderConstructor builderConstructor, Supplier<Collection<String>> libsSupplier) {
+    public BuilderConfig(String category, ModelBuilderConstructor builderConstructor, Supplier<Set<ModelInfo>> modelInfosSupplier) {
         this.category = category;
         this.builderConstructor = builderConstructor;
-        this.libsSupplier = libsSupplier;
+        this.modelInfosSupplier = modelInfosSupplier;
     }
 
     public String getCategory() {
@@ -42,7 +42,7 @@ public ModelBuilderConstructor getBuilderConstructor() {
         return builderConstructor;
     }
 
-    public Collection<String> getLibs() {
-        return libsSupplier.get();
+    public Set<ModelInfo> getModelInfos() {
+        return modelInfosSupplier.get();
     }
 }

dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/BuilderReports.java

@@ -29,11 +29,11 @@ public static void reportBuilderNotFound(ReportNode reportNode, String lib) {
                 .add();
     }
 
-    public static void reportLibNotFound(ReportNode reportNode, String builderName, String lib) {
+    public static void reportModelNotFound(ReportNode reportNode, String builderName, String modelName) {
         reportNode.newReportNode()
-                .withMessageTemplate("libNotFound", "Library ${lib} not found for ${builderName}")
+                .withMessageTemplate("modelNotFound", "Model ${lib} not found for ${builderName}")
                 .withUntypedValue("builderName", builderName)
-                .withUntypedValue("lib", lib)
+                .withUntypedValue("modelName", modelName)
                 .withSeverity(TypedValue.INFO_SEVERITY)
                 .add();
     }

dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/EventBuilderConfig.java

@@ -22,18 +22,18 @@ public interface EventModelBuilderConstructor {
     }
 
     private final EventModelBuilderConstructor builderConstructor;
-    private final String tag;
+    private final EventModelInfo eventModelInfo;
 
-    public EventBuilderConfig(EventModelBuilderConstructor builderConstructor, String tag) {
+    public EventBuilderConfig(EventModelBuilderConstructor builderConstructor, EventModelInfo eventModelInfo) {
         this.builderConstructor = builderConstructor;
-        this.tag = tag;
+        this.eventModelInfo = eventModelInfo;
     }
 
     public EventModelBuilderConstructor getBuilderConstructor() {
         return builderConstructor;
     }
 
-    public String getTag() {
-        return tag;
+    public EventModelInfo getEventModelInfo() {
+        return eventModelInfo;
     }
 }

dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/EventModelInfo.java

@@ -0,0 +1,23 @@
+/**
+ * Copyright (c) 2024, RTE (http://www.rte-france.com/)
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+package com.powsybl.dynawaltz.builders;
+
+/**
+ * @param name Model name
+ * @param info Definition of the event model
+ * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
+ */
+public record EventModelInfo(String name, String info) {
+
+    /**
+     * Concatenation of name and doc
+     */
+    public String formattedInfo() {
+        return String.format("%s: %s", name, info);
+    }
+}

dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/ModelConfig.java

@@ -13,19 +13,24 @@
 /**
  * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
  */
-public record ModelConfig(String lib, String alias, String internalModelPrefix, List<String> properties) {
+public record ModelConfig(String lib, String alias, String internalModelPrefix, List<String> properties, String doc) implements ModelInfo {
 
     private static final String CONTROLLABLE_PROPERTY = "CONTROLLABLE";
     private static final String DANGLING_PROPERTY = "DANGLING";
     private static final String SYNCHRONIZED_PROPERTY = "SYNCHRONIZED";
     private static final String TRANSFORMER_PROPERTY = "TRANSFORMER";
     private static final String AUXILIARY_PROPERTY = "AUXILIARY";
 
-    public ModelConfig(String lib, String alias, String internalModelPrefix, List<String> properties) {
+    public ModelConfig(String lib, String alias, String internalModelPrefix, List<String> properties, String doc) {
         this.lib = Objects.requireNonNull(lib);
         this.alias = alias;
         this.internalModelPrefix = internalModelPrefix;
         this.properties = Objects.requireNonNull(properties);
+        this.doc = doc;
+    }
+
+    public ModelConfig(String lib, String alias, String internalModelPrefix, List<String> properties) {
+        this(lib, alias, internalModelPrefix, properties, null);
     }
 
     public boolean isControllable() {
@@ -52,7 +57,13 @@ public boolean hasProperty(String property) {
         return properties.contains(property);
     }
 
+    @Override
     public String name() {
         return alias == null ? lib : alias;
     }
+
+    @Override
+    public String formattedInfo() {
+        return name() + (alias != null ? " (" + lib + ")" : "") + (doc != null ? ": " + doc : "");
+    }
 }

dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/ModelConfigLoader.java

@@ -40,4 +40,8 @@ default Map<String, ModelConfigs> loadModelConfigs() {
     }
 
     Stream<BuilderConfig> loadBuilderConfigs();
+
+    default Stream<EventBuilderConfig> loadEventBuilderConfigs() {
+        return Stream.empty();
+    }
 }

dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/ModelConfigLoaderImpl.java

@@ -18,6 +18,9 @@
 import com.powsybl.dynawaltz.models.automationsystems.phaseshifters.PhaseShifterPAutomationSystemBuilder;
 import com.powsybl.dynawaltz.models.buses.InfiniteBusBuilder;
 import com.powsybl.dynawaltz.models.buses.StandardBusBuilder;
+import com.powsybl.dynawaltz.models.events.EventActivePowerVariationBuilder;
+import com.powsybl.dynawaltz.models.events.EventDisconnectionBuilder;
+import com.powsybl.dynawaltz.models.events.NodeFaultEventBuilder;
 import com.powsybl.dynawaltz.models.generators.*;
 import com.powsybl.dynawaltz.models.hvdc.HvdcPBuilder;
 import com.powsybl.dynawaltz.models.hvdc.HvdcVscBuilder;
@@ -38,32 +41,37 @@ public final class ModelConfigLoaderImpl implements ModelConfigLoader {
     private static final String MODEL_CONFIG_FILENAME = "models.json";
 
     private static final Stream<BuilderConfig> BUILDER_CONFIGS = Stream.of(
-            new BuilderConfig(DynamicOverloadManagementSystemBuilder.CATEGORY, DynamicOverloadManagementSystemBuilder::of, DynamicOverloadManagementSystemBuilder::getSupportedLibs),
-            new BuilderConfig(DynamicTwoLevelsOverloadManagementSystemBuilder.CATEGORY, DynamicTwoLevelsOverloadManagementSystemBuilder::of, DynamicTwoLevelsOverloadManagementSystemBuilder::getSupportedLibs),
-            new BuilderConfig(TapChangerAutomationSystemBuilder.CATEGORY, TapChangerAutomationSystemBuilder::of, TapChangerAutomationSystemBuilder::getSupportedLibs),
-            new BuilderConfig(TapChangerBlockingAutomationSystemBuilder.CATEGORY, TapChangerBlockingAutomationSystemBuilder::of, TapChangerBlockingAutomationSystemBuilder::getSupportedLibs),
-            new BuilderConfig(UnderVoltageAutomationSystemBuilder.CATEGORY, UnderVoltageAutomationSystemBuilder::of, UnderVoltageAutomationSystemBuilder::getSupportedLibs),
-            new BuilderConfig(PhaseShifterPAutomationSystemBuilder.CATEGORY, PhaseShifterPAutomationSystemBuilder::of, PhaseShifterPAutomationSystemBuilder::getSupportedLibs),
-            new BuilderConfig(PhaseShifterIAutomationSystemBuilder.CATEGORY, PhaseShifterIAutomationSystemBuilder::of, PhaseShifterIAutomationSystemBuilder::getSupportedLibs),
-            new BuilderConfig(PhaseShifterBlockingIAutomationSystemBuilder.CATEGORY, PhaseShifterBlockingIAutomationSystemBuilder::of, PhaseShifterBlockingIAutomationSystemBuilder::getSupportedLibs),
-            new BuilderConfig(StandardBusBuilder.CATEGORY, StandardBusBuilder::of, StandardBusBuilder::getSupportedLibs),
-            new BuilderConfig(InfiniteBusBuilder.CATEGORY, InfiniteBusBuilder::of, InfiniteBusBuilder::getSupportedLibs),
-            new BuilderConfig(TransformerFixedRatioBuilder.CATEGORY, TransformerFixedRatioBuilder::of, TransformerFixedRatioBuilder::getSupportedLibs),
-            new BuilderConfig(LineBuilder.CATEGORY, LineBuilder::of, LineBuilder::getSupportedLibs),
-            new BuilderConfig(HvdcVscBuilder.CATEGORY, HvdcVscBuilder::of, HvdcVscBuilder::getSupportedLibs),
-            new BuilderConfig(HvdcPBuilder.CATEGORY, HvdcPBuilder::of, HvdcPBuilder::getSupportedLibs),
-            new BuilderConfig(BaseLoadBuilder.CATEGORY, BaseLoadBuilder::of, BaseLoadBuilder::getSupportedLibs),
-            new BuilderConfig(LoadOneTransformerBuilder.CATEGORY, LoadOneTransformerBuilder::of, LoadOneTransformerBuilder::getSupportedLibs),
-            new BuilderConfig(LoadOneTransformerTapChangerBuilder.CATEGORY, LoadOneTransformerTapChangerBuilder::of, LoadOneTransformerTapChangerBuilder::getSupportedLibs),
-            new BuilderConfig(LoadTwoTransformersBuilder.CATEGORY, LoadTwoTransformersBuilder::of, LoadTwoTransformersBuilder::getSupportedLibs),
-            new BuilderConfig(LoadTwoTransformersTapChangersBuilder.CATEGORY, LoadTwoTransformersTapChangersBuilder::of, LoadTwoTransformersTapChangersBuilder::getSupportedLibs),
-            new BuilderConfig(BaseShuntBuilder.CATEGORY, BaseShuntBuilder::of, BaseShuntBuilder::getSupportedLibs),
-            new BuilderConfig(BaseStaticVarCompensatorBuilder.CATEGORY, BaseStaticVarCompensatorBuilder::of, BaseStaticVarCompensatorBuilder::getSupportedLibs),
-            new BuilderConfig(GeneratorFictitiousBuilder.CATEGORY, GeneratorFictitiousBuilder::of, GeneratorFictitiousBuilder::getSupportedLibs),
-            new BuilderConfig(SynchronizedGeneratorBuilder.CATEGORY, SynchronizedGeneratorBuilder::of, SynchronizedGeneratorBuilder::getSupportedLibs),
-            new BuilderConfig(SynchronousGeneratorBuilder.CATEGORY, SynchronousGeneratorBuilder::of, SynchronousGeneratorBuilder::getSupportedLibs),
-            new BuilderConfig(WeccBuilder.CATEGORY, WeccBuilder::of, WeccBuilder::getSupportedLibs),
-            new BuilderConfig(GridFormingConverterBuilder.CATEGORY, GridFormingConverterBuilder::of, GridFormingConverterBuilder::getSupportedLibs));
+            new BuilderConfig(DynamicOverloadManagementSystemBuilder.CATEGORY, DynamicOverloadManagementSystemBuilder::of, DynamicOverloadManagementSystemBuilder::getSupportedModelInfos),
+            new BuilderConfig(DynamicTwoLevelsOverloadManagementSystemBuilder.CATEGORY, DynamicTwoLevelsOverloadManagementSystemBuilder::of, DynamicTwoLevelsOverloadManagementSystemBuilder::getSupportedModelInfos),
+            new BuilderConfig(TapChangerAutomationSystemBuilder.CATEGORY, TapChangerAutomationSystemBuilder::of, TapChangerAutomationSystemBuilder::getSupportedModelInfos),
+            new BuilderConfig(TapChangerBlockingAutomationSystemBuilder.CATEGORY, TapChangerBlockingAutomationSystemBuilder::of, TapChangerBlockingAutomationSystemBuilder::getSupportedModelInfos),
+            new BuilderConfig(UnderVoltageAutomationSystemBuilder.CATEGORY, UnderVoltageAutomationSystemBuilder::of, UnderVoltageAutomationSystemBuilder::getSupportedModelInfos),
+            new BuilderConfig(PhaseShifterPAutomationSystemBuilder.CATEGORY, PhaseShifterPAutomationSystemBuilder::of, PhaseShifterPAutomationSystemBuilder::getSupportedModelInfos),
+            new BuilderConfig(PhaseShifterIAutomationSystemBuilder.CATEGORY, PhaseShifterIAutomationSystemBuilder::of, PhaseShifterIAutomationSystemBuilder::getSupportedModelInfos),
+            new BuilderConfig(PhaseShifterBlockingIAutomationSystemBuilder.CATEGORY, PhaseShifterBlockingIAutomationSystemBuilder::of, PhaseShifterBlockingIAutomationSystemBuilder::getSupportedModelInfos),
+            new BuilderConfig(StandardBusBuilder.CATEGORY, StandardBusBuilder::of, StandardBusBuilder::getSupportedModelInfos),
+            new BuilderConfig(InfiniteBusBuilder.CATEGORY, InfiniteBusBuilder::of, InfiniteBusBuilder::getSupportedModelInfos),
+            new BuilderConfig(TransformerFixedRatioBuilder.CATEGORY, TransformerFixedRatioBuilder::of, TransformerFixedRatioBuilder::getSupportedModelInfos),
+            new BuilderConfig(LineBuilder.CATEGORY, LineBuilder::of, LineBuilder::getSupportedModelInfos),
+            new BuilderConfig(HvdcVscBuilder.CATEGORY, HvdcVscBuilder::of, HvdcVscBuilder::getSupportedModelInfos),
+            new BuilderConfig(HvdcPBuilder.CATEGORY, HvdcPBuilder::of, HvdcPBuilder::getSupportedModelInfos),
+            new BuilderConfig(BaseLoadBuilder.CATEGORY, BaseLoadBuilder::of, BaseLoadBuilder::getSupportedModelInfos),
+            new BuilderConfig(LoadOneTransformerBuilder.CATEGORY, LoadOneTransformerBuilder::of, LoadOneTransformerBuilder::getSupportedModelInfos),
+            new BuilderConfig(LoadOneTransformerTapChangerBuilder.CATEGORY, LoadOneTransformerTapChangerBuilder::of, LoadOneTransformerTapChangerBuilder::getSupportedModelInfos),
+            new BuilderConfig(LoadTwoTransformersBuilder.CATEGORY, LoadTwoTransformersBuilder::of, LoadTwoTransformersBuilder::getSupportedModelInfos),
+            new BuilderConfig(LoadTwoTransformersTapChangersBuilder.CATEGORY, LoadTwoTransformersTapChangersBuilder::of, LoadTwoTransformersTapChangersBuilder::getSupportedModelInfos),
+            new BuilderConfig(BaseShuntBuilder.CATEGORY, BaseShuntBuilder::of, BaseShuntBuilder::getSupportedModelInfos),
+            new BuilderConfig(BaseStaticVarCompensatorBuilder.CATEGORY, BaseStaticVarCompensatorBuilder::of, BaseStaticVarCompensatorBuilder::getSupportedModelInfos),
+            new BuilderConfig(GeneratorFictitiousBuilder.CATEGORY, GeneratorFictitiousBuilder::of, GeneratorFictitiousBuilder::getSupportedModelInfos),
+            new BuilderConfig(SynchronizedGeneratorBuilder.CATEGORY, SynchronizedGeneratorBuilder::of, SynchronizedGeneratorBuilder::getSupportedModelInfos),
+            new BuilderConfig(SynchronousGeneratorBuilder.CATEGORY, SynchronousGeneratorBuilder::of, SynchronousGeneratorBuilder::getSupportedModelInfos),
+            new BuilderConfig(WeccBuilder.CATEGORY, WeccBuilder::of, WeccBuilder::getSupportedModelInfos),
+            new BuilderConfig(GridFormingConverterBuilder.CATEGORY, GridFormingConverterBuilder::of, GridFormingConverterBuilder::getSupportedModelInfos));
+
+    private static final Stream<EventBuilderConfig> EVENT_BUILDER_CONFIGS = Stream.of(
+            new EventBuilderConfig(EventActivePowerVariationBuilder::of, EventActivePowerVariationBuilder.getEventModelInfo()),
+            new EventBuilderConfig(EventDisconnectionBuilder::of, EventDisconnectionBuilder.getEventModelInfo()),
+            new EventBuilderConfig(NodeFaultEventBuilder::of, NodeFaultEventBuilder.getEventModelInfo()));
 
     @Override
     public String getModelConfigFileName() {
@@ -74,4 +82,9 @@ public String getModelConfigFileName() {
     public Stream<BuilderConfig> loadBuilderConfigs() {
         return BUILDER_CONFIGS;
     }
+
+    @Override
+    public Stream<EventBuilderConfig> loadEventBuilderConfigs() {
+        return EVENT_BUILDER_CONFIGS;
+    }
 }