Update generation perturbation implementation and docs

Author: etienne-v

docs/components/param_handler.md

@@ -18,9 +18,13 @@ This module provides utilities for handling and manipulating configuration param
 
 ::: gridfm_datakit.utils.param_handler.get_load_scenario_generator
 
-### `initialize_generator`
+### `initialize_topology_generator`
 
-::: gridfm_datakit.utils.param_handler.initialize_generator
+::: gridfm_datakit.utils.param_handler.initialize_topology_generator
+
+### `initialize_generation_generator`
+
+::: gridfm_datakit.utils.param_handler.initialize_generation_generator
 
 ## Classes
 

docs/index.md

@@ -35,7 +35,7 @@ This library is brought to you by the GridFM team to generate power flow data to
         </tr>
       </thead>
       <tbody>
-        <tr><td>Generator Profile</td><td>✅</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td><td>✅</td><td>❌</td><td>❌</td></tr>
+        <tr><td>Generator Profile</td><td>✅</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td><td>✅</td><td>❌</td><td>✅</td></tr>
         <tr><td>N-1</td><td>❌</td><td>✅</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td><td>✅</td><td>✅</td></tr>
         <tr><td>&gt; 1000 Buses</td><td>❌</td><td>✅</td><td>✅</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td><td>✅</td></tr>
         <tr><td>N-k, k &gt; 1</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>❌</td><td>✅</td></tr>

docs/manual/generation_perturbations.md

@@ -0,0 +1,12 @@
+# Generation Perturbations
+
+## Overview
+Generation perturbations introduce random changes to the cost functions of generator elements (PV nodes) in the Panda Power `poly_cost` table.  The effect of this is that the cost of operating generators in the grid changes across examples, which allows them to be utilised differently when executing optimal power flow.  As aresult, examples produced will have more diverse generator setpoints which is beneficial for training ML models to improve generalisation.  Generation perturbation is applied to the existing topology perturbations.
+
+The module provides three options for generation perturbation strategies:
+
+- `NoGenPerturbationGenerator` yields the original example produced by the topology perturbation generator without any additional changes in generation cost.
+
+- `PermuteGenCostGenerator` randomly permutes the rows of generator cost coefficients in the `poly_cost` table across and among generator elements.
+
+- `PerturbGenCostGenerator` applies a scaling factor to all generator cost coefficients in the `poly_cost` table.  The scaling factor is sampled from a uniform distribution with a range given by `[max(0, 1-sigma), 1+sigma)`, where `sigma` is a user-defined adjustable parameter.

gridfm_datakit/perturbations/generator_perturbation.py

@@ -113,8 +113,8 @@ def __init__(self, base_net: pp.pandapowerNet, sigma: float) -> None:
         self.base_net = base_net
         self.num_gens = len(base_net.poly_cost)
         self.perturb_cols = self.base_net.poly_cost.columns[2:]
-        self.lower = 1 - sigma
-        self.upper = 1 + sigma
+        self.lower = np.max([0.0, 1.0 - sigma])
+        self.upper = 1.0 + sigma
         self.sample_size = [self.num_gens, len(self.perturb_cols)]
 
     def generate(
@@ -128,7 +128,7 @@ def generate(
             sigma: A constant that specifies the range from which to draw
                 samples from a uniform distribution to be used as a scaling
                 factor for cost coefficient perturbations. The range is
-                set as [1-sigma, 1+sigma]
+                set as [max([0,1-sigma]), 1+sigma)
 
         Yields:
             A topology scenario with cost coeffiecients in the poly_cost

mkdocs.yml

@@ -10,6 +10,7 @@ nav:
       - Network: manual/network.md
       - Load Scenarios: manual/load_scenarios.md
       - Topology Perturbations: manual/topology_perturbations.md
+      - Generation Perturbations: manual/generation_perturbations.md
       - Outputs: manual/outputs.md
   - Components:
     - Network: components/network.md