Workings for the beneficiaries-pay consultation paper (16 Jan 2014)
=====================================================

Contents
========

1. This directory should contain the following files:

   - "Prepare raw allocations.sql"                                      } SQL code used to model the various beneficiaries-pay 
   - "Calculate beneficiaries pay charges.sql"                          } charging options (using various inputs, including 
   - "Calculate beneficiaries pay charges at nodal level - 3 years.sql" } vSPD output files)

   - "Beneficiaries pay outputs for release.xlsx" - Excel graphs used in the consultation paper
   - "Data for Excel graphs.sql"                  - SQL code used to extract the raw data for the above graphs

   - "Incidence maps input data - gen.xlsx"  } Nodal charging rate data, used to produce the 'heat maps' used in the consultation paper
   - "Incidence maps input data - load.xlsx" } 
   
   - "List of vSPD model runs.xlsx" - Human-readable file listing the vSPD runs and experiments
                                      that were carried out in the course of the analysis, and are included in this package

2. The subdirectory 'Inputs' should contain the following files:

   - "Base case nodal charges.csv" - Results of preparatory calculations for the GIT-based method 
   - "Zonal 3 base case non asset specific charging rate.csv" } Results of preparatory calculations for non-interconnector parts of the Zonal 3 method
   - "Zonal 3 base case within region charging rates.csv"     }  
   - "Table of runs.csv" - which lists the vSPD runs whose outputs are in the 'Inputs' subdirectory, and organises them into factual/counterfactual pairs 
   - "annual revenue requirements.csv" - annual amounts to be recovered by approach, variant, and component)
   - "offer node to participant.csv" - a table mapping each generation node to a generator
   - "injecting load node to participant.csv" - a table mapping each demand node that is sometimes a net injector to a generator
   - "node to network.csv" - a table mapping each node to the _primary_ network or direct-connect customer it serves
   - "prefix to region.csv" - a table mapping each node to a region of NZ
   - "prefix to rcpd region.csv" - a table mapping each node to the four existing transmission pricing regions
   - "days per month.csv" - providing the number of days in each calendar month studied
   - "prefix to location for 3 year analysis.csv" - dividing the country into several regions for the purposes of a specific graph
   - "Variants - GIT-based charging rates.csv" - providing GIT-based charging rates for the purposes of a specific graph.

   Each of these CSV files is used by one or more of the SQL programs listed above.

3. The subdirectories 'Inputs\from vSPD' and 'Inputs\from vSPD\3 years' should contain many vSPD files of the form "*_NodeResults_TP.csv".

   These are used by "Prepare raw allocations.sql" above.

4. The subdirectory 'Data for vSPD' should contains the GDX files used by vSPD.
	   
   These GDX files are the inputs to the vSPD model, and can be used (along with the version of vSPD used for this work - see below)
   to recreate the "*_NodeResults_TP.csv" files in the 'Inputs' directory.   
   
   The GDX files are arranged similarly to the "*_NodeResults_TP.csv" files. There is a .ZIP for each 4 month set of inputs in the 'Inputs\Data for vSPD'
   folder and a .ZIP for each year in the 'Inputs\Data for vSPD\3 years' folder. 

   Note that there is some duplication of data between the two folders; and that there are fewer GDX input files than there are .csv output files. This 
   is because the same GDX can be used with different options in the GAMS code to produce different results. (see below)
   
   
Obtaining and running the version of vSPD used for this work
============================================================

1. The version of vSPD used to produce these results is hosted on and can be obtained from the EA's vSPD GITHUB repository.
	[https://github.com/BrianBull/vSPD/commit/484ebcb0ca16b87fd66ad8cb7c3c4ba6add83aef]

2. The version of vSPD used does not use the built-in override functionality, and this has been switched off in the settings file

3. It is recommended to run vSPD through the Excel interface and that up to one year of simulations is run at a time. (1 year take about 12 hours to run 
   on a modern computer) 

4. Certain runs require minor changes to the GAMS code, and different runs require different intpu GDXs. Consult the 'List of vSPD model runs' xlsx file
   for a complete list of code changes and GDX files to use for each run.


Notes
=====

1. Throughout these working files, the "Simplified SPD" method is sometimes referred to as the "SPD method", 
   and the "Zonal SPD" method is always referred to as the "Zonal 3" method. 
   Any confusion this may cause is regretted.

2. This README file assumes familiarity with the vSPD model and the GIT source code management system. 
   Please contact the Electricity Authority if you need more background information.