docs: update text and figures (#346)

docs/demand/transportation_electrification/data.rst

@@ -1,39 +1,41 @@
 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. 
+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: 
+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). 
++ 4 vehicle types (LDV, LDT, MDV, and HDV)
++ 34 simulation years (2017-2050)
++ 481 Urban Areas (as defined by the U.S. Census Bureau) and 48 Rural Areas (one for
+  each continental 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
+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`).  
+on the next trip. An example profile is in orange below, added on top of an example
+of non-transportation base 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)
+   Example of BEV Immediate Charging stacked on top of non-transportation base demand
 
-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).  
+Smart Charging refers to coordinated charging between drivers (either in aggregate or
+individually) and utilities or balancing authorities in response to a user-adjustable
+objective function. The example profile below (:numref:`example_ldv_smart_load`) 
+provides the same amount of charging energy 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 non-transportation base demand plus the 
+additional transportation electrification load to be substantially lower.  
 
 .. _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)
+   Example of BEV Smart Charging “filling in the Valleys” of non-transportation base demand

docs/demand/transportation_electrification/manual.rst

@@ -3,44 +3,58 @@ 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.
+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.
+  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 
+  :numref:`electric_vehicle_miles_traveled_projections` below for calculation process 
+  details using data from the National Renewable Energy Laboratory (NREL)’s 
+  Electrification Futures Study (EFS) 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).
+  NREL’s EFS, with more detail in Section :numref:`fuel_efficiency_projections` below.
++ Each vehicle type (LDV, LDT, MDV, and HDV) has a dataset with vehicle trip patterns
+  that is used by the algorithm to represent a typical day of driving.  See Sections 
+  :numref:`ev_charging_model` and :numref:`vehicle_travel_patterns` 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 the MOVES model from the U.S.
+  Environmental Protection Agency (EPA) 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:
+:py:mod:`prereise.gather.demanddata.transportation_electrification.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
+5. U.S. State and the underlying Urban Area(s) / Rural Area that are 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.
+script across multiple U.S. States 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.   
+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
+from one into 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 the two shape files. Finally, the user can simply multiply
+profiles in its original resolution, such as Urban Areas (UA) and Rural Areas (RA), 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.