VeloSim Release 3 User Manual

VeloSim Release 3 User Manual

Revision Date: April 12, 2026

Authors: Sumer Abd Alla, David Carciente, Thomas Mahut, Vinisha Manek, Ambrose McLaughlin, Christopher Mezzacappa, Michael Mezzacappa, Nirav Patel, Jutipong Puntuleng, Brian Tkatch, Giuliano Verdone

VeloSim Team. Copyright © 2026 VeloSim Team. All rights reserved. Licensed under the MIT License.

Introduction

Welcome to VeloSim, an open-source network simulation platform designed to help users manage distributed resources in dynamic environments. Below you will find step-by-step guidance on using the system’s features, from running simulations and dispatching drivers to managing tasks, using different pages and creating custom scenarios. This documentation applies to Release 3 of VeloSim. It is structured to help both new and experienced users understand the following:

• Getting Started: Walkthroughs for first-time setup, system navigation, and session management.
• System Features and Functionality: Detailed explanations of scenario management, the dispatch simulator, the simulations page, the traffic template page, API capabilities, and user management.
• Tips and Best Practices: Guidance on creating valid scenarios and running simulations.

Getting Started

First-Time Setup

Before getting started with VeloSim, please consult our User consent and End‐User license agreement. Prior to accessing VeloSim’s main system features, speak to a system administrator to create your user account. Once your credentials have been issued, you can log into the platform to access the system. Certain pages of the website remain publicly accessible without an account, such as the diversity statement.

System Navigation Overview

After successfully logging in, you will be directed to the website’s main homepage, featuring the Scenario Editor as the main workspace. You can use this workspace to view, create, and modify existing scenarios. When you’re ready to run a simulation with the provided scenario, use the “Start Simulation” button located towards the bottom right of the Scenario Editor page.

Features Overview

1. User Management Page: You can access and manage the list of user accounts through this page.
2. Simulations Page: This page lets you see all previously run simulations with their report summary and completion percentage, as well as allow you to resume a simulation.
3. Scenario Editor Page: The current page and website's main homepage.
4. Scenario Title: You can enter or view a scenario title in this field.
5. Scenario JSON: This field holds the json configuration of a scenario. You can add a scenario json here or view an existing one.
6. Edit/Save button: When a scenario is selected, clicking the ‘Edit’ button will allow you to modify the scenario and the button will then turn to ‘Save’ to save the scenario.
7. Export button: This button allows you to export the scenario JSON to an external file for sharing the scenario with others.
8. Start Simulation button: This button will start the simulation with the provided scenario configuration as long as they are valid. Otherwise, a message will be shown to notify about the invalidity.
9. Import button: By selecting this button, you will be asked to select a scenario JSON external file to import into its contents to reuse a shared and already created scenario.
10. New button: This button will allow you to create a new scenario. It provides a template within each field for support.
11. Saved Scenarios: This section provides a list of previously saved scenarios. Selecting one of them will automatically fill out the scenario fields, such that you can directly run it.
12. Traffic Templates: This page lets you manage traffic CSV templates used by scenarios, including importing, editing, downloading, and deleting templates.
13. Account settings: the settings allow you to change the current account's password or access the user preferences where you can change the application's language.

If you are logged in with a standard user account, you can begin working directly within this interface. Administrators have full access to all features described above, plus additional tools for system management. For more details on administrative capabilities, see the System Features and Functionality section.

Logging Out and Session Management

The avatar icon located at the bottom left of the sidebar provides access to user options, including Log Out. Login sessions are valid for one hour. Upon session expiration, users are prompted to re-authenticate and are redirected to the most recently accessed page.

System Features and Functionality

Scenario Management

The Scenario Editor is used to create, save, load, and export simulation setups, including stations, drivers, vehicles, tasks, traffic and time windows. See the Glossary for details on simulation entities. To get started, define your scenario using the following JSON format:

{
  "start_time": "day1:08:00",
  "end_time": "day1:19:00",
  "vehicle_battery_capacity": 50,
  "drivers": [
    {
      "name": "Driver 1",
      "shift": {
        "end_time": "day1:17:00",
        "start_time": "day1:08:00",
        "lunch_break": "day1:12:00"
      }
    },
    {
      "name": "Driver 2",
      "shift": {
        "end_time": "day1:19:00",
        "start_time": "day1:10:00",
        "lunch_break": "day1:15:00"
      }
    }
  ],
  "vehicles": [
    {
      "name": "Vehicle 1",
      "position": [
        -73.561,
        45.507
      ],
      "battery_count": 30
    },
    {
      "name": "Vehicle 2",
      "battery_count": 2
    }
  ],
  "stations": [
    {
      "name": "Station 1",
      "position": [
        -73.57314,
        45.50137
      ],
      "scheduled_tasks": [
        "day1:09:00"
      ],
      "initial_task_count": 1
    },
    {
      "name": "Station 2",
      "position": [
        -73.57314,
        45.50137
      ],
      "scheduled_tasks": [],
      "initial_task_count": 2
    }
  ],
  "traffic": {
      "traffic_level": "low_congestion",
      "global": [
          {
              "multiplier": 0.5,
              "start_time": "day1:08:00",
              "end_time": "day1:10:00"
          },
          {
              "multiplier": 0.7,
              "start_time": "day1:11:00",
              "end_time": "day1:12:00"
          }
      ]
    }
}

