Update documentation of pumped hydro storage. Explicit describe units of various energy-based components in the storage model (to reduce confusion between power & energy), and rewrap line endings to conform to PEP-8 recommendations for reading two files side-by-side in a single screen (or a single file in large font on a small screen)

Author: josiahjohnston

switch_model/generators/extensions/hydro_simple.py

@@ -22,11 +22,23 @@
 but the advanced framework would take longer to read and understand. To really
 take advantage of it, you'll also need more data than we usually have
 available.
+
+This module can model pumped hydro systems if the storage module is listed
+after simple_hydro in modules.txt, and pumped hydro generation projects are
+flagged via gen_is_pumped_hydro. The current implementation of pumped_hydro
+implicitly assumes that the lower reservoir always has sufficient water in it
+for pumping uphill into storage. Existing resevoir energy capacity can be
+constrained via gen_predetermined_storage_energy_mwh as needed. If existing
+reservoir energy capacity is never a binding constraint for day-to-day
+operations of pumped hydro, leave gen_predetermined_storage_energy_mwh
+unspecified, and set gen_storage_energy_overnight_cost to 0 and the
+optimization will set the energy value to a conveniently large value.
+
 """
 # ToDo: Refactor this code to move the core components into a
 # switch_model.hydro.core module, the simplest components into
 # switch_model.hydro.simple, and the advanced components into
-# switch_model.hydro.water_network. That should set a good example
+# switch_model.hydro.water_network. That could set a good example
 # for other people who want to do other custom handling of hydro.
 
 from __future__ import division

switch_model/generators/extensions/storage.py

@@ -5,6 +5,13 @@
 This module defines storage technologies. It builds on top of generic
 generators, adding components for deciding how much energy to build into
 storage, when to charge, energy accounting, etc.
+
+To do: 
+
+* Add optional ability to exogenously constrain StateOfCharge based on
+input files. See notes under the Track_State_Of_Charge documentation below.
+* Update the PumpedHydro features to work with the hydro_system module,
+and use full mass balance accounting.
 """
 
 from pyomo.environ import *
@@ -66,47 +73,61 @@ def define_components(mod):
     Note that this describes the energy component and the overnight_cost
     describes the power component.
 
-    BuildStorageEnergy[(g, bld_yr) in STORAGE_GEN_BLD_YRS]
-    is a decision of how much energy capacity to build onto a storage
-    project. This is analogous to BuildGen, but for energy rather than power.
+    BuildStorageEnergy[(g, bld_yr) in STORAGE_GEN_BLD_YRS] is a decision of
+    how much energy capacity to build onto a storage project in units of MWh.
+    This is analogous to BuildGen, but for energy rather than power.
 
-    StorageEnergyInstallCosts[PERIODS] is an expression of the
-    annual costs incurred by the BuildStorageEnergy decision.
+    StorageEnergyInstallCosts[PERIODS] is an expression of the annual costs
+    incurred by the BuildStorageEnergy decision, in units of $/MWh
 
     StorageEnergyCapacity[g, period] is an expression describing the
-    cumulative available energy capacity of BuildStorageEnergy. This is
-    analogous to GenCapacity.
+    cumulative available energy capacity of BuildStorageEnergy in units of
+    MWh. This is analogous to GenCapacity.
 
     STORAGE_GEN_TPS is the subset of GEN_TPS,
     restricted to storage projects.
 
-    ChargeStorage[(g, t) in STORAGE_GEN_TPS] is a dispatch
-    decision of how much to charge a storage project in each timepoint.
+    ChargeStorage[(g, t) in STORAGE_GEN_TPS] is a dispatch decision of how
+    much to charge a storage project in each timepoint in units of MW.
 
     StorageNetCharge[LOAD_ZONE, TIMEPOINT] is an expression describing the
-    aggregate impact of ChargeStorage in each load zone and timepoint.
+    aggregate impact of ChargeStorage in each load zone and timepoint in units
+    of MW.
 
     Charge_Storage_Upper_Limit[(g, t) in STORAGE_GEN_TPS]
     constrains ChargeStorage to available power capacity (accounting for
     gen_store_to_release_ratio)
 
-    StateOfCharge[(g, t) in STORAGE_GEN_TPS] is a variable
-    for tracking state of charge. This value stores the state of charge at
-    the end of each timepoint for each storage project.
+    StateOfCharge[(g, t) in STORAGE_GEN_TPS] is a variable for tracking state
+    of charge, in units of MWh. This value stores the state of charge at the
+    end of each timepoint for each storage project.
     
