Introducing scaling function in copy builders

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Implementing missing typical methods in `Try` [#970](https://github.com/ie3-institute/PowerSystemDataModel/issues/970)
 - Added log warning when using `SwitchInputs` with `parallelDevices` parameter [#840](https://github.com/ie3-institute/PowerSystemDataModel/issues/840)
 - Validation for `EvcsInput` [#1000](https://github.com/ie3-institute/PowerSystemDataModel/issues/1000)
+- Scaling method in system participant copy builders [#1011](https://github.com/ie3-institute/PowerSystemDataModel/issues/1011)
 
 ### Fixed
 - Fixed Couchbase integration tests that randomly failed [#755](https://github.com/ie3-institute/PowerSystemDataModel/issues/755)

docs/readthedocs/io/csvfiles.md

@@ -58,7 +58,7 @@ You may extend / alter the naming with pre- or suffix by calling `new EntityPers
 Let's spend a few more words on the individual time series:
 Those files are meant to carry different types of content - one might give information about wholesale market prices,
 the other is a record of power values provided by a real system.
-To be able to understand, what's inside of the file, the *columnScheme* part of the file name gives insight of it's
+To be able to understand, what's inside of the file, the *columnScheme* part of the file name gives insight of its
 content.
 The following keys are supported until now:
 

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

@@ -77,7 +77,7 @@ If you found something, please contact us!
 
 ## Load Profiles
 
-The {code}`LoadProfile` is an interface, that forces it's implementing classes to have a {code}`String` *key*
+The {code}`LoadProfile` is an interface, that forces its implementing classes to have a {code}`String` *key*
 and being able to parse a {code}`String` to a {code}`LoadProfile`.
 Its only purpose is to give note, which load profile has to be used by the simulation.
 The actual profile has to be provided by the simulation itself.

docs/readthedocs/models/models.md

@@ -18,22 +18,26 @@ We designed the models in a way, that does not allow for adaptions of the repres
 objects.
 Thereby you can be sure, that your models are *thread-safe* and no unwanted or unobserved changes are made.
 
-**Copyable** <br>
+**Clonability** <br>
 With the general design principle of immutability, entity modifications (e.g. updates of field values) can become
 hard and annoying. To avoid generating methods to update each field value, we provide an adapted version of the
 [Builder pattern](https://en.wikipedia.org/wiki/Builder_pattern/) to make entity modifications as easy as possible.
-Each entity holds it's own copy builder class, which follows the same inheritance as the entity class itself. With a
-call of `.copy()` on an entity instance a builder instance is returned, that allows for modification of fields and
-can be terminated with `.build()` which will return an instance of the entity with modified field values as required.
-For the moment, this pattern is only implemented for a small amount of `AssetInput` entities (all entities held by a
-`GridContainer` except thermal units to be precise), but we plan to extend this capability to all input entities in the
-future.
+Each entity holds its own copy builder class, which follows the same inheritance as the entity class itself. With a
+call of `.copy()` on an entity instance a builder instance is returned, which allows for modification of fields and
+can be terminated with `.build()`. This will return an instance of the entity with modified field values as indicated.
+For the moment, this pattern is only implemented for a limited set of entities, but we plan to extend this capability 
+to all input entities in the future.
+
+**Scaling entity properties** <br>
+Using the copy builders (as described above) we provide a convenience method that helps with scaling system 
+participants and respective type inputs. Scaling entities tries to preserve proportions that are related to power. 
+This means that capacity, consumption etc. are scaled with the same factor as power.
 
 **Single Point of Truth** <br>
 Throughout all models you can be sure, that no information is given twice, reducing the possibility to have ambiguous
 information in your simulation set up.
 "Missing" information can be received through the grids relational information - e.g. if you intend to model a wind
-energy converter in detail, you may find information of it's geographical location in the model of it's common
+energy converter in detail, you may find information of its geographical location in the model of its common
 coupling point ([node](/models/input/grid/node)).
 
 **Harmonized Units System** <br>

src/main/java/edu/ie3/datamodel/exceptions/NotImplementedException.java

@@ -0,0 +1,12 @@
+/*
+ * © 2021. TU Dortmund University,
+ * Institute of Energy Systems, Energy Efficiency and Energy Economics,
+ * Research group Distribution grid planning and operation
+*/
+package edu.ie3.datamodel.exceptions;
+
+public class NotImplementedException extends UnsupportedOperationException {
+  public NotImplementedException(String msg) {
+    super(msg);
+  }
+}

src/main/java/edu/ie3/datamodel/io/factory/timeseries/IconTimeBasedWeatherValueFactory.java

@@ -24,7 +24,7 @@
 
 /**
  * Factory implementation of {@link TimeBasedWeatherValueFactory}, that is able to handle field to
- * value mapping in the column scheme, ie<sup>3</sup> uses to store it's data from German Federal
+ * value mapping in the column scheme, ie<sup>3</sup> uses to store its data from German Federal
  * Weather Service's ICON-EU model
  */
 public class IconTimeBasedWeatherValueFactory extends TimeBasedWeatherValueFactory {

src/main/java/edu/ie3/datamodel/io/processor/input/InputEntityProcessor.java

@@ -23,7 +23,7 @@
 import java.util.List;
 
 /**
- * Processes all {@link InputEntity}s and it's child classes
+ * Processes all {@link InputEntity}s and its child classes
  *
  * @version 0.1
  * @since 23.03.20

src/main/java/edu/ie3/datamodel/io/sink/InfluxDbSink.java

@@ -155,7 +155,7 @@ private <E extends TimeSeriesEntry<V>, V extends Value> Set<Point> transformToPo
       String valueClassName =
           timeSeries.getEntries().iterator().next().getValue().getClass().getSimpleName();
       log.warn(
-          "I could not get a measurement name for TimeSeries value class {}. I am using it's value's simple name instead.",
+          "I could not get a measurement name for TimeSeries value class {}. I am using its value's simple name instead.",
           valueClassName);
       return transformToPoints(timeSeries, valueClassName);
     }

src/main/java/edu/ie3/datamodel/models/StandardUnits.java

@@ -78,8 +78,8 @@ public class StandardUnits {
   /** Voltage angle variation per tap (for transformers) in ° (arc degree) */
   public static final Unit<Angle> DPHI_TAP = DEGREE_GEOM;
   /**
-   * Gradient, with which a system participant can change it's set point (with regard to rated
-   * active power = rated apparent power * rated power factor) in %/h
+   * Gradient, with which a system participant can change its set point (with regard to rated active
+   * power = rated apparent power * rated power factor) in %/h
    */
   public static final Unit<DimensionlessRate> ACTIVE_POWER_GRADIENT = PERCENT_PER_HOUR;
   /** Efficiency of a process in % */

src/main/java/edu/ie3/datamodel/models/input/AssetTypeInput.java

@@ -43,4 +43,35 @@ public int hashCode() {
   public String toString() {
     return "AssetTypeInput{" + "uuid=" + getUuid() + ", id=" + id + "}";
   }
+
+  /**
+   * Abstract class for all builder that build child entities of abstract class {@link
+   * AssetTypeInput}
+   */
+  public abstract static class AssetTypeInputCopyBuilder<
+          B extends AssetTypeInput.AssetTypeInputCopyBuilder<B>>
+      extends UniqueEntityCopyBuilder<B> {
+
+    private String id;
+
+    protected AssetTypeInputCopyBuilder(AssetTypeInput entity) {
+      super(entity);
+      this.id = entity.getId();
+    }
+
+    public B id(String id) {
+      this.id = id;
+      return thisInstance();
+    }
+
+    protected String getId() {
+      return id;
+    }
+
+    @Override
+    public abstract AssetTypeInput build();
+
+    @Override
+    protected abstract B thisInstance();
+  }
 }

src/main/java/edu/ie3/datamodel/models/input/connector/Transformer3WInput.java

@@ -79,7 +79,7 @@ public Transformer3WInput(
    * transformer (here: that not holds node A in its grid).
    *
    * <p>Then, the internal node becomes a virtual representation of a slack node for the grid and
-   * allows for power flow calculations based on it's 'close-to-T-equivalent' representation
+   * allows for power flow calculations based on its 'close-to-T-equivalent' representation
    *
    * @param uuid of the input entity
    * @param id of the asset

src/main/java/edu/ie3/datamodel/models/input/container/ThermalGrid.java

@@ -10,6 +10,7 @@
 import edu.ie3.datamodel.models.input.thermal.ThermalInput;
 import edu.ie3.datamodel.models.input.thermal.ThermalStorageInput;
 import java.util.*;
+import java.util.stream.Collectors;
 
 /**
  * Container object to denote a fully connected thermal "grid". As there are currently no branch
@@ -108,6 +109,18 @@ public ThermalGridCopyBuilder storages(Set<ThermalStorageInput> storages) {
       return this;
     }
 
+    public ThermalGridCopyBuilder scale(Double factor) {
+      houses(
+          houses.stream()
+              .map(house -> house.copy().scale(factor).build())
+              .collect(Collectors.toSet()));
+      storages(
+          storages.stream()
+              .map(storage -> storage.copy().scale(factor).build())
+              .collect(Collectors.toSet()));
+      return this;
+    }
+
     @Override
     public ThermalGrid build() {
       return new ThermalGrid(bus, houses, storages);

src/main/java/edu/ie3/datamodel/models/input/system/BmInput.java

@@ -205,6 +205,12 @@ public BmInputCopyBuilder feedInTariff(ComparableQuantity<EnergyPrice> feedInTar
       return this;
     }
 
+    @Override
+    public BmInputCopyBuilder scale(Double factor) {
+      this.type = this.type.copy().scale(factor).build();
+      return this;
+    }
+
     @Override
     public BmInput build() {
       return new BmInput(

src/main/java/edu/ie3/datamodel/models/input/system/ChpInput.java

@@ -222,6 +222,12 @@ public ChpInputCopyBuilder marketReaction(boolean marketReaction) {
       return this;
     }
 
+    @Override
+    public ChpInputCopyBuilder scale(Double factor) {
+      this.type = this.type.copy().scale(factor).build();
+      return this;
+    }
+
     @Override
     protected ChpInputCopyBuilder thisInstance() {
       return this;

src/main/java/edu/ie3/datamodel/models/input/system/EvInput.java

@@ -127,6 +127,17 @@ private EvInputCopyBuilder(EvInput entity) {
       this.type = entity.getType();
     }
 
+    public EvInputCopyBuilder type(EvTypeInput type) {
+      this.type = type;
+      return this;
+    }
+
+    @Override
+    public EvInputCopyBuilder scale(Double factor) {
+      type(type.copy().scale(factor).build());
+      return this;
+    }
+
     @Override
     public EvInput build() {
       return new EvInput(
@@ -140,11 +151,6 @@ public EvInput build() {
           type);
     }
 
-    public EvInputCopyBuilder type(EvTypeInput type) {
-      this.type = type;
-      return this;
-    }
-
     @Override
     protected EvInputCopyBuilder thisInstance() {
       return this;

src/main/java/edu/ie3/datamodel/models/input/system/EvcsInput.java

@@ -283,6 +283,12 @@ public EvcsInputCopyBuilder v2gSupport(boolean v2gSupport) {
       return this;
     }
 
+    @Override
+    public EvcsInputCopyBuilder scale(Double factor) {
+      type(type.copy().scale(factor).build());
+      return this;
+    }
+
     @Override
     public EvcsInput build() {
       return new EvcsInput(

src/main/java/edu/ie3/datamodel/models/input/system/FixedFeedInInput.java

@@ -144,6 +144,22 @@ private FixedFeedInInputCopyBuilder(FixedFeedInInput entity) {
       this.cosPhiRated = entity.getCosPhiRated();
     }
 
+    public FixedFeedInInputCopyBuilder sRated(ComparableQuantity<Power> sRated) {
+      this.sRated = sRated;
+      return this;
+    }
+
+    public FixedFeedInInputCopyBuilder cosPhiRated(double cosPhiRated) {
+      this.cosPhiRated = cosPhiRated;
+      return this;
+    }
+
+    @Override
+    public FixedFeedInInputCopyBuilder scale(Double factor) {
+      sRated(sRated.multiply(factor));
+      return this;
+    }
+
     @Override
     public FixedFeedInInput build() {
       return new FixedFeedInInput(
@@ -158,16 +174,6 @@ public FixedFeedInInput build() {
           cosPhiRated);
     }
 
-    public FixedFeedInInputCopyBuilder sRated(ComparableQuantity<Power> sRated) {
-      this.sRated = sRated;
-      return this;
-    }
-
-    public FixedFeedInInputCopyBuilder cosPhiRated(double cosPhiRated) {
-      this.cosPhiRated = cosPhiRated;
-      return this;
-    }
-
     @Override
     protected FixedFeedInInputCopyBuilder thisInstance() {
       return this;

src/main/java/edu/ie3/datamodel/models/input/system/HpInput.java

@@ -146,6 +146,22 @@ private HpInputCopyBuilder(HpInput entity) {
       this.thermalBus = entity.getThermalBus();
     }
 
+    public HpInputCopyBuilder type(HpTypeInput type) {
+      this.type = type;
+      return this;
+    }
+
+    public HpInputCopyBuilder thermalBus(ThermalBusInput thermalBus) {
+      this.thermalBus = thermalBus;
+      return this;
+    }
+
+    @Override
+    public HpInputCopyBuilder scale(Double factor) {
+      type(type.copy().scale(factor).build());
+      return this;
+    }
+
     @Override
     public HpInput build() {
       return new HpInput(
@@ -160,16 +176,6 @@ public HpInput build() {
           type);
     }
 
-    public HpInputCopyBuilder type(HpTypeInput type) {
-      this.type = type;
-      return this;
-    }
-
-    public HpInputCopyBuilder thermalBus(ThermalBusInput thermalBus) {
-      this.thermalBus = thermalBus;
-      return this;
-    }
-
     @Override
     protected HpInputCopyBuilder thisInstance() {
       return this;

src/main/java/edu/ie3/datamodel/models/input/system/LoadInput.java

@@ -317,6 +317,13 @@ public LoadInputCopyBuilder cosPhiRated(double cosPhiRated) {
       return this;
     }
 
+    @Override
+    public LoadInputCopyBuilder scale(Double factor) {
+      eConsAnnual(eConsAnnual.multiply(factor));
+      sRated(sRated.multiply(factor));
+      return this;
+    }
+
     @Override
     public LoadInput build() {
       return new LoadInput(

src/main/java/edu/ie3/datamodel/models/input/system/PvInput.java

@@ -321,6 +321,12 @@ public PvInputCopyBuilder cosPhiRated(double cosPhiRated) {
       return this;
     }
 
+    @Override
+    public PvInputCopyBuilder scale(Double factor) {
+      this.sRated = this.sRated.multiply(factor);
+      return this;
+    }
+
     @Override
     public PvInput build() {
       return new PvInput(

src/main/java/edu/ie3/datamodel/models/input/system/StorageInput.java

@@ -127,6 +127,17 @@ private StorageInputCopyBuilder(StorageInput entity) {
       this.type = entity.getType();
     }
 
+    public StorageInputCopyBuilder type(StorageTypeInput type) {
+      this.type = type;
+      return this;
+    }
+
+    @Override
+    public StorageInputCopyBuilder scale(Double factor) {
+      type(type.copy().scale(factor).build());
+      return this;
+    }
+
     @Override
     public StorageInput build() {
       return new StorageInput(
@@ -140,11 +151,6 @@ public StorageInput build() {
           type);
     }
 
-    public StorageInputCopyBuilder type(StorageTypeInput type) {
-      this.type = type;
-      return this;
-    }
-
     @Override
     protected StorageInputCopyBuilder thisInstance() {
       return this;