Merge pull request #12 from gridfm/gen-cost

Update generation perturbation implementation and docs

Author: albanpuech

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 generators and static generators (`gens` and `sgens`) 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 a result, 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