Merge pull request #1439 from ie3-institute/ms/#1438-abstracting-power-value-sources

Added abstraction for power value sources.

Author: sebastian-peter

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added standard asset parameter for `3wTransformer` in `ReadTheDocs` [#1417](https://github.com/ie3-institute/PowerSystemDataModel/issues/1417)
 - Added getter sRated for SystemParticipant inputs and updated them in tests in src[#1412](https://github.com/ie3-institute/PowerSystemDataModel/issues/1412)
 - Added converters documentation [#1139](https://github.com/ie3-institute/PowerSystemDataModel/issues/1139)
+- Added abstraction for power value sources [#1438](https://github.com/ie3-institute/PowerSystemDataModel/issues/1438)
 
 ### Fixed
 - Fixed small issues in tests [#1400](https://github.com/ie3-institute/PowerSystemDataModel/issues/1400)

src/main/java/edu/ie3/datamodel/io/factory/timeseries/BdewLoadProfileFactory.java

@@ -9,7 +9,6 @@
 
 import edu.ie3.datamodel.exceptions.FactoryException;
 import edu.ie3.datamodel.exceptions.ParsingException;
-import edu.ie3.datamodel.io.naming.timeseries.LoadProfileMetaInformation;
 import edu.ie3.datamodel.models.profile.BdewStandardLoadProfile;
 import edu.ie3.datamodel.models.timeseries.TimeSeriesEntry;
 import edu.ie3.datamodel.models.timeseries.repetitive.BdewLoadProfileTimeSeries;
@@ -70,9 +69,7 @@ protected List<Set<String>> getFields(Class<?> entityClass) {
 
   @Override
   public BdewLoadProfileTimeSeries build(
-      LoadProfileMetaInformation metaInformation, Set<LoadProfileEntry<BdewLoadValues>> entries) {
-
-    BdewStandardLoadProfile profile = parseProfile(metaInformation.getProfile());
+      BdewStandardLoadProfile profile, Set<LoadProfileEntry<BdewLoadValues>> entries) {
     ComparableQuantity<Power> maxPower = calculateMaxPower(profile, entries);
     ComparableQuantity<Energy> profileEnergyScaling = getLoadProfileEnergyScaling(profile);
 

src/main/java/edu/ie3/datamodel/io/factory/timeseries/LoadProfileFactory.java

@@ -6,7 +6,6 @@
 package edu.ie3.datamodel.io.factory.timeseries;
 
 import edu.ie3.datamodel.io.factory.Factory;
-import edu.ie3.datamodel.io.naming.timeseries.LoadProfileMetaInformation;
 import edu.ie3.datamodel.models.profile.LoadProfile;
 import edu.ie3.datamodel.models.timeseries.repetitive.LoadProfileEntry;
 import edu.ie3.datamodel.models.timeseries.repetitive.LoadProfileTimeSeries;
@@ -37,8 +36,7 @@ protected LoadProfileFactory(Class<? extends V>... valueClass) {
     super(valueClass);
   }
 
-  public abstract LoadProfileTimeSeries<P, V> build(
-      LoadProfileMetaInformation metaInformation, Set<LoadProfileEntry<V>> entries);
+  public abstract LoadProfileTimeSeries<P, V> build(P profile, Set<LoadProfileEntry<V>> entries);
 
   public abstract P parseProfile(String profile);
 

src/main/java/edu/ie3/datamodel/io/factory/timeseries/RandomLoadProfileFactory.java

@@ -8,7 +8,6 @@
 import static edu.ie3.datamodel.models.profile.LoadProfile.RandomLoadProfile.RANDOM_LOAD_PROFILE;
 import static tech.units.indriya.unit.Units.WATT;
 
-import edu.ie3.datamodel.io.naming.timeseries.LoadProfileMetaInformation;
 import edu.ie3.datamodel.models.profile.LoadProfile.RandomLoadProfile;
 import edu.ie3.datamodel.models.timeseries.repetitive.LoadProfileEntry;
 import edu.ie3.datamodel.models.timeseries.repetitive.RandomLoadProfileTimeSeries;
@@ -73,9 +72,7 @@ protected List<Set<String>> getFields(Class<?> entityClass) {
 
   @Override
   public RandomLoadProfileTimeSeries build(
-      LoadProfileMetaInformation metaInformation, Set<LoadProfileEntry<RandomLoadValues>> entries) {
-    RandomLoadProfile profile = RANDOM_LOAD_PROFILE;
-
+      RandomLoadProfile profile, Set<LoadProfileEntry<RandomLoadValues>> entries) {
     ComparableQuantity<Power> maxPower = calculateMaxPower(profile, entries);
     ComparableQuantity<Energy> profileEnergyScaling = getLoadProfileEnergyScaling(profile);
 

src/main/java/edu/ie3/datamodel/io/naming/timeseries/LoadProfileMetaInformation.java

@@ -17,11 +17,6 @@ public LoadProfileMetaInformation(String profile) {
     this.profile = profile;
   }
 
-  public LoadProfileMetaInformation(UUID uuid, String profile) {
-    super(uuid);
-    this.profile = profile;
-  }
-
   public String getProfile() {
     return profile;
   }
@@ -41,13 +36,6 @@ public int hashCode() {
 
   @Override
   public String toString() {
-    return "LoadProfileTimeSeriesMetaInformation{"
-        + "uuid='"
-        + getUuid()
-        + '\''
-        + ", profile='"
-        + profile
-        + '\''
-        + '}';
+    return "LoadProfileTimeSeriesMetaInformation{profile='" + profile + '}';
   }
 }

src/main/java/edu/ie3/datamodel/io/sink/SqlSink.java

@@ -190,7 +190,7 @@ private <C extends Entity> void persistMixedList(List<C> entities, DbGridMetadat
       void persistList(List<C> entities, Class<C> cls, DbGridMetadata identifier)
           throws SQLException {
     // Check if there are only elements of the same class
-    Class<?> firstClass = entities.get(0).getClass();
+    Class<?> firstClass = entities.getFirst().getClass();
     boolean allSameClass = entities.stream().allMatch(e -> e.getClass() == firstClass);
 
     if (allSameClass) {

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

@@ -14,35 +14,36 @@
 import edu.ie3.datamodel.io.factory.timeseries.LoadProfileFactory;
 import edu.ie3.datamodel.io.factory.timeseries.RandomLoadProfileFactory;
 import edu.ie3.datamodel.io.naming.timeseries.FileLoadProfileMetaInformation;
+import edu.ie3.datamodel.io.naming.timeseries.LoadProfileMetaInformation;
 import edu.ie3.datamodel.io.source.csv.CsvDataSource;
 import edu.ie3.datamodel.io.source.csv.CsvLoadProfileSource;
 import edu.ie3.datamodel.models.profile.BdewStandardLoadProfile;
 import edu.ie3.datamodel.models.profile.LoadProfile;
 import edu.ie3.datamodel.models.timeseries.repetitive.LoadProfileEntry;
-import edu.ie3.datamodel.models.timeseries.repetitive.LoadProfileTimeSeries;
 import edu.ie3.datamodel.models.timeseries.repetitive.RandomLoadProfileTimeSeries;
-import edu.ie3.datamodel.models.value.PValue;
 import edu.ie3.datamodel.models.value.Value;
 import edu.ie3.datamodel.models.value.load.BdewLoadValues;
 import edu.ie3.datamodel.models.value.load.LoadValues;
 import edu.ie3.datamodel.models.value.load.RandomLoadValues;
 import edu.ie3.datamodel.utils.Try;
 import java.time.ZonedDateTime;
-import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.Set;
 import java.util.function.Function;
 import java.util.stream.Collectors;
-import javax.measure.quantity.Energy;
-import javax.measure.quantity.Power;
-import tech.units.indriya.ComparableQuantity;
 
 public abstract class LoadProfileSource<P extends LoadProfile, V extends LoadValues<P>>
-    extends EntitySource {
+    extends EntitySource implements PowerValueSource.TimeSeriesBased {
+  protected final P profile;
   protected final Class<V> entryClass;
   protected final LoadProfileFactory<P, V> entryFactory;
 
-  protected LoadProfileSource(Class<V> entryClass, LoadProfileFactory<P, V> entryFactory) {
+  protected LoadProfileSource(
+      LoadProfileMetaInformation metaInformation,
+      Class<V> entryClass,
+      LoadProfileFactory<P, V> entryFactory) {
+    this.profile = entryFactory.parseProfile(metaInformation.getProfile());
     this.entryClass = entryClass;
     this.entryFactory = entryFactory;
   }
@@ -60,33 +61,18 @@ protected Try<LoadProfileEntry<V>, FactoryException> createEntries(
     return entryFactory.get(factoryData);
   }
 
-  public abstract LoadProfileTimeSeries<P, V> getTimeSeries();
+  /** Returns the load profile entries as a set. */
+  public abstract Set<LoadProfileEntry<V>> getEntries();
 
-  /**
-   * Method to return all time keys after a given timestamp.
-   *
-   * @param time given time
-   * @return a list of time keys
-   */
-  public abstract List<ZonedDateTime> getTimeKeysAfter(ZonedDateTime time);
-
-  /**
-   * Method to get the value for a given time.
-   *
-   * @param time for which a value is needed
-   * @return an optional
-   * @throws SourceException if an exception occurred
-   */
-  public abstract Optional<PValue> getValue(ZonedDateTime time) throws SourceException;
-
-  /** Returns the load profile of this source. */
-  public abstract P getLoadProfile();
-
-  /** Returns the maximal power value of the time series */
-  public abstract Optional<ComparableQuantity<Power>> getMaxPower();
+  @Override
+  public P getProfile() {
+    return profile;
+  }
 
-  /** Returns the load profile energy scaling for this load profile time series. */
-  public abstract Optional<ComparableQuantity<Energy>> getLoadProfileEnergyScaling();
+  @Override
+  public Optional<ZonedDateTime> getNextTimeKey(ZonedDateTime time) {
+    return Optional.of(time.plusSeconds(getResolution(getProfile())));
+  }
 
   /**
    * Returns the resolution for the given {@link LoadProfile}.
@@ -125,7 +111,7 @@ public static long getResolution(LoadProfile loadProfile) {
             metaInformation ->
                 new CsvLoadProfileSource<>(
                     buildInSource, metaInformation, BdewLoadValues.class, factory))
-        .collect(Collectors.toMap(CsvLoadProfileSource::getLoadProfile, Function.identity()));
+        .collect(Collectors.toMap(CsvLoadProfileSource::getProfile, Function.identity()));
   }
 
   /**

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

@@ -0,0 +1,83 @@
+/*
+ * © 2025. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.io.source;
+
+import edu.ie3.datamodel.models.profile.LoadProfile;
+import edu.ie3.datamodel.models.profile.PowerProfile;
+import edu.ie3.datamodel.models.value.PValue;
+import java.time.ZonedDateTime;
+import java.util.Optional;
+import java.util.function.Supplier;
+import javax.measure.quantity.Energy;
+import javax.measure.quantity.Power;
+import tech.units.indriya.ComparableQuantity;
+
+/** Interface defining base functionality for power value sources. */
+public sealed interface PowerValueSource<
+        P extends PowerProfile, I extends PowerValueSource.PowerValueIdentifier>
+    permits PowerValueSource.MarkovBased, PowerValueSource.TimeSeriesBased {
+
+  /** Returns the profile of this source. */
+  P getProfile();
+
+  /**
+   * Method to get a supplier for the next power value based on the provided input data. Depending
+   * on the implementation the supplier will either always return the same value or each time a
+   * random value.
+   *
+   * @param data input data that is used to calculate the next power value.
+   * @return A supplier for an option on the value at the given time step.
+   */
+  Supplier<Optional<PValue>> getValueSupplier(I data);
+
+  /**
+   * Method to determine the next timestamp for which data is present.
+   *
+   * @param time current time
+   * @return an option for the next timestamp or {@link Optional#empty()} if no timestamp was found.
+   */
+  Optional<ZonedDateTime> getNextTimeKey(ZonedDateTime time);
+
+  /** Returns the maximal power that can be returned by this source. */
+  Optional<ComparableQuantity<Power>> getMaxPower();
+
+  /** Returns the energy scaling of this power source. */
+  Optional<ComparableQuantity<Energy>> getProfileEnergyScaling();
+
+  // -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+  // non-sealed implementations
+
+  /** Interface for time-series-based power value sources. */
+  non-sealed interface TimeSeriesBased
+      extends PowerValueSource<LoadProfile, TimeSeriesInputValue> {}
+
+  /** Interface for markov-chain-based power value sources. */
+  non-sealed interface MarkovBased extends PowerValueSource<PowerProfile, PowerValueIdentifier> {}
+
+  // -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
+  // input data
+
+  /**
+   * Interface for the input data of {@link #getValueSupplier(PowerValueIdentifier)}. The data is
+   * used to determine the next power.
+   */
+  sealed interface PowerValueIdentifier permits PowerValueSource.TimeSeriesInputValue {
+    /** Returns the timestamp for which a power value is needed. */
+    ZonedDateTime getTime();
+  }
+
+  /**
+   * Input data for time-series-based power value sources.
+   *
+   * @param time
+   */
+  record TimeSeriesInputValue(ZonedDateTime time) implements PowerValueIdentifier {
+    @Override
+    public ZonedDateTime getTime() {
+      return time;
+    }
+  }
+}

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

@@ -18,9 +18,9 @@
 import edu.ie3.datamodel.models.value.load.LoadValues;
 import edu.ie3.datamodel.utils.Try;
 import java.nio.file.Path;
-import java.time.ZonedDateTime;
 import java.util.*;
 import java.util.function.Function;
+import java.util.function.Supplier;
 import java.util.stream.Collectors;
 import javax.measure.quantity.Energy;
 import javax.measure.quantity.Power;
@@ -40,13 +40,13 @@ public CsvLoadProfileSource(
       FileLoadProfileMetaInformation metaInformation,
       Class<V> entryClass,
       LoadProfileFactory<P, V> entryFactory) {
-    super(entryClass, entryFactory);
+    super(metaInformation, entryClass, entryFactory);
     this.dataSource = source;
     this.filePath = metaInformation.getFullFilePath();
 
     /* Read in the full time series */
     try {
-      this.loadProfileTimeSeries = buildLoadProfileTimeSeries(metaInformation, this::createEntries);
+      this.loadProfileTimeSeries = buildLoadProfileTimeSeries(this::createEntries);
     } catch (SourceException e) {
       throw new IllegalArgumentException(
           "Unable to obtain load profile time series with profile '"
@@ -61,24 +61,18 @@ public void validate() throws ValidationException {
     validate(entryClass, () -> dataSource.getSourceFields(filePath), entryFactory);
   }
 
-  @Override
   public LoadProfileTimeSeries<P, V> getTimeSeries() {
     return loadProfileTimeSeries;
   }
 
   @Override
-  public List<ZonedDateTime> getTimeKeysAfter(ZonedDateTime time) {
-    return loadProfileTimeSeries.getTimeKeysAfter(time);
+  public Set<LoadProfileEntry<V>> getEntries() {
+    return loadProfileTimeSeries.getEntries();
   }
 
   @Override
-  public Optional<PValue> getValue(ZonedDateTime time) throws SourceException {
-    return loadProfileTimeSeries.getValue(time);
-  }
-
-  @Override
-  public P getLoadProfile() {
-    return getTimeSeries().getLoadProfile();
+  public Supplier<Optional<PValue>> getValueSupplier(TimeSeriesInputValue data) {
+    return loadProfileTimeSeries.supplyValue(data.time());
   }
 
   @Override
@@ -87,7 +81,7 @@ public Optional<ComparableQuantity<Power>> getMaxPower() {
   }
 
   @Override
-  public Optional<ComparableQuantity<Energy>> getLoadProfileEnergyScaling() {
+  public Optional<ComparableQuantity<Energy>> getProfileEnergyScaling() {
     return loadProfileTimeSeries.loadProfileScaling();
   }
 
@@ -98,15 +92,12 @@ public Optional<ComparableQuantity<Energy>> getLoadProfileEnergyScaling() {
    * entries are obtained entries with the help of {@code fieldToValueFunction}. If the file does
    * not exist, an empty Stream is returned.
    *
-   * @param metaInformation containing an unique identifier of the time series, a path to the file
-   *     to read as well as the profile
    * @param fieldToValueFunction function, that is able to transfer a mapping (from field to value)
    *     onto a specific instance of the targeted entry class
    * @throws SourceException If the file cannot be read properly
    * @return an individual time series
    */
   protected LoadProfileTimeSeries<P, V> buildLoadProfileTimeSeries(
-      FileLoadProfileMetaInformation metaInformation,
       Function<Map<String, String>, Try<LoadProfileEntry<V>, FactoryException>>
           fieldToValueFunction)
       throws SourceException {
@@ -120,6 +111,6 @@ protected LoadProfileTimeSeries<P, V> buildLoadProfileTimeSeries(
             .getOrThrow()
             .collect(Collectors.toSet());
 
-    return entryFactory.build(metaInformation, entries);
+    return entryFactory.build(profile, entries);
   }
 }