"wi_lib_vrp.py" – The main entry point for the project code. This script runs from the command line and parses the arguments describing the Vehicle Routing Problem (VRP) set-up options, problem parameters, solution search strategies, and solution output options. The script also reads the library data from the input file into a Pandas DataFrame, then organizes calls to other modules to process the data, build the VRP input distance and duration matrices, create the VRP model, and solve the VRP. Finally, this script manages the various solution output options to display the solution on the console, write it to a text file, create a Google Map of the optimal routes, and save a screenshot of the map as a PNG file.
"wi_lib_vrp_finalize_data.py" – Utility script to add regional designations and geolocation data for each library to the input data file. This script runs from the command line and users need to run it one time to prepare the data before running the main script, "wi_lib_vrp.py." With command-line arguments, users can add regional data, geolocation data, or both and specify the format of the output file as either CSV or XLSX.
"wi_lib_vrp_gmaps_sub_classes.py" – This file contains class definitions and methods used to patch selected code from the "gmplot" package that creates Google Maps files. I separated this code from other scripts for organizational and readability purposes. The "wi_lib_vrp_route_viz.py" script imports the modified definitions and methods and overwrites the originals contained in the GoogleMapPlotter class of the "gmplot" package.
"wi_lib_vrp_matrix_build.py" – A script used to create the distance and duration matrices for input to the Google OR-Tools routing solver. A function filters the full input data set to the region of interest and formats the data for use in the Openrouteservice Matrix Service API request ("Openrouteservice," 2020). The code builds the matrices piecewise to accommodate API request quotas, then assembles the pieces into full versions and checks the results to ensure proper formatting. Users can run the script from the command line as a standalone program which creates the matrices and saves them to Python pickle files for later use. If needed, it can also be called from the "wi_lib_vrp.py" script to create the matrices in real-time. Note that the latter approach requires a significant amount of time to retrieve the data and can exceed daily API request quotas if used excessively.
"wi_lib_vrp_route_viz.py" – The code in this file uses the "gmplot" package to create an HTML file with a Google Map showing the optimal routes found by the OR-Tools routing solver. The script patches the "gmplot" GoogleMapPlotter class methods as needed (see description of "wi_lib_vrp_gmaps_mod_classes.py"), creates a map object, draws color-coded lines showing each route, and adds markers at each route stop. The stop markers are clickable and display an InfoWindow with more information about the library. This file also contains functions for opening the HTML output file in a web browser and saving a screenshot of the map to a PNG file.
"wi_lib_vrp_VrpModelObj.py" – This script defines a Python class to handle operations related to creating and solving a VRP. Class methods generate a unique model ID for every VRP, format the input data for the Google OR-Tools routing solver, initialize the OR-Tools model and constraints, and solve the model. Additional methods format the solution output in a readable form for display on screen or output to a text file and generate route stop sequences used to create Google Maps visualizations.
"chromedriver_win32" – A copy of the 'selenium' package web driver for the Chrome browser. The screenshot functionality in "wi_lib_vrp_route_viz.py" requires the driver to open a headless browser. Note that users must add the path to the directory to the PATH environment variable, but they can store the directory and EXE file in any location.
"vrp_matrix_data" – This directory contains Python pickle files that store pre-generated distance and duration matrices in a dictionary object. Each file corresponds to a region in either the PLSR Delivery Workgroup's ideal or starting point proposal.
"vrp_output" – This directory contains subdirectories to store output files generated by the OR-Tools routing solver: "map_files" (HTML files of Google Maps), "solution_files" (TXT files of formatted solutions), and "screenshots" (PNG files of Google Maps screenshots).
"model_id_codes.md" - An explanation of the codes used to name solution output files. Each filename encodes the proposal name and region number of the model, the value of the maximum route duration parameter, the initial solution strategy, the local search metaheuristic, and the value of the vehicle capacity parameter.
"WI_Library_Delivery_Services_and_the_Vehicle_Routing_Problem.pdf" - A PDF copy of the final project report. The report includes sections on the project background, a literature review, the research methodology, the results and findings, and a discussion of the implications.
"vrp_results_tracker.xlsx" - A copy of the Excel file used to store solution data for every regional VRP and combination of problem parameters. Includes a tab showing results from the test model set used to narrow down the options for the initial solution strategy and local search metaheuristic used by the Google OR-Tools vehicle routing solver on the full set of VRP variants.
"wi_library_directory.csv" and "wi_library_directory_geo_reg.csv" – The first file is a copy of the input data file containing information on all Wisconsin library delivery stops. The second file includes additional columns added listing proposed regional designations and geocoded location data.