(1) Overview
Introduction
When solving real-world logistic problems, it is essential to have a large dataset of realistic instances that capture all relevant features and constraints of the problem in order to validate and compare algorithmic solutions through numerical experiments. For example, in the vehicle routing problem (VRP) literature, most studied problems are theoretical VRP variants that are tested on synthetic datasets. These datasets usually assume Euclidean distances and may not be very useful beyond the scientific community (1). In this sense, it is of high importance to have benchmark instances that reflect real-world operational settings.
Benchmark instances for VRPs that incorporate real-life attributes are often either randomly generated, provided by companies, or are adaptations of other specific variants (2). Recent works have made progress toward instance-generation tools for simulating realistic transportation scenarios (3, 4). In these works, realism may be expressed in the representation of the transportation network or in the modeling of demand. For example, the REQreate tool (3) generates instances for on-demand transportation problems, such as dial-a-ride problems, and creates real-life networks of urban areas using the OSMnx Python package. EVRPGen (4) is an instance generator for electric vehicle routing problems that also uses OSMnx to create urban networks. The framework of Urra, Ramírez, and Castro (5) infers a realistic demand distribution for urban transit routing instances from demand information collected in the Santiago metropolitan area. In contrast, long-haul transportation problems have their own distinct requirements. For example, trips may last multiple days (6) and typically involve the movement of large quantities of goods. The transportation of bulk commodities, including grains, oil, gas, and fuel, is an example of such applications. To the best of our knowledge, there is no instance generator for long-haul problems that tries to mimic real-world situations.
Aiming to address this gap, we developed BigVRSP, a tool that supports the generation of test instances for benchmarking long-haul vehicle routing and scheduling problems involving heavy freight transportation. The tool is designed to assist the transportation planning processes of both industry practitioners and researchers, and it creates new instances based on historical data from previous transportation records. The optimization problem that motivated the development of the software originates from a fuel distribution supply chain of a large transportation company in Brazil. The problem consists of moving different refined products, such as ethanol and biodiesel, among refineries and fuel storage terminals.
The core idea of BigVRSP is to generate instances based on historical structured data of the company’s specific problem. These data are used to extract parameters and infer instances that simulate real-world operations. The instance generator uses data from two primary sources to create instances: the available truck fleet and historical trip records. For example, the user provides a CSV file describing key fleet characteristics, such as average fuel consumption, average speed, and vehicle capacity, and a CSV file containing previously performed trips with their origin-destination pairs and other relevant information, such as demand. Based on this information, BigVRSP can generate benchmark instances with demands, distances, costs, and vehicle and client positions. If the user does not have available data for their problem, BigVRSP can also generate artificial input data files to serve as a basis for generating instances. The generation of these files can be customized by defining a set of input parameters through the command-line interface (CLI). The final instance is composed of two CSV files, one containing relevant information about the fleet of trucks, and the other a set of requests with pickup and delivery locations and other relevant features, such as time windows and demand.
The tool EVRPGen is similar to ours in the sense that it allows users to specify parameters for the instance generation. However, in contrast to this and other related works, the BigVRSP generator does not provide a road network with real distance matrices. Instead, BigVRSP uses approximate estimations through geodesic distances. In both scenarios, the Euclidean distance will result in shorter distances. The tool can generate a file with the distance matrix, if needed.
Problem description
The motivating problem shares the attributes of several VRP variants. It can be classified as a pickup and delivery problem (PDP) (7, 8), particularly a full-truckload (FTL) problem with paired pickup and delivery locations. Combining FTL with paired locations implies that no other customer can be visited between a pickup and its associated delivery location during the transportation of the corresponding load. In our case study, pickup locations are refinery locations, while delivery locations are fuel storage terminals.
There are n requests, or fuel transportation orders, and a heterogeneous fleet of m tanker trucks with different capacities that are situated at different locations (truck yards, resting locations, etc). The problem consists of assigning sequences of customer requests to the available trucks over a planning horizon. Each request is associated with a pickup and delivery location, a demand for a certain type of fuel commodity, a revenue (price) per unit of the commodity, an availability time window in which the request can be served, and a time window for pickup and one for delivery, indicating the working hours at the refinery and storage terminal, respectively. A similar problem to ours is the log-truck scheduling problem (LTSP) (9), where transportation orders of round timber between paired pickup and delivery locations are sequenced among the vehicles, and all transports are carried out as FTL.
In our real-world case study, the fuel demand of a request usually exceeds the truck capacity, turning our problem into a split-delivery PDP. This scenario is also present in LTSP problems (10). In Figures 1 and 2, we present a small example of an instance and its parameters to illustrate our problem. Green marks represent pickup locations while red marks represent delivery locations. Each line connecting a location pair represents a request or transportation order. The truck marks on the map represent the tanker trucks.
Figure 1
Conceptual formulation of an instance.
Figure 2
Conceptual formulation of instance parameters for a request and a truck.
The described problem is considered a multi-attribute (11), or a so-called rich VRP variant. An instance is made of a list of requests and a set of vehicles, and a solution consists of assigning requests to vehicles located at different positions. In practice, however, operations are continuous, and assignment planning occurs dynamically, considering only the vehicles available at that moment. Accordingly, the generated instances contain the information necessary to represent such attributes. In this sense, a request must have the following parameters:
A demand for a fuel commodity
A variability rate of acceptance that allows more or less demand to be delivered
An availability time period in which the request can be served
A pickup and a delivery time window
A revenue per unit of the fuel commodity
In our instance, a driver and a vehicle are considered a single entity. To represent each vehicle’s characteristics, we consider parameters describing capacity, truck weight, average speed, and fuel consumption when traveling fully loaded or unloaded.
To manage the fleet of vehicles and drivers, we include information that indicates the vehicle’s initial position, ensure that truck maintenance can be scheduled, and guarantee that drivers operate within the working limitations imposed by law. For this purpose, we include parameters to track the working days and hours of activity, schedule maintenance dates, and record the total distance driven. Finally, a parameter indicating the revenue generated by each vehicle is included.
Implementation and architecture
The open-source repository BigVRSP is structured as a set of Python scripts that generate data files in CSV format. To generate the instances, the user may provide four historical data files in CSV format, which is a distinct and innovative feature of our tool. If the user does not have these data, they can be generated using the input data generation scripts provided in the repository. The instance generation process is configurable through CLI arguments; the user must adjust these arguments in order to output instance files that better represent the intended problem. The final output instance consists of two CSV files. An optional file containing the geodesic distance matrix between pickup, delivery, and truck locations can also be generated.
The scripts in BigVRSP were designed using a modular architecture so that the user can make use of all or specific features and generators individually. The complete technical documentation concerning instance parameters, CLI arguments, and file descriptions is available in the API documentation on GitLab (cf. Availability section). Figure 3 illustrates the architecture of BigVRSP.
Figure 3
Flow chart of instance generation of BigVRSP.
Input data structure
Four input data files are required to generate the final instance. These files can be provided by the user or generated artificially using the three scripts provided in the repository. The inputTruckTypes.csv file represents a catalog of truck types with their features. Each line corresponds to a different truck with its specific characteristics. The file format is presented in Table 1.
Table 1
Data format for inputTruckTypes.csv.
| Field | Type | Description |
|---|---|---|
| truck_type_id | str | Vehicle type identifier |
| truck_weight | int | Weight of the unloaded truck |
| truck_capacity | int | Maximum cargo capacity |
| average_unloaded_speed | float | Average speed when unloaded |
| average_loaded_speed | float | Average speed when fully loaded |
| average_unloaded_fuel_efficiency | float | Fuel efficiency when unloaded |
| average_loaded_fuel_efficiency | float | Fuel efficiency when fully loaded |
| probability | float | Selection probability in final instance |
The inputTripPositions.csv file represents a historical registry of trips/requests that will be the pickup and delivery locations that the instance generator can choose from. In our motivational problem, trucks are located in distinct sites at the beginning of the planning (cf. Problem description section). Due to this requirement, the inputTruckPositions.csv file contains the initial vehicle positions. The file formats are presented in Tables 2 and 3, respectively.
Table 2
Data format for inputTripPositions.csv.
| Field | Type | Description |
|---|---|---|
| origin | str | City name of the origin location |
| origin_latitude | float | Latitude coordinate of the origin |
| origin_longitude | float | Longitude coordinate of the origin |
| destination | str | City name of the destination location |
| destination_latitude | float | Latitude coordinate of the destination |
| destination_longitude | float | Longitude coordinate of the destination |
| probability | float | Probability of choosing this position |
Table 3
Data format for inputTruckPositions.csv.
| Field | Type | Description |
|---|---|---|
| location | str | City name of the truck position |
| latitude | float | Latitude coordinate of the truck |
| longitude | float | Longitude coordinate of the truck |
| probability | float | Probability of choosing this position |
Finally, the inputItems.csv file provides a list of possible items (e.g., ethanol, biodiesel) to be demanded in the final instance requests. The file format is presented in Table 4.
Table 4
Data format for inputItems.csv.
| Field | Type | Description |
|---|---|---|
| item | str | Item’s name or identifier |
| probability | float | Probability of choosing the item |
Each input file has a probability field, which is used by the instance generation scripts to sample data. The values for each record in these files are expected to be provided by the user, but can be artificially generated when the input data generation scripts are used.
Artificial input data generation
The input files previously described can be generated using three Python scripts. The data present in each file are generated based on CLI parameters. Below, we describe the generation process of each script:
truckTypesGenerator.py: Generates the inputTruckTypes.csv file. For each truck record, the weight, capacity, speed, and fuel efficiency attributes shown in Table 1 are uniformly sampled from intervals defined by minimum and maximum bounds specified through CLI arguments (e.g., --min_truck_capacity and --max_truck_ capacity).
positionsGenerator.py: Generates the inputTripPositions.csv and inputTruck Positions.csv files. Pickup and delivery locations, as well as truck positions, are selected using the geonamescache Python library. The script allows the selection of locations from any geographic location and based on population size, provided that the locations are supported by the geonamescache library.
itemsGenerator.py: Generates the file inputItems.csv.
When data are artificially generated, the probability field values are randomly sampled from a uniform distribution and then normalized so that their sum is exactly one. This procedure is implemented in a core module (src/core.py) containing functions that are reused across all scripts. Additionally, the script that generates inputTripPositions.csv allows the user to provide a custom function to assign probabilities for each trip, making it possible to control how likely a city is to be selected based on population size and distance. The API documentation contains details on how to provide the function.
Output structure
The two output files generated by BigVRSP are trucks.csv and jobs.csv. These files represent a complete instance for truck assignment and pickup and delivery problems. The distance matrix file (distanceMatrixGenerator.py) can be generated once the instances have been created.
To generate both the trucks.csv and jobs.csv files, the scripts trucksGenerator.py and jobsGenerator.py must be executed, respectively. The trucks.csv file contains the available truck fleet and its features, such as truck characteristics, current positions, and request assignments. The jobs.csv file represents a list of requests made by customers that take place in the planning horizon. The file formats are presented in Tables 5 and 6, respectively.
Table 5
Data format for trucks.csv.
| Field | Type | Description |
|---|---|---|
| truck_id | str | Vehicle identifier |
| truck_latitude | float | Truck’s current latitude position |
| truck_longitude | float | Truck’s current longitude position |
| destination | str | Parked or city name of the assigned destination |
| destination_latitude | float | Destination’s latitude |
| destination_longitude | float | Destination’s longitude |
| next_scheduled_maintenance | str | Date of the next scheduled maintenance (DD/MM/YYYY) |
| maintenance_days | int | Amount of days to complete the maintenance |
| truck_type_id | str | Identifier for the specific truck type |
| truck_capacity | float | Maximum cargo capacity |
| average_unloaded_speed | float | Average speed when empty |
| average_loaded_speed | float | Average speed when fully loaded |
| average_unloaded_fuel_efficiency | float | Fuel efficiency when empty |
| average_loaded_fuel_efficiency | float | Fuel efficiency when fully loaded |
| driven_kilometers | float | Truck’s driven kilometers quantity |
| current_month_revenue | float | Current month’s revenue from truck |
| current_month_work_hours | float | Current amount of hours worked by the driver |
| current_day_work_hours | float | Amount of worked hours in current day |
| current_week_work_days | float | Amount of worked days in current week |
Table 6
Data format for jobs.csv.
| Field | Type | Description |
|---|---|---|
| customer_id | str | Unique identifier for the customer or order |
| job_id | str | Unique identifier for the request |
| origin_name | str | City name of the pickup location |
| origin_latitude | float | Latitude of the pickup location |
| origin_longitude | float | Longitude of the pickup location |
| destination_name | str | City name of the delivery location |
| destination_latitude | float | Latitude of the delivery location |
| destination_longitude | float | Longitude of the delivery location |
| demand | int | Total required quantity of the item |
| serviced_demand | int | Current quantity of the item already delivered |
| item | str | Demanded item identifier |
| price_per_item | float | Value of a single unit of the item |
| min_demand_variation | float | Minimum acceptable variation in attended demand |
| max_demand_variation | float | Maximum acceptable variation in attended demand |
| has_own_valet | bool | Indicates if the customer has their own valet staff |
| pickup_start_date | str | First date available for pickup (DD/MM/YYYY) |
| delivery_deadline_date | str | Final date allowed for delivery (DD/MM/YYYY) |
| pickup_start | str | Earliest time of day for pickup |
| pickup_end | str | Latest time of day for pickup |
| delivery_start | str | Earliest time of day for delivery |
| delivery_end | str | Latest time of day for delivery |
Instance generation methodology
The final instances are composed of entries, each corresponding to a record from the input files augmented with new fields. The instance generation process follows a common logic based on two procedures: sampling records from the input files and generating new fields through CLI parameters. In the first procedure, entries for the final instances are sampled according to the values of the probability field in the input files. For this purpose, we use the Python random library and the random.choices method to select records based on their assigned probabilities.
The second procedure is responsible for generating fields that are not present in the input files but are relevant to the studied optimization problem (cf. Problem description). These fields are generated according to CLI parameters that define how their values are assigned. Most of them are sampled from a uniform distribution within minimum and maximum bounds specified via CLI arguments. For instance, the values of the demand field are sampled from the interval specified by the arguments --min_demand and --max_demand. The user should consult the help documentation of each script to check the available CLI arguments.
Trucks data
The trucks.csv file is generated by the trucksGenerator.py script. This script samples random truck types from inputTruckTypes.csv to represent a fleet of trucks with a size specified by the user. The attributes from the selected truck types are included in the trucks.csv file, within the new generated fields, as shown in Table 5. Due to the non-stop nature of the operations, at the beginning of the planning horizon, some trucks in the fleet may be available, while others may already be assigned to existing requests. The destination field indicates this status. The field may hold a status of ‘parked’ or the delivery location of a request, indicating whether the vehicle is available or assigned to a trip from inputTripPositions.csv. The trucks’ positions are sampled from inputTruckPositions.csv regardless of the destination status. Alternatively, it is possible to configure the generator to assign truck destinations exclusively from jobs.csv instead of inputTripPositions.csv. In this mode, the system ensures truck capacities do not exceed remaining demand at each job location. A threshold value defined by the CLI argument parked_truck_probability is used to probabilistically determine whether the truck is parked or assigned to a trip.
The new fields next_scheduled_maintenance, maintenance_days, and driven_kilometers, are present due to the need to schedule truck maintenance, as demanded by the optimization problem. The fields related to drivers’ working hours, such as current_day_work_hours, are related to legal working constraints and the need to impose limits on driving periods. The field current_month_revenue may be used to balance the revenue generated by each truck driver. By default, these instance parameters are hidden and must be defined through CLI arguments. Furthermore, BigVRSP does not enforce any specific unit of measurement, so the user must relate the units used (e.g., truck capacity and item demand) correctly to ensure consistency across the CSV files.
Jobs data
The jobs.csv file is generated by the jobsGenerator.py script. This script defines what is being requested and where it takes place by sampling records from the inputItems.csv and inputTripPositions.csv files. New fields are relevant attributes of the requests related to the optimization problem, and are shown in Table 6. The fields has_own_valet and serviced_demand are determined using threshold values (valet_probability and partial_service_ probability arguments) to probabilistically decide whether a terminal has a truck yard operator and whether a parcel of a requested demand has already been delivered. In our problem, the presence of a truck yard operator influences the loading or unloading time at refineries or terminal locations, and the demand is usually larger than truck capacity. The demand variation fields specify the minimum and maximum percentage of deviation allowed with respect to the requested demand.
Time windows within the time of the day for loading and unloading at pickup and delivery sites, as well as start and deadline dates for requests, are also generated. The logic for generating request dates works as follows:
pickup_start_date = datetime.today() + timedelta(days=random_extra_days_pickup) delivery_deadline_date = pickup_start_date + timedelta(days=travel_time_days + random_extra_days_delivery)
The variable random_extra_days_pickup is sampled from the minimum and maximum pickup days defined via CLI arguments (the same logic applies to random_extra_days_delivery). The variable travel_time_days is computed based on the distance between pickup and delivery locations and the average truck speed. The user is expected to adapt the generator scripts’ parameters to produce more accurate instances for the problem at hand. This flexibility allows the user to control the levels of realism and complexity of the generated instances.
Quality control
The quality of BigVRSP is ensured through a series of unit tests implemented using the pytest library and internal validation checks in the data generation scripts to handle edge cases. The validation checks are implemented in the main generator scripts jobsGenerator.py and trucksGenerator.py. These include:
Consistency checks to verify if lower bounds do not exceed upper bounds for parameters that require these bounds (e.g., --min_demand, --max_demand)
Domain checks to verify if parameters lie within the admissible interval (e.g., parameters constrained to the interval [0,1])
Whenever a check fails, instance generation is aborted and a descriptive ValueError is raised. The unit tests include negative tests, CSV writing operations, validation of the build process, reproducibility checks using a fixed random seed to guarantee that the same output values are generated across code changes, and additional domain and consistency checks. Users can verify that the package is working properly by running make test, which also reports code coverage. The current test suite contains 29 unit tests and achieves 66% code coverage.
We included a ready-to-run reuse example with input files containing a dataset of real refinery and terminal locations from Raizen,1 one of the largest Brazilian fuel distribution companies. The example is located at _research/example and the output files jobs.csv and trucks.csv are located in the output subdirectory. The example can be rebuilt by running build-example.sh.
To assess the scalability of the generators, we measured the wall time and the output file size of jobsGenerator and trucksGenerator for increasing instance sizes, using a fixed random seed. The results are presented in Table 7. Generation time grows approximately linearly with the number of records, and an instance with 106 requests is generated in less than three minutes on a modest laptop (Apple M1, 8 GB RAM, macOS 15), producing a 159 MB CSV file. This indicates that the tool is suitable for producing arbitrarily large instances for benchmarking and stress testing of solvers. The benchmark can be reproduced by running the benchmark.py script located in _research/example.
Table 7
Generation wall time and output file size per number of records.
| jobsGenerator | trucksGenerator | |||
|---|---|---|---|---|
| Records | Time (s) | Size (Mb) | Time (s) | Size (Mb) |
| 102 | 0.16 | 0.02 | 0.07 | 0.01 |
| 103 | 0.30 | 0.16 | 0.09 | 0.10 |
| 104 | 1.78 | 1.59 | 0.21 | 1.01 |
| 105 | 15.52 | 15.92 | 1.44 | 10.05 |
| 106 | 168.11 | 159.23 | 17.47 | 100.54 |
To demonstrate that the generated instances can be directly consumed by optimization models, the repository includes usage_example.jl. This self-contained Julia script formulates a simplified version of the truck assignment and scheduling problem described in the Problem description section as a mixed-integer linear program (MILP), using the JuMP modeling language. It solves the model with the open-source solver HiGHS, though any other solver supported by JuMP can be used interchangeably. Table 8 reports the results for three small instances generated with a fixed random seed and tight date windows. The solver produces feasible schedules servicing about 95% of the total demand in all cases, with optimality gaps below 1%. Since each request is expanded into one task per feasible pickup and delivery day combination, the model grows quickly, illustrating the difficulty of exact methods on rich VRP variants and reinforcing the usefulness of large synthetic instances for the development of heuristics and learning-based methods.
Table 8
Results of the MILP usage example (usage_example.jl) solved with HiGHS over generated instances (seed 42, 300 s time limit). The columns ‘j’ and ‘t’ are, respectively, the number of jobs and trucks used, while the ‘Tasks’ column is the number of tasks after the expansion of jobs into pickup and delivery day combinations, and ‘Served’ is the fraction of the total demand transported.
| j | t | Tasks | Vars | Consts | Status | Gap | Time (s) | Served |
|---|---|---|---|---|---|---|---|---|
| 4 | 3 | 21 | 1 794 | 4 432 | Optimal | <10-4 | 1.6 | 94.5% |
| 6 | 4 | 27 | 3 712 | 9 534 | Time limit | 0.66% | 300 | 96.2% |
| 8 | 5 | 36 | 7 790 | 20 738 | Time limit | 0.83% | 300 | 95.1% |
(2) Availability
Operating system
Tested: Windows 11,10, UNIX/Linux, macOS
Programming language
Requires Python >= 3.10, tested up to Python version 3.12.
Additional system requirements
No additional hardware requirements are necessary.
Dependencies
BigVRSP depends on geopy and geonamescache Python libraries. The specific version of dependencies can be found in the requirements file in the code repository.
Software location
Archive
Name: Zenodo archive
Persistent identifier: https://doi.org/10.5281/zenodo.21299722
Licence: GNU General Public License v3.
Publisher: André Felipe Zanella
Version published: v1.0.0
Code repository
Name: GitLab
Persistent identifier: https://gitlab.com/dma-uem/bigvrsp/
Licence: GNU General Public License v3.
Date published: 10/02/2026
Language
The repository, software, and supporting files are written in English.
(3) Reuse Potential
Since this instance generator software was originally designed to support the planning of fuel distribution operations for a truck fleet from a logistics transport company in Brazil, the implementation considers all the known operational characteristics of such a company, as well as the continental scale of that country. This motivated the creation of a flexible tool representing the real characteristics of a heterogeneous fleet and large demands emerging from different customers dispersed across different states. Besides the original motivation, the software was made to be general and can be reused in different operations of transport of goods in scenarios of various sizes.
It generates synthetic or data-driven instances based on historical operational data, such as trips, requests, vehicle types, and fuel types. Users can simulate realistic transportation scenarios either by selecting a specific geographic region or by providing their own datasets of historical requests, trips, and vehicles. This flexibility allows the tool to be adapted for various vehicle assignment problems or pickup and delivery applications, where the software can be employed to create benchmark instances that reflect the unique characteristics of different logistics networks.
Beyond these applications, the software can be employed in any research that requires controlled generation of transportation datasets with realistic spatial and operational patterns. For example, researchers working on numerical optimization models, heuristics, both supervised and unsupervised learning or reinforcement learning for logistics can benefit from customizable instances that preserve geographical coherence and heterogeneous fleet characteristics. Even in teaching environments, the tool can also be used to create progressively more complex scenarios for students studying vehicle assignment problems, operations research, or supply chain management.
The modular design of BigVRSP, combined with its standard text input and output, makes it easy to extend and customize. New sampling rules, probability distributions, or even totally new characteristics in the output schema (such as emission factors, driver schedules, or road-network constraints) can be incorporated by modifying only a small subset of scripts in the data-generation stage. Contributors may also introduce new input file specifications or replace the current sampling strategy with more advanced statistical or machine learning models. Concrete starting points for reuse are provided in the repository: a ready-to-run example built from real refinery and terminal locations (_research/example), a script demonstrating the integration of the generated instances with an optimization model (usage_example.jl, cf. Quality control), and a scalability benchmark of the generators (benchmark.py).
External contributions are welcome through the public GitLab repository. Users may open issues, submit merge requests, or contact the maintainers directly via the repository’s communication channels. The development team will continue to monitor the repository and respond to bug reports, although no formal support is provided.
Given its flexibility and extensibility, BigVRSP has the potential to serve as a general use instance generation tool for researchers testing, benchmarking, and sensitivity analyses across a wide range of truck routing and assignment problems, facilitating reproducibility and scalability and enabling fair comparisons of algorithms under realistic operating conditions.
Note
Acknowledgements
We would like to thank Hungaro Transportes for presenting the initial optimization problem that motivated the development of this software.