Merge pull request #441 from ie3-institute/ck/#440-impedanceWeightedGraph

Add impedance weighted graph

Author: t-ober

CHANGELOG.md

@@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - SQL time series sources (`SqlTimeSeriesSource` and `SqlTimeSeriesMappingSource`) [#467](https://github.com/ie3-institute/PowerSystemDataModel/issues/467)
+- Graph with impedance weighted edges including facilities to create it [#440](https://github.com/ie3-institute/PowerSystemDataModel/issues/440)
 
 ### Fixed
 - Reduced code smells [#492](https://github.com/ie3-institute/PowerSystemDataModel/issues/492)

docs/readthedocs/models/ValidationUtils.rst

@@ -4,16 +4,16 @@ Validation Utils
 This page gives an overview about the ValidationUtils in the *PowerSystemDataModel*.
 
 What are the ValidationUtils?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+=============================
 The methods in ValidationUtils and subclasses can be used to check that objects are valid, meaning their parameters have valid values and they are correctly connected.
 
 What is checked?
-^^^^^^^^^^^^^^^^
+================
 - The check methods include checks that assigned values are valid, e.g. lines are not allowed to have negative lengths or the rated power factor of any unit must be between 0 and 1.
 - Furthermore, several connections are checked, e.g. that lines only connect nodes of the same voltage level or that the voltage levels indicated for the transformer sides match the voltage levels of the nodes they are connected to.
 
 How does it work?
-^^^^^^^^^^^^^^^^^
+=================
 - The method :code:`ValidationUtils.check(Object)` is the only method that should be called by the user.
 - This check method identifies the object class and forwards it to a specific check method for the given object
 - The overall structure of the ValidationUtils methods follows a cascading scheme, orientated along the class tree
@@ -26,7 +26,7 @@ How does it work?
 - ValidationUtils furthermore contains several utils methods used in the subclasses
 
 Which objects are checked?
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+==========================
 The ValidationUtils include validation checks for...
 
 - NodeValidationUtils
@@ -81,7 +81,7 @@ The ValidationUtils include validation checks for...
     - SystemParticipants
 
 What should be considered?
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+==========================
 - Due to many checks with if-conditions, the usage of the ValidationUtils for many objects might be runtime relevant.
 - The check for a GridContainer includes the interplay of the contained entities as well as the checks of all contained entities.
 - If new classes are introduced to the *PowerSystemDataModel*, make sure to follow the forwarding structure of the ValidationUtils methods when writing the check methods!

docs/readthedocs/models/input/grid/line.rst

@@ -49,8 +49,8 @@ Entity Model
 | nodeB             | --   |                                                        |
 +-------------------+------+--------------------------------------------------------+
 | parallelDevices   | --   | | overall amount of parallel lines to automatically    |
-|                   | --   | | construct (e.g. parallelDevices = 2 will build a     |
-|                   | --   | | total of two lines using the specified parameters)   |
+|                   |      | | construct (e.g. parallelDevices = 2 will build a     |
+|                   |      | | total of two lines using the specified parameters)   |
 +-------------------+------+--------------------------------------------------------+
 | type              | --   |                                                        |
 +-------------------+------+--------------------------------------------------------+

docs/readthedocs/models/input/grid/transformer2w.rst

@@ -66,8 +66,8 @@ Entity Model
 | nodeB           | --   | Lower voltage node                                         |
 +-----------------+------+------------------------------------------------------------+
 | parallelDevices | --   | | overall amount of parallel transformers to automatically |
-|                 | --   | | construct (e.g. parallelDevices = 2 will build a         |
-|                 | --   | | total of two transformers using the specified parameters)|
+|                 |      | | construct (e.g. parallelDevices = 2 will build a         |
+|                 |      | | total of two transformers using the specified parameters)|
 +-----------------+------+------------------------------------------------------------+
 | type            | --   |                                                            |
 +-----------------+------+------------------------------------------------------------+

docs/readthedocs/models/input/grid/transformer3w.rst

@@ -88,8 +88,8 @@ Entity Model
 | nodeC           | --   | Lowest voltage node                                        |
 +-----------------+------+------------------------------------------------------------+
 | parallelDevices | --   | | overall amount of parallel transformers to automatically |
-|                 | --   | | construct (e.g. parallelDevices = 2 will build a         |
-|                 | --   | | total of two transformers using the specified parameters)|
+|                 |      | | construct (e.g. parallelDevices = 2 will build a         |
+|                 |      | | total of two transformers using the specified parameters)|
 +-----------------+------+------------------------------------------------------------+
 | type            | --   |                                                            |
 +-----------------+------+------------------------------------------------------------+

docs/readthedocs/models/models.rst

@@ -54,31 +54,32 @@ Equality Checks
   instances is not as trivial as it might seem, because there might be different understandings about the equality of
   quantities (e.g. there is a big difference between two instances being equal or equivalent). After long discussions how to
   treat quantities in the entity :code:`equals()` method, we agreed on the following rules to be applied:
-    - equality check is done by calling :code:`Objects.equals(<QuantityInstanceA>, <QuantityInstanceB>)` or
-      :code:`<QuantityInstanceA>.equals(<QuantityInstanceB>)`.
-      Using :code:`Objects.equals(<QuantityInstanceA>, <QuantityInstanceB>)` is necessary especially for time series data.
-      As in contrast to all other places, quantity time series from real world data sometimes are not complete and
-      hence contain missing values. To represent missing values this is the only place where the usage of :code:`null`
-      is a valid choice and hence needs to be treated accordingly. Please remember that his is only allowed in very few
-      places and you should try to avoid using :code:`null` for quantities or any other constructor parameter whenever possible!
-    - equality is given if, and only if, the quantities value object and unit are exactly equal. Value objects can become
-      e.g. :code:`BigDecimal` or :code:`Double` instances. It is important, that the object type is also the same, otherwise
-      the entities :code:`equals()` method returns false. This behavior is in sync with the equals implementation
-      of the indriya library. Hence, you should ensure that your code always pass in the same kind of a quantity instance
-      with the same underlying number format and type. For this purpose you should especially be aware of the unit conversion
-      method :code:`AbstractQuantity.to(Quantity)` which may return seemingly unexpected types, e.g. if called on a quantity
-      with a :code:`double` typed value, it may return a quantity with a value of either :code:`Double` type or :code:`BigDecimal` type.
-    - for now, there is no default way to compare entities in a 'number equality' way provided. E.g. a line with a length
-      of 1km compared to a line with a length of 1000m is actually of the same length, but calling :code:`LineA.equals(LineB)`
-      would return :code:`false` as the equality check does NOT convert units. If you want to compare two entity instances
-      based on their equivalence you have (for now) check for each quantity manually using their :code:`isEquivalentTo()`
-      method. If you think you would benefit from a standard method that allows entity equivalence check, please consider
-      handing in an issue `here <https://github.com/ie3-institute/PowerSystemDataModel/issues>`_.
-      Furthermore, the current existing implementation of :code:`isEquivalentTo()` in indriya does not allow the provision of
-      a tolerance threshold that might be necessary when comparing values from floating point operations. We consider
-      providing such a method in our `PowerSystemUtils <https://github.com/ie3-institute/PowerSystemUtils>`_ library.
-      If you think you would benefit from such a method, please consider handing in an issue
-      `here <https://github.com/ie3-institute/PowerSystemUtils/issues>`_.
+
+  - equality check is done by calling :code:`Objects.equals(<QuantityInstanceA>, <QuantityInstanceB>)` or
+    :code:`<QuantityInstanceA>.equals(<QuantityInstanceB>)`.
+    Using :code:`Objects.equals(<QuantityInstanceA>, <QuantityInstanceB>)` is necessary especially for time series data.
+    As in contrast to all other places, quantity time series from real world data sometimes are not complete and
+    hence contain missing values. To represent missing values this is the only place where the usage of :code:`null`
+    is a valid choice and hence needs to be treated accordingly. Please remember that his is only allowed in very few
+    places and you should try to avoid using :code:`null` for quantities or any other constructor parameter whenever possible!
+  - equality is given if, and only if, the quantities value object and unit are exactly equal. Value objects can become
+    e.g. :code:`BigDecimal` or :code:`Double` instances. It is important, that the object type is also the same, otherwise
+    the entities :code:`equals()` method returns false. This behavior is in sync with the equals implementation
+    of the indriya library. Hence, you should ensure that your code always pass in the same kind of a quantity instance
+    with the same underlying number format and type. For this purpose you should especially be aware of the unit conversion
+    method :code:`AbstractQuantity.to(Quantity)` which may return seemingly unexpected types, e.g. if called on a quantity
+    with a :code:`double` typed value, it may return a quantity with a value of either :code:`Double` type or :code:`BigDecimal` type.
+  - for now, there is no default way to compare entities in a 'number equality' way provided. E.g. a line with a length
+    of 1km compared to a line with a length of 1000m is actually of the same length, but calling :code:`LineA.equals(LineB)`
+    would return :code:`false` as the equality check does NOT convert units. If you want to compare two entity instances
+    based on their equivalence you have (for now) check for each quantity manually using their :code:`isEquivalentTo()`
+    method. If you think you would benefit from a standard method that allows entity equivalence check, please consider
+    handing in an issue `here <https://github.com/ie3-institute/PowerSystemDataModel/issues>`_.
+    Furthermore, the current existing implementation of :code:`isEquivalentTo()` in indriya does not allow the provision of
+    a tolerance threshold that might be necessary when comparing values from floating point operations. We consider
+    providing such a method in our `PowerSystemUtils <https://github.com/ie3-institute/PowerSystemUtils>`_ library.
+    If you think you would benefit from such a method, please consider handing in an issue
+    `here <https://github.com/ie3-institute/PowerSystemUtils/issues>`_.
 
 Conditional Parameters
   Some of the models have conditional parameters. When reading model data from a data source, their respective factories for building these 

gradle/scripts/tests.gradle

@@ -4,6 +4,7 @@ test {
 		events "skipped", "failed"
 	}
 
+	// Improve logging for failed Spock tests
 	testLogging {
 		exceptionFormat "Full"
 	}

src/main/java/edu/ie3/datamodel/graph/ImpedanceWeightedEdge.java

@@ -0,0 +1,37 @@
+/*
+ * © 2021. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.graph;
+
+import static tech.units.indriya.unit.Units.OHM;
+
+import javax.measure.Quantity;
+import javax.measure.Unit;
+import javax.measure.quantity.ElectricResistance;
+import org.jgrapht.graph.DefaultWeightedEdge;
+import tech.units.indriya.quantity.Quantities;
+
+/**
+ * A default implementation for edges in a {@link ImpedanceWeightedGraph}. All access to the weight
+ * of an edge must go through the graph interface, which is why this class doesn't expose any public
+ * methods.
+ *
+ * @version 0.1
+ * @since 04.06.20
+ */
+public class ImpedanceWeightedEdge extends DefaultWeightedEdge {
+  private static final long serialVersionUID = -3331046813188425729L;
+
+  protected static final Unit<ElectricResistance> DEFAULT_IMPEDANCE_UNIT = OHM;
+
+  public Quantity<ElectricResistance> getImpedance() {
+    return Quantities.getQuantity(getWeight(), DEFAULT_IMPEDANCE_UNIT);
+  }
+
+  @Override
+  public String toString() {
+    return "ImpedanceWeightedEdge{" + "impedance=" + getImpedance() + "} " + super.toString();
+  }
+}

src/main/java/edu/ie3/datamodel/graph/ImpedanceWeightedGraph.java

@@ -0,0 +1,59 @@
+/*
+ * © 2021. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.graph;
+
+import edu.ie3.datamodel.models.input.NodeInput;
+import java.util.function.Supplier;
+import javax.measure.Quantity;
+import javax.measure.quantity.ElectricResistance;
+import org.jgrapht.graph.SimpleWeightedGraph;
+import tech.units.indriya.ComparableQuantity;
+
+/** An impedance weighted graph that uses {@link ImpedanceWeightedEdge}s as edge type. */
+public class ImpedanceWeightedGraph extends SimpleWeightedGraph<NodeInput, ImpedanceWeightedEdge> {
+
+  private static final long serialVersionUID = -2797654003980753342L;
+
+  public ImpedanceWeightedGraph() {
+    super(ImpedanceWeightedEdge.class);
+  }
+
+  public ImpedanceWeightedGraph(
+      Supplier<NodeInput> vertexSupplier, Supplier<ImpedanceWeightedEdge> edgeSupplier) {
+    super(vertexSupplier, edgeSupplier);
+  }
+
+  /**
+   * Assigns a {@link Quantity} of type {@link ElectricResistance} to an instance of edge {@link
+   * ImpedanceWeightedEdge}
+   *
+   * @param edge edge whose weight should be altered
+   * @param weight the weight of the {@link ImpedanceWeightedEdge}
+   */
+  public void setEdgeWeightQuantity(
+      ImpedanceWeightedEdge edge, ComparableQuantity<ElectricResistance> weight) {
+    double weightDouble =
+        weight.to(ImpedanceWeightedEdge.DEFAULT_IMPEDANCE_UNIT).getValue().doubleValue();
+    super.setEdgeWeight(edge, weightDouble);
+  }
+
+  /**
+   * The only purpose for overriding this method is to provide a better indication of the unit that
+   * is expected to be passed in. It is highly advised to use the {@link
+   * ImpedanceWeightedGraph#setEdgeWeightQuantity(ImpedanceWeightedEdge, ComparableQuantity)} for
+   * safety purposes that the provided edge weight is correct.
+   *
+   * @param edge the edge whose weight should be altered
+   * @param impedanceInOhm the weight of the {@link ImpedanceWeightedEdge} in ohm
+   * @deprecated Use {@link ImpedanceWeightedGraph#setEdgeWeightQuantity(ImpedanceWeightedEdge,
+   *     ComparableQuantity)} instead, as it provides means for proper unit handling
+   */
+  @Override
+  @Deprecated
+  public void setEdgeWeight(ImpedanceWeightedEdge edge, double impedanceInOhm) {
+    super.setEdgeWeight(edge, impedanceInOhm);
+  }
+}

src/main/java/edu/ie3/datamodel/io/connectors/InfluxDbConnector.java

@@ -50,7 +50,7 @@ public class InfluxDbConnector implements DataConnector {
    * @param databaseName the name of the database the session should be set to
    * @param createDb true if the connector should create the database if it doesn't exist yet, false
    *     otherwise
-   * @param logLevel log level of the {@link InfluxDB.LogLevel} logger
+   * @param logLevel log level of the {@link org.influxdb.InfluxDB.LogLevel} logger
    * @param batchOptions write options to write batch operations
    */
   public InfluxDbConnector(