Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

The Starting Kit for Learning to Dispatch and Reposition Competition

This repository is the official Learning to Dispatch and Reposition (LDR) Competition submission template and starter kit! Clone this to make a new submission!

Note: we recommend keeping your clone up-to-date with the upstream before your submission to make sure you receive the latest information about the competition. You could also watch this repo so that you are notified whenever there are new updates.

Value Function is All You Need: A Unified Learning Framework for Ride Hailing Platforms

Xiaocheng Tang, Fan Zhang, Zhiwei (Tony) Qin, Yansheng Wang, Dingyuan Shi, Bingchen Song, Yongxin Tong, Hongtu Zhu, Jieping Ye

A link to our KDD 2021 paper describing the winning solution can be found here

Table of contents

Other Resources:


Please contact the organizers ( if you have any problem concerning this challenge.

├── samples                 # The sample data illustrating the api of your agent required by the simulator.
├──           # A demo of how your agent will be used during simulation.
├──            # Run test in the simulation environment.
├── environment.yml         # The simulation environment specified in a conda environment file.
├── Dockerfile              # The simulation environment specified in a Dockerfile.
├── README                  # The readme file.
└── model                   # IMPORTANT: Your submission folder.
    └──            # IMPORTANT: Your implementation of the dispatch and reposition.


Clone this repo. Create your submission bundle by zipping the whole model folder. Make sure no extra directories are created within the zip, e.g., zip -j model/*. And head over to the competition website for your first submission!

Implement your own dispatch and reposition agent!

A LDR agent is equipped with two performable actions, dispatch and reposition, which receive observations from the environment, computing order-driver assignment and driver repositioning destinations, respectively.

class Agent(object):
  """ Agent for dispatching and reposition """

  def __init__(self):
    """ Load your trained model and initialize the parameters """

  def dispatch(self, dispatch_observ):
    """ Compute the assignment between drivers and passengers at each time step
    :param dispatch_observ: a list of dict, the key in the dict includes:
        order_id, int
        driver_id, int
        order_driver_distance, estimated distance between the driver and the order, float
        order_start_location, a list as [lng, lat], float
        order_finish_location, a list as [lng, lat], float
        driver_location, a list as [lng, lat], float
        timestamp, current simulation time, int
        order_finish_timestamp, estimated order finish time, int
        day_of_week, Monday=0, Sunday=6, int
        reward_units, reward received after the order is completed, float
        pick_up_eta, estimated time (in seconds) it takes the driver to pick up the order, float

    :return: a list of dict, the key in the dict includes:
        order_id and driver_id, the pair indicating the assignment

  def reposition(self, repo_observ):
    """ Compute the reposition action for the given drivers
    :param repo_observ: a dict, the key in the dict includes:
        timestamp: int
        driver_info: a list of dict, the key in the dict includes:
            driver_id: id of the idle driver in the treatment group, int
            grid_id: id of the grid the driver is located at, str
        day_of_week: int

    :return: a list of dict, the key in the dict includes:
        driver_id: id of the idle driver in the treatment group, int
        destination: id of the grid the driver is repositioned to, str

Look into the file inside the model folder for more details. The implements a default policy and is provided for you to base your submission. The model folder must contain all your submitted files including the and its dependencies.

Test your agent locally

During online evaluation the simulator will look for the file inside your submission bundle and import your Agent class. A valid submission requires

  • An file in the first directory level of your submission bundle after unzipped;
  • The Agent class structure and function signatures kept unchanged as documented above.

We suggest developing your agent inside the model folder. To make sure your agent run correctly in the online evaluation environment, you just need to run


It will launch a docker environment, import your model and call your agent on a sample dataset provided for you as a quick test before the submission.

In particular, the gives an example of how your submission will be used in the simulation and the Dockerfile describes the environment where your will be executed.

Get ready for submission

When you are ready to submit, zip the model folder while making sure no extra directories are created within the zip, e.g., go inside the model folder and run zip -r ../ . -x '*.git*' -x '*__pycache__*' which creates your submission bundle just outside of the model folder.

Finally head over to the competition website to see how your algorithm performs!

Development tips

Test your agent locally first before online submission

Online evaluation puts a limit on number of submissions per day and provides only rudimentary error messages for security reasons. The purpose of this repo is thus to provide you with a local testing environment so that you can eliminate most of errors without the need for online submission. Also in local testing you get access to the full stack trace and much faster feedback. This can save you a lot of time debugging. Please make use of it as much as possible.

Enhance your agent with your offline trained modelfile

Suppose your model directory looks like this, where modelfile resides next to the inside the model folder

├── model
    └── modelfile

You can use code like below to load the modelfile into your agent

import os
MODEL_PATH = os.path.join(
    os.path.dirname(os.path.abspath(__file__)), 'modelfile')
class Agent(object):
  def __init__(self):
  def _load(self, modelpath):
    """ Implement your model loading routine """

Debug using the error messages

We currently do not provide stack trace for security reasons. We do provide error messages with error types defined for each case involving the Agent:

  • InitAgentError when there are exceptions from Agent.__init__
  • DispatchAgentError when there are exceptions from Agent.dispatch
  • RepositionAgentError when there are exceptions from Agent.reposition


The submission template for the Learning to Dispatch and Reposition Competition @ KDD2020.






No releases published


No packages published