Introducing energy demand for warm water heating

CHANGELOG.md

@@ -63,6 +63,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Replace `BmModel` with its new implementation [#1157](https://github.com/ie3-institute/simona/issues/1157)
 - Integration test for thermal grids without Em [#1145](https://github.com/ie3-institute/simona/issues/1145)
 - Change thermal house behaviour to heat till targetTemperature [#1176](https://github.com/ie3-institute/simona/issues/1176)
+- Integration test for thermal grids with Em [#1146](https://github.com/ie3-institute/simona/issues/1146)
+- Introducing warm water heating to `ThermalHouse` [#856](https://github.com/ie3-institute/simona/issues/856)
 
 ### Changed
 - Adapted to changed data source in PSDM [#435](https://github.com/ie3-institute/simona/issues/435)

docs/readthedocs/models.md

@@ -29,6 +29,7 @@ maxdepth: 1
 models/bm_model
 models/chp_model
 models/cts_model
+models/dhws_model
 models/evcs_model
 models/hp_model
 models/load_model

docs/readthedocs/models/cts_model.md

@@ -3,7 +3,7 @@
 This page documents the functionality of the cylindrical thermal storage available in SIMONA.
 
 ## Behaviour
-This storage model operates on volumes, although the functions it provides for other models all operate with energy. Internally the storage model converts energy to volume and vice versa with formulas specified below. Furthermore, it is assumed that the storage medium is water. Also, the model holds a variable for the current storage level.
+This storage model operates on volumes, although the functions it provides for other models all operate with energy. Internally the storage model converts energy to volume and vice versa with formulas specified below. Furthermore, it is assumed that the storage medium is water. Also, the model holds a variable for the current storage level. At initialisation the storage will be empty.
 
 ## Attributes, Units and Remarks
 

docs/readthedocs/models/dhws_model.md

@@ -0,0 +1,56 @@
+(dhws_model)=
+# Domestic Hot Water Storage
+This page documents the functionality of the domestic hot water storage available in SIMONA.
+
+## Behaviour
+This storage model operates on volumes, although the functions it provides for other models all operate with energy. Internally the storage model converts energy to volume and vice versa with formulas specified below. Furthermore it is assumed that the storage medium is water. Also the model holds a variable for the current storage level. At initialisation the storage will be full. Domestic hot water storage will be refilled when the state of charge will be below 20 % or when the required water demand can not be covered by the stored energy in the storage itself.
+
+## Attributes, Units and Remarks
+
+Please refer to  {doc}`PowerSystemDataModel - CTS Model <psdm:models/input/thermal/domestichotwaterstorage>` for Attributes and Units used in this Model.
+
+## Calculations
+### Maximal storage capacity
+As the name suggests this storage has a cylindric form, hence its maximum storage capacity $V_{st, max}$ can be given by:
+
+$$
+V_{st, max} = \pi \cdot r^2 \cdot h
+$$
+
+### Conversions of energy and volume
+
+In this model the change of stored energy (heat) is represented by the change of the volume of the storage medium. This relation between stored heat and volume change is given by:
+
+$$
+V = (\frac{W}{c \cdot (tE - tA)})
+$$
+
+with
+W = energy to be converted to volume
+V = resulting volume
+tE = return temperature
+tA = inlet temperature
+c = $1,15 \frac{kWh}{m^3 \cdot K}$
+
+The original equation is given by:
+
+$$
+\Delta V_{st} = (\frac{\dot{Q_{th}} \cdot \Delta t}{c \cdot (tA - tE)})
+$$
+
+Reference:
+
+* {cite:cts}`Quaschning.2013`
+
+
+That is the mathematical description of loading and unloading processes concerning the buffer storage. Whenever heat is stored within the storage or removed from the storage this equation is used. This includes the case that the whole heat demand is satisfied by the storage.
+
+The same relationship is used to determine the quantity of heat which is stored in the storage by converting the equation to:
+
+$$
+W = V \cdot c \cdot (tE - tA)
+$$
+
+## Store/Take energy
+
+This calculation is performed as follows: An amount of energy is specified for storing or taking. The model then changes the storage level and returns if it exceeded the maximum (when storing energy) or the minimum (when taking energy).

docs/readthedocs/models/thermal_house_model.md

@@ -4,10 +4,10 @@
 
 This page documents the functionality of the thermal house available in SIMONA.
 
+
 ## Behaviour
 
-This house model represents the thermal behaviour of a building. It represents a simple shoebox with thermal capacity and transmission losses.
-The house can optionally be equipped with a {ref}`cts_model` as thermal storage. Both are connected by the {ref}`thermal_grid_model`.
+This house model represents the thermal behaviour of a building. It represents a simple shoebox with thermal capacity and  transmission losses for its heating demand. As well the hot water demand (tap water) based on the number of inhabitants and the housing type on hourly basis is considered. The house can optionally be equipped with a {ref}`cts_model` as thermal storage. Both are connected by the {ref}`thermal_grid_model`.
 
 The thermal house provides two different energy demands. The required demand indicates that the inner temperature of the house is below the lower temperature boundary and thus, requires mandatory heating. An additional demand indicates the amount of energy necessary to reach the target temperature. Additional demand not necessarily requires to be covered but could, e.g. for flexibility purposes.
 
@@ -21,7 +21,9 @@ As the storage is initialised as empty, the heat source will start charging the
 
 ### Behaviour under EM control
 
-Currently, not fully supported. Will be fixed by [PR #1159](https://github.com/ie3-institute/simona/pull/1159)
+When {ref}`em` is applied to the heat source of this building, the thermal behaviour should be basically the same as without EM control, so internal temperature of the house should remain between the target temperature and the lower temperature limit. 
+
+However, for flexibility usage, the energy management system can turn on the heat source whenever the thermal house has additional demand. Same for the thermal storage. When the heat source is EM controlled, the thermal storage will only be recharged when the flexibility strategy allows. E.g. when there is surplus energy from PV plant.
 
 ## Attributes, Units and Remarks
 

src/main/scala/edu/ie3/simona/agent/participant/ParticipantAgentFundamentals.scala

@@ -61,7 +61,6 @@ import edu.ie3.simona.event.ResultEvent
 import edu.ie3.simona.event.ResultEvent.{
   FlexOptionsResultEvent,
   ParticipantResultEvent,
-  ThermalResultEvent,
 }
 import edu.ie3.simona.event.notifier.NotifierConfig
 import edu.ie3.simona.exceptions.CriticalFailureException
@@ -1946,8 +1945,7 @@ protected trait ParticipantAgentFundamentals[
       result: R
   ): Option[ResultEvent] = result match {
     case thermalUnitResult: ThermalUnitResult =>
-      Some(ThermalResultEvent(thermalUnitResult))
-
+      Some(ResultEvent.ThermalResultEvent(thermalUnitResult))
     case unsupported =>
       log.debug(
         s"Results of class '${unsupported.getClass.getSimpleName}' are currently not supported."

src/main/scala/edu/ie3/simona/agent/participant/hp/HpAgentFundamentals.scala

@@ -430,6 +430,12 @@ trait HpAgentFundamentals
     HpRelevantData(
       tick,
       weatherData.temp.inKelvin,
+      baseStateData.startDate,
+      baseStateData.model.thermalGrid.house.map(_.houseInhabitants).getOrElse {
+        throw new InconsistentStateException(
+          s"The model ${baseStateData.model.thermalGrid.house} was not provided with the needed number of inhabitants."
+        )
+      },
     )
   }
 

src/main/scala/edu/ie3/simona/event/ResultEvent.scala

@@ -18,9 +18,11 @@ import edu.ie3.datamodel.models.result.system.{
 }
 import edu.ie3.datamodel.models.result.thermal.{
   CylindricalStorageResult,
+  DomesticHotWaterStorageResult,
   ThermalHouseResult,
   ThermalUnitResult,
 }
+import edu.ie3.datamodel.models.result.system.{EmResult, HpResult}
 import edu.ie3.simona.agent.grid.GridResultsSupport.PartialTransformer3wResult
 import edu.ie3.simona.event.listener.ResultEventListener
 import tech.units.indriya.ComparableQuantity
@@ -45,6 +47,44 @@ object ResultEvent {
       systemParticipantResult: SystemParticipantResult
   ) extends ResultEvent
 
+  object HpResult {
+    def unapply(result: HpResult): Option[
+      (
+          ZonedDateTime,
+          UUID,
+          ComparableQuantity[Power],
+          ComparableQuantity[Power],
+      )
+    ] =
+      Option(result).map { result =>
+        (
+          result.getTime,
+          result.getInputModel,
+          result.getP,
+          result.getQ,
+        )
+      }
+  }
+
+  object EmResult {
+    def unapply(result: EmResult): Option[
+      (
+          ZonedDateTime,
+          UUID,
+          ComparableQuantity[Power],
+          ComparableQuantity[Power],
+      )
+    ] =
+      Option(result).map { result =>
+        (
+          result.getTime,
+          result.getInputModel,
+          result.getP,
+          result.getQ,
+        )
+      }
+  }
+
   /** Event, that is triggered every time a thermal model has a new result
     * @param thermalResult
     *   Result of the thermal calculation
@@ -92,6 +132,26 @@ object ResultEvent {
     }
   }
 
+  object DomesticHotWaterStorageResult {
+    def unapply(result: DomesticHotWaterStorageResult): Option[
+      (
+          ZonedDateTime,
+          UUID,
+          ComparableQuantity[Power],
+          ComparableQuantity[Energy],
+      )
+    ] = {
+      Option(result).map { result =>
+        (
+          result.getTime,
+          result.getInputModel,
+          result.getqDot,
+          result.getEnergy,
+        )
+      }
+    }
+  }
+
   /** Event that holds all grid calculation results of a power flow calculation.
     * The usage of a type is necessary here, to avoid passing in other instances
     * of [[edu.ie3.datamodel.models.result.ResultEntity]] except of the wanted

src/main/scala/edu/ie3/simona/model/participant/HpModel.scala

@@ -175,7 +175,8 @@ final case class HpModel(
     *   ThermalEnergyDemand of the house and the thermal storage
     * @return
     *   boolean defining if heat pump runs in next time step, if it can be in
-    *   operation and can be out of operation
+    *   operation and out of operation plus the [[ThermalEnergyDemand]] of
+    *   house, heat storage, domestic hot water storage
     */
   private def operatesInNextState(
       lastState: HpState,
@@ -186,20 +187,26 @@ final case class HpModel(
 
     val demandHouse = thermalDemands.houseDemand
     val demandThermalStorage = thermalDemands.heatStorageDemand
+    val demandDomesticHotWaterStorage =
+      thermalDemands.domesticHotWaterStorageDemand
+
     val noThermalStorageOrThermalStorageIsEmpty =
       currentThermalGridState.isThermalStorageEmpty
 
     val turnHpOn =
       (demandHouse.hasRequiredDemand && noThermalStorageOrThermalStorageIsEmpty) ||
         (demandHouse.hasAdditionalDemand && lastState.isRunning) ||
         demandThermalStorage.hasRequiredDemand ||
-        (demandThermalStorage.hasAdditionalDemand && lastState.isRunning)
+        (demandThermalStorage.hasAdditionalDemand && lastState.isRunning) ||
+        demandDomesticHotWaterStorage.hasRequiredDemand ||
+        (demandDomesticHotWaterStorage.hasAdditionalDemand && lastState.isRunning)
 
     val canOperate =
       demandHouse.hasRequiredDemand || demandHouse.hasAdditionalDemand ||
-        demandThermalStorage.hasRequiredDemand || demandThermalStorage.hasAdditionalDemand
+        demandThermalStorage.hasRequiredDemand || demandThermalStorage.hasAdditionalDemand ||
+        demandDomesticHotWaterStorage.hasRequiredDemand || demandDomesticHotWaterStorage.hasAdditionalDemand
     val canBeOutOfOperation =
-      !(demandHouse.hasRequiredDemand && noThermalStorageOrThermalStorageIsEmpty)
+      !(demandHouse.hasRequiredDemand && noThermalStorageOrThermalStorageIsEmpty) && !demandDomesticHotWaterStorage.hasRequiredDemand
 
     (
       turnHpOn,
@@ -218,8 +225,9 @@ final case class HpModel(
     *   data of heat pump including state of the heat pump
     * @param isRunning
     *   determines whether the heat pump is running or not
-    * @param demandWrapper
-    *   holds the thermal demands of the thermal units (house, storage)
+    * @param thermalDemands
+    *   holds the thermal demands of the thermal units (house, heatStorage,
+    *   hotDomesticWaterStorage)
     * @param currentThermalGridState
     *   Current state of the thermalGrid
     * @return
@@ -229,7 +237,7 @@ final case class HpModel(
       lastState: HpState,
       relevantData: HpRelevantData,
       isRunning: Boolean,
-      demandWrapper: ThermalDemandWrapper,
+      thermalDemands: ThermalDemandWrapper,
       currentThermalGridState: ThermalGridState,
   ): HpState = {
     val lastHouseQDot = lastState.thermalGridState.houseState
@@ -245,12 +253,12 @@ final case class HpModel(
       if (isRunning)
         (pRated, pThermal, pThermal)
       else if (
-        currentStorageEnergy > zeroKWh && demandWrapper.houseDemand.hasRequiredDemand
+        currentStorageEnergy > zeroKWh && thermalDemands.houseDemand.hasRequiredDemand
       ) {
         // If the house has req. demand and storage isn't empty, we can heat the house from storage.
         (zeroKW, zeroKW, currentStoragePThermal)
       } else if (
-        currentStorageEnergy > zeroKWh && demandWrapper.houseDemand.hasAdditionalDemand && lastHouseQDot > zeroKW
+        currentStorageEnergy > zeroKWh && thermalDemands.houseDemand.hasAdditionalDemand && lastHouseQDot > zeroKW
       )
         // Edge case when em controlled: If the house was heated last state by Hp and setPower is below turnOn condition now,
         // but house didn't reach target or boundary temperature yet. House can be heated from storage, if this one is not empty.
@@ -266,7 +274,7 @@ final case class HpModel(
         lastState.ambientTemperature.getOrElse(relevantData.ambientTemperature),
         isRunning,
         qDotIntoGrid,
-        demandWrapper,
+        thermalDemands,
       )
 
     HpState(
@@ -333,7 +341,7 @@ final case class HpModel(
     val turnOn = setPower > (sRated.toActivePower(cosPhiRated) * 0.5)
 
     val (
-      thermalDemandWrapper,
+      thermalDemands,
       updatedThermalGridState,
     ) =
       thermalGrid.energyDemandAndUpdatedState(
@@ -345,7 +353,7 @@ final case class HpModel(
       lastState,
       relevantData,
       turnOn,
-      thermalDemandWrapper,
+      thermalDemands,
       updatedThermalGridState,
     )
 
@@ -445,10 +453,16 @@ object HpModel {
     *   contains current time tick
     * @param ambientTemperature
     *   Ambient temperature at current tick
+    * @param simulationStart
+    *   simulationStartDate as ZonedDateTime
+    * @param houseInhabitants
+    *   number of people living in the building
     */
   final case class HpRelevantData(
       currentTick: Long,
       ambientTemperature: Temperature,
+      simulationStart: ZonedDateTime,
+      houseInhabitants: Double,
   ) extends CalcRelevantData
 
   /** Internal method to construct a new [[HpModel]] based on a provided