The example provided above includes:

• The Start and End Times which are set to "day1:08:00" to "day1:19:00" respectively. This example spans within a single day.
• The vehicle battery capacity which sets a maximum of 50 batteries per vehicle.
• Two drivers with their own shift times and lunch breaks.
• Two vehicles containing 30 and 2 batteries respectively. The first vehicle starts at specific longitude-latitude position while the second will be located at HQ since it has no provided position.
• Two stations with names, longitude-latitude positions, initial task counts and an optional scheduled task list.
  • The first station's scheduled task will appear 3600 seconds (1 hour) after the simulation starts.
• Traffic with traffic_level set to low congestion levels.
• Two global traffic schedules at different times with multipliers of 0.5 and 0.7.

To know whether your input parameters are valid, you can click “New” on the Scenario Editor page, add the scenario contents, and finally click “Save” at the bottom of the page. This will attempt to save the scenario contents. If something is invalid, a clear error message will appear to help you identify and fix the issue before saving again. Finally, you can load saved scenarios or export them to share with others. This is especially useful if you’d like to share your JSON configurations with other dispatchers or trainees to test out a simulation instance.

Dispatch Simulator

The main simulation page consists of a map-based monitoring system. After loading data to start a simulation instance, a collection of stations, tasks, and drivers will appear on the map. Each of these items can be interacted with to carry out different outcomes from the initial scenario provided. The picture below shows an example of the main simulation page.

Key Items:

1. Headquarters where drivers go to restock on batteries and end their shifts.
2. Day and time of the simulation which gets updated as time goes on.
3. Current speed of the simulation which is defaulted to 1x. You can speed up or slow down the simulation with this option.
4. Pause/Play button for the simulation.
5. Resources bar containing the list of available drivers, their current state and the battery count of their vehicle.
6. BIXI stations. Numbers represent that station's task count.
7. Available driver icons showing the direction they are heading. Their color represents their current state.
8. Vehicles and drivers currently at HQ. This shows the list of drivers which are not on shift yet and when they will be.
9. Live report of 5 different metrics. The full metric descriptions can be viewed on hover.
10. Cluster of multiple stations. When zoomed out, stations close together are grouped under a cluster. The number represents the total amount of tasks for all stations under it.

You can select a driver on the map to manage its assigned tasks. When a driver is selected, it is highlighted in yellow and its name is circled within the Resources bar. The tasks assigned to this driver are displayed. By default, tasks are displayed grouped by station. By toggling the button indicated in the picture below, you can switch between this view and the task view which shows the full list of tasks.

As shown in the second image below, when a driver is selected, its full route with traffic states is displayed towards all its tasks. Drivers will make their full trip to their assigned task’s station. If a driver does not have any tasks assigned, it will remain idle on the map until it is assigned something.

Tasks can be assigned, reassigned, and unassigned in several ways:

• Drag-and-Drop: Drag tasks between drivers or from its task list onto a driver to assign or reassign them.
• “X” Icon: Pictured in the second image below, in a Driver’s task list, click this icon to remove (unassign) a task from the currently selected driver.

Multiple tasks can be selected and assigned at the same time using different methods:

• Ctrl+click: In a task list, by holding the ctrl key and clicking on different tasks, multiple tasks will be selected and you can drag and drop them to assign them to a driver.
• Shift+click: Similarly, by holding the shift key and clicking on different tasks, multiple tasks will be selected and can be assigned to a driver.
• RMB and drag: In a task list, by holding the right mouse button and dragging it around multiple tasks, they will be selected and assignable to a driver.
• Drag-and-Drop a Station: By dragging a station and dropping it on a driver, all tasks at that station will be assigned to the driver.
  • Multiple stations can be selected through Ctrl+click or RMB-and-drag to assign tasks from all of them simultaneously.
• Drag-and-Drop a Cluster: By dragging a cluster and dropping it on a driver, all tasks from all stations within it will be assigned to the driver.