-    With the current "circular" implementation of each timeseries,
-    StateOfCharge[first] = StateOfCharge[last] + net_energy. This effectively
-    allows each timeseries to begin and end with any given charge level (0 to
-    100% of energy capacity), and the optimization process will choose a value
-    that is convenient. If you wish to constrain the value, you will need to
-    write an extension.
-
     Track_State_Of_Charge[(g, t) in STORAGE_GEN_TPS] constrains StateOfCharge
     based on the StateOfCharge in the previous timepoint, ChargeStorage and
     DispatchGen. If pumped hydro projects are available (defined in the
     optional prerequisite simple_hydro module), this constraint will also
     include average stream inflow and spilled water for pumped hydro projects.
 
+    With the current circular implementation of each timeseries,
+    StateOfCharge[first] = StateOfCharge[last] + net_energy. This effectively
+    allows each timeseries to begin and end with any given charge level (0 to
+    100% of energy capacity), and the optimization process will choose a value
+    that is convenient. 
+    
+    For some applications, you may wish to constrain the StateOfCharge values
+    to pre-determined values, which would require writing a new module that
+    reads data and applies a constraint to StateOfCharge at the beginning of
+    each day - either as a fixed amount of energy (MWh) or as a fraction of
+    energy storage capacity (%). Or alternately, updating this file to include
+    that behavior as an optional feature.
+    
+    Other applications may require linking consecutive timeseries so that the
+    StateOfCharge carries over from one timeseries to the next. That would
+    require writing a new version of the timescales module and redefining
+    tp_previous to use sequential indexing rather than consecutive. Note, that
+    strategy is not required for 8760 hourly/annual production cost models;
+    those problems can define a single timeseries of an entire year. 
+
     State_Of_Charge_Upper_Limit[(g, t) in STORAGE_GEN_TPS]
     constrains StateOfCharge based on installed energy capacity.
 
@@ -271,19 +292,34 @@ def load_inputs(mod, switch_data, inputs_dir):
 
     """
 
-    # TODO: maybe move these columns to a storage_gen_info file to avoid the weird index
-    # reading and avoid having to create these extra columns for all projects;
-    # Alternatively, say that these values are specified for _all_ projects (maybe with None
-    # as default) and then define STORAGE_GENS as the subset of projects for which
-    # gen_storage_efficiency has been specified, then require valid settings for all
-    # STORAGE_GENS.
+    # TODO: consider moving these columns to a storage_gen_info file to avoid
+    # avoid having to create these extra columns for all projects, and to
+    # allow unambiguous marking of storage projects without looking for
+    # non-empty gen_storage_efficiency columns. This is similar to how
+    # simple_hydro specifies input files. Pro: less empty values for
+    # non-storage projects. Con: another input file to keep track of.
+    # Alternatively, say that these values are specified for _all_ projects
+    # (maybe with None as default) and then define STORAGE_GENS as the subset
+    # of projects for which gen_storage_efficiency has been specified, then
+    # require valid settings for all STORAGE_GENS.
+    # Note: The current implementation is similar to the 2nd option above, but
+    # requires checking `g in mod.gen_storage_efficiency` rather than checking
+    # `mod.gen_storage_efficiency[g] is not None`.
     switch_data.load_aug(
         filename=os.path.join(inputs_dir, 'generation_projects_info.tab'),
         auto_select=True,
-        optional_params=['gen_store_to_release_ratio', 'gen_storage_energy_to_power_ratio', 'gen_storage_max_cycles_per_year'],
-        param=(mod.gen_storage_efficiency, mod.gen_store_to_release_ratio, mod.gen_storage_energy_to_power_ratio, mod.gen_storage_max_cycles_per_year))
+        optional_params=[
+            'gen_store_to_release_ratio', 
+            'gen_storage_energy_to_power_ratio',
+            'gen_storage_max_cycles_per_year'],
+        param=(
+            mod.gen_storage_efficiency, 
+            mod.gen_store_to_release_ratio,
+            mod.gen_storage_energy_to_power_ratio,
+            mod.gen_storage_max_cycles_per_year))
     # Base the set of storage projects on storage efficiency being specified.
-    # TODO: define this in a more normal way
+    # TODO: define this in a more normal way, possibly with a binary flag
+    # gen_is_storage.
     switch_data.data()['STORAGE_GENS'] = {
         None: list(switch_data.data(name='gen_storage_efficiency').keys())}
     switch_data.load_aug(