Have system participants reference their respective EMs

CHANGELOG.md

@@ -23,7 +23,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Changing from comparing strings to comparing uuids in `EntitySource.findFirstEntityByUuid` [#829](https://github.com/ie3-institute/PowerSystemDataModel/issues/829)
 - Adding JavaDoc to `EntitySource.safeMapGet` [#828](https://github.com/ie3-institute/PowerSystemDataModel/issues/828)
 - Abstracting some methods in `ValidationUtils` [#852](https://github.com/ie3-institute/PowerSystemDataModel/issues/852)
-- `EmInput` should not be connected to the grid [#955](https://github.com/ie3-institute/PowerSystemDataModel/issues/955)
+- Changes to Energy Management inputs:
+  - `EmInput` should not be connected to the grid [#955](https://github.com/ie3-institute/PowerSystemDataModel/issues/955)
+  - System participants now reference the em entity [#957](https://github.com/ie3-institute/PowerSystemDataModel/issues/957)
 - Enhancing the error message for coordinate sources with invalid column names [#670](https://github.com/ie3-institute/PowerSystemDataModel/issues/670) 
 - Allowing for additional unused columns in sources [#839](https://github.com/ie3-institute/PowerSystemDataModel/issues/839)
 - Improving column name validation to only run once per source [#849](https://github.com/ie3-institute/PowerSystemDataModel/issues/849)

docs/readthedocs/models/input/participant/bm.md

@@ -107,6 +107,12 @@ Model of a biomass power plant.
      - € / MWh
      - Fixed feed in tariff
 
+   * - em
+     - --
+     - | UUID reference to an :ref:`Energy Management Unit<em_model>` that is controlling
+       | this system participant. Field can be empty or missing, if this participant
+       | is not controlled.
+
 ```
 
 ## Caveats

docs/readthedocs/models/input/participant/chp.md

@@ -114,6 +114,12 @@ Combined heat and power plant.
      - | Whether to adapt output based on (volatile)
        | market price or not
 
+   * - em
+     - --
+     - | UUID reference to an :ref:`Energy Management Unit<em_model>` that is controlling
+       | this system participant. Field can be empty or missing, if this participant
+       | is not controlled.
+
 ```
 
 ## Caveats

docs/readthedocs/models/input/participant/em.md

@@ -0,0 +1,50 @@
+(em_model)=
+
+# Energy Management Unit
+
+A model of an Energy Management Unit that controls the power of connected system participants. 
+Participants are connected to an EM each via their `em` field.
+
+## Attributes, Units and Remarks
+
+```{eval-rst}
+.. list-table::
+   :widths: 33 33 33
+   :header-rows: 0
+
+
+   * - Attribute
+     - Unit
+     - Remarks
+
+   * - uuid
+     - --
+     - 
+
+   * - id
+     - --
+     - Human readable identifier
+
+   * - operator
+     - --
+     - 
+
+   * - operationTime
+     - --
+     - Timely restriction of operation
+
+   * - controlStrategy
+     - --
+     - String representation (e.g. name) of a control strategy
+
+   * - parentEm
+     - --
+     - | Reference to a superior Energy Management Unit that is controlling this EM.
+       | Field can be empty or missing, if this EM itself is not controlled.
+
+```
+
+## Caveats
+
+Nothing - at least not known.
+If you found something, please contact us!

docs/readthedocs/models/input/participant/ev.md

@@ -93,6 +93,12 @@ Model of an electric vehicle, that is occasionally connected to the grid via an
      - --
      - 
 
+   * - em
+     - --
+     - | UUID reference to an :ref:`Energy Management Unit<em_model>` that is controlling
+       | this system participant. Field can be empty or missing, if this participant
+       | is not controlled.
+
 ```
 
 ## Caveats

docs/readthedocs/models/input/participant/evcs.md

@@ -59,6 +59,12 @@ station and has some limitations outlined below.
      - --
      - 	:ref:`Charging station location types<location-types>` 
 
+   * - em
+     - --
+     - | UUID reference to an :ref:`Energy Management Unit<em_model>` that is controlling
+       | this system participant. Field can be empty or missing, if this participant
+       | is not controlled.
+
 ```
 
 ### Type Model

docs/readthedocs/models/input/participant/fixedfeedin.md

@@ -49,6 +49,12 @@ model can be derived.
      - --
      - Rated power factor
 
+   * - em
+     - --
+     - | UUID reference to an :ref:`Energy Management Unit<em_model>` that is controlling
+       | this system participant. Field can be empty or missing, if this participant
+       | is not controlled.
+
 ```
 
 ## Caveats

docs/readthedocs/models/input/participant/hp.md

@@ -93,6 +93,12 @@ Model of a heat pump.
      - --
      -
 
+   * - em
+     - --
+     - | UUID reference to an :ref:`Energy Management Unit<em_model>` that is controlling
+       | this system participant. Field can be empty or missing, if this participant
+       | is not controlled.
+
 
 ```
 

docs/readthedocs/models/input/participant/load.md

@@ -60,6 +60,12 @@ Model of (mainly) domestic loads.
      - --
      - Rated power factor
 
+   * - em
+     - --
+     - | UUID reference to an :ref:`Energy Management Unit<em_model>` that is controlling
+       | this system participant. Field can be empty or missing, if this participant
+       | is not controlled.
+
 ```
 
 ## Caveats

docs/readthedocs/models/input/participant/pv.md

@@ -76,6 +76,12 @@ Detailed model of a photovoltaic power plant.
      - --
      - Rated power factor
 
+   * - em
+     - --
+     - | UUID reference to an :ref:`Energy Management Unit<em_model>` that is controlling
+       | this system participant. Field can be empty or missing, if this participant
+       | is not controlled.
+
 ```
 
 ## Caveats

docs/readthedocs/models/input/participant/storage.md

@@ -73,6 +73,12 @@ Model of an ideal electrical battery energy storage.
      - --
      - Permissible amount of full cycles
 
+   * - em
+     - --
+     - | UUID reference to an :ref:`Energy Management Unit<em_model>` that is controlling
+       | this system participant. Field can be empty or missing, if this participant
+       | is not controlled.
+
 ```
 
 ### Entity Model

docs/readthedocs/models/input/participant/wec.md

@@ -106,6 +106,12 @@ Model of a wind energy converter.
      - | Whether to adapt output based on (volatile)
        | market price or not
 
+   * - em
+     - --
+     - | UUID reference to an :ref:`Energy Management Unit<em_model>` that is controlling
+       | this system participant. Field can be empty or missing, if this participant
+       | is not controlled.
+
 ```
 
 ## Caveats

docs/readthedocs/models/models.md

@@ -135,6 +135,7 @@ input/participant/wec
 input/participant/thermalbus
 input/participant/thermalhouse
 input/participant/cylindricalstorage
+input/participant/em
 ```
 
 ### Additional Data

src/main/java/edu/ie3/datamodel/io/factory/FactoryData.java

@@ -135,29 +135,6 @@ field, getField(field)),
     }
   }
 
-  /**
-   * Parses and returns an array of UUIDs from field value of given field name. Throws {@link
-   * FactoryException} if field does not exist or parsing fails.
-   *
-   * @param field field name
-   * @return UUID
-   */
-  public UUID[] getUUIDs(String field) {
-    try {
-      String fieldValue = getField(field);
-      if (fieldValue.trim().isEmpty()) return new UUID[0];
-
-      String[] uuidFields = fieldValue.split(" ");
-      return Arrays.stream(uuidFields).map(UUID::fromString).toArray(UUID[]::new);
-    } catch (IllegalArgumentException iae) {
-      throw new FactoryException(
-          String.format(
-              "Exception while trying to parse UUIDs of field \"%s\" with value \"%s\"",
-              field, getField(field)),
-          iae);
-    }
-  }
-
   @Override
   public boolean equals(Object o) {
     if (this == o) return true;

src/main/java/edu/ie3/datamodel/io/factory/input/EmAssetInputEntityData.java

@@ -0,0 +1,70 @@
+/*
+ * © 2023. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.io.factory.input;
+
+import edu.ie3.datamodel.models.UniqueEntity;
+import edu.ie3.datamodel.models.input.EmInput;
+import edu.ie3.datamodel.models.input.OperatorInput;
+import java.util.Map;
+import java.util.Objects;
+
+/**
+ * Data used for the construction of {@link edu.ie3.datamodel.models.input.AssetInput} entities
+ * which also require an EM attribute. This data object can include additional information about the
+ * {@link EmInput}, which cannot be provided through the attribute map as it is a complex shared
+ * entity.
+ */
+public class EmAssetInputEntityData extends AssetInputEntityData {
+
+  private final EmInput emUnit;
+
+  public EmAssetInputEntityData(
+      Map<String, String> fieldsToAttributes,
+      Class<? extends UniqueEntity> entityClass,
+      EmInput emUnit) {
+    super(fieldsToAttributes, entityClass);
+    this.emUnit = emUnit;
+  }
+
+  public EmAssetInputEntityData(
+      Map<String, String> fieldsToAttributes,
+      Class<? extends UniqueEntity> entityClass,
+      OperatorInput operator,
+      EmInput emUnit) {
+    super(fieldsToAttributes, entityClass, operator);
+    this.emUnit = emUnit;
+  }
+
+  /**
+   * Creates a new EmAssetInputEntityData object based on a given {@link AssetInputEntityData}
+   * object and given em unit
+   *
+   * @param entityData The entity data object to use attributes of
+   * @param emUnit The em input to use
+   */
+  public EmAssetInputEntityData(AssetInputEntityData entityData, EmInput emUnit) {
+    super(entityData, entityData.getOperatorInput());
+    this.emUnit = emUnit;
+  }
+
+  public EmInput getEmUnit() {
+    return emUnit;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) return true;
+    if (o == null || getClass() != o.getClass()) return false;
+    if (!super.equals(o)) return false;
+    EmAssetInputEntityData that = (EmAssetInputEntityData) o;
+    return Objects.equals(emUnit, that.emUnit);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(super.hashCode(), emUnit);
+  }
+}

src/main/java/edu/ie3/datamodel/io/factory/input/participant/BmInputFactory.java

@@ -7,6 +7,7 @@
 
 import edu.ie3.datamodel.models.OperationTime;
 import edu.ie3.datamodel.models.StandardUnits;
+import edu.ie3.datamodel.models.input.EmInput;
 import edu.ie3.datamodel.models.input.NodeInput;
 import edu.ie3.datamodel.models.input.OperatorInput;
 import edu.ie3.datamodel.models.input.system.BmInput;
@@ -41,6 +42,7 @@ protected BmInput buildModel(
       ReactivePowerCharacteristic qCharacteristics,
       OperatorInput operator,
       OperationTime operationTime) {
+    final EmInput em = data.getEm().orElse(null);
     final BmTypeInput typeInput = data.getTypeInput();
     final boolean marketReaction = data.getBoolean(MARKET_REACTION);
     final boolean costControlled = data.getBoolean(COST_CONTROLLED);
@@ -54,6 +56,7 @@ protected BmInput buildModel(
         operationTime,
         node,
         qCharacteristics,
+        em,
         typeInput,
         marketReaction,
         costControlled,

src/main/java/edu/ie3/datamodel/io/factory/input/participant/ChpInputEntityData.java

@@ -5,6 +5,7 @@
 */
 package edu.ie3.datamodel.io.factory.input.participant;
 
+import edu.ie3.datamodel.models.input.EmInput;
 import edu.ie3.datamodel.models.input.NodeInput;
 import edu.ie3.datamodel.models.input.OperatorInput;
 import edu.ie3.datamodel.models.input.system.ChpInput;
@@ -21,10 +22,11 @@ public class ChpInputEntityData extends SystemParticipantTypedEntityData<ChpType
   public ChpInputEntityData(
       Map<String, String> fieldsToAttributes,
       NodeInput node,
+      EmInput em,
       ChpTypeInput typeInput,
       ThermalBusInput thermalBusInput,
       ThermalStorageInput thermalStorageInput) {
-    super(fieldsToAttributes, ChpInput.class, node, typeInput);
+    super(fieldsToAttributes, ChpInput.class, node, em, typeInput);
     this.thermalBusInput = thermalBusInput;
     this.thermalStorageInput = thermalStorageInput;
   }
@@ -33,10 +35,11 @@ public ChpInputEntityData(
       Map<String, String> fieldsToAttributes,
       OperatorInput operator,
       NodeInput node,
+      EmInput em,
       ChpTypeInput typeInput,
       ThermalBusInput thermalBusInput,
       ThermalStorageInput thermalStorageInput) {
-    super(fieldsToAttributes, ChpInput.class, operator, node, typeInput);
+    super(fieldsToAttributes, ChpInput.class, operator, node, em, typeInput);
     this.thermalBusInput = thermalBusInput;
     this.thermalStorageInput = thermalStorageInput;
   }

src/main/java/edu/ie3/datamodel/io/factory/input/participant/ChpInputFactory.java

@@ -6,6 +6,7 @@
 package edu.ie3.datamodel.io.factory.input.participant;
 
 import edu.ie3.datamodel.models.OperationTime;
+import edu.ie3.datamodel.models.input.EmInput;
 import edu.ie3.datamodel.models.input.NodeInput;
 import edu.ie3.datamodel.models.input.OperatorInput;
 import edu.ie3.datamodel.models.input.system.ChpInput;
@@ -34,6 +35,7 @@ protected ChpInput buildModel(
       ReactivePowerCharacteristic qCharacteristics,
       OperatorInput operator,
       OperationTime operationTime) {
+    final EmInput em = data.getEm().orElse(null);
     final boolean marketReaction = data.getBoolean(MARKET_REACTION);
 
     return new ChpInput(
@@ -44,6 +46,7 @@ protected ChpInput buildModel(
         node,
         data.getThermalBusInput(),
         qCharacteristics,
+        em,
         data.getTypeInput(),
         data.getThermalStorageInput(),
         marketReaction);