One can refer to the GitHub repository for source code and more information about this package.
If you use the tool, it is strongly recommended to cite the tool using the following link:
@inproceedings{
title={Evaluating Potential SOC Commuter Home-to-Work Carpool Using a Scalable and Practical Simulation Framework}
author={Liu, Diyi and Fan, Huiying and Guin, Angshuman and Guensler, Randall}
year={2024}
booktitle={Journal of Transport Geography}
}
Or,
@inproceedings{
title={CarpoolSim: A Computational Framework Measuring Carpool Potentials Given Travel Demands}
author={Liu, Diyi and Fan, Huiying and Guin, Angshuman and Guensler, Randall}
year={2024}
booktitle={SoftwareX}
}
Or,
@article{liu2022evaluating,
title={Evaluating the Sustainability Impacts of Intelligent Carpooling Systems for SOV Commuters in the Atlanta Region},
author={Liu, Diyi and Guin, Angshuman},
year={2022}
}
Between two travelers, there are two possible schemes of direct carpool
Between two travelers, given a middle point to meet, there are two possible schemes of carpooling (i.e., Park-and-Ride Carpool)
Three datasets or shapefiles are necessary to represent a traffic network:
- TrafficNetworkNode
- TrafficNetworkLink
- TrafficAnalysisZone
classDiagram
TrafficNetworkNode: +int nid
TrafficNetworkNode: +float lon
TrafficNetworkNode: +float lat
TrafficNetworkNode: +float x
TrafficNetworkNode: +float y
TrafficNetworkNode: +Point geometry
TrafficNetworkLink: +int a
TrafficNetworkLink: +int b
TrafficNetworkLink: +str a_b
TrafficNetworkLink: +str name
TrafficNetworkLink: +float distance
TrafficNetworkLink: +float factype
TrafficNetworkLink: +float speed_limit
TrafficNetworkLink: +LineString geometry
TrafficAnalysisZone: +int taz_id
TrafficAnalysisZone: +str group_id
TrafficAnalysisZone: +Polygon geometry
Another dataset is necessary to define the travel demands by providing the following minimal required set of information.
classDiagram
TripDemand: +int trip_id
TripDemand: +float orig_lon
TripDemand: +float orig_lat
TripDemand: +float dest_lon
TripDemand: +float dest_lat
TripDemand: +float new_min
TripDemand: +Point geometry
The geometry field of "TripDemand" corresponds to the origin of the trip. Finally, some parking lots can be identified and represented to consider park and ride carpool.
classDiagram
ParkAndRideStation: +int station_id
ParkAndRideStation: +str name
ParkAndRideStation: +float lon
ParkAndRideStation: +float lat
ParkAndRideStation: +int capacity
ParkAndRideStation: +Point geometry
By default, all geometry fields are using "EPSG:4326" (WGS84) projection as inputs.
.
├── carpoolsim # contains Python code (called by Jupyter Notebooks)
│ ├── basic_settings.py # IMPORTANT: set up basic information of the project (modify based on your need)
│ ├── carpool # the core pipeline of running the carpool "simulation"
│ │ ├── __init__.py
│ │ ├── trip_cluster.py
│ │ └── trip_cluster_with_time.py
│ ├── carpool_solver # the core algorithm (i.e., bipartite) to solve the problem
│ │ ├── __init__.py
│ │ └── bipartite_solver.py
│ ├── database # code to prepare and interact with the database (e.g., SQLite)
│ │ ├── __init__.py
│ │ ├── prepare_database.py
│ │ └── query_database.py
│ ├── dataclass # an interface of all data objects to standardize input data
│ │ ├── __init__.py
│ │ ├── parking_lots.py
│ │ ├── traffic_network.py
│ │ └── travel_demands.py
│ ├── network_prepare.py
│ ├── prepare_input.py
│ └── visualization # visualization tool for plotting results
│ ├── __init__.py
│ ├── carpool_viz.py
│ └── carpool_viz_seq.py
├── data_inputs # all input data (example of the notebooks)
│ ├── ABM2020 203K
│ │ ├── 2020 links # traffic network link file
│ │ ├── 2020 nodes with latlon # traffic network node file
│ │ └── taz # traffic analysis zone
│ ├── Park_and_Ride_locations # a shapefile/csv of parking lots
│ ├── gt_survey # trip demands (survey data in this case)
│ └── cleaned # cleaned dataset (for all intermediate results before runnig simulation)
├── data_outputs # store the outputs (and intermediate results)
└── notebooks # all Jupyter notebooks to run the program
You can move those files to "data_inputs" folder. The files within the "data_inputs" folder are just an example of our own project. You can set up any folder structure, but remember to reset the paths parameters in basic_settings.py.
Require inputs
- Three network files:
- traffic networks shapefile: a shapefile of traffic links
- traffic nodes shapefile: a shapefile of traffic nodes
- taz: traffic analysis zone that splits a metropolitan region to many small parts
- One file for PNR stations of Park-and-ride mode:
- Park_and_Ride_locations: Parking lots that can be used for Park and Ride trip
- One file for traffic demand:
- gt_survey: a survey of trip demands providing origin, destination, depart time, etc.
Four Jupyter notebooks are provided to run the package. Users are obligated to modify those notebooks to align with their own analysis purpose. The code talks by itself in those notebooks.
- step0_prepare_data_inputs.ipynb
- step1_prepare_path_retention_database.ipynb
- step2_prepare_traffic_demands.ipynb
- step3_run_carpoolsim.ipynb
The tool provides a rich set of parameters as a filtering "safe net" of the tool.
kwargs = {
# use bipartite method. If not, may try to use linear optimization
'rt_bipartite': True,
# setup print options
'verbose': False, 'print_mat': False, 'plot_all': True,
# coordinate filters
'mu1': 1.5, 'mu2': 0.1, 'dst_max': 5*5280,
# reroute filters
'delta': 10, 'gamma': 1.3, 'ita': 0.9, 'ita_pnr': 0.5, # reroute filters
# Delta1: control passenger/driver's departure time difference
# Delta2: control driver's maximum waiting time
'Delta1': 15, 'Delta2': 10, 'Gamma': 0.2,
# carpool mode
# 0: direct carpool only;
# 1: pnr carpool only;
# 2: both at the same time
'mode':0
}
A slightly more detailed explaination is given as follows: