Merge branch 'refs/heads/dev' into sh/#872-storage-documentation

Author: danielfeismann

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Enhancing `VoltageLevel` with `equals` method [#1063](https://github.com/ie3-institute/PowerSystemDataModel/issues/1063)
+- `ConnectorValidationUtils` checks if parallel devices is > 0 [#1077](https://github.com/ie3-institute/PowerSystemDataModel/issues/1077)
+- `GridContainerValidationUtils` checks the connectivity for all defined operation time intervals [#1091](https://github.com/ie3-institute/PowerSystemDataModel/issues/1091)
 
 ### Fixed
 - Fixed `MappingEntryies` not getting processed by adding `Getter` methods for record fields [#1084](https://github.com/ie3-institute/PowerSystemDataModel/issues/1084) 

build.gradle

@@ -5,7 +5,7 @@ plugins {
   id 'signing'
   id 'pmd' // code check, working on source code
   id 'com.diffplug.spotless' version '6.25.0' //code format
-  id 'com.github.spotbugs' version '6.0.14' // code check, working on byte code
+  id 'com.github.spotbugs' version '6.0.15' // code check, working on byte code
   id 'de.undercouch.download' version '5.6.0'
   id 'kr.motd.sphinx' version '2.10.1' // documentation generation
   id 'jacoco' // java code coverage plugin
@@ -73,7 +73,7 @@ dependencies {
   testImplementation 'org.junit.jupiter:junit-jupiter:5.10.2'
   testImplementation "org.spockframework:spock-core:2.3-groovy-$groovyVersion"
   testImplementation 'org.objenesis:objenesis:3.4' // Mock creation with constructor parameters
-  testImplementation 'net.bytebuddy:byte-buddy:1.14.15' // Mocks of classes
+  testImplementation 'net.bytebuddy:byte-buddy:1.14.17' // Mocks of classes
 
   // testcontainers (docker framework for testing)
   testImplementation "org.testcontainers:testcontainers:$testcontainersVersion"
@@ -95,7 +95,7 @@ dependencies {
 
   implementation 'commons-io:commons-io:2.16.1' // I/O functionalities
   implementation 'commons-codec:commons-codec:1.17.0' // needed by commons-compress
-  implementation 'org.apache.commons:commons-compress:1.26.1' // I/O functionalities
+  implementation 'org.apache.commons:commons-compress:1.26.2' // I/O functionalities
 }
 
 tasks.withType(JavaCompile) {

docs/readthedocs/io/ValidationUtils.md

@@ -11,6 +11,7 @@ The methods in ValidationUtils and subclasses can be used to check that objects
 The general validation checks:
 - if assigned values are valid, e.g. lines are not allowed to have negative lengths or the rated power factor of any unit must be between 0 and 1
 - furthermore, several connections are checked, e.g. that lines only connect nodes of the same voltage level or that the voltage levels indicated for the transformer sides match the voltage levels of the nodes they are connected to.
+- the connectivity of the given grid for all defined operation intervals
 
 The uniqueness validation checks if a collection of given objects are unique in either:
 - a specific field

src/main/java/edu/ie3/datamodel/utils/validation/ConnectorValidationUtils.java

@@ -65,6 +65,7 @@ protected static List<Try<Void, InvalidEntityException>> check(ConnectorInput co
 
     List<Try<Void, InvalidEntityException>> exceptions = new ArrayList<>();
     exceptions.add(connectsDifferentNodes(connector));
+    exceptions.add(lessThanOneParallelDevice(connector));
 
     // Further checks for subclasses
     if (LineInput.class.isAssignableFrom(connector.getClass())) {
@@ -443,6 +444,23 @@ private static Try<Void, InvalidEntityException> connectsDifferentNodes(
                 connectorInput));
   }
 
+  /**
+   * Check that the given connector has at least one parallel device.
+   *
+   * @param connectorInput to check
+   * @return a try
+   */
+  private static Try<Void, InvalidEntityException> lessThanOneParallelDevice(
+      ConnectorInput connectorInput) {
+    return Try.ofVoid(
+        connectorInput.getParallelDevices() < 1,
+        () ->
+            new InvalidEntityException(
+                connectorInput.getClass().getSimpleName()
+                    + " needs to have at least one parallel device",
+                connectorInput));
+  }
+
   /**
    * Check if subnets of connector's nodes are correct depending on if they should be equal or not
    *

src/main/java/edu/ie3/datamodel/utils/validation/GridContainerValidationUtils.java

@@ -8,19 +8,33 @@
 import static edu.ie3.datamodel.utils.validation.UniquenessValidationUtils.checkAssetUniqueness;
 import static edu.ie3.datamodel.utils.validation.UniquenessValidationUtils.checkUniqueEntities;
 
-import edu.ie3.datamodel.exceptions.*;
+import edu.ie3.datamodel.exceptions.DuplicateEntitiesException;
+import edu.ie3.datamodel.exceptions.InvalidEntityException;
+import edu.ie3.datamodel.exceptions.InvalidGridException;
+import edu.ie3.datamodel.exceptions.ValidationException;
+import edu.ie3.datamodel.models.OperationTime;
 import edu.ie3.datamodel.models.input.AssetInput;
 import edu.ie3.datamodel.models.input.MeasurementUnitInput;
 import edu.ie3.datamodel.models.input.NodeInput;
-import edu.ie3.datamodel.models.input.connector.*;
+import edu.ie3.datamodel.models.input.connector.ConnectorInput;
+import edu.ie3.datamodel.models.input.connector.LineInput;
+import edu.ie3.datamodel.models.input.connector.Transformer3WInput;
 import edu.ie3.datamodel.models.input.container.*;
 import edu.ie3.datamodel.models.input.graphics.GraphicInput;
 import edu.ie3.datamodel.models.input.system.SystemParticipantInput;
 import edu.ie3.datamodel.utils.ContainerUtils;
 import edu.ie3.datamodel.utils.Try;
-import edu.ie3.datamodel.utils.Try.*;
+import edu.ie3.datamodel.utils.Try.Failure;
+import edu.ie3.datamodel.utils.Try.Success;
+import java.time.ZonedDateTime;
 import java.util.*;
+import java.util.function.Predicate;
+import java.util.stream.Collectors;
 import java.util.stream.Stream;
+import org.jgrapht.Graph;
+import org.jgrapht.alg.connectivity.ConnectivityInspector;
+import org.jgrapht.graph.DefaultEdge;
+import org.jgrapht.graph.SimpleGraph;
 
 public class GridContainerValidationUtils extends ValidationUtils {
 
@@ -155,9 +169,105 @@ private GridContainerValidationUtils() {
               exceptions.add(MeasurementUnitValidationUtils.check(measurement));
             });
 
+    exceptions.addAll(checkConnectivity(rawGridElements));
+
     return exceptions;
   }
 
+  /**
+   * Checks the connectivity of the given grid for all defined {@link OperationTime}s. If every
+   * {@link AssetInput} is set to {@link OperationTime#notLimited()}, the connectivity is only
+   * checked once.
+   *
+   * @param rawGridElements to check
+   * @return a try
+   */
+  protected static List<Try<Void, InvalidGridException>> checkConnectivity(
+      RawGridElements rawGridElements) {
+    Set<ZonedDateTime> times =
+        rawGridElements.allEntitiesAsList().stream()
+            .map(AssetInput::getOperationTime)
+            .filter(OperationTime::isLimited)
+            .map(OperationTime::getOperationLimit)
+            .filter(Optional::isPresent)
+            .map(Optional::get)
+            .map(interval -> Set.of(interval.getLower(), interval.getUpper()))
+            .flatMap(Collection::stream)
+            .collect(Collectors.toSet());
+
+    if (times.isEmpty()) {
+      return List.of(checkConnectivity(rawGridElements, Optional.empty()));
+    } else {
+      return times.stream()
+          .sorted()
+          .map(time -> checkConnectivity(rawGridElements, Optional.of(time)))
+          .toList();
+    }
+  }
+
+  /**
+   * Checks if the given {@link RawGridElements} from a connected grid.
+   *
+   * @param rawGridElements to check
+   * @param time for operation filtering
+   * @return a try
+   */
+  protected static Try<Void, InvalidGridException> checkConnectivity(
+      RawGridElements rawGridElements, Optional<ZonedDateTime> time) {
+
+    Predicate<AssetInput> isInOperation =
+        assetInput -> time.map(assetInput::inOperationOn).orElse(true);
+
+    // build graph
+    Graph<UUID, DefaultEdge> graph = new SimpleGraph<>(DefaultEdge.class);
+
+    rawGridElements.getNodes().stream()
+        .filter(isInOperation)
+        .forEach(node -> graph.addVertex(node.getUuid()));
+    rawGridElements.getLines().stream()
+        .filter(isInOperation)
+        .forEach(
+            connector ->
+                graph.addEdge(connector.getNodeA().getUuid(), connector.getNodeB().getUuid()));
+    rawGridElements.getTransformer2Ws().stream()
+        .filter(isInOperation)
+        .forEach(
+            connector ->
+                graph.addEdge(connector.getNodeA().getUuid(), connector.getNodeB().getUuid()));
+    rawGridElements.getTransformer3Ws().stream()
+        .filter(isInOperation)
+        .forEach(
+            connector ->
+                graph.addEdge(connector.getNodeA().getUuid(), connector.getNodeB().getUuid()));
+    rawGridElements.getSwitches().stream()
+        .filter(isInOperation)
+        .forEach(
+            connector ->
+                graph.addEdge(connector.getNodeA().getUuid(), connector.getNodeB().getUuid()));
+
+    ConnectivityInspector<UUID, DefaultEdge> inspector = new ConnectivityInspector<>(graph);
+
+    if (inspector.isConnected()) {
+      return Success.empty();
+    } else {
+      List<Set<UUID>> sets = inspector.connectedSets();
+
+      List<UUID> unconnected =
+          sets.stream()
+              .max(Comparator.comparing(Set::size))
+              .map(set -> graph.vertexSet().stream().filter(v -> !set.contains(v)).toList())
+              .orElse(List.of());
+
+      String message = "The grid contains unconnected elements";
+
+      if (time.isPresent()) {
+        message += " for time " + time.get();
+      }
+
+      return Failure.of(new InvalidGridException(message + ": " + unconnected));
+    }
+  }
+
   /**
    * Checks the validity of each and every system participant. Moreover, it checks, if the systems
    * are connected to a node that is not in the provided set

src/test/groovy/edu/ie3/datamodel/utils/validation/ConnectorValidationUtilsTest.groovy

@@ -62,6 +62,23 @@ class ConnectorValidationUtilsTest extends Specification {
   OlmCharacteristicInput.CONSTANT_CHARACTERISTIC
   )
 
+  def "A ConnectorInput needs at least one parallel device"() {
+    when:
+    def actual = ConnectorValidationUtils.lessThanOneParallelDevice(invalidConnector)
+
+    then:
+    actual.failure
+    actual.exception.get().class == InvalidEntityException
+    actual.exception.get().message.contains(expectedMessage)
+
+    where:
+    invalidConnector                                                  || expectedMessage
+    GridTestData.lineFtoG.copy().parallelDevices(0).build()           || "LineInput needs to have at least one parallel device"
+    GridTestData.lineCtoD.copy().parallelDevices(-1).build()          || "LineInput needs to have at least one parallel device"
+    GridTestData.transformerBtoE.copy().parallelDevices(0).build()    || "Transformer2WInput needs to have at least one parallel device"
+    GridTestData.transformerAtoBtoC.copy().parallelDevices(0).build() || "Transformer3WInput needs to have at least one parallel device"
+  }
+
   def "ConnectorValidationUtils.checkLine() recognizes all potential errors for a line"() {
     when:
     List<Try<Void, InvalidEntityException>> exceptions = ConnectorValidationUtils.check(invalidLine).stream().filter { it -> it.failure }.toList()

src/test/groovy/edu/ie3/datamodel/utils/validation/GridContainerValidationUtilsTest.groovy

@@ -0,0 +1,106 @@
+/*
+ * © 2024. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+ */
+package edu.ie3.datamodel.utils.validation
+
+import edu.ie3.datamodel.exceptions.InvalidGridException
+import edu.ie3.datamodel.models.OperationTime
+import edu.ie3.datamodel.models.input.container.RawGridElements
+import edu.ie3.datamodel.utils.Try
+import edu.ie3.test.common.GridTestData as GTD
+import spock.lang.Shared
+import spock.lang.Specification
+
+import java.time.ZonedDateTime
+
+class GridContainerValidationUtilsTest extends Specification {
+  @Shared
+  private ZonedDateTime start
+
+  @Shared
+  private RawGridElements limitedElements
+
+  def setupSpec() {
+    start = ZonedDateTime.now()
+
+    def operationTimeFrame1 = OperationTime.builder().withStart(start).withEnd(start.plusHours(2)).build()
+    def operationTimeFrame2 = OperationTime.builder().withStart(start.plusHours(1)).withEnd(start.plusHours(3)).build()
+
+    def nodes = [
+      GTD.nodeC,
+      GTD.nodeD,
+      GTD.nodeE,
+      GTD.nodeF,
+      GTD.nodeG
+    ] as Set
+
+    def lines = [
+      GTD.lineCtoD.copy().operationTime(operationTimeFrame1).build(),
+      GTD.lineFtoG.copy().operationTime(operationTimeFrame2).build()
+    ] as Set
+
+    def transformers = [
+      GTD.transformerCtoF.copy().operationTime(operationTimeFrame1).build(),
+      GTD.transformerCtoE.copy().operationTime(operationTimeFrame2).build()
+    ] as Set
+
+    limitedElements = new RawGridElements(nodes, lines, transformers, [] as Set, [] as Set, [] as Set)
+  }
+
+  def "The GridContainerValidationUtils should check the connectivity for all operation intervals correctly"() {
+    when:
+    def actual = GridContainerValidationUtils.checkConnectivity(limitedElements)
+
+    then:
+    actual.size() == 4
+    actual.get(0).failure
+    actual.get(1).success
+    actual.get(2).success
+    actual.get(3).failure
+
+    actual.get(0).exception.get().message == "The grid contains unconnected elements for time " + start + ": " + [
+      GTD.nodeE.uuid,
+      GTD.nodeG.uuid
+    ]
+    actual.get(3).exception.get().message == "The grid contains unconnected elements for time " + start.plusHours(3) + ": " + [
+      GTD.nodeD.uuid,
+      GTD.nodeF.uuid,
+      GTD.nodeG.uuid
+    ]
+  }
+
+  def "The GridContainerValidationUtils should check the connectivity correctly"() {
+    when:
+    def actual = GridContainerValidationUtils.checkConnectivity(limitedElements, time as Optional<ZonedDateTime>)
+
+    then:
+    actual == expectedResult
+
+    where:
+    time                            || expectedResult
+    Optional.empty()                || Try.Success.empty()
+    Optional.of(start.plusHours(1)) || Try.Success.empty()
+  }
+
+  def "The GridContainerValidationUtils should return an exception if the grid is not properly connected"() {
+    when:
+    def actual = GridContainerValidationUtils.checkConnectivity(limitedElements, time as Optional<ZonedDateTime>)
+
+    then:
+    actual.exception.get().message == expectedException.message
+
+    where:
+    time                            || expectedException
+    Optional.of(start)              || new InvalidGridException("The grid contains unconnected elements for time " + start + ": " + [
+      GTD.nodeE.uuid,
+      GTD.nodeG.uuid
+    ])
+    Optional.of(start.plusHours(3)) || new InvalidGridException("The grid contains unconnected elements for time " + start.plusHours(3) + ": " + [
+      GTD.nodeD.uuid,
+      GTD.nodeF.uuid,
+      GTD.nodeG.uuid
+    ])
+  }
+}