Breakthrough-Energy · dmuldrew · Jan 5, 2022 · Mar 12, 2022 · Mar 14, 2022 · May 26, 2022
diff --git a/.gitignore b/.gitignore
@@ -144,4 +144,6 @@ Thumbs.db
 prereise/gather/winddata/data/StatePowerCurves.csv
 
 # Jupyter Notebook
-share/
+share/
+
+.devcontainer
diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md
@@ -205,6 +205,22 @@ These datasets are used to generate flexibility profiles that are realized throu
 These datasets are generously provided by NREL, which is operated for the U.S. Department of Energy by the Alliance for Sustainable Energy, LLC. Before using these datasets, please read [this disclaimer](https://www.nrel.gov/disclaimer.html) first.
 
 
+#### U.S. Environmental Protection Agency
+##### Source
+* Name: MOVES2010 Highway Vehicle Population and Activity Data
+* Author: U.S. Environmental Protection Agency
+* Description: Vehicle Miles Travelled disribution by month and by weekday/weekend
+* Source: https://www.epa.gov/moves/moves-onroad-technical-reports
+* Exact Source Location: https://nepis.epa.gov/Exe/ZyPDF.cgi?Dockey=P100ABRO.pdf
+
+##### Destination
+* Modifications to source file(s): None
+* Location:
+  * ***prereise/gather/demanddata/transportation_electrification/moves_daily.csv***
+  * ***prereise/gather/demanddata/transportation_electrification/moves_monthly.csv***
+
+##### General Purpose
+The dataset is used to distribute the annual vehicle miles traveled (VMT) using seasonal weight factors for the final charging profiles.
 
 ---
 ### Hydro

diff --git a/docs/demand/transportation_electrification/data.rst b/docs/demand/transportation_electrification/data.rst
@@ -0,0 +1,39 @@
+Capabilities and Data
+#####################
+The transportation electrification module calculates an estimate of the additional hourly electricity demand from the electrification of transportation vehicles for all U.S. urban and rural areas for years ranging from 2017-2050.  The hourly estimation builds upon data collected representing over half a million driving events. 
+
+Additional data sets allow for profiles to be generated across the following
+dimensions: 
+
++ 4 vehicle types (light-duty vehicles (LDV), light-duty trucks (LDT), medium-duty
+  vehicles (MDV), and heavy-duty vehicles (HDV)) 
++ 33 simulation years (2017-2050) 
++ 481 Urban Areas (as defined by the U.S. Census Bureau) and 50 Rural Areas (one for
+  each U.S. State). 
+
+The charging of each vehicle is currently simulated via one of two methods: Immediate
+Charging and Smart Charging.  Immediate Charging simulates charging occurring from the
+time the vehicle plugs in until either the battery is full or until the vehicle departs
+on the next trip.  An example profile is in orange below, added on top of the base load
+demand (:numref:`example_ldv_immediate_load`).  
+
+.. _example_ldv_immediate_load:
+
+.. figure:: demand/transportation_electrification/img/data/ldv_immediate_load.png
+   :align: center
+
+   Example of LDV Immediate Charging Stacked on Top of Base Load (3 Weeks)
+
+Smart Charging refers to coordinated charging in response to a user-adjustable
+objective function.  The example profile below (:numref:`example_ldv_smart_load`)
+provides the same amount of charging to the same set of vehicles in the Immediate
+Charging figure above (:numref:`example_ldv_immediate_load`).  This instance of Smart
+Charging manages the peak demand of the base load plus the additional transportation
+electrification load to be substantially lower (~50GW vs ~40GW in this example case).  
+
+.. _example_ldv_smart_load:
+
+.. figure:: demand/transportation_electrification/img/data/ldv_smart_load.png
+   :align: center
+
+   Example of LDV Smart Charging “Filling in the Valleys” of Base Load (3 Weeks)
diff --git a/docs/demand/transportation_electrification/img/data/ldv_immediate_load.png b/docs/demand/transportation_electrification/img/data/ldv_immediate_load.png
diff --git a/docs/demand/transportation_electrification/img/data/ldv_smart_load.png b/docs/demand/transportation_electrification/img/data/ldv_smart_load.png
diff --git a/docs/demand/transportation_electrification/img/methodology/daily_trips.png b/docs/demand/transportation_electrification/img/methodology/daily_trips.png
diff --git a/docs/demand/transportation_electrification/img/methodology/dwelling_over_24h.png b/docs/demand/transportation_electrification/img/methodology/dwelling_over_24h.png
diff --git a/...nd/transportation_electrification/img/methodology/immediate_charging_result.png b/...nd/transportation_electrification/img/methodology/immediate_charging_result.png
diff --git a/...ransportation_electrification/img/methodology/ldt_immediate_charging_output.png b/...ransportation_electrification/img/methodology/ldt_immediate_charging_output.png
diff --git a/...nd/transportation_electrification/img/methodology/ldt_smart_charging_output.png b/...nd/transportation_electrification/img/methodology/ldt_smart_charging_output.png
diff --git a/...ransportation_electrification/img/methodology/ldv_immediate_charging_output.png b/...ransportation_electrification/img/methodology/ldv_immediate_charging_output.png
diff --git a/...nd/transportation_electrification/img/methodology/ldv_smart_charging_output.png b/...nd/transportation_electrification/img/methodology/ldv_smart_charging_output.png
diff --git a/...transportation_electrification/img/methodology/scaling_process_vehicle_trip.png b/...transportation_electrification/img/methodology/scaling_process_vehicle_trip.png
diff --git a/...demand/transportation_electrification/img/methodology/smart_charging_result.png b/...demand/transportation_electrification/img/methodology/smart_charging_result.png
diff --git a/docs/demand/transportation_electrification/img/methodology/vmt_by_hour.png b/docs/demand/transportation_electrification/img/methodology/vmt_by_hour.png
diff --git a/docs/demand/transportation_electrification/manual.rst b/docs/demand/transportation_electrification/manual.rst
@@ -0,0 +1,46 @@
+User Manual
+###########
+Pre-processed input data
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following data is provided for the user or could be overridden via an input from the user with a different preferred data set.
+
++ Annual projections of vehicle miles traveled (VMT) are calculated in advance and are
+  provided for the user for all Urban Areas in the U.S.  Each state also has a VMT
+  projection for the Rural Area in that state.  See Section 3.1 below for calculation
+  process details using data from NREL’s Electrification Futures Study and the
+  Department of Transportation’s Transportation and Health Indicators.
++ Projections of the fuel efficiency of battery electric vehicles are provided from
+  NREL’s Electrification Futures Study, with more detail in Section 3.4 below.
++ Each vehicle type (light-duty vehicles (LDV), light-duty trucks (LDT), medium-duty
+  vehicles (MDV), and heavy-duty vehicles (HDV)) has a data set with vehicle trip
+  patterns that is used by the algorithm to represent a typical day of driving.  See
+  Sections 1 and 2 for more details on the input data from the National Household
+  Travel Survey (NHTS) and the Texas Commercial Vehicle Survey.
++ Each typical day of driving is scaled by data from EPA’s MOVES that captures the
+  variation in typical driving behavior across (i) urban/rural areas, (ii) weekend/
+  weekday patterns, and (iii) monthly driving behavior (e.g. more driving in the summer
+  than the winter).
+
+
+Calling the main Transportation Electrification method
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+With the above input data, the main function call for the transportation module is
+``generate_BEV_vehicle_profiles`` and is called using a few user-specified inputs:
+
+1. Charging Strategy (e.g. Immediate charging or Smart charging)
+2. Vehicle type (LDV, LDT, MDV, HDV)
+3. Vehicle range (whether 100, 200, or 300 miles on a single charge)
+4. Model Year
+5. Urban Area / Rural Area that is being modelled
+
+Depending on the spatial region included in the broader simulation, the user can run a
+script across multiple Urban Areas and Rural Areas to calculate the projected
+electricity demand from electrified transportation for the full spatial region.  From
+there, a spatial translation mechanism (described next) converts this demand to the
+accompanying demand nodes in the base simulation grid.
+
+
+Spatial translation mechanism – between any two different spatial resolutions 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+We have developed a module called :py:mod:`prereise.utility.translate_zones`. It takes in the shape files of the two spatial resolutions that the user would like to transform into one from the other. Then a transformation matrix that gives the fractions of every region in one resolution onto each region in the other resolution will be generated based on the overlay of two shape files. Finally, the user can simply multiply profiles in its original resolution, such as Urban/Rural Areas, by the transformation matrix to obtain profiles in the resultant resolution, such as load zones in the base simulation grid. This allows each module to be built in whatever spatial resolution is best for that module and to then transform each module into a common spatial resolution that is then used by the multi-sector integrated energy systems model.