Skip to content

Commit

Permalink
Models documentation (#367)
Browse files Browse the repository at this point in the history 
* Add model documentation in models.json
* Return formatted doc in DynamicModelGroovyExtension::getModelNames
* Add event models documentation
* Move ModelConfigsHandler::eventBuilderConfigs in ModelConfigLoader
* Rename lib to modelName
* Add ModelInfo interface
* Rename tag to modelName/name
* Add EventModelInfo

Signed-off-by: lisrte <[email protected]>
  • Loading branch information
@Lisrte
Lisrte authored Jul 17, 2024
1 parent 7df9e1b commit b510b19
Show file tree
Hide file tree
Showing 48 changed files with 502 additions and 426 deletions.
9 changes: 5 additions & 4 deletions ...dsl/src/main/groovy/com/powsybl/dynawaltz/dsl/DynaWaltzDynamicModelGroovyExtension.groovy
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
6 changes: 3 additions & 3 deletions ...z-dsl/src/main/groovy/com/powsybl/dynawaltz/dsl/DynaWaltzEventModelGroovyExtension.groovy
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
8 changes: 8 additions & 0 deletions dynawaltz-dsl/src/test/java/com/powsybl/dynawaltz/dsl/DynamicModelsSupplierTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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) {
Expand Down
8 changes: 8 additions & 0 deletions dynawaltz-dsl/src/test/java/com/powsybl/dynawaltz/dsl/EventModelsSupplierTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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) {
Expand Down
12 changes: 6 additions & 6 deletions dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/BuilderConfig.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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<Collection<ModelInfo>> modelInfosSupplier;

public BuilderConfig(String category, ModelBuilderConstructor builderConstructor, Supplier<Collection<String>> libsSupplier) {
public BuilderConfig(String category, ModelBuilderConstructor builderConstructor, Supplier<Collection<ModelInfo>> modelInfosSupplier) {
this.category = category;
this.builderConstructor = builderConstructor;
this.libsSupplier = libsSupplier;
this.modelInfosSupplier = modelInfosSupplier;
}

public String getCategory() {
Expand All @@ -42,7 +42,7 @@ public ModelBuilderConstructor getBuilderConstructor() {
return builderConstructor;
}

public Collection<String> getLibs() {
return libsSupplier.get();
public Collection<ModelInfo> getModelInfos() {
return modelInfosSupplier.get();
}
}
6 changes: 3 additions & 3 deletions dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/BuilderReports.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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();
}
Expand Down
10 changes: 5 additions & 5 deletions dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/EventBuilderConfig.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
}
23 changes: 23 additions & 0 deletions dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/EventModelInfo.java
View file
Original file line number Diff line number Diff line change
@@ -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);
}
}
15 changes: 13 additions & 2 deletions dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/ModelConfig.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand All @@ -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 : "");
}
}
4 changes: 4 additions & 0 deletions dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/ModelConfigLoader.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,4 +40,8 @@ default Map<String, ModelConfigs> loadModelConfigs() {
}

Stream<BuilderConfig> loadBuilderConfigs();

default Stream<EventBuilderConfig> loadEventBuilderConfigs() {
return Stream.empty();
}
}
65 changes: 39 additions & 26 deletions dynawaltz/src/main/java/com/powsybl/dynawaltz/builders/ModelConfigLoaderImpl.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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() {
Expand All @@ -74,4 +82,9 @@ public String getModelConfigFileName() {
public Stream<BuilderConfig> loadBuilderConfigs() {
return BUILDER_CONFIGS;
}

@Override
public Stream<EventBuilderConfig> loadEventBuilderConfigs() {
return EVENT_BUILDER_CONFIGS;
}
}
Loading

0 comments on commit b510b19

Please sign in to comment.