Merge branch 'dev' into df/#1131-psdm-update-for-tap-water-demand

# Conflicts:
#	CHANGELOG.md

Author: danielfeismann

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Adding timeseries for voltage values [#1128](https://github.com/ie3-institute/PowerSystemDataModel/issues/1128)
 - Added Staudt to list of reviewers [#1190](https://github.com/ie3-institute/PowerSystemDataModel/issues/1190)
 - Extend ValidationUtils for validating ThermalGrids [#1216](https://github.com/ie3-institute/PowerSystemDataModel/issues/1216) 
+- Enhance `TimeSeriesSource` with method to retrieve the previous value before a given key [#1182](https://github.com/ie3-institute/PowerSystemDataModel/issues/1182)
 - Extend ValidationUtils for validating ThermalGrids [#1216](https://github.com/ie3-institute/PowerSystemDataModel/issues/1216) 
 - Attribute `pThermalRated` for `ThermalStorage`s [#679](https://github.com/ie3-institute/PowerSystemDataModel/issues/679)
 - Attributes `housingType` and `numberInhabitants` for `ThermalHouse`s [#1131](https://github.com/ie3-institute/PowerSystemDataModel/issues/1131)
@@ -30,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Renamed timeseries mapping `participant` column to `asset` [#1191](https://github.com/ie3-institute/PowerSystemDataModel/issues/1191)
 - Removed attribute `dsm` from `LoadInput` [#1195](https://github.com/ie3-institute/PowerSystemDataModel/issues/1195)
 - Fix spotless deprecations [#1123](https://github.com/ie3-institute/PowerSystemDataModel/issues/1223)
+- Refactored `CongestionResult`, removed `ModelResultEntity` [#1234](https://github.com/ie3-institute/PowerSystemDataModel/issues/1234)
 
 ## [5.1.0] - 2024-06-24
 

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

@@ -2,7 +2,7 @@
 
 # Congestion
 
-Representation of a congestion result for a given subnet.
+Representation of a congestion result for a given asset.
 
 ## Attributes, Units and Remarks
 
@@ -18,30 +18,30 @@ Representation of a congestion result for a given subnet.
    * - time
      - ZonedDateTime
      - date and time for the produced result
-   
-   * - subgrid
+     
+   * - inputModel
      -
-     - Sub grid number
-
-   * - vMin
-     - p.u.
-     - minimal voltage of the subnet
-
-   * - vMax
-     - p.u.
-     - maximal voltage of the subnet
-
-   * - voltage
+     - uuid for the associated input model
+     
+   * - inputModelType
      -
-     - Boolean indicator, if a voltage congestion occurred
-
-   * - line
+     - the type of the input model (e.g. node, line, etc.)
+     
+   * - subgrid
      -
-     - Boolean indicator, if a line congestion occurred
+     - Sub grid number
 
-   * - transformer
-     -
-     - Boolean indicator, if a transformer congestion occurred
+   * - value
+     - Percent
+     - the actual value that was calculated in relation to its base value
+     
+   * - min
+     - Percent
+     - minimal limit value
+
+   * - max
+     - Percent
+     - maximal limit value
 ```
 
 ## Caveats

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

@@ -5,24 +5,28 @@
 */
 package edu.ie3.datamodel.io.factory.result;
 
-import static edu.ie3.util.quantities.PowerSystemUnits.PU;
+import static tech.units.indriya.unit.Units.PERCENT;
 
+import edu.ie3.datamodel.exceptions.FactoryException;
+import edu.ie3.datamodel.exceptions.ParsingException;
 import edu.ie3.datamodel.io.factory.EntityData;
 import edu.ie3.datamodel.models.result.CongestionResult;
+import edu.ie3.datamodel.models.result.CongestionResult.InputModelType;
+import edu.ie3.datamodel.utils.Try;
 import java.time.ZonedDateTime;
 import java.time.format.DateTimeFormatter;
 import java.util.List;
 import java.util.Set;
+import java.util.UUID;
 import javax.measure.quantity.Dimensionless;
 import tech.units.indriya.ComparableQuantity;
 
 public class CongestionResultFactory extends ResultEntityFactory<CongestionResult> {
+  private static final String TYPE = "type";
   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";
+  private static final String VALUE = "value";
+  private static final String MIN = "min";
+  private static final String MAX = "max";
 
   public CongestionResultFactory() {
     super(CongestionResult.class);
@@ -34,19 +38,25 @@ public CongestionResultFactory(DateTimeFormatter dateTimeFormatter) {
 
   @Override
   protected List<Set<String>> getFields(Class<?> entityClass) {
-    return List.of(newSet(TIME, SUBGRID, VMIN, VMAX, VOLTAGE, LINE, TRANSFORMER));
+    return List.of(newSet(TIME, INPUT_MODEL, TYPE, SUBGRID, MIN, MAX));
   }
 
   @Override
   protected CongestionResult buildModel(EntityData data) {
     ZonedDateTime zdtTime = timeUtil.toZonedDateTime(data.getField(TIME));
+    UUID inputModel = data.getUUID(INPUT_MODEL);
+
+    InputModelType type =
+        Try.of(() -> InputModelType.parse(data.getField(TYPE)), ParsingException.class)
+            .transformF(FactoryException::new)
+            .getOrThrow();
+
     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);
+    ComparableQuantity<Dimensionless> value = data.getQuantity(VALUE, PERCENT);
+    ComparableQuantity<Dimensionless> min = data.getQuantity(MIN, PERCENT);
+    ComparableQuantity<Dimensionless> max = data.getQuantity(MAX, PERCENT);
+
+    return new CongestionResult(zdtTime, inputModel, type, subgrid, value, min, max);
   }
 }

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 ModelResultFactory<ConnectorResult> {
+public class ConnectorResultFactory extends ResultEntityFactory<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 ModelResultFactory<FlexOptionsResult> {
+public class FlexOptionsResultFactory extends ResultEntityFactory<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

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

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

@@ -22,6 +22,7 @@ public 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/ResultEntityFactory.java

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

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

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

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

@@ -22,7 +22,7 @@
 import javax.measure.quantity.Temperature;
 import tech.units.indriya.ComparableQuantity;
 
-public class ThermalResultFactory extends ModelResultFactory<ThermalUnitResult> {
+public class ThermalResultFactory extends ResultEntityFactory<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/factory/result/ThermalResultFactory.java

@@ -50,7 +50,9 @@ protected Try<TimeBasedValue<V>, FactoryException> createTimeBasedValue(
   public abstract IndividualTimeSeries<V> getTimeSeries(ClosedInterval<ZonedDateTime> timeInterval)
       throws SourceException;
 
-  public abstract Optional<V> getValue(ZonedDateTime time) throws SourceException;
+  public abstract Optional<V> getValue(ZonedDateTime time);
+
+  public abstract Optional<TimeBasedValue<V>> getPreviousTimeBasedValue(ZonedDateTime time);
 
   /**
    * Method to return all time keys after a given timestamp.

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

@@ -128,6 +128,15 @@ public Optional<V> getValue(ZonedDateTime time) {
     return timeSeries.getValue(time);
   }
 
+  @Override
+  public Optional<TimeBasedValue<V>> getPreviousTimeBasedValue(ZonedDateTime time) {
+    return timeSeries.getPreviousTimeBasedValue(time);
+  }
+
+  public Optional<TimeBasedValue<V>> getNextTimeBasedValue(ZonedDateTime time) {
+    return timeSeries.getNextTimeBasedValue(time);
+  }
+
   @Override
   public List<ZonedDateTime> getTimeKeysAfter(ZonedDateTime time) {
     return timeSeries.getTimeKeysAfter(time);

src/main/java/edu/ie3/datamodel/io/source/csv/CsvTimeSeriesSource.java

@@ -48,6 +48,7 @@ public class SqlTimeSeriesSource<V extends Value> extends TimeSeriesSource<V> {
 
   private final String queryTimeInterval;
   private final String queryTimeKeysAfter;
+  private final String queryForValueBefore;
   private final String queryTime;
 
   public SqlTimeSeriesSource(
@@ -63,15 +64,16 @@ public SqlTimeSeriesSource(
     final ColumnScheme columnScheme = ColumnScheme.parse(valueClass).orElseThrow();
     this.tableName = sqlDataSource.databaseNamingStrategy.getTimeSeriesEntityName(columnScheme);
 
+    String schemaName = sqlDataSource.schemaName;
+
     String dbTimeColumnName =
         sqlDataSource.getDbColumnName(factory.getTimeFieldString(), tableName);
 
-    this.queryFull = createQueryFull(sqlDataSource.schemaName, tableName);
-    this.queryTimeInterval =
-        createQueryForTimeInterval(sqlDataSource.schemaName, tableName, dbTimeColumnName);
-    this.queryTimeKeysAfter =
-        createQueryForTimeKeysAfter(sqlDataSource.schemaName, tableName, dbTimeColumnName);
-    this.queryTime = createQueryForTime(sqlDataSource.schemaName, tableName, dbTimeColumnName);
+    this.queryFull = createQueryFull(schemaName, tableName);
+    this.queryTimeInterval = createQueryForTimeInterval(schemaName, tableName, dbTimeColumnName);
+    this.queryTimeKeysAfter = createQueryForTimeKeysAfter(schemaName, tableName, dbTimeColumnName);
+    this.queryForValueBefore = createQueryForValueBefore(schemaName, tableName, dbTimeColumnName);
+    this.queryTime = createQueryForTime(schemaName, tableName, dbTimeColumnName);
   }
 
   /**
@@ -179,6 +181,14 @@ public Optional<V> getValue(ZonedDateTime time) {
     return Optional.of(timeBasedValues.stream().toList().get(0).getValue());
   }
 
+  @Override
+  public Optional<TimeBasedValue<V>> getPreviousTimeBasedValue(ZonedDateTime time) {
+    return getTimeBasedValueSet(
+            queryForValueBefore, ps -> ps.setTimestamp(1, Timestamp.from(time.toInstant())))
+        .stream()
+        .max(TimeBasedValue::compareTo);
+  }
+
   @Override
   public List<ZonedDateTime> getTimeKeysAfter(ZonedDateTime time) {
     return dataSource
@@ -278,8 +288,30 @@ private String createQueryForTimeKeysAfter(
   }
 
   /**
-   * Creates a basic query to retrieve an entry for the given time series uuid and time with the
-   * following pattern: <br>
+   * Creates a base query to retrieve all time keys after a given time for given time series with
+   * the following pattern: <br>
+   * {@code <base query> WHERE time_series = $timeSeriesUuid AND <time column> < ?;}
+   *
+   * @param schemaName the name of the database schema
+   * @param tableName the name of the database table
+   * @param timeColumnName the name of the column holding the timestamp info
+   * @return the query string
+   */
+  private String createQueryForValueBefore(
+      String schemaName, String tableName, String timeColumnName) {
+    return createBaseQueryString(schemaName, tableName)
+        + WHERE
+        + TIME_SERIES
+        + " = '"
+        + timeSeriesUuid.toString()
+        + "' AND "
+        + timeColumnName
+        + " < ?"
+        + "ORDER BY time DESC LIMIT 1;";
+  }
+  /**
+   * Creates a base query to retrieve all time keys before a given time for given time series with
+   * the following pattern: <br>
    * {@code <base query> WHERE time_series = $timeSeriesUuid AND <time column>=?;}
    *
    * @param schemaName the name of the database schema