Move switch on calibration parameters into a function

Stress the relations between variables and equations of the seminal
paper and the code with comments

Co-authored-by: Gokarna.Dhungel <[email protected]>

ramp/core/core.py

@@ -7,6 +7,7 @@
 import random
 import math
 from ramp.core.constants import NEW_TO_OLD_MAPPING, OLD_TO_NEW_MAPPING
+from ramp.core.initialise import switch_on_parameters
 
 #%% Definition of Python classes that constitute the model architecture
 """
@@ -557,15 +558,28 @@ def calc_indexes_for_rand_switch_on(self, switch_on, rand_time, max_free_spot, r
             indexes = np.arange(switch_on, switch_on + upper_limit)
         return indexes
 
-    def calc_coincident_switch_on(self, peak_time_range, indexes, s_peak, mu_peak, op_factor):
-        """Computes how many of the 'n' of the Appliance instance are switched on simultaneously"""
+    def calc_coincident_switch_on(self, peak_time_range, indexes):
+        """Computes how many of the 'n' of the Appliance instance are switched on simultaneously
+
+            Implement eqs. 3 and 4 of [1]
+
+        Notes
+        -----
+        [1] F. Lombardi, S. Balderrama, S. Quoilin, E. Colombo,
+            Generating high-resolution multi-energy load profiles for remote areas with an open-source stochastic model,
+            Energy, 2019, https://doi.org/10.1016/j.energy.2019.04.097.
+        """
+        s_peak, mu_peak, op_factor = switch_on_parameters()
+
         # check if indexes are in peak window
         if np.in1d(peak_time_range, indexes).any() is True and self.fixed == 'no':
             # calculates coincident behaviour within the peak time range
+            # eq. 4 of [1]
             coincidence = min(self.number, max(1, math.ceil(random.gauss(mu=(self.number * mu_peak + 0.5), sigma=(s_peak * self.number * mu_peak)))))
         # check if indexes are off-peak
         elif np.in1d(peak_time_range, indexes).any() is False and self.fixed == 'no':
             # calculates probability of coincident switch_ons off-peak
+            # eq. 3 of [1]
             prob = random.uniform(0, (self.number - op_factor) / self.number)
 
             # randomly selects how many appliances are on at the same time

ramp/core/initialise.py

@@ -36,6 +36,28 @@ def user_defined_inputs(j=None, fname=None):
     return(User_list)
 
 
+def switch_on_parameters():
+    """
+    Calibration parameters. These can be changed in case the user has some real data against which the model can be calibrated
+    They regulate the probability of coincident switch-on within the peak window
+
+    mu_peak corresponds to \mu_{%} in [1], p.8
+    s_peak corresponds to \sigma_{%} in [1], p.8
+
+    Notes
+    -----
+    [1] F. Lombardi, S. Balderrama, S. Quoilin, E. Colombo,
+        Generating high-resolution multi-energy load profiles for remote areas with an open-source stochastic model,
+        Energy, 2019, https://doi.org/10.1016/j.energy.2019.04.097.
+    """
+
+    mu_peak = 0.5  # median value of gaussian distribution [0,1] by which the number of coincident switch_ons is randomly selected
+    s_peak = 0.5  # standard deviation (as percentage of the median value) of the gaussian distribution [0,1] above mentioned
+    op_factor = 0.5  # off-peak coincidence calculation parameter
+
+    return mu_peak, s_peak, op_factor
+
+
 def Initialise_model(num_profiles):
     '''
     The model is ready to be initialised
@@ -51,16 +73,7 @@ def Initialise_model(num_profiles):
 def Initialise_inputs(j=None, fname=None):
     Year_behaviour = yearly_pattern()
     user_list = user_defined_inputs(j, fname)
-
-    # Calibration parameters
-    '''
-    Calibration parameters. These can be changed in case the user has some real data against which the model can be calibrated
-    They regulate the probabilities defining the largeness of the peak window and the probability of coincident switch-on within the peak window
-    '''
-    peak_enlarg = 0.15 #percentage random enlargement or reduction of peak time range length
-    mu_peak = 0.5 #median value of gaussian distribution [0,1] by which the number of coincident switch_ons is randomly selected
-    s_peak = 0.5 #standard deviation (as percentage of the median value) of the gaussian distribution [0,1] above mentioned
-    op_factor = 0.5 #off-peak coincidence calculation parameter
 
-    return (peak_enlarg, mu_peak, s_peak, op_factor, Year_behaviour, user_list)
+    peak_enlarge = 0.15  # percentage random enlargement or reduction of peak time range length, corresponds to \delta_{peak} in [1], p.7
+    return (peak_enlarge, Year_behaviour, user_list)
 

ramp/core/stochastic_process.py

@@ -24,7 +24,7 @@ def calc_peak_time_range(user_list, peak_enlarge=0.15):
         list containing all the user types
     peak_enlarge: float
         percentage random enlargement or reduction of peak time range length
-        corresponds to \delta_{peak} in [1]
+        corresponds to \delta_{peak} in [1], p.7
 
     Notes
     -----
@@ -54,7 +54,7 @@ def calc_peak_time_range(user_list, peak_enlarge=0.15):
 
 def Stochastic_Process(j=None, fname=None, num_profiles=None):
     Profile, num_profiles = Initialise_model(num_profiles)
-    peak_enlarge, mu_peak, s_peak, op_factor, Year_behaviour, User_list = Initialise_inputs(j, fname)
+    peak_enlarge, Year_behaviour, User_list = Initialise_inputs(j, fname)
     # Calculation of the peak time range, which is used to discriminate between off-peak and on-peak coincident switch-on probability
     peak_time_range = calc_peak_time_range(User_list, peak_enlarge)
 
@@ -120,10 +120,8 @@ def Stochastic_Process(j=None, fname=None, num_profiles=None):
 
                     App.daily_use_masked = np.zeros_like(ma.masked_not_equal(App.daily_use,0.001))
 
-
                     App.assign_random_cycles()
 
-
                     while tot_time <= rand_time: #this is the key cycle, which runs for each App until the switch_ons and their duration equals the randomised total time of use of the App
                             #check how many windows to consider
                             # step 2c of [1]
@@ -164,9 +162,6 @@ def Stochastic_Process(j=None, fname=None, num_profiles=None):
                                     coincidence = App.calc_coincident_switch_on(
                                         peak_time_range=peak_time_range,
                                         indexes=indexes_adj,
-                                        s_peak=s_peak,
-                                        mu_peak=mu_peak,
-                                        op_factor=op_factor
                                     )
                                     # Update the daily use depending on existence of duty cycles of the Appliance instance
                                     App.update_daily_use(
@@ -181,9 +176,6 @@ def Stochastic_Process(j=None, fname=None, num_profiles=None):
                                     coincidence = App.calc_coincident_switch_on(
                                         peak_time_range=peak_time_range,
                                         indexes=indexes,
-                                        s_peak=s_peak,
-                                        mu_peak=mu_peak,
-                                        op_factor=op_factor
                                     )
                                     # Update the daily use depending on existence of duty cycles of the Appliance instance
                                     App.update_daily_use(