Merge branch 'dev' into ms/#943-adding-basic-congestion-management

# Conflicts:
#	CHANGELOG.md

.github/workflows/ci.yml

@@ -28,19 +28,31 @@ jobs:
       - name: Checkout Source
         uses: actions/checkout@v4
         with:
-          fetch-depth: 1
-          ref: ${{ github.event.pull_request.head.ref || github.ref }}
-          repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }}
+          fetch-depth: 0
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v4
+
+      - name: Check Branch
+        run: |
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            branchName="${{ github.head_ref }}"
+          else
+            branchName="${{ github.ref_name }}"
+          fi
+
+          if [[ "$branchName" == refs/heads/* ]]; then
+            branchName="${branchName#refs/heads/}"
+          fi
+
+          ./gradlew checkBranchName -PbranchName="$branchName"
 
       - name: Setup Java
         uses: actions/setup-java@v4
         with:
           distribution: 'temurin'
           java-version: 17
 
-      - name: Setup Gradle
-        uses: gradle/actions/setup-gradle@v4
-
       - name: Build Project
         run: ./gradlew --refresh-dependencies clean assemble spotlessCheck
 

CHANGELOG.md

@@ -38,6 +38,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add some quote to 'printGoodbye' [#997](https://github.com/ie3-institute/simona/issues/997)
 - Add unapply method for ThermalHouseResults [#934](https://github.com/ie3-institute/simona/issues/934)
 - Added `ApparentPower` to differentiate between different power types [#794](https://github.com/ie3-institute/simona/issues/794)
+- Update/enhance config documentation [#1013](https://github.com/ie3-institute/simona/issues/1013)
+- Create `CITATION.cff` [#1035](https://github.com/ie3-institute/simona/issues/1035)
+- Introduce ThermalDemandWrapper [#1049](https://github.com/ie3-institute/simona/issues/1049)
 - Adding basic congestion management consisting of congestion detection and transformer tapping [#953](https://github.com/ie3-institute/simona/issues/943)
 
 ### Changed
@@ -103,6 +106,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Refactoring to use zeroKW and zeroKWH in thermal grid unit tests [#1023](https://github.com/ie3-institute/simona/issues/1023)
 - Refactor `ResultFileHierarchy` [#1031](https://github.com/ie3-institute/simona/issues/1031)
 - Removing logs in `logs/simona` [#1017](https://github.com/ie3-institute/simona/issues/1017)
+- Fix implausible test cases of HpModelSpec [#1042](https://github.com/ie3-institute/simona/issues/1042)
+- Refactoring to only use 'lastHpState' and 'relevantData' for 'ThermalGrid' calculations [#916](https://github.com/ie3-institute/simona/issues/916)
+- Refactor thermal calcRelevantData [#1051](https://github.com/ie3-institute/simona/issues/1051)
 
 ### Fixed
 - Fix rendering of references in documentation [#505](https://github.com/ie3-institute/simona/issues/505)
@@ -141,6 +147,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fix grammar and spelling in docs and comments [#1022](https://github.com/ie3-institute/simona/issues/1022)
 - Fix some minor issues and findings from inspections [#1019](https://github.com/ie3-institute/simona/issues/1019)
 - Fix initialisation freezing on empty primary data [#981](https://github.com/ie3-institute/simona/issues/981)
+- Shallow fetch in CI [#1041](https://github.com/ie3-institute/simona/issues/1041)
+- Correct wrong use of term "wall clock time" [#727](https://github.com/ie3-institute/simona/issues/727)
 
 ## [3.0.0] - 2023-08-07
 

CITATION.cff

@@ -0,0 +1,41 @@
+cff-version: 1.2.0
+title: SIMONA
+message: "If you use this software, please cite it as below."
+type: software
+authors:
+  - family-names: Hiry
+    given-names: Johannes
+    orcid: https://orcid.org/0000-0002-1447-0607
+  - family-names: Kittl
+    given-names: Chris
+    orcid: https://orcid.org/0000-0002-1187-0568
+  - family-names: Sen Sarma
+    given-names: Debopama
+    orcid: https://orcid.org/0000-0003-3311-3020
+  - family-names: Oberließen
+    given-names: Thomas
+    orcid: https://orcid.org/0000-0001-5805-5408
+  - family-names: Peter
+    given-names: Sebastian
+    orcid: https://orcid.org/0000-0001-6311-6113
+  - family-names: Feismann
+    given-names: Daniel
+    orcid: https://orcid.org/0000-0002-3531-9025
+  - family-names: Bao
+    given-names: Johannes
+    orcid: https://orcid.org/0009-0008-3641-6469
+  - family-names: Hohmann
+    given-names: Julian
+  - family-names: Staudt
+    given-names: Marius
+repository-code: https://github.com/ie3-institute/simona
+url: https://simona.ie3.e-technik.tu-dortmund.de
+repository-artifact: https://central.sonatype.com/artifact/com.github.ie3-institute/simona
+keywords:
+  - agent-based
+  - discrete-event simulation
+  - powerflow
+  - electricity distribution grid
+license: BSD-3-Clause
+version: 3.0.0
+date-released: 2023-08-07

build.gradle

@@ -11,7 +11,7 @@ plugins {
   id "de.undercouch.download" version "5.6.0" // downloads plugin
   id "kr.motd.sphinx" version "2.10.1" // documentation generation
   id "com.github.johnrengelman.shadow" version "8.1.1" // fat jar
-  id "org.sonarqube" version "6.0.0.5145" // sonarqube
+  id "org.sonarqube" version "6.0.1.5171" // sonarqube
   id "org.scoverage" version "8.1" // scala code coverage scoverage
   id "com.github.maiflai.scalatest" version "0.32" // run scalatest without specific spec task
   id 'org.hidetake.ssh' version '2.11.2'
@@ -54,6 +54,7 @@ apply from: scriptsLocation + 'scoverage.gradle' // scoverage scala code coverag
 apply from: scriptsLocation + 'deploy.gradle'
 apply from: scriptsLocation + 'semVer.gradle'
 apply from: scriptsLocation + 'mavenCentralPublish.gradle'
+apply from: scriptsLocation + 'branchName.gradle'
 
 configurations {
   scalaCompilerPlugin

docs/readthedocs/config.md

@@ -12,15 +12,13 @@ To create the output directory name, the name of the simulation is used as a str
   `simona.simulationName = "vn_simona"`
 
 ### Time parameters
-Starting date and time of the simulation
-  - Format: "YYYY-MM-DD HH:MM:SS"
+Starting date and time of the simulation in ISO-8601 date and time format with offset
 
-  `simona.time.startDateTime = "2011-01-01 00:00:00"`
+  `simona.time.startDateTime = "2011-01-01T00:00:00Z"`
 
-Ending date and time of the simulation
-  - Format: "YYYY-MM-DD HH:MM:SS"
+Ending date and time of the simulation in ISO-8601 date and time format with offset
 
-  `simona.time.endDateTime = "2011-01-01 02:00:00"`
+  `simona.time.endDateTime = "2011-01-01T02:00:00Z"`
 
 The preset ReadyCheckWindow should be maintained 
 
@@ -39,7 +37,9 @@ Setting of the data source
 
   `simona.input.grid.datasource.id = "csv"`
 
-Specify the folder path containing the csv data of the grid components and the csv separator (e.g. "," or ";")
+Specify the folder path containing the csv data of the grid components and the csv separator (e.g. "," or ";").
+The directory structure is determined by the boolean `isHierarchic`. 
+If files are placed within [a specific set of subdirectories](https://powersystemdatamodel.readthedocs.io/en/latest/io/csvfiles.html#default-directory-hierarchy), `isHierarchic: true` needs to be set.
 
 ```
 simona.input.primary.csvParams = {  

gradle/scripts/branchName.gradle

@@ -0,0 +1,26 @@
+tasks.register('checkBranchName') {
+  doLast {
+    if (!project.hasProperty('branchName')) {
+      throw new GradleException("Error: Missing required property 'branchName'.")
+    }
+
+    def branchName = project.property('branchName')
+
+    def patterns = [
+      ~/^(developer|develop|dev)$/,
+      ~/.*rel\/.*/,
+      ~/^dependabot\/.*$/,
+      ~/.*hotfix\/\pL{2}\/#\d+.*/,
+      ~/.*main/,
+      ~/^[a-z]{2}\/#[0-9]+(?:-.+)?$/
+    ]
+
+    def isValid = patterns.any { pattern -> branchName ==~ pattern }
+
+    if (!isValid) {
+      throw new GradleException("Error: Check Branch name format (e.g., ps/#1337-FeatureName).")
+    }
+
+    println "Branch name is $branchName"
+  }
+}

