Package: bevpo
Bevpo stands for 'battery electric vehicle policy' and was first named this way
by Anthony Patt and Marc Melliger. It is a package that provides city-scale car
traffic and parking analyses. It utilizes a Hidden Markov Model to translate changes
in travel time between different zones of a city throughout multiple time steps
into probabilities of driving or not, as well as choosing a destination if driving.
Given the joint distribution from these two multivariate probability distributions,
bevpo then samples a vehicle fleet of arbitrary size. One key strength of bevpo
is that it is able to model at arbitrary granularities in time and space, which
are eventually given by the data provided to bevpo.Installation:pip install bevpoDocker:For using bevpo within an Ubuntu docker containerdocker run -it aryandoustarsam/bevpoFor using bevpo with Jupyter notebook inside a docker containerdocker run -it -p 3333:1111 -v ~/path_to_data/data:/data aryandoustarsam/bevpo:jupyter
[inside running container]: jupyter notebook --ip 0.0.0.0 --port 1111 --no-browser --allow-root
[in local machine browser]: localhost:3333 
[in local machine browser, type token shown in terminal]Usage guide:At the core of bevpo stands the class bevpo.TrafficSystem. It bundles all
properties and methods of the traffic system modeled with bevpo. Bellow is a list
of all parameters, attributes, methods and generated results.Parameterscity_zone_coordinates (required):n_zones x 3 matrixA pandas.DataFrame containing the columns 'zone_id', 'zone_lat' and 
      'zone_long' indicating the respective geographic coordinates of each 
      city zone polygon centroid.od_mean_travel_time_list (required):list of n_data_t x 3 
      matricesList of pandas.DataFrames containing the columns 'source_id', 'dest_id' 
      and 'mean_travel_time'. Each list element corresponds to measurements in
      one time stamp. List elements should appear in consecutive temporal order.od_stddev_travel_time_list (=None):list of 
      n_data_t x 3 matricesList of pandas.DataFrames containing the columns 'source_id', 'dest_id' and
      'stddev_travel_time'. Each list element corresponds to measurements in one
      time stamp. List elements should appear in consecutive temporal order.od_distances (=None):n_zones x n_zonesSymmetric origin destination matrix with same zone IDs as columns and 
      indices in pandas.DataFramecharging_profile (=None):list of floats > 0A charging profile for electric vehicles with one floating point entry per
      simulation time step. It hence has to have a length equal to
      len(od_mean_travel_time_list)e_drive (=2):float > 0Exponential parameter describing the (exponential) functional relationship
      between changes in travel time in a particular city zone and the 
      probability that a car will drive.e_dest (=2):float > 0Exponential parameter describing the (expoential) functional relationship
      between changes in travel time from one particular city zone to all other
      zones and the probabiity of choosing any of these other zones as a
      destination for a trip.p_min (=0.1):float in [0, p_max)The lower bound of probability distribution for p_drive.p_max (=0.9):float in (p_min, 1]The upper bound of probability distribution for p_drive.cars_per_zone (=100):int > 0The number of cars to be sampled for each city zone during traffic 
      simulation.AttributesT:int > 0Number of simulation time steps which results to len(od_mean_travel_time_list)number_zones:int > 0Number of city zones in od matrices which results to
      len(city_zone_coordinates)datatensor_mean:number_zones x number_zones x TSparse tensor that contains all provided OD values for mean travel time.datatensor_stddev:number_zones x number_zones x TSparse tensor that contains all provided OD values for standard deviation 
       of travel time.C:int > 0Size of vehicle fleet to be simulated, which results to number_zones *
      cars_per_zonestate_tensor:C x TTensor for saving states of traffic system which consists of the location
      of each simulated vehicletransition_tensor:C x T x 4Tensor for saving state transition of traffic system which consists of the
      driving, destination, travel time and travel distance of each simulated
      vehicle.Methodssimulate_traffic():Simulates the traffic system when called.calc_od_distances(city_zone_coordinates):Called on initialization of class objects if od_distances=None. Calculates 
      the beeline distance between origin destination zones of a city if no 
      explicit matrix of such distances was past when initializing class object.create_datatensors():Called by simulate_traffic() method. Transforms the list of od matrices 
      into a single datatensor. City zone indexing corresponds to respective 
      index positions in city_zone_coordinates.index. Time step indexing 
      corresponds to respective position of OD matrix in 
      od_mean_travel_time_list. If od_stddev_travel_time_list is available, the 
      same is done for this list too.save_tfs_results(path_to_results=None):Saves the resulting plots and numeric values unter path_to_results when 
      called. If no path is passed, a directory called bevpo_results will be 
      created within current working directory, where results are stored.Resultsdriving_map:number_zones x TMultivariate distribution of driving activity among all modeled city zones
      and sampled time steps. Distributions sum up to 1 across all time step and
      cityzones.parking_map:number_zones x TMultivariate distribution of parking cars among all modeled city zones
      and sampled time steps. Distributions sum up to 1 across all time step
      and city zones.charging_map:number_zones x T(Optional). Only created if parameter charging_profile is provided. 
      Multivariate distribution of charging cars among all modeled city zones
      and sampled time steps. Distribution sums up to 1 for all city zones and
      time steps.avg_driving_times:array of length T+1Average driving durations of all sampled trips. The first entry corresponds
       to the average over all time steps. The following entries correspond to
       the average over each simulated time step.avg_driving_distances:array of length T+1Average driving distance of all sampled trips. The first entry corresponds
      to the average over all time steps. The following entries correspond to
      the average over each simulated time step.driving_share_lifetime:%The average share of the lifetime of a car in which it drives.parking_share_lifetime:%The average share of the lifetime of a car in which it is parked.circadian_rhythm:array of length TThe circadian rhythm, that is the percentual traffic activity, throughout
      all simulated time steps.distr_distances_per_t:T x 10A multivariate distribution of travelled distances for each time steps, 
      categorized into 10 bins.distr_durations_per_t:T x 10A multivariate distribution of travelled durations for each time steps, 
      categorized into 10 bins.distr_distances_total:array of length 10The total distribution of travelled distances categorized into 10 bins.distr_durations_total:array of length 10The total distribution of travelled durations categorized into 10 bins.distr_bins_km:array of length 10The distance category of each bin in km unit.distr_bins_s:array of length 10The duration category of each bin in s unit.Examples:Simulating traffic for exemplar Uber Movement travel time data, using only the
