feat: mesh branch upgrade priorities

[danielolsen]

Purpose

This PR adds a feature to be able to choose how to prioritize which congested mesh branches to upgrade. Previously the ranking was always by average congestion shadow price, now there are also options for [average congestion shadow price per MW that will be upgraded] and [average congestion shadow price per MW-mile that will be upgraded]. For zero-length branches the length is given as 1 mile.
Closes #116

What is the code doing

The function _identify_mesh_branch_upgrades now takes one more parameter, method, which must be one of ('branches', 'MW', 'MWmiles') (defaults to 'branches'). Once the average congestion shadow price is determined, the metric by which the branches will be ranked is calculated in one of three ways (specified by method), and branches are then ranked by this metric, with the top N branches returned.

Tests for the new ranking methods are given in test_design_transmission.py, where the test case is engineering to produce different rankings for the three methods.

How to test the code

IMPORTANT: This code requires that you have the following fix applied to PostREISE: Breakthrough-Energy/PostREISE#84

Demo:

>>> from powersimdata.scenario.scenario import Scenario
>>> from powersimdata.input import design_transmission as pdt
>>> scenario = Scenario('87')
SCENARIO: base | WesternBase_2016_noHVDC_Final_2019Sep

--> State
analyze
>>> pdt._identify_mesh_branch_upgrades(scenario, upgrade_n=3, method='branches')
--> Loading CONGU
--> Loading CONGL
{94529, 100585, 95773}
>>> pdt._identify_mesh_branch_upgrades(scenario, upgrade_n=3, method='MW')
--> Loading CONGU
--> Loading CONGL
--> Loading grid
Loading bus
Loading plant
Loading heat_rate_curve
Loading gencost_before
Loading gencost_after
Loading branch
Loading sub
Loading bus2sub
{94529, 100585, 95773}
>>> pdt._identify_mesh_branch_upgrades(scenario, upgrade_n=3, method='MWmiles')
--> Loading CONGU
--> Loading CONGL
--> Loading grid
Loading bus
Loading plant
Loading heat_rate_curve
Loading gencost_before
Loading gencost_after
Loading branch
Loading sub
Loading bus2sub
{94529, 100585, 99238}

Overall the rankings for this scenario are similar, but MWmiles gives a different result than MW or branches.

Time to review

Estimated 1 hour or less. There's about 30 lines of real useful code, the rest is tests.

[rouille]

Set --> set in docstring

[rouille]

2 blank lines (PEP8)

[rouille]

variable allowed_list is not used. 'method must be one of: {%s}' % allowed_list should work

[danielolsen]

Good catch, I had meant to use f-strings, which does the same thing (in my opinion in a cleaner format).
ValueError(f'method must be one of: {allowed_list}')

[rouille]

l.63 in docstring, :param pandas.DataFrame branch: branch DataFrame from Grid object. --> :param pandas.DataFrame plant: plant DataFrame from Grid object.

[rouille]

Is there any reason for _identify_mesh_branch_upgrades to be a private function? It seems that it will be used outside of the module.

[danielolsen]

@rouille I think I see the public vs. private issue. I intended this whole module to be invoked via scale_congested_mesh_branches, which invokes the other private functions, but I forgot to add a method parameter to scale_congested_mesh_branches to be passed through to _identify_mesh_branch_upgrades. If scale_congested_mesh_branches get this extra param and passes it through, does the design make sense?

[danielolsen]

All style/doc changes are addressed, and the public function has been updated to pass through the method parameter. Better demo of the function as the user will interact with it:

>>> from powersimdata.scenario.scenario import Scenario
>>> from powersimdata.input import design_transmission as pdt
>>> ref_scenario = Scenario('87')
SCENARIO: base | WesternBase_2016_noHVDC_Final_2019Sep

--> State
analyze
>>> new_scenario = Scenario('')
>>> new_scenario.state.set_builder(['Western'])
Reading bus.csv
Reading plant.csv
Reading gencost.csv
Reading branch.csv
Reading dcline.csv
Reading sub.csv
Reading bus2sub.csv
Reading zone.csv
--> Summary
# Existing study
base | test | pos_base
# Available profiles
demand: ca2020 | ca2030 | v3 | v4
hydro: v1 | v2
solar: v2
wind: v1 | v2
>>> new_scenario.state.builder.change_table.ct
{}
>>> new_scenario.state.builder.change_table.scale_congested_mesh_branches(ref_scenario, upgrade_n=3, method='MW')
--> Loading CONGU
--> Loading CONGL
--> Loading grid
Loading bus
Loading plant
Loading heat_rate_curve
Loading gencost_before
Loading gencost_after
Loading branch
Loading sub
Loading bus2sub
>>> new_scenario.state.builder.change_table.ct
{'branch': {'branch_id': {94529: 2, 100585: 2, 95773: 2}}}
>>> new_scenario.state.builder.change_table.clear()
>>> new_scenario.state.builder.change_table.scale_congested_mesh_branches(ref_scenario, upgrade_n=3, method='MWmiles')
--> Loading CONGU
--> Loading CONGL
--> Loading grid
Loading bus
Loading plant
Loading heat_rate_curve
Loading gencost_before
Loading gencost_after
Loading branch
Loading sub
Loading bus2sub
>>> new_scenario.state.builder.change_table.ct
{'branch': {'branch_id': {94529: 2, 100585: 2, 99238: 2}}}
>>> new_scenario.state.builder.change_table.scale_congested_mesh_branches(ref_scenario, upgrade_n=3, method='foobar')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "C:\Users\dolsen\repos\iv\PowerSimData\powersimdata\input\change_table.py", line 309, in scale_congested_mesh_branches
    scale_congested_mesh_branches(self, ref_scenario, **kwargs)
  File "C:\Users\dolsen\repos\iv\PowerSimData\powersimdata\input\design_transmission.py", line 155, in scale_congested_mesh_branches
    ref_scenario, upgrade_n=upgrade_n, quantile=quantile, method=method)
  File "C:\Users\dolsen\repos\iv\PowerSimData\powersimdata\input\design_transmission.py", line 178, in _identify_mesh_branch_upgrades
    raise ValueError(f'method must be one of: {allowed_list}')
ValueError: method must be one of: branches, MW, MWmiles

[danielolsen]

The branch has now been interactive rebased to what I think are only the essential commits.

[rouille]

Great new feature