src/main/scala/edu/ie3/simona/agent/grid/GridAgentController.scala

@@ -455,9 +455,9 @@ class GridAgentController(
     * @param primaryServiceProxy
     *   Reference to the primary data service proxy
     * @param simulationStartDate
-    *   First wall clock time in simulation
+    *   The simulation time at which the simulation starts
     * @param simulationEndDate
-    *   Last wall clock time in simulation
+    *   The simulation time at which the simulation ends
     * @param resolution
     *   Frequency of power flow calculations
     * @param requestVoltageDeviationThreshold
@@ -512,9 +512,9 @@ class GridAgentController(
     * @param primaryServiceProxy
     *   Reference to the primary data service proxy
     * @param simulationStartDate
-    *   First wall clock time in simulation
+    *   The simulation time at which the simulation starts
     * @param simulationEndDate
-    *   Last wall clock time in simulation
+    *   The simulation time at which the simulation ends
     * @param resolution
     *   Frequency of power flow calculations
     * @param requestVoltageDeviationThreshold
@@ -571,9 +571,9 @@ class GridAgentController(
     * @param weatherService
     *   Reference to the weather service actor
     * @param simulationStartDate
-    *   First wall clock time in simulation
+    *   The simulation time at which the simulation starts
     * @param simulationEndDate
-    *   Last wall clock time in simulation
+    *   The simulation time at which the simulation ends
     * @param resolution
     *   Frequency of power flow calculations
     * @param requestVoltageDeviationThreshold
@@ -631,9 +631,9 @@ class GridAgentController(
     * @param evMovementsService
     *   Reference to the ev movements service actor
     * @param simulationStartDate
-    *   First wall clock time in simulation
+    *   The simulation time at which the simulation starts
     * @param simulationEndDate
-    *   Last wall clock time in simulation
+    *   The simulation time at which the simulation ends
     * @param resolution
     *   Frequency of power flow calculations
     * @param requestVoltageDeviationThreshold
@@ -749,9 +749,9 @@ class GridAgentController(
     * @param weatherService
     *   Reference to the weather service actor
     * @param simulationStartDate
-    *   First wall clock time in simulation
+    *   The simulation time at which the simulation starts
     * @param simulationEndDate
-    *   Last wall clock time in simulation
+    *   The simulation time at which the simulation ends
     * @param resolution
     *   Frequency of power flow calculations
     * @param requestVoltageDeviationThreshold
@@ -807,9 +807,9 @@ class GridAgentController(
     * @param primaryServiceProxy
     *   Reference to the primary data service proxy
     * @param simulationStartDate
-    *   First wall clock time in simulation
+    *   The simulation time at which the simulation starts
     * @param simulationEndDate
-    *   Last wall clock time in simulation
+    *   The simulation time at which the simulation ends
     * @param resolution
     *   Frequency of power flow calculations
     * @param requestVoltageDeviationThreshold

src/main/scala/edu/ie3/simona/agent/grid/GridResultsSupport.scala

@@ -617,7 +617,7 @@ object GridResultsSupport {
     /** Partial result for the port at the high voltage side
       *
       * @param time
-      *   Wall clock time, the result does belong to
+      *   Simulation time of the result
       * @param input
       *   Unique identifier of the input model
       * @param currentMagnitude
@@ -638,7 +638,7 @@ object GridResultsSupport {
     /** Partial result for the port at the medium voltage side
       *
       * @param time
-      *   Wall clock time, the result does belong to
+      *   Simulation time of the result
       * @param input
       *   Unique identifier of the input model
       * @param currentMagnitude
@@ -656,7 +656,7 @@ object GridResultsSupport {
     /** Partial result for the port at the low voltage side
       *
       * @param time
-      *   Wall clock time, the result does belong to
+      *   Simulation time of the result
       * @param input
       *   Unique identifier of the input model
       * @param currentMagnitude

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

@@ -214,9 +214,9 @@ protected trait ParticipantAgentFundamentals[
     * @param modelConfig
     *   Configuration for the model
     * @param simulationStartDate
-    *   Wall clock time of first instant in simulation
+    *   Simulation time of first instant in simulation
     * @param simulationEndDate
-    *   Wall clock time of last instant in simulation
+    *   Simulation time of last instant in simulation
     * @return
     */
   def buildModel(

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

@@ -440,9 +440,9 @@ trait HpAgentFundamentals
     * @param modelConfig
     *   Configuration for the model
     * @param simulationStartDate
-    *   Wall clock time of first instant in simulation
+    *   Simulation time of first instant in simulation
     * @param simulationEndDate
-    *   Wall clock time of last instant in simulation
+    *   Simulation time of last instant in simulation
     * @return
     */
   override def buildModel(

src/main/scala/edu/ie3/simona/agent/participant/statedata/BaseStateData.scala

@@ -43,7 +43,7 @@ trait BaseStateData[+PD <: PrimaryDataWithApparentPower[PD]]
     */
   val startDate: ZonedDateTime
 
-  /** The wall clock date, at which the simulation ends
+  /** The simulation time at which the simulation ends
     */
   val endDate: ZonedDateTime
 
@@ -132,7 +132,7 @@ object BaseStateData {
     * @param startDate
     *   The date, that fits the tick 0
     * @param endDate
-    *   The wall clock date, at which the simulation ends
+    *   The simulation time at which the simulation ends
     * @param outputConfig
     *   Determines the output behaviour of this model
     * @param additionalActivationTicks
@@ -179,7 +179,7 @@ object BaseStateData {
     * @param startDate
     *   The date, that fits the tick 0
     * @param endDate
-    *   The wall clock date, at which the simulation ends
+    *   The simulation time at which the simulation ends
     * @param model
     *   Physical model of the load
     * @param services