Velosim Release 2 User Manual
Revision Date: January 26, 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.
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 and creating custom scenarios. This documentation applies to Release 2 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, menu navigation, API capabilities, and user management.
- Tips and Best Practices: Guidance on creating valid scenarios and running simulations.
- User Feedback and Troubleshooting: How to report issues, ask questions, and provide feedback to help improve the platform.
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.
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.
- User Management Page: You can access and manage the list of user accounts through this page.
- Scenario Title: You can enter or view a scenario title in this field.
- Scenario JSON: This field holds the json configuration of a scenario. You can add a scenario json here or view an existing one.
- 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.
- Export button: This button allows you to export the scenario JSON to an external file for sharing the scenario with others.
- 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.
- 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.
- New button: This button will allow you to create a new scenario. It provides a template within each field for support.
- 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.
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.
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.
The Scenario Editor is used to create, save, load, and export simulation setups, including stations, drivers, vehicles, tasks, 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:12:00",
"lunch_break": "day1:15:00"
}
}
],
"vehicles": [
{
"name": "Vehicle 1",
"position": [
-73.561,
45.507
],
"battery_count": 2
},
{
"name": "Vehicle 2",
"position": [
-73.57314,
45.50137
],
"battery_count": 30
}
],
"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
}
]
}
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 starting at specific longitude-latitude positions and containing 2 and 30 batteries respectively.
- 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.
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.
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.
- Headquarters where drivers go to restock on batteries and end their shifts.
- Day and time of the simulation which gets updated as time goes on.
- Current speed of the simulation which is defaulted to 1x. You can speed up or slow down the simulation with this option.
- Pause/Play button for the simulation.
- Resources bar containing the list of available drivers and the battery count of their vehicle.
- BIXI station icons. Numbers above them represent that station's task count.
- Available driver icons.
- Vehicles and drivers currently at HQ. This shows the list of drivers which are not on shift yet and when they will be.
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. As shown in the second image below, its full route 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.
- Search Bar: Locate and assign tasks by selecting them from the search results.
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. 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 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.
Menus are readily available to locate a station, a task, or a field agent. As shown in figures from the section above, you can see the list of available drivers and stations for a simulation, as well as each one’s respective tasks. For simulations with lots of drivers or stations, use the Search bar on the right of the page to quickly filter through items.
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.
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
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.
- Verify that your JSON syntax has the required commas, brackets, and quotes.
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.
We highly value user feedback to help shape the product’s future development! If you have any miscellaneous questions about VeloSim software, please send an email to: d_carcie@live.concordia.ca. We’ll reply to your inquiries at the earliest possible time.