Ridehail Simulation

Ridehail is a Python package for simulating and analyzing the dynamics of ride-hailing platforms, such as Uber and Lyft. The package lets you model vehicle fleets, trip demand patterns, and pricing dynamics with interactive visualizations.

The best way to get an idea of what it's about is to try it out interactively at https://tomslee.github.io/ridehail/lab. Full[ish] documentation is available at https://tomslee.github.io/ridehail.

Features

• Flexible Simulation Engine: Configure city size, vehicle counts, trip rates, and dispatch strategies among other variables
• Multiple Visualization Modes:
  • Terminal-based animations (console, map, stats) using Textual
  • Desktop matplotlib visualizations
  • Interactive browser-based visualizations with Pyodide
• Dispatch Algorithm Comparison: Test different vehicle assignment strategies (in progress)
• Parameter Sweeps: Run sequences of simulations to explore parameter spaces
• Real-time Metrics: Track vehicle utilization, wait times, ride times, and pricing
• Reproducible Results: Date-based versioning and reproducible builds

Quick Start

Install with uv (recommended)

uv add ridehail

Dont have uv? Install it with: pip install uv or see uv installation docs

Or install with pip

pip install ridehail

Install all features (matplotlib visualizations + dev tools)

uv pip install ridehail[full]

Run your first simulation

Without a configuration file or command-line arguments, ridehail runs a simulation using default values for all simulation parameters. The output is just some text to the screen, and a table of results. It verifies that the package is properly installed.

ridehail

Check visualizations

The best way to manage sets of simulation parameters is in a configuration file (see below), but to get a handle on what is happening here, try these simulations that use command-line arguments to set simulation parameters:

Display a (primitive, terminal-based) animation of a vehicle moving around a very small "city", occasionally picking up passengers and dropping them off.

ridehail -cs 4 -vc 2 -a terminal_map -ad 0.5

Display a set of statistics for a simulation of a larger city, with 1760 vehicles. The statistics use the following industry-standard terms:

• P1 is the proportion of vehicle-time waiting for a trip
• P2 is the proportion of vehicle-time en route to picking up a passenger
• P3 is the proportion of vehicle-time with a passenger in the car

ridehail -cs 48 -vc 1760 -a terminal_stats

Create your own simulations

Each simulation is managed by a configuration file. You can either copy an existing configuration file or generate a new one with the following commands:

# Generate a config file with default parameters
ridehail -wc my_simulation.config

# Generate a config file with custom parameters
ridehail -wc my_simulation.config -cs 46 -vc 24

# Or with multiple overrides
ridehail -wc custom.config -cs 20 -vc 100 -bd 5.0

You can call it anything you want, but the extension .config is standard.

If you edit your configuration file in a text editor you should see each parameter has a description.

Run a simulation with web animation

The project uses pyodide, which is brilliant, to run the python code in a browser using Web Assembly.

This command shows a map of the city with vehicles moving around, picking up passengers at trip origins and dropping them at trip destinations.

The "-a" argument tells ridehail to use the web_map animation. Others include web_stats, text, terminal_map, terminal_stats, and console.

The "-ad" argument tells ridehail to delay execution of each step in the simulation by half a second. For map visualizations, this makes the display easier to understand, but for other visualizations it just slows down the simulation.

ridehail -a web_map -ad 0.5

Finding parameter values

ridehail -h lists every option with a one-line summary. Give it an option name, short form, or unique prefix of a name to see that option's full description (the same text that is written into configuration files), its allowed range, and any values it accepts:

ridehail -h city_size
ridehail -h cs              # same thing
ridehail -h inhomogeneous   # unique prefix of inhomogeneous_destinations

Options that take one of a fixed set of values (such as -a, -e, -dm and -p) also show this description when given help, and accept any unique prefix of a value:

ridehail -a help            # same as ridehail -h animation
ridehail -a terminal_m      # same as -a terminal_map

Tab completion (optional)

ridehail can complete its options and their values when you press Tab. To turn this on, register it once with your shell. Run the line for your shell from the environment where ridehail is installed (so that register-python-argcomplete, installed alongside ridehail, is on your path), then open a new shell:

# bash
register-python-argcomplete ridehail >> ~/.bashrc

# zsh
register-python-argcomplete ridehail >> ~/.zshrc

# fish
register-python-argcomplete --shell fish ridehail > ~/.config/fish/completions/ridehail.fish

Then ridehail -a term<Tab> lists the terminal animations (zsh and fish also show each value's description). Completion works for the installed ridehail command, not for python -m ridehail.

Next steps

Read the full[ish] documentation at https://tomslee.github.io/ridehail.

Development install

Prerequisites

This README assumes that you are familiar with the Windows or Linux command line, have git installed, and have python installed.

Some features require python 3.8 or later.

Clone the project and install packages

Clone the project into a directory where you will run the application. I use the src/ directory under my home directory.

src > git clone <https://github.com/tomslee/ridehail-animation.git>
src > cd ridehail-animation

Development Setup

The base package includes the full simulation engine, terminal animations, and web-based animations. It should be sufficient for most users.

The project uses optional dependency groups for different features. Choose the setup that matches your needs:

Recommended: Full local development setup (matplotlib visualizations and development packages):

uv sync --extra full

What each extra includes:

• desktop: matplotlib, seaborn, scipy, pandas (for matplotlib visualizations, which may be good for presentations and including in documents)
• dev: ruff, pytest, textual-dev, psutil (development tools)
• full: All of the above

Ridehail Lab: running a simulation in the browser

Here are instructions for running the source code in a local browser. You can access a hosted version at https://tomslee.github.io/ridehail/lab/.

Start a web server from the project directory:

> ./build.sh
> cd docs/lab
> python -m http.server > /dev/null 2>&1 &

At least, that command runs the server silently and in the background in Linux. Just try python -m http.server in a separate console if you're on Windows or want to see output.

Then go to http://localhost:8000 to see the output. If there are problems in the browser the next step is to use the browser developer tools to see what is going on

Set up Apache to serve the lab as default

As an alternative to running the python http server, you can run the application from an Apache server if you have one on the machine. I'm trying this in case I want to expose it via ngrok.

Here's three steps I did, taken from this 'does not meet the guidelines' StackOverflow question:

1. sudo nano /etc/apache2/sites-available/000-default.conf

   • change DocumentRoot /var/www/html to /home//project-directory

2. sudo nano /etc/apache2/apache2.conf

   • change <Directory /var/www> to the same project directory

3. sudo adduser www-data $USER

   • to give permissions

4. sudo service apache2 restart

Then accessing http://<machine-name> should show the page.

Development notes

Quick Reference for Developers

Install dependencies:

# Full development environment (recommended)
uv sync --extra full

# After installation, run simulations:
uv run python -m ridehail your_config.config -a terminal_stats

Build wheel for web distribution:

./build_wheel.sh
# Creates minimal wheel with only numpy dependency
# Copies to docs/lab/dist/ for browser version

Qt library for matplotlib animations.

I've had some problems with incompatible Qt versions that I have been unable to solve. Here is a specific case:

Error message: - "Cannot mix incompatible Qt library (5.15.3) with this library (5.15.17)". Root Cause: You have: - System Qt5 libraries: 5.15.3 (in /usr/lib/x86_64-linux-gnu/) - PyQt5-Qt5 package: 5.15.17 (in your virtual environment)

With the terminal-based animations and web-based animations, this is not so important.