Merge pull request #1098 from ie3-institute/ms/#1097-add-congestion-r…

…esult

Adding `CongestionResult`.

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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)
+- Implemented a `CongestionResult` [#1097](https://github.com/ie3-institute/PowerSystemDataModel/issues/1097)
 
 ### Fixed
 - Fixed `MappingEntryies` not getting processed by adding `Getter` methods for record fields [#1084](https://github.com/ie3-institute/PowerSystemDataModel/issues/1084) 

docs/readthedocs/models/models.md

@@ -185,6 +185,7 @@ result/grid/switch
 result/grid/transformer
 result/grid/transformer2w
 result/grid/transformer3w
+result/grid/congestion
 ```
 
 ### Participant Related Models

docs/readthedocs/models/result/grid/congestion.md

@@ -0,0 +1,51 @@
+(congestion-result)=
+
+# Congestion
+
+Representation of a congestion result for a given subnet.
+
+## Attributes, Units and Remarks
+
+```{eval-rst}
+.. list-table::
+   :widths: 33 33 33
+   :header-rows: 1
+
+
+   * - Attribute
+     - Unit
+     - Remarks
+
+   * - time
+     - ZonedDateTime
+     - date and time for the produced result
+   
+   * - subgrid
+     - --
+     - Sub grid number
+
+   * - vMin
+     - p.u.
+     - minimal voltage of the subnet
+
+   * - vMax
+     - p.u.
+     - maximal voltage of the subnet
+
+   * - voltage
+     - --
+     - Boolean indicator, if a voltage congestion occurred
+
+   * - line
+     - --
+     - Boolean indicator, if a line congestion occurred
+
+   * - transformer
+     - --
+     - Boolean indicator, if a transformer congestion occurred
+```
+
+## Caveats
+
+Nothing - at least not known.
+If you found something, please contact us!

src/main/java/edu/ie3/datamodel/io/factory/result/CongestionResultFactory.java

@@ -0,0 +1,52 @@
+/*
+ * © 2024. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.io.factory.result;
+
+import static edu.ie3.util.quantities.PowerSystemUnits.PU;
+
+import edu.ie3.datamodel.io.factory.EntityData;
+import edu.ie3.datamodel.models.result.CongestionResult;
+import java.time.ZonedDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.List;
+import java.util.Set;
+import javax.measure.quantity.Dimensionless;
+import tech.units.indriya.ComparableQuantity;
+
+public class CongestionResultFactory extends ResultEntityFactory<CongestionResult> {
+  private static final String SUBGRID = "subgrid";
+  private static final String VMIN = "vMin";
+  private static final String VMAX = "vMax";
+  private static final String VOLTAGE = "voltage";
+  private static final String LINE = "line";
+  private static final String TRANSFORMER = "transformer";
+
+  public CongestionResultFactory() {
+    super(CongestionResult.class);
+  }
+
+  public CongestionResultFactory(DateTimeFormatter dateTimeFormatter) {
+    super(dateTimeFormatter, CongestionResult.class);
+  }
+
+  @Override
+  protected List<Set<String>> getFields(Class<?> entityClass) {
+    return List.of(newSet(TIME, SUBGRID, VMIN, VMAX, VOLTAGE, LINE, TRANSFORMER));
+  }
+
+  @Override
+  protected CongestionResult buildModel(EntityData data) {
+    ZonedDateTime zdtTime = timeUtil.toZonedDateTime(data.getField(TIME));
+    int subgrid = data.getInt(SUBGRID);
+    ComparableQuantity<Dimensionless> vMin = data.getQuantity(VMIN, PU);
+    ComparableQuantity<Dimensionless> vMax = data.getQuantity(VMAX, PU);
+    boolean voltage = data.getBoolean(VOLTAGE);
+    boolean line = data.getBoolean(LINE);
+    boolean transformer = data.getBoolean(TRANSFORMER);
+
+    return new CongestionResult(zdtTime, subgrid, vMin, vMax, voltage, line, transformer);
+  }
+}

src/main/java/edu/ie3/datamodel/io/factory/result/ConnectorResultFactory.java

@@ -20,7 +20,7 @@
 import javax.measure.quantity.ElectricCurrent;
 import tech.units.indriya.ComparableQuantity;
 
-public class ConnectorResultFactory extends ResultEntityFactory<ConnectorResult> {
+public class ConnectorResultFactory extends ModelResultFactory<ConnectorResult> {
 
   private static final String IAMAG = "iAMag";
   private static final String IAANG = "iAAng";

src/main/java/edu/ie3/datamodel/io/factory/result/FlexOptionsResultFactory.java

@@ -14,7 +14,7 @@
 import javax.measure.quantity.Power;
 import tech.units.indriya.ComparableQuantity;
 
-public class FlexOptionsResultFactory extends ResultEntityFactory<FlexOptionsResult> {
+public class FlexOptionsResultFactory extends ModelResultFactory<FlexOptionsResult> {
 
   private static final String P_REF = "pRef";
   private static final String P_MIN = "pMin";

src/main/java/edu/ie3/datamodel/io/factory/result/ModelResultFactory.java

@@ -0,0 +1,23 @@
+/*
+ * © 2024. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.io.factory.result;
+
+import edu.ie3.datamodel.models.result.ModelResultEntity;
+import java.time.format.DateTimeFormatter;
+
+public abstract class ModelResultFactory<T extends ModelResultEntity>
+    extends ResultEntityFactory<T> {
+  protected static final String INPUT_MODEL = "inputModel";
+
+  protected ModelResultFactory(Class<? extends T>... allowedClasses) {
+    super(allowedClasses);
+  }
+
+  protected ModelResultFactory(
+      DateTimeFormatter dateTimeFormatter, Class<? extends T>... allowedClasses) {
+    super(dateTimeFormatter, allowedClasses);
+  }
+}

src/main/java/edu/ie3/datamodel/io/factory/result/NodeResultFactory.java

@@ -15,7 +15,7 @@
 import javax.measure.quantity.Dimensionless;
 import tech.units.indriya.ComparableQuantity;
 
-public class NodeResultFactory extends ResultEntityFactory<NodeResult> {
+public class NodeResultFactory extends ModelResultFactory<NodeResult> {
   private static final String VMAG = "vMag";
   private static final String VANG = "vAng";
 

src/main/java/edu/ie3/datamodel/io/factory/result/ResultEntityFactory.java

@@ -21,7 +21,6 @@
 abstract class ResultEntityFactory<T extends ResultEntity> extends EntityFactory<T, EntityData> {
 
   protected static final String TIME = "time";
-  protected static final String INPUT_MODEL = "inputModel";
 
   protected final TimeUtil timeUtil;
 

src/main/java/edu/ie3/datamodel/io/factory/result/SwitchResultFactory.java

@@ -11,7 +11,7 @@
 import java.time.format.DateTimeFormatter;
 import java.util.*;
 
-public class SwitchResultFactory extends ResultEntityFactory<SwitchResult> {
+public class SwitchResultFactory extends ModelResultFactory<SwitchResult> {
 
   private static final String CLOSED = "closed";
 

src/main/java/edu/ie3/datamodel/io/factory/result/SystemParticipantResultFactory.java

@@ -23,7 +23,7 @@
  * Factory class for creating {@link SystemParticipantResult} entities from provided {@link
  * EntityData} data objects.
  */
-public class SystemParticipantResultFactory extends ResultEntityFactory<SystemParticipantResult> {
+public class SystemParticipantResultFactory extends ModelResultFactory<SystemParticipantResult> {
 
   private static final String POWER = "p";
   private static final String REACTIVE_POWER = "q";

src/main/java/edu/ie3/datamodel/io/factory/result/ThermalResultFactory.java

@@ -21,7 +21,7 @@
 import javax.measure.quantity.Temperature;
 import tech.units.indriya.ComparableQuantity;
 
-public class ThermalResultFactory extends ResultEntityFactory<ThermalUnitResult> {
+public class ThermalResultFactory extends ModelResultFactory<ThermalUnitResult> {
   private static final String Q_DOT = "qDot";
   private static final String INDOOR_TEMPERATURE = "indoorTemperature";
   private static final String ENERGY = "energy";

src/main/java/edu/ie3/datamodel/io/processor/result/ResultEntityProcessor.java

@@ -9,6 +9,7 @@
 import edu.ie3.datamodel.io.factory.result.SystemParticipantResultFactory;
 import edu.ie3.datamodel.io.processor.EntityProcessor;
 import edu.ie3.datamodel.models.StandardUnits;
+import edu.ie3.datamodel.models.result.CongestionResult;
 import edu.ie3.datamodel.models.result.NodeResult;
 import edu.ie3.datamodel.models.result.ResultEntity;
 import edu.ie3.datamodel.models.result.connector.LineResult;
@@ -58,7 +59,8 @@ public class ResultEntityProcessor extends EntityProcessor<ResultEntity> {
           ThermalHouseResult.class,
           CylindricalStorageResult.class,
           EmResult.class,
-          FlexOptionsResult.class);
+          FlexOptionsResult.class,
+          CongestionResult.class);
 
   public ResultEntityProcessor(Class<? extends ResultEntity> registeredClass)
       throws EntityProcessorException {

src/main/java/edu/ie3/datamodel/io/source/ResultEntitySource.java

@@ -11,6 +11,7 @@
 import edu.ie3.datamodel.io.factory.EntityData;
 import edu.ie3.datamodel.io.factory.EntityFactory;
 import edu.ie3.datamodel.io.factory.result.*;
+import edu.ie3.datamodel.models.result.CongestionResult;
 import edu.ie3.datamodel.models.result.NodeResult;
 import edu.ie3.datamodel.models.result.ResultEntity;
 import edu.ie3.datamodel.models.result.connector.LineResult;
@@ -41,6 +42,7 @@ public class ResultEntitySource extends EntitySource {
   private final SwitchResultFactory switchResultFactory;
   private final NodeResultFactory nodeResultFactory;
   private final ConnectorResultFactory connectorResultFactory;
+  private final CongestionResultFactory congestionResultFactory;
   private final FlexOptionsResultFactory flexOptionsResultFactory;
 
   public ResultEntitySource(DataSource dataSource) {
@@ -52,6 +54,7 @@ public ResultEntitySource(DataSource dataSource) {
     this.switchResultFactory = new SwitchResultFactory();
     this.nodeResultFactory = new NodeResultFactory();
     this.connectorResultFactory = new ConnectorResultFactory();
+    this.congestionResultFactory = new CongestionResultFactory();
     this.flexOptionsResultFactory = new FlexOptionsResultFactory();
   }
 
@@ -64,6 +67,7 @@ public ResultEntitySource(DataSource dataSource, DateTimeFormatter dateTimeForma
     this.switchResultFactory = new SwitchResultFactory();
     this.nodeResultFactory = new NodeResultFactory();
     this.connectorResultFactory = new ConnectorResultFactory();
+    this.congestionResultFactory = new CongestionResultFactory();
     this.flexOptionsResultFactory = new FlexOptionsResultFactory();
   }
 
@@ -95,7 +99,8 @@ public void validate() throws ValidationException {
             validate(LineResult.class, connectorResultFactory),
             validate(Transformer2WResult.class, connectorResultFactory),
             validate(Transformer3WResult.class, connectorResultFactory),
-            validate(FlexOptionsResult.class, flexOptionsResultFactory)));
+            validate(FlexOptionsResult.class, flexOptionsResultFactory),
+            validate(CongestionResult.class, congestionResultFactory)));
 
     Try.scanCollection(participantResults, Void.class)
         .transformF(FailedValidationException::new)
@@ -357,6 +362,15 @@ public Set<EmResult> getEmResults() throws SourceException {
     return getResultEntities(EmResult.class, systemParticipantResultFactory);
   }
 
+  /**
+   * Returns a unique set of {@link CongestionResult} instances.
+   *
+   * @return a set of object and subgrid unique {@link CongestionResult} entities
+   */
+  public Set<CongestionResult> getCongestionResults() throws SourceException {
+    return getResultEntities(CongestionResult.class, congestionResultFactory);
+  }
+
   // -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 
   /**

src/main/java/edu/ie3/datamodel/models/result/CongestionResult.java

@@ -0,0 +1,113 @@
+/*
+ * © 2024. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.models.result;
+
+import java.time.ZonedDateTime;
+import java.util.Objects;
+import javax.measure.quantity.Dimensionless;
+import tech.units.indriya.ComparableQuantity;
+
+public class CongestionResult extends ResultEntity {
+  /** Values */
+  private final Integer subgrid;
+
+  private final ComparableQuantity<Dimensionless> vMin;
+  private final ComparableQuantity<Dimensionless> vMax;
+  private final boolean voltage;
+  private final boolean line;
+  private final boolean transformer;
+
+  /**
+   * Standard constructor which includes auto generation of the resulting output models uuid.
+   *
+   * @param time date and time when the result is produced
+   * @param subgrid the subgrid
+   * @param vMin minimum voltage in pu
+   * @param vMax maximal voltage in pu
+   * @param voltage {@code true} if a voltage congestion occurred in the subnet
+   * @param line {@code true} if a line congestion occurred in the subnet
+   * @param transformer {@code true} if a transformer congestion occurred in the subnet
+   */
+  public CongestionResult(
+      ZonedDateTime time,
+      int subgrid,
+      ComparableQuantity<Dimensionless> vMin,
+      ComparableQuantity<Dimensionless> vMax,
+      boolean voltage,
+      boolean line,
+      boolean transformer) {
+    super(time);
+    this.subgrid = subgrid;
+    this.vMin = vMin;
+    this.vMax = vMax;
+    this.voltage = voltage;
+    this.line = line;
+    this.transformer = transformer;
+  }
+
+  public int getSubgrid() {
+    return subgrid;
+  }
+
+  public boolean getVoltage() {
+    return voltage;
+  }
+
+  public boolean getLine() {
+    return line;
+  }
+
+  public boolean getTransformer() {
+    return transformer;
+  }
+
+  public ComparableQuantity<Dimensionless> getVMin() {
+    return vMin;
+  }
+
+  public ComparableQuantity<Dimensionless> getVMax() {
+    return vMax;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (o == null || getClass() != o.getClass()) return false;
+    CongestionResult that = (CongestionResult) o;
+    return getTime().equals(that.getTime())
+        && Objects.equals(subgrid, that.subgrid)
+        && vMin.equals(that.vMin)
+        && vMax.equals(that.vMax)
+        && voltage == that.voltage
+        && line == that.line
+        && transformer == that.transformer;
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(
+        super.hashCode(), getTime(), subgrid, vMin, vMax, voltage, line, transformer);
+  }
+
+  @Override
+  public String toString() {
+    return "InputResultEntity{time="
+        + getTime()
+        + ", subgrid="
+        + subgrid
+        + ", vMin="
+        + vMin
+        + ", vMan="
+        + vMax
+        + ", voltage="
+        + voltage
+        + ", line="
+        + line
+        + ", transformer="
+        + transformer
+        + '}';
+  }
+}