add ground temperature 1m as option to weather data

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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)
+- Add ground temperatures level 1 and 2 as  option to weather data. [#1343](https://github.com/ie3-institute/PowerSystemDataModel/issues/1343)
 
 ### Fixed
 - Fixed small issues in tests [#1400](https://github.com/ie3-institute/PowerSystemDataModel/issues/1400)

docs/readthedocs/models/input/additionaldata/weathersource.md

@@ -62,5 +62,14 @@ Weather data is comprised of five key components:
    * - **`windDirection`**
      - Wind direction, where 0° is North, 90° is East, etc.
      - ° (degrees)
+
+   * - **`groundTemperatureLevel1`**
+     - Ground temperature at level 2 for this coordinate.
+     - K (Kelvin)
+
+   * - **`groundTemperatureLevel2`**
+     - Ground temperature at level 2 for this coordinate.
+     - K (Kelvin)
 ```
-Weather data in COSMO and ICON formats is supported. Additional optional weather data can also be provided.
+Weather data in COSMO and ICON formats is supported. Additional optional weather data can also be provided.
+The ground temperature measurements at level 1 and level 2 depth are used. Underground cables are typically laid at around 80 cm depth.

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

@@ -13,8 +13,9 @@
 import edu.ie3.util.quantities.interfaces.Irradiance;
 import java.time.ZonedDateTime;
 import java.time.format.DateTimeFormatter;
-import java.util.Collections;
+import java.util.Arrays;
 import java.util.List;
+import java.util.Optional;
 import java.util.Set;
 import javax.measure.quantity.Angle;
 import javax.measure.quantity.Speed;
@@ -32,6 +33,8 @@ public class CosmoTimeBasedWeatherValueFactory extends TimeBasedWeatherValueFact
   private static final String TEMPERATURE = "temperature";
   private static final String WIND_DIRECTION = "windDirection";
   private static final String WIND_VELOCITY = "windVelocity";
+  private static final String GROUND_TEMPERATURE_LEVEL_1 = "groundTemperatureLevel1";
+  private static final String GROUND_TEMPERATURE_LEVEL_2 = "groundTemperatureLevel2";
 
   public CosmoTimeBasedWeatherValueFactory(TimeUtil timeUtil) {
     super(timeUtil);
@@ -55,7 +58,11 @@ protected List<Set<String>> getFields(Class<?> entityClass) {
             TEMPERATURE,
             WIND_DIRECTION,
             WIND_VELOCITY);
-    return Collections.singletonList(minConstructorParams);
+
+    Set<String> withGroundTemp =
+        expandSet(minConstructorParams, GROUND_TEMPERATURE_LEVEL_1, GROUND_TEMPERATURE_LEVEL_2);
+
+    return Arrays.asList(minConstructorParams, withGroundTemp);
   }
 
   @Override
@@ -72,14 +79,21 @@ protected TimeBasedValue<WeatherValue> buildModel(TimeBasedWeatherValueData data
         data.getQuantity(WIND_DIRECTION, StandardUnits.WIND_DIRECTION);
     ComparableQuantity<Speed> windVelocity =
         data.getQuantity(WIND_VELOCITY, StandardUnits.WIND_VELOCITY);
+    Optional<ComparableQuantity<Temperature>> groundTempValOne =
+        data.getQuantityOptional(GROUND_TEMPERATURE_LEVEL_1, StandardUnits.TEMPERATURE);
+    Optional<ComparableQuantity<Temperature>> groundTempValTwo =
+        data.getQuantityOptional(GROUND_TEMPERATURE_LEVEL_2, StandardUnits.TEMPERATURE);
     WeatherValue weatherValue =
         new WeatherValue(
             coordinate,
             directIrradiance,
             diffuseIrradiance,
             temperature,
             windDirection,
-            windVelocity);
+            windVelocity,
+            groundTempValOne,
+            groundTempValTwo);
+
     return new TimeBasedValue<>(time, weatherValue);
   }
 }

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

@@ -33,6 +33,8 @@ public class IconTimeBasedWeatherValueFactory extends TimeBasedWeatherValueFacto
   private static final String TEMPERATURE = "t2m";
   private static final String WIND_VELOCITY_U = "u131m";
   private static final String WIND_VELOCITY_V = "v131m";
+  private static final String GROUND_TEMPERATURE_LEVEL_1 = "tg_1";
+  private static final String GROUND_TEMPERATURE_LEVEL_2 = "tg_2";
 
   public IconTimeBasedWeatherValueFactory() {
     super();
@@ -53,7 +55,8 @@ protected List<Set<String>> getFields(Class<?> entityClass) {
             "albrad",
             "asobs",
             "aswdifuS",
-            "tG",
+            "tg_1",
+            "tg_2",
             "u10m",
             "u20m",
             "u216m",
@@ -88,14 +91,21 @@ protected TimeBasedValue<WeatherValue> buildModel(TimeBasedWeatherValueData data
         data.getQuantity(TEMPERATURE, Units.KELVIN).to(StandardUnits.TEMPERATURE);
     ComparableQuantity<Angle> windDirection = getWindDirection(data);
     ComparableQuantity<Speed> windVelocity = getWindVelocity(data);
+    Optional<ComparableQuantity<Temperature>> groundTemperatureLevel1 =
+        data.getQuantityOptional(GROUND_TEMPERATURE_LEVEL_1, Units.KELVIN);
+    Optional<ComparableQuantity<Temperature>> groundTemperatureLevl2 =
+        data.getQuantityOptional(GROUND_TEMPERATURE_LEVEL_2, Units.KELVIN);
+
     WeatherValue weatherValue =
         new WeatherValue(
             coordinate,
             directIrradiance,
             diffuseIrradiance,
             temperature,
             windDirection,
-            windVelocity);
+            windVelocity,
+            groundTemperatureLevel1,
+            groundTemperatureLevl2);
     return new TimeBasedValue<>(time, weatherValue);
   }
 

src/main/java/edu/ie3/datamodel/io/processor/timeseries/FieldSourceToMethod.java

@@ -25,5 +25,7 @@ public enum FieldSource {
     WEATHER_IRRADIANCE,
     WEATHER_TEMPERATURE,
     WEATHER_WIND,
+    GROUND_TEMPERATURE_LEVEL_1,
+    GROUND_TEMPERATURE_LEVEL_2,
   }
 }

src/main/java/edu/ie3/datamodel/io/processor/timeseries/TimeSeriesProcessor.java

@@ -165,13 +165,31 @@ private SortedMap<String, FieldSourceToMethod> buildFieldToSource(
     if (valueClass.equals(WeatherValue.class)) {
       /* Treat the nested weather values specially. */
       /* Flatten the nested structure of Weather value */
-      mapFieldNameToGetter(valueClass, Arrays.asList("solarIrradiance", "temperature", "wind"))
+      mapFieldNameToGetter(
+              valueClass,
+              Arrays.asList(
+                  "solarIrradiance",
+                  "temperature",
+                  "wind",
+                  "groundTemperatureLevel1",
+                  "groundTemperatureLevel2"))
           .forEach(addFunction.apply(VALUE));
 
       mapFieldNameToGetter(SolarIrradianceValue.class)
           .forEach(addFunction.apply(WEATHER_IRRADIANCE));
       mapFieldNameToGetter(TemperatureValue.class).forEach(addFunction.apply(WEATHER_TEMPERATURE));
       mapFieldNameToGetter(WindValue.class).forEach(addFunction.apply(WEATHER_WIND));
+      Map<String, GetterMethod> groundTempMap = mapFieldNameToGetter(GroundTemperatureValue.class);
+      groundTempMap.forEach(
+          (fieldName, getter) ->
+              addFunction
+                  .apply(GROUND_TEMPERATURE_LEVEL_1)
+                  .accept("groundTemperatureLevel1", getter));
+      groundTempMap.forEach(
+          (fieldName, getter) ->
+              addFunction
+                  .apply(GROUND_TEMPERATURE_LEVEL_2)
+                  .accept("groundTemperatureLevel2", getter));
 
     } else if (valueClass.equals(BdewLoadValues.class)) {
 
@@ -272,6 +290,20 @@ private Map<String, String> handleEntry(T timeSeries, E entry) throws EntityProc
 
       Map<String, GetterMethod> windFieldToMethod = extractFieldToMethod(WEATHER_WIND);
       valueResult.putAll(processObject(weatherValue.getWind(), windFieldToMethod));
+
+      Map<String, GetterMethod> groundTempOneFieldToMethod =
+          extractFieldToMethod(GROUND_TEMPERATURE_LEVEL_1);
+      Optional<GroundTemperatureValue> gtOneOpt = weatherValue.getGroundTemperatureLevel1();
+      if (gtOneOpt.isPresent()) {
+        valueResult.putAll(processObject(gtOneOpt.get(), groundTempOneFieldToMethod));
+      }
+
+      Map<String, GetterMethod> groundTempTwoFieldToMethod =
+          extractFieldToMethod(GROUND_TEMPERATURE_LEVEL_2);
+      Optional<GroundTemperatureValue> gtTwoOpt = weatherValue.getGroundTemperatureLevel2();
+      if (gtTwoOpt.isPresent()) {
+        valueResult.putAll(processObject(gtTwoOpt.get(), groundTempTwoFieldToMethod));
+      }
     }
 
     /* Join all information and sort them */

src/main/java/edu/ie3/datamodel/models/value/GroundTemperatureValue.java

@@ -0,0 +1,30 @@
+/*
+ * © 2025. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.models.value;
+
+import javax.measure.quantity.Temperature;
+import tech.units.indriya.ComparableQuantity;
+
+/**
+ * Describes a ground temperature value. This class extends {@link TemperatureValue} to represent
+ * temperature at a specific depth in the ground.
+ */
+public class GroundTemperatureValue extends TemperatureValue {
+
+  /**
+   * Constructs a new GroundTemperatureValue.
+   *
+   * @param temperature The temperature quantity (typically in K)
+   */
+  public GroundTemperatureValue(ComparableQuantity<Temperature> temperature) {
+    super(temperature);
+  }
+
+  @Override
+  public String toString() {
+    return "GroundTemperatureValue{" + "temperature=" + getTemperature().orElse(null) + '}';
+  }
+}

src/main/java/edu/ie3/datamodel/models/value/WeatherValue.java

@@ -7,6 +7,7 @@
 
 import edu.ie3.util.quantities.interfaces.Irradiance;
 import java.util.Objects;
+import java.util.Optional;
 import javax.measure.quantity.Angle;
 import javax.measure.quantity.Speed;
 import javax.measure.quantity.Temperature;
@@ -27,44 +28,66 @@ public class WeatherValue implements Value {
   /** Wind values for this coordinate */
   private final WindValue wind;
 
+  /** Ground temperature value for this coordinate */
+  private final Optional<GroundTemperatureValue> groundTemperatureLevel1;
+
+  /** Ground temperature value for this coordinate */
+  private final Optional<GroundTemperatureValue> groundTemperatureLevel2;
+
   /**
    * @param coordinate of this weather value set
    * @param solarIrradiance values for this coordinate
    * @param temperature values for this coordinate
    * @param wind values for this coordinate
+   * @param groundTemperatureValueOne values for this coordinate (can be null)
+   * @param groundTemperatureValueTwo values for this coordinate (can be null)
    */
   public WeatherValue(
       Point coordinate,
       SolarIrradianceValue solarIrradiance,
       TemperatureValue temperature,
-      WindValue wind) {
+      WindValue wind,
+      Optional<GroundTemperatureValue> groundTemperatureValueOne,
+      Optional<GroundTemperatureValue> groundTemperatureValueTwo) {
     this.coordinate = coordinate;
     this.solarIrradiance = solarIrradiance;
     this.temperature = temperature;
     this.wind = wind;
+    this.groundTemperatureLevel1 = groundTemperatureValueOne;
+    this.groundTemperatureLevel2 = groundTemperatureValueTwo;
   }
 
   /**
+   * Constructor with all parameters as quantities.
+   *
    * @param coordinate of this weather value set
    * @param directSolarIrradiance Direct sun irradiance for this coordinate (typically in W/m²)
    * @param diffuseSolarIrradiance Diffuse sun irradiance for this coordinate (typically in W/m²)
    * @param temperature for this coordinate (typically in K)
    * @param direction Direction, the wind comes from as an angle from north increasing clockwise
    *     (typically in rad)
    * @param velocity Wind velocity for this coordinate (typically in m/s)
+   * @param groundTempValOne Ground temperature for this coordinate (typically in K, can be null)
+   * @param groundTempValTwo Ground temperature for this coordinate (typically in K, can be null)
    */
   public WeatherValue(
       Point coordinate,
       ComparableQuantity<Irradiance> directSolarIrradiance,
       ComparableQuantity<Irradiance> diffuseSolarIrradiance,
       ComparableQuantity<Temperature> temperature,
       ComparableQuantity<Angle> direction,
-      ComparableQuantity<Speed> velocity) {
+      ComparableQuantity<Speed> velocity,
+      Optional<ComparableQuantity<Temperature>> groundTempValOne,
+      Optional<ComparableQuantity<Temperature>> groundTempValTwo) {
     this(
         coordinate,
         new SolarIrradianceValue(directSolarIrradiance, diffuseSolarIrradiance),
         new TemperatureValue(temperature),
-        new WindValue(direction, velocity));
+        new WindValue(direction, velocity),
+        Optional.ofNullable(groundTempValOne)
+            .flatMap(optional -> optional.map(GroundTemperatureValue::new)),
+        Optional.ofNullable(groundTempValTwo)
+            .flatMap(optional -> optional.map(GroundTemperatureValue::new)));
   }
 
   public Point getCoordinate() {
@@ -83,6 +106,14 @@ public WindValue getWind() {
     return wind;
   }
 
+  public Optional<GroundTemperatureValue> getGroundTemperatureLevel1() {
+    return groundTemperatureLevel1;
+  }
+
+  public Optional<GroundTemperatureValue> getGroundTemperatureLevel2() {
+    return groundTemperatureLevel2;
+  }
+
   @Override
   public boolean equals(Object o) {
     if (this == o) return true;
@@ -91,12 +122,20 @@ public boolean equals(Object o) {
     return coordinate.equals(that.coordinate)
         && solarIrradiance.equals(that.solarIrradiance)
         && temperature.equals(that.temperature)
-        && wind.equals(that.wind);
+        && wind.equals(that.wind)
+        && Objects.equals(groundTemperatureLevel1, that.groundTemperatureLevel1)
+        && Objects.equals(groundTemperatureLevel2, that.groundTemperatureLevel2);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(coordinate, solarIrradiance, temperature, wind);
+    return Objects.hash(
+        coordinate,
+        solarIrradiance,
+        temperature,
+        wind,
+        groundTemperatureLevel1,
+        groundTemperatureLevel2);
   }
 
   @Override
@@ -110,6 +149,10 @@ public String toString() {
         + temperature
         + ", wind="
         + wind
+        + ", groundTemperatureLevel1="
+        + groundTemperatureLevel1
+        + ", groundTemperatureLevel2="
+        + groundTemperatureLevel2
         + '}';
   }
 }

src/test/groovy/edu/ie3/datamodel/io/factory/timeseries/CosmoTimeBasedWeatherValueFactoryTest.groovy

@@ -28,7 +28,9 @@ class CosmoTimeBasedWeatherValueFactoryTest extends Specification {
       "directIrradiance" : "286.872985839844",
       "temperature"      : "",
       "windDirection"    : "0",
-      "windVelocity"     : "1.66103506088257"
+      "windVelocity"     : "1.66103506088257",
+      "groundTemperatureLevel1"     : "",
+      "groundTemperatureLevel2"     : ""
     ]
 
     def data = new TimeBasedWeatherValueData(parameter, coordinate)
@@ -39,7 +41,9 @@ class CosmoTimeBasedWeatherValueFactoryTest extends Specification {
         Quantities.getQuantity(282.671997070312d, StandardUnits.SOLAR_IRRADIANCE),
         null,
         Quantities.getQuantity(0d, StandardUnits.WIND_DIRECTION),
-        Quantities.getQuantity(1.66103506088257d, StandardUnits.WIND_VELOCITY)))
+        Quantities.getQuantity(1.66103506088257d, StandardUnits.WIND_VELOCITY),
+        Optional.empty(),
+        Optional.empty()))
 
     when:
     def model = factory.buildModel(data)
@@ -61,7 +65,9 @@ class CosmoTimeBasedWeatherValueFactoryTest extends Specification {
       "directIrradiance" : "286.872985839844",
       "temperature"      : "278.019012451172",
       "windDirection"    : "0",
-      "windVelocity"     : "1.66103506088257"
+      "windVelocity"     : "1.66103506088257",
+      "groundTemperatureLevel1"     : "",
+      "groundTemperatureLevel2"     : ""
     ]
 
     def data = new TimeBasedWeatherValueData(parameter, coordinate)
@@ -72,7 +78,9 @@ class CosmoTimeBasedWeatherValueFactoryTest extends Specification {
         Quantities.getQuantity(282.671997070312d, StandardUnits.SOLAR_IRRADIANCE),
         Quantities.getQuantity(278.019012451172d, StandardUnits.TEMPERATURE),
         Quantities.getQuantity(0d, StandardUnits.WIND_DIRECTION),
-        Quantities.getQuantity(1.66103506088257d, StandardUnits.WIND_VELOCITY)))
+        Quantities.getQuantity(1.66103506088257d, StandardUnits.WIND_VELOCITY),
+        Optional.of(Quantities.getQuantity(278.019012451172d, StandardUnits.TEMPERATURE)),
+        Optional.of(Quantities.getQuantity(278.019012451172d, StandardUnits.TEMPERATURE))))
 
     when:
     def model = factory.buildModel(data)