Velosim Release 2 User Manual
Revision Date: January 20, 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 © 2025 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
],
"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. Drivers are represented by the black car icons, and the stations are represented by the red BIXI station icons. Numbers above a station represent that station’s task count.
You can select a driver on the map to manage its assigned tasks. When a driver is selected, it is highlighted in yellow. Tasks can then 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.
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.
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.
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! Please fill out the release 2 feedback survey available here: https://forms.gle/Kv5n3FgYdSJYDrLe7. 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.