Models documentation

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

@@ -38,14 +38,14 @@ class DynaWaltzDynamicModelGroovyExtension implements DynamicModelGroovyExtensio
 
     @Override
     List<String> getModelNames() {
-        builderConfigs.stream().flatMap { it -> it.libs}.toList() as List<String>
+        builderConfigs.stream().flatMap { it -> it.libs.libsInfo.stream()}.toList() as List<String>
     }
 
 
     @Override
     void load(Binding binding, Consumer<DynamicModel> consumer, ReportNode reportNode) {
         builderConfigs.forEach {conf ->
-            conf.libs.forEach {lib ->
+            conf.libs.libsName.forEach {lib ->
                 binding.setVariable(lib , { Closure<Void> closure ->
                     def cloned = closure.clone()
                     ModelBuilder<DynamicModel> builder = conf.builderConstructor

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

@@ -37,7 +37,7 @@ class DynaWaltzEventModelGroovyExtension implements EventModelGroovyExtension {
     }
 
     List<String> getModelNames() {
-        builderConfigs.collect {it.tag}
+        builderConfigs.collect {it.info}
     }
 
     @Override

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,6 @@
 import com.powsybl.dynamicsimulation.DynamicModel;
 import com.powsybl.iidm.network.Network;
 
-import java.util.Collection;
 import java.util.function.Supplier;
 
 /**
@@ -26,9 +25,9 @@ public interface ModelBuilderConstructor {
 
     private final String category;
     private final ModelBuilderConstructor builderConstructor;
-    private final Supplier<Collection<String>> libsSupplier;
+    private final Supplier<ModelConfigsLibsInfo> libsSupplier;
 
-    public BuilderConfig(String category, ModelBuilderConstructor builderConstructor, Supplier<Collection<String>> libsSupplier) {
+    public BuilderConfig(String category, ModelBuilderConstructor builderConstructor, Supplier<ModelConfigsLibsInfo> libsSupplier) {
         this.category = category;
         this.builderConstructor = builderConstructor;
         this.libsSupplier = libsSupplier;
@@ -42,7 +41,7 @@ public ModelBuilderConstructor getBuilderConstructor() {
         return builderConstructor;
     }
 
-    public Collection<String> getLibs() {
+    public ModelConfigsLibsInfo getLibs() {
         return libsSupplier.get();
     }
 }

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

@@ -23,10 +23,12 @@ public interface EventModelBuilderConstructor {
 
     private final EventModelBuilderConstructor builderConstructor;
     private final String tag;
+    private final String info;
 
-    public EventBuilderConfig(EventModelBuilderConstructor builderConstructor, String tag) {
+    public EventBuilderConfig(EventModelBuilderConstructor builderConstructor, String tag, String info) {
         this.builderConstructor = builderConstructor;
         this.tag = tag;
+        this.info = info;
     }
 
     public EventModelBuilderConstructor getBuilderConstructor() {
@@ -36,4 +38,8 @@ public EventModelBuilderConstructor getBuilderConstructor() {
     public String getTag() {
         return tag;
     }
+
+    public String getInfo() {
+        return 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) {
 
     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() {
@@ -55,4 +60,8 @@ public boolean hasProperty(String property) {
     public String name() {
         return alias == null ? lib : alias;
     }
+
+    public String getLibInfo() {
+        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

@@ -17,6 +17,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;
@@ -61,6 +64,11 @@ public final class ModelConfigLoaderImpl implements ModelConfigLoader {
             new BuilderConfig(WeccBuilder.CATEGORY, WeccBuilder::of, WeccBuilder::getSupportedLibs),
             new BuilderConfig(GridFormingConverterBuilder.CATEGORY, GridFormingConverterBuilder::of, GridFormingConverterBuilder::getSupportedLibs));
 
+    private static final Stream<EventBuilderConfig> EVENT_BUILDER_CONFIGS = Stream.of(
+            new EventBuilderConfig(EventActivePowerVariationBuilder::of, EventActivePowerVariationBuilder.TAG, EventActivePowerVariationBuilder.getInfo()),
+            new EventBuilderConfig(EventDisconnectionBuilder::of, EventDisconnectionBuilder.TAG, EventDisconnectionBuilder.getInfo()),
+            new EventBuilderConfig(NodeFaultEventBuilder::of, NodeFaultEventBuilder.TAG, NodeFaultEventBuilder.getInfo()));
+
     @Override
     public String getModelConfigFileName() {
         return MODEL_CONFIG_FILENAME;
@@ -70,4 +78,9 @@ public String getModelConfigFileName() {
     public Stream<BuilderConfig> loadBuilderConfigs() {
         return BUILDER_CONFIGS;
     }
+
+    @Override
+    public Stream<EventBuilderConfig> loadEventBuilderConfigs() {
+        return EVENT_BUILDER_CONFIGS;
+    }
 }

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

@@ -13,11 +13,12 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
+import java.util.stream.Collectors;
 
 /**
  * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
  */
-public class ModelConfigs {
+public class ModelConfigs implements ModelConfigsLibsInfo {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ModelConfigs.class);
 
@@ -43,10 +44,16 @@ public ModelConfig getModelConfig(String libName) {
         return modelConfigMap.get(libName);
     }
 
-    public Set<String> getSupportedLibs() {
+    @Override
+    public Set<String> getLibsName() {
         return modelConfigMap.keySet();
     }
 
+    @Override
+    public Set<String> getLibsInfo() {
+        return modelConfigMap.values().stream().map(ModelConfig::getLibInfo).collect(Collectors.toSet());
+    }
+
     void addModelConfigs(ModelConfigs modelConfigsToMerge) {
         modelConfigMap.putAll(modelConfigsToMerge.modelConfigMap);
         if (hasDefaultModelConfig() && modelConfigsToMerge.hasDefaultModelConfig()) {

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

@@ -11,9 +11,6 @@
 import com.powsybl.commons.report.ReportNode;
 import com.powsybl.dynamicsimulation.DynamicModel;
 import com.powsybl.dynamicsimulation.EventModel;
-import com.powsybl.dynawaltz.models.events.EventActivePowerVariationBuilder;
-import com.powsybl.dynawaltz.models.events.EventDisconnectionBuilder;
-import com.powsybl.dynawaltz.models.events.NodeFaultEventBuilder;
 import com.powsybl.iidm.network.Network;
 
 import java.util.HashMap;
@@ -32,14 +29,8 @@ public final class ModelConfigsHandler {
     private final Map<String, ModelConfigs> modelConfigsCat = new HashMap<>();
     private final List<BuilderConfig> builderConfigs;
     private final Map<String, BuilderConfig.ModelBuilderConstructor> builderConstructorByName = new HashMap<>();
-
-    private final List<EventBuilderConfig> eventBuilderConfigs = List.of(
-            new EventBuilderConfig(EventActivePowerVariationBuilder::of, EventActivePowerVariationBuilder.TAG),
-            new EventBuilderConfig(EventDisconnectionBuilder::of, EventDisconnectionBuilder.TAG),
-            new EventBuilderConfig(NodeFaultEventBuilder::of, NodeFaultEventBuilder.TAG));
-
-    private final Map<String, EventBuilderConfig.EventModelBuilderConstructor> eventBuilderConstructorByName =
-            eventBuilderConfigs.stream().collect(Collectors.toMap(EventBuilderConfig::getTag, EventBuilderConfig::getBuilderConstructor));
+    private final List<EventBuilderConfig> eventBuilderConfigs;
+    private final Map<String, EventBuilderConfig.EventModelBuilderConstructor> eventBuilderConstructorByName;
 
     private ModelConfigsHandler() {
         List<ModelConfigLoader> modelConfigLoaders = Lists.newArrayList(ServiceLoader.load(ModelConfigLoader.class));
@@ -50,8 +41,10 @@ private ModelConfigsHandler() {
                 })
         ));
         builderConfigs = modelConfigLoaders.stream().flatMap(ModelConfigLoader::loadBuilderConfigs).toList();
-        builderConfigs.forEach(bc -> modelConfigsCat.get(bc.getCategory()).getSupportedLibs()
+        builderConfigs.forEach(bc -> modelConfigsCat.get(bc.getCategory()).getLibsName()
                 .forEach(lib -> builderConstructorByName.put(lib, bc.getBuilderConstructor())));
+        eventBuilderConfigs = modelConfigLoaders.stream().flatMap(ModelConfigLoader::loadEventBuilderConfigs).toList();
+        eventBuilderConstructorByName = eventBuilderConfigs.stream().collect(Collectors.toMap(EventBuilderConfig::getTag, EventBuilderConfig::getBuilderConstructor));
     }
 
     public static ModelConfigsHandler getInstance() {

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

@@ -62,6 +62,7 @@ private static ModelConfig parseModelConfig(JsonParser parser) {
             String lib = null;
             String alias = null;
             String internalModelPrefix = null;
+            String doc = null;
             List<String> properties = Collections.emptyList();
         };
         JsonUtil.parseObject(parser, name ->
@@ -82,9 +83,13 @@ private static ModelConfig parseModelConfig(JsonParser parser) {
                     parsingContext.alias = parser.nextTextValue();
                     yield true;
                 }
+                case "doc" -> {
+                    parsingContext.doc = parser.nextTextValue();
+                    yield true;
+                }
                 default -> false;
             }
         );
-        return new ModelConfig(parsingContext.lib, parsingContext.alias, parsingContext.internalModelPrefix, parsingContext.properties);
+        return new ModelConfig(parsingContext.lib, parsingContext.alias, parsingContext.internalModelPrefix, parsingContext.properties, parsingContext.doc);
     }
 }

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

@@ -0,0 +1,20 @@
+/**
+ * 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;
+
+import java.util.Set;
+
+/**
+ * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
+ */
+public interface ModelConfigsLibsInfo {
+
+    Set<String> getLibsName();
+
+    Set<String> getLibsInfo();
+}

dynawaltz/src/main/java/com/powsybl/dynawaltz/models/automationsystems/TapChangerAutomationSystemBuilder.java

@@ -14,8 +14,6 @@
 import com.powsybl.iidm.network.Load;
 import com.powsybl.iidm.network.Network;
 
-import java.util.Set;
-
 /**
  * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
  */
@@ -48,8 +46,8 @@ public static TapChangerAutomationSystemBuilder of(Network network, String lib,
         return new TapChangerAutomationSystemBuilder(network, modelConfig, reportNode);
     }
 
-    public static Set<String> getSupportedLibs() {
-        return MODEL_CONFIGS.getSupportedLibs();
+    public static ModelConfigsLibsInfo getSupportedLibs() {
+        return MODEL_CONFIGS;
     }
 
     protected TapChangerAutomationSystemBuilder(Network network, ModelConfig modelConfig, ReportNode reportNode) {

dynawaltz/src/main/java/com/powsybl/dynawaltz/models/automationsystems/TapChangerBlockingAutomationSystemBuilder.java

@@ -50,8 +50,8 @@ public static TapChangerBlockingAutomationSystemBuilder of(Network network, Stri
         return new TapChangerBlockingAutomationSystemBuilder(network, modelConfig, reportNode);
     }
 
-    public static Set<String> getSupportedLibs() {
-        return MODEL_CONFIGS.getSupportedLibs();
+    public static ModelConfigsLibsInfo getSupportedLibs() {
+        return MODEL_CONFIGS;
     }
 
     protected TapChangerBlockingAutomationSystemBuilder(Network network, ModelConfig modelConfig, ReportNode reportNode) {

dynawaltz/src/main/java/com/powsybl/dynawaltz/models/automationsystems/UnderVoltageAutomationSystemBuilder.java

@@ -8,17 +8,11 @@
 package com.powsybl.dynawaltz.models.automationsystems;
 
 import com.powsybl.commons.report.ReportNode;
-import com.powsybl.dynawaltz.builders.BuilderEquipment;
-import com.powsybl.dynawaltz.builders.ModelConfig;
-import com.powsybl.dynawaltz.builders.ModelConfigsHandler;
-import com.powsybl.dynawaltz.builders.ModelConfigs;
-import com.powsybl.dynawaltz.builders.BuilderReports;
+import com.powsybl.dynawaltz.builders.*;
 import com.powsybl.iidm.network.Generator;
 import com.powsybl.iidm.network.IdentifiableType;
 import com.powsybl.iidm.network.Network;
 
-import java.util.Set;
-
 /**
  * @author Laurent Issertial {@literal <laurent.issertial at rte-france.com>}
  */
@@ -50,8 +44,8 @@ public static UnderVoltageAutomationSystemBuilder of(Network network, String lib
         return new UnderVoltageAutomationSystemBuilder(network, MODEL_CONFIGS.getModelConfig(lib), reportNode);
     }
 
-    public static Set<String> getSupportedLibs() {
-        return MODEL_CONFIGS.getSupportedLibs();
+    public static ModelConfigsLibsInfo getSupportedLibs() {
+        return MODEL_CONFIGS;
     }
 
     protected UnderVoltageAutomationSystemBuilder(Network network, ModelConfig modelConfig, ReportNode reportNode) {