add ground temperature 1m as option to weather data

CHANGELOG.md

@@ -46,6 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - Extend Validation to EnergyManagement Systems. [#1356](https://github.com/ie3-institute/PowerSystemDataModel/issues/1356)
+- Add ground temperature (1m) as  option to weather data. [#1343](https://github.com/ie3-institute/PowerSystemDataModel/issues/1343)
 
 ### Fixed
 - Fixed handling of `CongestionResult.InputModelType` in `EntityProcessor` [#1325](https://github.com/ie3-institute/PowerSystemDataModel/issues/1325)

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)
+
+   * - **`groundTemperatureValueOne`**
+     - Ground temperature at 0cm for this coordinate.
+     - K (Kelvin)
+
+   * - **`groundTemperatureValueTwo`**
+     - Ground temperature at 0cm 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 0 cm and 80 cm depth are used because 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_VALUE_ONE = "groundTemperature0cm";
+  private static final String GROUND_TEMPERATURE_VALUE_TWO = "groundTemperature80cm";
 
   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_VALUE_ONE, GROUND_TEMPERATURE_VALUE_TWO);
+
+    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_VALUE_ONE, StandardUnits.TEMPERATURE);
+    Optional<ComparableQuantity<Temperature>> groundTempValTwo =
+        data.getQuantityOptional(GROUND_TEMPERATURE_VALUE_TWO, 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_VALUE_ONE = "t_v1";
+  private static final String GROUND_TEMPERATURE_VALUE_TWO = "t_v2";
 
   public IconTimeBasedWeatherValueFactory() {
     super();
@@ -53,7 +55,8 @@ protected List<Set<String>> getFields(Class<?> entityClass) {
             "albrad",
             "asobs",
             "aswdifuS",
-            "tG",
+            "t_v1",
+            "t_v2",
             "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>> groundTemperatureValueOne =
+        data.getQuantityOptional(GROUND_TEMPERATURE_VALUE_ONE, Units.KELVIN);
+    Optional<ComparableQuantity<Temperature>> groundTemperatureValueTwo =
+        data.getQuantityOptional(GROUND_TEMPERATURE_VALUE_TWO, Units.KELVIN);
+
     WeatherValue weatherValue =
         new WeatherValue(
             coordinate,
             directIrradiance,
             diffuseIrradiance,
             temperature,
             windDirection,
-            windVelocity);
+            windVelocity,
+            groundTemperatureValueOne,
+            groundTemperatureValueTwo);
     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_ONE,
+    GROUND_TEMPERATURE_TWO,
   }
 }

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

@@ -172,6 +172,17 @@ private SortedMap<String, FieldSourceToMethod> buildFieldToSource(
           .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_ONE)
+                  .accept("groundTemperatureValueOne", getter));
+      groundTempMap.forEach(
+          (fieldName, getter) ->
+              addFunction
+                  .apply(GROUND_TEMPERATURE_TWO)
+                  .accept("groundTemperatureValueTwo", getter));
 
     } else if (valueClass.equals(BdewLoadValues.class)) {
 
@@ -272,6 +283,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_ONE);
+      Optional<GroundTemperatureValue> gtOneOpt = weatherValue.getGroundTemperatureValueOne();
+      if (gtOneOpt.isPresent()) {
+        valueResult.putAll(processObject(gtOneOpt.get(), groundTempOneFieldToMethod));
+      }
+
+      Map<String, GetterMethod> groundTempTwoFieldToMethod =
+          extractFieldToMethod(GROUND_TEMPERATURE_TWO);
+      Optional<GroundTemperatureValue> gtTwoOpt = weatherValue.getGroundTemperatureValueTwo();
+      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 @@
   /** Wind values for this coordinate */
   private final WindValue wind;
 
+  /** Ground temperature value for this coordinate */
+  private final Optional<GroundTemperatureValue> groundTemperatureValueOne;
+
+  /** Ground temperature value for this coordinate */
+  private final Optional<GroundTemperatureValue> groundTemperatureValueTwo;
+
   /**
    * @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.groundTemperatureValueOne = groundTemperatureValueOne;
+    this.groundTemperatureValueTwo = 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 @@
     return wind;
   }
 
+  public Optional<GroundTemperatureValue> getGroundTemperatureValueOne() {
+    return groundTemperatureValueOne;
+  }
+
+  public Optional<GroundTemperatureValue> getGroundTemperatureValueTwo() {
+    return groundTemperatureValueTwo;
+  }
+
   @Override
   public boolean equals(Object o) {
     if (this == o) return true;
@@ -91,12 +122,20 @@
     return coordinate.equals(that.coordinate)
         && solarIrradiance.equals(that.solarIrradiance)
         && temperature.equals(that.temperature)
-        && wind.equals(that.wind);
+        && wind.equals(that.wind)
+        && Objects.equals(groundTemperatureValueOne, that.groundTemperatureValueOne)
+        && Objects.equals(groundTemperatureValueTwo, that.groundTemperatureValueTwo);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(coordinate, solarIrradiance, temperature, wind);
+    return Objects.hash(
+        coordinate,
+        solarIrradiance,
+        temperature,
+        wind,
+        groundTemperatureValueOne,
+        groundTemperatureValueTwo);
   }
 
   @Override
@@ -110,6 +149,10 @@
         + temperature
         + ", wind="
         + wind
+        + ", groundTemperatureValueOne="
+        + groundTemperatureValueOne
+        + ", groundTemperatureValueTwo="
+        + groundTemperatureValueTwo
         + '}';
   }
 }

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",
+      "groundTemperatureValueOne"     : "",
+      "groundTemperatureValueTwo"     : ""
     ]
 
     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",
+      "groundTemperatureValueOne"     : "",
+      "groundTemperatureValueTwo"     : ""
     ]
 
     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)

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

@@ -84,6 +84,8 @@ class IconTimeBasedWeatherValueFactoryTest extends Specification {
       "aswdirS"     : "2.317613203124999",
       "t2m"         : "289.1179319051744",
       "tg"          : "288.4101691197649",
+      "t_v1":"288.4101691197649",
+      "t_v2":"288.4101691197649",
       "u10m"        : "0.3021732864307963",
       "u131m"       : "2.6058700426057797",
       "u20m"        : "0.32384365019387784",
@@ -125,6 +127,10 @@ class IconTimeBasedWeatherValueFactoryTest extends Specification {
       assert QuantityUtil.isEquivalentAbs(it.value.wind.direction.get(), Quantities.getQuantity(214.16711674907722, PowerSystemUnits.DEGREE_GEOM))
       assert it.value.wind.velocity.present
       assert QuantityUtil.isEquivalentAbs(it.value.wind.velocity.get(), Quantities.getQuantity(4.640010877529081, PowerSystemUnits.METRE_PER_SECOND))
+      assert it.value.groundTemperatureValueOne.present
+      assert QuantityUtil.isEquivalentAbs(it.value.groundTemperatureValueOne.get().temperature.get(), Quantities.getQuantity(15.2601691197649, Units.CELSIUS))
+      assert it.value.groundTemperatureValueTwo.present
+      assert QuantityUtil.isEquivalentAbs(it.value.groundTemperatureValueTwo.get().temperature.get(), Quantities.getQuantity(15.2601691197649, Units.CELSIUS))
     }
   }
 }