You can also re-order tasks in a driver's task queue to prioritize one from others. This can be done by dragging a task from the driver's task list and dropping it at the desired location in the list. Note: You cannot re-order a task currently being serviced.

---

When a driver arrives at a task's station, it services the task and executes a battery swap. As a result, the vehicle's battery count decreases by one as a battery was used for swapping. When the vehicle runs out of battery, the driver heads directly to HQ to restock on batteries as shown in the image below. It takes 20 minutes to fully restock on batteries.

---

When it is time for a driver to start their shift, they will spawn at HQ as long as a vehicle is available. The driver's name will appear in the Resources bar and you will be able to assign tasks to them through their vehicle icon or name. If they start with a vehicle which is not at full capacity, they will first start restocking on batteries till full. Once their shift ends, the driver will head back to HQ to end their shift and release all tasks that were assigned to them.

---

Similarly to drivers, selecting a station highlights it on the map and displays the tasks associated with that station. From this view, you can inspect task details and monitor activity related to that specific station. A bordering circle around a station number shows that it has tasks assigned to a driver.

---

When hovering over the live report metrics at the bottom right of the page, the block expands to show the full description of each metric. This provides statistics on the simulation is going.

A simulation stops when it has reached its end time based on the originally provided input parameters. Once you’ve received confirmation that a simulation has ended, you can navigate to another page on the VeloSim website.

User Management and User Profile

User management is exclusive to administrator users. In addition to viewing a list of all users and filtering by username, administrators can handle accounts across the system. User management includes changing any user’s password, their account status, and their administrator privileges. To create a new user account with all of its attributes, select the “New user” button which opens a form dialog. To manage an existing user account, select the ellipsis “...” menu’s icon next to that user’s account. Clicking anywhere else on the page outside closes this menu.

Default and administrator users can view their avatar and profile at the bottom-left of the website’s sidebar. Clicking this menu opens two options: “Change password” and “Log out”. Clicking anywhere else on the page outside closes this menu

Simulations Page

The simulations page provides a list of all previously run simulations in a table format. It gives details on each simulation, such as its completion percentage and report summary. While the Preview button opens a small window with details on the report, the Download button downloads it as a csv file. The simulation can be resumed by selecting the Resume button. This will open the simulation page and start it where you had last left it.

Traffic Templates Page

In this page, a list of available traffic templates is shown. The four preset templates "default", "low_congestion", "medium_congestion" and "high_congestion" are given by default. Templates are csv files containing traffic data. You can add a template by selecting the Import Template button. Templates can be edited, downloaded or deleted by selecting the "..." next to one of them.

When configuring a scenario with traffic, the traffic_level field will use one of these templates. A template will be identified by its key. As a result, make sure that the template key is easy to use and remember.

API Capabilities

As part of version 1.0.0 (v1) of the VeloSim Backend API, a set of endpoints are available for accessing current system services. This mechanism uses standard HTTP authentication and the data exchange format is JSON. The following endpoints are currently available:

• /api/token: Handles user authentication and token retrieval. All other routes require a valid access token.
• /simulation: Manages simulation operations, including starting, stopping, and controlling simulation playback and task distribution.
• /users: Provides user-related functionality such as profile retrieval and administrative account management (see User Management and User Profile).
• /logs: Receives and stores log data from clients and browsers, including error reports and feature metrics, for analysis in Grafana/Loki.
• /scenarios: Supports scenario management, including retrieving scenario templates and validating scenario configurations (see Scenario Management). For detailed endpoint specification including parameters, request/response formats, and status codes, kindly refer to the OpenAPI documentation.

Tips and Best Practices

Creating a Valid Scenario

In addition to the tips listed under the “Scenario Management” sub-section, more details are listed below:

• Assign each driver a unique starting position.
• Ensure driver shifts end after its start time and lunch breaks are during the shift.
• Assign each station a descriptive name.
• Use valid longitude-latitude coordinates for all positions.
• Determine initial and scheduled tasks (start of simulation and later, respectively).
• Ensure scheduled task times fall within the simulation window.
• Ensure vehicles have a battery count smaller or equal to the vehicle battery capacity you defined.
• Ensure global traffic schedules do not overlap each other.
• Ensure each global traffic schedules end after its start time.
• Verify that your JSON syntax has the required commas, brackets, and quotes.

Running Simulations

Please note that while the system technically allows users to start more than one simulation at a time, we strongly encourage you not to run an excessive amount of simulations simultaneously. Running several simulations in parallel can place unnecessary load on shared servers and may impact performance for other users. We ask all users to follow an honours system, run one simulation at a time and close any sessions you’re no longer using. This helps ensure that everyone can enjoy a smooth and responsive experience.