Merge branch 'dev' into ms/#188-consider-none-equivalent-value-for-mi…

…ssing-data-pints-in-weather

# Conflicts:
#	CHANGELOG.md
#	src/main/scala/edu/ie3/simona/service/weather/WeatherSource.scala

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add additional test cases from references for PvModelTest [#590](https://github.com/ie3-institute/simona/issues/590)
 - Instantiation of Heat Pump Agents [#253](https://github.com/ie3-institute/simona/issues/253)
 - Output of accompanying thermal result models
+- Added JDK installation, Scala Plugin + SDK in usersguide [#324](https://github.com/ie3-institute/simona/issues/324)
 - Added an interpolation for missing weather data [#188](https://github.com/ie3-institute/simona/issues/188)
 
 ### Changed
@@ -27,6 +28,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Schedule lock [#651](https://github.com/ie3-institute/simona/issues/651)
   - New scheduling protocol [#650](https://github.com/ie3-institute/simona/issues/650)
 - Replaced akka with pekko [#641](https://github.com/ie3-institute/simona/issues/641)
+- Use `ThermalGrid` to calculate thermal environment of a heat pump [#315](https://github.com/ie3-institute/simona/issues/315)
+
+### Fixed
+- Removed a repeated line in the documentation of vn_simona config [#658](https://github.com/ie3-institute/simona/issues/658)
+- Removed version number "2.0" from the logo printed to console [#642](https://github.com/ie3-institute/simona/issues/642)
+- Fixed PV Model documentation [#684](https://github.com/ie3-institute/simona/issues/684), [#686](https://github.com/ie3-institute/simona/issues/686)
 
 ## [3.0.0] - 2023-08-07
 
@@ -124,6 +131,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed broken layout in RTD documentation [#500](https://github.com/ie3-institute/simona/issues/500)
 - Corrected tests in RefSystemTest [#560](https://github.com/ie3-institute/simona/issues/560)
 - Take log file event filters from `logback.xml` when defining the run log appender [#108](https://github.com/ie3-institute/simona/issues/108)
+- Fix rendering of references in documentation [#505](https://github.com/ie3-institute/simona/issues/505)
 
 ### Removed
 - Remove workaround for tscfg tmp directory [#178](https://github.com/ie3-institute/simona/issues/178)

build.gradle

@@ -7,7 +7,7 @@ plugins {
   id 'signing'
   id 'maven-publish' // publish to a maven repo (local or mvn central, has to be defined)
   id 'pmd' // code check, working on source code
-  id 'com.diffplug.spotless' version '6.23.0'// code format
+  id 'com.diffplug.spotless' version '6.23.3'// code format
   id "com.github.ben-manes.versions" version '0.50.0'
   id "de.undercouch.download" version "5.5.0" // downloads plugin
   id "kr.motd.sphinx" version "2.10.1" // documentation generation
@@ -102,12 +102,12 @@ dependencies {
 
   /* logging */
   implementation "com.typesafe.scala-logging:scala-logging_${scalaVersion}:3.9.5" // pekko scala logging
-  implementation "ch.qos.logback:logback-classic:1.4.13"
+  implementation "ch.qos.logback:logback-classic:1.4.14"
 
   /* testing */
   testImplementation 'org.spockframework:spock-core:2.3-groovy-4.0'
   testImplementation 'org.scalatestplus:mockito-3-4_2.13:3.2.10.0'
-  testImplementation 'org.mockito:mockito-core:5.7.0' // mocking framework
+  testImplementation 'org.mockito:mockito-core:5.8.0' // mocking framework
   testImplementation "org.scalatest:scalatest_${scalaVersion}:3.2.17"
   testRuntimeOnly 'com.vladsch.flexmark:flexmark-all:0.64.8' //scalatest html output
   testImplementation group: 'org.pegdown', name: 'pegdown', version: '1.6.0'

docs/readthedocs/models.md

@@ -15,6 +15,7 @@ models/switch_model
 models/two_winding_transformer_model
 models/three_winding_transformer_model
 models/reference_system
+models/thermal_grid_model
 ```
 
 ## System Participant Related Models

docs/readthedocs/models/pv_model.md

@@ -30,7 +30,7 @@ To calculate the overall feed in of the pv unit, the sum of the direct radiation
 
 **Caution:** all angles are given in radian!
 
-The azimuth angle $\alpha_{E}$ starts at negative values in the East and moves over 0° (South) towards positive values in the West. [Source](https://www.photovoltaik.org/wissen/azimutwinkel)
+The surface azimuth angle $\alpha_{E}$ starts at negative values in the East and moves over 0° (South) towards positive values in the West. [(Source)](https://www.photovoltaik.org/wissen/azimutwinkel)
 
 ### Declination Angle
 
@@ -46,8 +46,8 @@ $$
 Based on $J$ the declination angle $\delta$ (in radian!) can be calculated as follows:
 
 $$
-\begin{eqnarray*}\delta = 0.006918 - 0.399912 \cdot cos(J) + 0.070257 \cdot
-sin(J) \\ - 0.006758 \cdot cos(2\cdot J) + 0.000907 \cdot sin(2 \cdot J) \\ - 0.002697 \cdot cos(3 \cdot J) + 0.00148 \cdot sin(3 \cdot J)
+\begin{eqnarray*}\delta = 0.006918 - 0.399912 \cdot \cos(J) + 0.070257 \cdot
+\sin(J) \\ - 0.006758 \cdot \cos(2\cdot J) + 0.000907 \cdot \sin(2 \cdot J) \\ - 0.002697 \cdot \cos(3 \cdot J) + 0.00148 \cdot \sin(3 \cdot J)
 \end{eqnarray*}
 $$
 
@@ -92,8 +92,8 @@ $$
 **λ** = longitude of the location of the PV panel
 
 $$
-\begin{eqnarray*}ET = 0.0066 + 7.3525 \cdot cos(J + 1.4992378274631293) \\ +
-9.9359 \cdot cos(2 \cdot J + 1.9006635554218247) \\ + 0.3387 \cdot cos(3 \cdot J + 1.8360863730980346)
+\begin{eqnarray*}ET = 0.0066 + 7.3525 \cdot \cos(J + 1.4992378274631293) \\ +
+9.9359 \cdot \cos(2 \cdot J + 1.9006635554218247) \\ + 0.3387 \cdot \cos(3 \cdot J + 1.8360863730980346)
 \end{eqnarray*}
 $$
 
@@ -112,18 +112,19 @@ $$
 
 ### Sunrise Angle
 
-The hour angles at sunrise and sunset are very useful quantities to know. These two values have the same absolute value, however the sunrise angle ($\omega_{SR}$) is positive and the sunset angle ($\omega_{S}$) is negative. Both can be calculated from:
+The hour angles at sunrise and sunset are very useful quantities to know. These two values have the same absolute value, however the sunset angle ($\omega_{SS}$) is positive and the sunrise angle ($\omega_{SR}$) is negative. Both can be calculated from:
 
 $$
-\omega_{SR}=\cos^{-1}(-\tan (\phi) \cdot \tan (\delta))
+\omega_{SS}=\cos^{-1}(-\tan (\phi) \cdot \tan (\delta))
 $$
 
 $$
-\omega_{SS}=-\omega_{SR}
+\omega_{SR}=-\omega_{SS}
 $$
 
 *with*\
-**$\delta$** = the declination angle
+**$\delta$** = the declination angle\
+**$\phi$** = observer's latitude
 
 **References:**
 ```{eval-rst}
@@ -136,7 +137,7 @@ $$
 Represents the angle between the horizontal and the line to the sun, that is, the complement of the zenith angle.
 
 $$
-sin(\alpha_{s}) = sin (\phi) \cdot sin (\delta) + cos (\delta) \cdot cos (\omega) \cdot cos (\phi)
+\sin(\alpha_{s}) = \sin (\phi) \cdot \sin (\delta) + \cos (\delta) \cdot \cos (\omega) \cdot \cos (\phi)
 $$
 
 *with*\
@@ -177,14 +178,13 @@ $$
 \cos(\delta) \cdot \cos(\phi) \cdot \cos(\gamma_{e}) \cdot
 \cos(\omega) \\ + \cos(\delta) \cdot \sin(\phi) \cdot \sin(\gamma_{e})
 \cdot \cos(\alpha_{e}) \cdot \cos(\omega) \\ +
-cos(\delta) \cdot sin(\gamma_{e}) \cdot sin(\alpha_{e}) \cdot
-sin(\omega))
+\cos(\delta) \cdot \sin(\gamma_{e}) \cdot \sin(\alpha_{e}) \cdot
+\sin(\omega))
 \end{eqnarray*}
 $$
 
 *with*\
-**$\alpha_e$** = sun azimuth\
-**$\alpha_s$** = solar altitude angle\
+**$\alpha_e$** = surface azimuth angle\
 **$\gamma_e$** = slope angle of the surface\
 **$\delta$** = the declination angle\
 **$\phi$** = observer's latitude\
@@ -254,6 +254,8 @@ $$
 \end{eqnarray*}
 $$
 
+Additionally, the condition $\theta_{g} < 90°$ must be met (the sun must not be behind the surface).
+
 *with*\
 **$\omega$** = hour angle\
 **$\omega_{SS}$** = hour angle $\omega$ at sunset\
@@ -264,10 +266,10 @@ From here on, formulas from given reference below are used:
 
 $$
 \begin{eqnarray*}
-a = (\sin(\delta) \cdot \sin(\phi) \cdot \cos(\gamma_{e})
+a = (\sin(\delta) \cdot \sin(\phi) \cdot \cos(\gamma_{e}) - 
 \sin(\delta) \cdot \cos(\phi) \cdot \sin(\gamma_{e}) \cdot
 \cos(\alpha_{e})) \cdot (\omega_{2} - \omega_{1}) \\ + (\cos(\delta) \cdot \cos(\phi) \cdot \cos(\gamma_{e}) +
-\cos(\delta) \cdot \sin(\phi) \cdot \sin(\gamma\_{e}) \cdot
+\cos(\delta) \cdot \sin(\phi) \cdot \sin(\gamma_{e}) \cdot
 \cos(\alpha_{e})) \cdot (\sin(\omega_{2}) \\ -
 \sin(\omega_{1}))  - (\cos(\delta) \cdot \sin(\gamma_{e}) \cdot \sin(\alpha_{e})) \cdot (\cos(\omega_{2}) - \cos(\omega_{1}))
 \end{eqnarray*}
@@ -278,19 +280,19 @@ b = (\cos(\phi) \cdot \cos(\delta)) \cdot (\sin(\omega_{2}) - \sin(\omega_{1}))
 $$
 
 $$
-E_{dir,S} = E_{dir,H} \cdot \frac{a}{b}
+E_{beam,S} = E_{beam,H} \cdot \frac{a}{b}
 $$
 
 **Please note:** $\frac{1}{180}\pi$ is omitted from these formulas, as we are already working with data in *radians*.
 
 *with*\
 **$\delta$** = the declination angle\
 **$\phi$** = observer's latitude\
-**$\gamma$** = slope angle of the surface\
+**$\gamma_{e}$** = slope angle of the surface\
 **$\omega_1$** = hour angle $\omega$\
 **$\omega_2$** = hour angle $\omega$ + 1 hour\
-**$\alpha_e$** = sun azimuth\
-**$E_{dir,H}$** = beam radiation (horizontal surface)
+**$\alpha_e$** = surface azimuth angle\
+**$E_{beam,H}$** = beam radiation (horizontal surface)
 
 **Reference:**
 
@@ -305,7 +307,7 @@ The diffuse radiation is computed using the Perez model, which divides the radia
 A cloud index is defined by
 
 $$
-\epsilon = \frac{\frac{E_{dif,H} + E_{dir,H}}{E_{dif,H}} + 5.535 \cdot 10^{-6} \cdot \theta_{z}^3}{1 + 5.535 \cdot 10^{-6} \cdot \theta_{z}^3}
+\epsilon = \frac{\frac{E_{dif,H} + E_{beam,H}}{E_{dif,H}} + 5.535 \cdot 10^{-6} \cdot \theta_{z}^3}{1 + 5.535 \cdot 10^{-6} \cdot \theta_{z}^3}
 $$
 
 Calculating a brightness index
@@ -398,11 +400,10 @@ $$
 **$\theta_{z}$** = zenith angle\
 **$\theta_{g}$** = angle of incidence\
 **$\alpha_{s}$** = solar altitude angle\
-**$\alpha_{z}$** = sun azimuth\
 **$\gamma_{e}$** = slope angle of the surface\
 **$I_{0}$** = Extraterrestrial Radiation\
 **$m$** = air mass\
-**$E_{dir,H}$** = direct radiation (horizontal surface)\
+**$E_{beam,H}$** = beam radiation (horizontal surface)\
 **$E_{dif,H}$** = diffuse radiation (horizontal surface)
 
 **References:**
@@ -421,7 +422,7 @@ E_{ref,S} = E_{Ges,H} \cdot \frac{\rho}{2} \cdot (1-
 $$
 
 *with*\
-**$E_{Ges,H}$** = total horizontal radiation ($E_{dir,H} + E_{dif,H})$\
+**$E_{Ges,H}$** = total horizontal radiation ($E_{beam,H} + E_{dif,H})$\
 **$\gamma_e$** = slope angle of the surface\
 **$\rho$** = albedo
 
@@ -436,11 +437,11 @@ $$
 Received energy is calculated as the sum of all three types of irradiation.
 
 $$
-E_{total} = E_{dir,S} + E_{dif,S} + E_{ref,S}
+E_{total} = E_{beam,S} + E_{dif,S} + E_{ref,S}
 $$
 
 *with*\
-**$E_{dir,S}$** = Beam radiation\
+**$E_{beam,S}$** = Beam radiation\
 **$E_{dif,S}$** = Diffuse radiation\
 **$E_{ref,S}$** = Reflected radiation
 

docs/readthedocs/models/thermal_grid_model.md

@@ -0,0 +1,8 @@
+(thermal_grid_model)=
+# Thermal Grid Model
+
+The Thermal Grid Model introduces a coupling point to thermal system, equivalent to an electrical node. It can be used to interconnect thermal units to a thermal heat network.
+
+## Attributes, Units and Remarks
+
+Please refer to {doc}`PowerSystemDataModel - Thermal Bus <psdm:models/input/participant/thermalbus>` for Attributes and Units used in this Model.

docs/readthedocs/requirements.txt

@@ -1,7 +1,7 @@
-Sphinx==5.3.0
-sphinx-rtd-theme==1.3.0
+Sphinx==7.2.6
+sphinx-rtd-theme==2.0.0
 sphinxcontrib-plantuml==0.27
-myst-parser==1.0.0
-markdown-it-py==2.2.0
+myst-parser==2.0.0
+markdown-it-py==3.0.0
 sphinx-hoverxref==1.3.0
 sphinxcontrib-bibtex==2.6.1

docs/readthedocs/usersguide.md

@@ -6,7 +6,17 @@ The user's guide is here to give you a basic rundown of all the things you need
 
 ## Requirements
 
-To run and customize the project you need a Java Development Kit (JDK) installation. You can download it [here](https://adoptopenjdk.net/).
+To run and customise the project you need to install **Java Development Kit (JDK)**, which you can do directly from IntelliJ IDEA. To do this, press ``ALT + Ctrl + Shift + s`` to open the Project Structure window. Go to ``SDKs``, press on the ``+`` sign in the second column and select ``Download JDK``. Then select version 17 from any vendor and click ``download``. Also, make sure version 17 is selected in the Project tab of the Project Structure window.
+
+![](../readthedocs/images/usersguide/jdk-download.png)
+
+Additionally, a **Scala Plugin** is required to work with SIMONA. If it is not already installed, a notification will pop up at the top of the editor, which lets you quickly download one.
+
+![](../readthedocs/images/usersguide/scala-plugin.png)
+
+Finally, you will also need a **Scala SDK**. Similarly to the Scala Plugin, a notification will let you know if you have not installed one already. To fix this issue, go to ``Setup Scala SDK -> create``, then choose the newest version and download.
+
+![](../readthedocs/images/usersguide/scala-sdk-error.png)
 
 
 ## Installation
@@ -83,7 +93,7 @@ If you are using IntelliJ IDEA as your IDE, this is how setting the command line
 
     ![](../readthedocs/images/usersguide/edit-conf2.png)
 
-4. Click Apply on the bottom right
+4. Click ``Apply`` on the bottom right
 
 
 ### Configuring your Simulation
@@ -95,7 +105,7 @@ For a detailed description on how to do that and all the various configuration p
 ### Model and Grid Data
 
 Besides a simulation configuration, the specifications of each grid component (e.g. lines, transformers, ...) and system participant (e.g. loads, pv plants, ... ) have to be fed into the simulation.
-Within SIMONA, we use the PowerSystemDataModel (PSDM) for modeling the system components.
+Within SIMONA, we use the [PowerSystemDataModel (PSDM)](https://github.com/ie3-institute/PowerSystemDataModel) for modeling the system components.
 Before the data can be utilized for a simulation run, make sure to convert them to the PSDM.
 For more information on the PSDM visit the [docs](https://powersystemdatamodel.readthedocs.io/en/latest/index.html) and for an example of how the converted data looks like you can take a look at an example grid at ``./input/samples/vn_simona/fullGrid``.
 The example grids are provided as csv files. You can choose to use a different data source for your own grid.

docs/uml/main/models/thermal/grid/HandleConsumption.puml

@@ -0,0 +1,15 @@
+@startuml
+'https://plantuml.com/activity-diagram-beta
+
+start
+if (house exists?) then (yes)
+  :Set qDot = 0 and\ncalculate next threshold;
+else (no)
+endif
+if (storage exists?) then (yes)
+  :Discharge storage and calculate next threshold;
+endif
+:Return thermal grid state and grid threshold;
+stop
+
+@enduml

docs/uml/main/models/thermal/grid/HandleInfeed.puml

@@ -0,0 +1,15 @@
+@startuml
+'https://plantuml.com/activity-diagram-beta
+
+start
+if (house exists?) then (no)
+  :Fill storage;
+else if (house below upper temp?) then (yes)
+    :Heat the house;
+else if (storage exists?) then (yes)
+:Fill storage;
+endif
+:Return updated state and reached threshold;
+stop
+
+@enduml

input/samples/vn_simona/vn_simona.conf

@@ -4,7 +4,6 @@ include "../common/pekko.conf"
 # ATTENTION: Do not change this config file directly but use it as a base for your personal delta config for the
 # vn_simona scenario! Delta configs can be created by including the config you want to change
 # parameters from via include <path-to-config> (e.g. include "input/samples/vn_simona/vn_simona.conf") at the
-# parameters from via include <path-to-config> (e.g. include "input/samples/vn_simona/vn_simona.conf") at the
 # beginning of your config file and then just override the parameters you want to change!
 #########
 

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

@@ -500,7 +500,7 @@ abstract class ParticipantAgent[
     *   Transition to [[HandleInformation]] utilising appropriate new
     *   [[DataCollectionStateData]]
     */
-  def handleActivationAndGoToHandleInformation(
+  private def handleActivationAndGoToHandleInformation(
       tick: Long,
       baseStateData: BaseStateData[PD]
   ): FSM.State[AgentState, ParticipantStateData[PD]] = {

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

@@ -1713,7 +1713,7 @@ case object ParticipantAgentFundamentals {
   ): ApparentPower = {
     val p = QuantityUtil.average[Power, Energy](
       tickToResults.map { case (tick, pd) =>
-        tick -> Megawatts(pd.p.toMegawatts)
+        tick -> pd.p
       },
       windowStart,
       windowEnd