minimum required information to pass to model.import bevpo.datasets.prep_ubermovement as prep_data
import bevpo.trafficsystem as trafficsystem


### 1. Prepare Uber Data

# provide paths to Uber Movement data
path_to_rawdata = *insert path to Uber Movement .csv file here*
path_to_json_data = *insert path to Uber Movement .json file here*

# create city zone data from json file
city_zone_coordinates = (
    prep_data.create_city_zone_coordinates(path_to_json_data)
)

# create list of OD matrices from csv file
(
    od_mean_travel_time_list,
    od_std_travel_time_list
) = prep_data.create_od_matrix_lists(path_to_rawdata)


### 2. Simulate traffic 

# create object of class TrafficSystem and pass minimum required data
tfs = trafficsystem.TrafficSystem(
    city_zone_coordinates,
    od_mean_travel_time_list
)

# simulate traffic
tfs.simulate_traffic()

# save results
tfs.save_tfs_results()Simulating traffic for from exemplar Uber Movement travel time data, using more
than the minimum required information to pass to model, and customized parameters.import bevpo.datasets.prep_ubermovement as prep_data
import bevpo.trafficsystem as trafficsystem


### 1. Prepare Uber Data

# provide paths to Uber Movement data
path_to_rawdata = *insert path to Uber Movement .csv file here*
path_to_json_data = *insert path to Uber Movement .json file here*
path_to_results = *insert path to desired results folder here*

# create city zone data from json file
city_zone_coordinates = (
    prep_data.create_city_zone_coordinates(path_to_json_data)
)

# create list of OD matrices from csv file
(
    od_mean_travel_time_list,
    od_std_travel_time_list
) = prep_data.create_od_matrix_lists(path_to_rawdata)

# create a charging profile of length 24
charging_profile = [
    5, 6, 7, 10, 10, 9, 8, 7, 6, 3, 2, 1, 5, 7, 4, 2, 1, 6, 4, 5, 5, 3, 7, 6
]

### 2. Simulate traffic 

# create object of class TrafficSystem and decleare custom parameters
tfs = trafficsystem.TrafficSystem(
    city_zone_coordinates,
    od_mean_travel_time_list,
    od_std_travel_time_list,
    charging_profile=charging_profile,
    e_drive=0.5,
    e_dest=2.3,
    p_min=0.085,
    p_max=0.81
)

# simulate traffic
tfs.simulate_traffic()

# save results
tfs.save_tfs_results(path_to_results)