About VRP-REP

What exactly is VRP-REP?
VRP-REP is an open data platform for sharing benchmark instances and solutions to vehicle routing problem.

How do I cite VRP-REP on my research
You can give credit to the people running the platform by citing the following reference in your research:

J.E. Mendoza, C. Guéret, M. Hoskins, H. Lobit, V. Pillac, T. Vidal, D. Vigo. VRP-REP: the vehicle routing community repository. Third meeting of the EURO Working Group on Vehicle Routing and Logistics Optimization (VeRoLog). Oslo, Norway. 2014.

VRP-REP instance specification

What is the VRP-REP instance specification?
The VRP-REP instance specification is a set of rules to format VRP instances using xml. Technically speaking, the specification is an XML schema (a .xsd file) defining the building blocks of an XML language specifically conceived for VRP data.

You can download the VRP-REP instance specification from the resources page.

Can I write instance files for any imaginable VRP variant using the VRP-REP specification?
Not really. The specification was written by the VRP-REP team, using input from several researchers in the field, with one purpose: providing a universal data format able to model the “most common” VRP features. As it stands, you should be able to write instances for “rich” variants considering a number of features, but not necessarily for any imaginable problem variant.

If I want to contribute my instances to the VRP-REP platform, am I obliged to write my files using the VRP-REP instance specification?
The VRP-REP instance specification is just a recommendation. You can contribute instances in other formats as well (e.g., TSPLIB).

Then why should I go through the trouble of doing it?
Three main reasons: your instances are more readable and understandable to humans, you save people who want to use your data a lot of coding because they can reuse the code for instance reading and writing stored in the GitHub repository, and you get the “VRP-REP compliant” badge on your datasets (which shows that you’re an active part of the VRP-REP community). You’re right, these may seem like small rewards for your trouble, especially if you have to learn a bit of XML or you are not an expert Java developer. We believe, however, that formatting your instances using the specification is a worthy effort. The VRP-REP project is growing fast, and cool and exciting new features are coming in the near future; some of these features are reserved for VRP-REP compliant data.

Can I contribute to the VRP-REP instance specification?
Definitely! You’re actually encouraged to do so. If you think there is an important feature that cannot be addressed using the current version of the specification, you’re welcome to submit to the steering committee a proposal for a new version of the specification. However, changing the specification is a big deal (for reasons you will understand later), so there should be a good reason to do it. Please follow the the procedure below:

1. Be absolutely sure that the extension is needed: check the tutorials, the forum, download VRP-REP compliant instances for related problem variants, and make sure that the current specification cannot address the VRP feature you want to include in your instances.
2. Download the latest version of the specification from the VRP-REP GitHub site (project model)
3. Do your modifications locally (make sure you document the elements you add to the schema)
4. Download a “large-enough” number of VRP-REP compliant instances and test that your proposed version of the specification is backwards-compatible. “Large-enough” is a fuzzy concept, but here is a hint: the larger the number of backward-compatible instances, the greater the probability that your proposal is accepted.
5. Log in to the platform, go to the contribute menu and choose instance specification. Fill out and submit the form. Please be crystal clear in the description part of the form. Let the committee know why you are proposing the extension, what are the changes you introduced, if the proposed specification is 100% backwards compatible with existing instances, which problem variants will benefit from the extension, etc.

The committee will get in contact with you to work out together on your proposal.

I want to use the VRP-REP instance specification to format my data, but I don’t know how to model one or more of my VRP features. What can I do?
The VRP-REP community is there to give you a hand with that. Try this:

1. Download (VRP-REP specification compliant) instances for problem variants that are closely related to your problem and used them as template.
2. Download the pdf tutorial (you will find it on the resources page) and give it a read.
3. If you could not find what you’re looking for, go to the forum and post a question.
4. If none of the above works, send an email to the steering committee, they will be glad to try to help you.

Instances

What is a dataset?
A dataset is simply a set of instances. A dataset contains: one file for each instance of the dataset, and one readme.txt file explaining the format of the instance files.

What is the dataset alias?
The alias of a dataset is the quick reference name of the dataset in the VRP-REP platform. By default, the alias is built using the information of the reference in which the dataset was proposed (see bellow What is a reference?). The default alias is built as follows:

• author year if the reference was single authored
• first_author_last_name and second_author_last_name year if the reference was coauthored by two authors
• first_author_last_name et al. year if the reference was coauthored by more than two authors

When a user contributes more than one dataset proposed in the same reference, the system assigns a default alias as follows:

• default_alias - Set #

where # is the upload order of the dataset (e.g., Set 1, Set 2, Set 3).

When contributing a dataset, a user can choose to set a non-default alias for the dataset.

The owner of a dataset can change its alias at anytime to reflect changes in the reference proposing the dataset. Imagine you contributed a dataset in 2015 after completing a paper and submitting it to a journal. For simplicity assume that you authored the paper alone. The default alias for your dataset would be “your_last_name 2015”. Now imagine that after a couple of review rounds, the production process, and slowly moving to the top of paper queue in the journal, your paper is finally published in 2017. Then you can simply update the alias to “author 2017”. You can, and should, also update the reference to reflect the new status of your paper (see more in What is a reference?).

What is the VRP-REP-ID of a dataset? The VRP-REP-ID of a dataset is a unique identifier automatically assigned to a dataset when it is contributed. Contrary to the alias, the VRP-REP-ID cannot be changed. In other words, the VRP-REP-ID provides a permanent reference to your datasets. The latter becomes handy when referencing datasets in publications. Imagine the VRP-REP-ID of your dataset is “2014-002”. When introducing your dataset in your paper you can write something like “our instances are publicly available at http://www.vrp-rep.org (VRP-REP:2014-0002)” and someone who worked on your dataset could write “we tested our algorithm on the your_last_name 2014 instances (VRP-REP:2014-002)”. The VRP-REP-ID can also be used to quickly find datasets using the search bar int he welcome page.

Who is the owner of a dataset?
The owner of a dataset is the user who contributed the dataset to the VRP-REP database. The owner of a dataset has privileges over the dataset that other users don’t have:

• Editing the alias of the dataset
• Linking the dataset to an existing problem variant
• Linking the dataset to a new problem variant (thus adding a new problem variant to the database)
• Removing the link between the dataset and a problem variant
• Changing the instance files

If you find inconsistencies in a dataset, let the owner know by posting a ticket (see below, What is a ticket? on the page of the dataset. The owner is expected to correct any eventual problem.

What is the visibility of a dataset?
Datasets in VRP-REP can be public or private. Public datasets can be accessed (i.e., view and downloaded) by any user of visitor of the platform. On the other hand, private datasets can only be accessed through a private shareable link. This link automatically generated by the system when the dataset is contributed and it is only known to the owner of the dataset (see Who is the owner of a dataset?).

Private datasets are totally invisible for users and visitors. They are not listed in the browse/dataset menu and they cannot be accessed through the page of their problem variant or the page of their reference (a reference that is linked only to a private dataset is also private).

The owner of a dataset can change its visibility from private to public at any time but public datasets cannot become private. Contributing a solution report for a private dataset is strictly forbidden (even to the owner of the dataset).

So what is the point of a private dataset?
Private datasets are useful during the reviewing process of your articles. They allow you to show your reviewers and editors that your willing to share your instances with the community after the completion of the reviewing process. You can for instance write the private shareable link in the submitted paper and mention that you will make the dataset public when the paper gets accepted.

How do I change the visibility of a dataset?
Go to the page of the dataset. In the Properties table look up the field Visibility. In front of Private you should see a Make public button, just click on it.

What happens if I forget to change the visibility of my dataset once the paper gets accepted?
Try not to ;). The system will send you an email every 6 months remaining you that your dataset is private and giving you a link to make it public.

I want to contribute a dataset but I don’t quite understand what I have to do. Where do I find help?
Here you can find a video tutorial showing how to contribute a dataset. BTW you can find video tutorials explaining other functions on the VRP-REP Youtube channel.

I am the owner of a dataset and I just realized that there are errors in my files. What can I do?
If you become aware of the problem before anyone has contributed solutions for your dataset dataset, follow these steps:

1. Repair your instance files and double check that the problem is solved.
2. Go to your profile page and delete the dataset.
3. Upload the dataset again.
4. If the dataset you just deleted was already downloaded (you will see the number of downloads in your profile page), after uploading the repaired dataset, please post a ticket telling people which files changed and how they changed. This will save other users lots of time trying to figure out why the data they downloaded earlier does not correspond to the data that is now available on the platform.

Be aware that the VRP-REP-ID of the newly uploaded dataset will be different than that of the old one. If you have references to the VRP-REP-ID of your old dataset in publications, please do not use this procedure; contact instead the steering committee.

If you find out about the problem when your dataset is already linked to solutions, you cannot delete your dataset (the system won’t allow you to). In that case, please get in touch with the steering committee; they will give you directions on how to solve the problem.

Problem Variants

What is a problem variant?
As the term suggests, it is a type of VRP. Problem variants can be added to the VRP-REP database in two situations: when a user contributes a dataset or when the owner of a dataset edits the page of the dataset.

Who is the owner of a problem variant?
The owner of a problem variant is the user who contributed the variant to the VRP-REP database. The owner has privileges over a problem variant that other users do not have:

• Editing the variant’s title
• Editing the variant’s acronym
• Editing the variant’s optimisation criteria
• Editing the variant’s description

If you find inconsistencies in a problem variant, let the owner know by posting a ticket (see below, What is a ticket?) on the page of the problem variant. The owner is expected to correct any eventual problem.

References

What is a reference?
A reference is any type of publication (e.g., articles, Ph.D. theses, technical reports). References are added to the VRP-REP database in only two cases: when a user contributes a dataset proposed in that reference or when a user contributes a solution report with the results reported in the corresponding reference for a given dataset.

Who is the owner of a reference?
The owner of a reference is the user who contributed the reference to the VRP-REP database. The owner has special privileges over a reference that other users don’t have:

• Change the title
• Change the list of authors
• Change the year of publication
• Change the reference (citation information)

If you find inconsistencies in a reference, let the owner know by posting a ticket (see below, “What is a ticket?”) on the page of the reference. The owner is expected to correct any eventual problem.

Solutions

What is a solution?
A solution is an objective function value produced by a given method for a given instance of a given dataset. The only way to add a solution to the VRP-REP database is via the solution report.

What is a solution report?
A solution report is an xml file containing objective function values for one or more instances of a dataset. Solution report files must be formatted according to a predefined xml schema (that you can download from the resources page). You can also download from the page of each dataset an xml file with a solution report template specifically tailored for the corresponding dataset (this is the easiest way to build a solution report).

Who is the owner of a solution?
The owner of a solution is the user who contributed the solution to the VRP-REP database. The owner has privileges over a solution that other users do not have:

• Change the objective function value
• Change the solution’s optimality status
• Delete the solution from the database

I found an error in a solution. How can I notify the owner?
For technical reasons that are not worth discussing here, the current version of the VRP-REP platform does not support tickets for solutions. There is, however, a simple way to notify the owner of a solution that something is wrong with his/her data. Follow these steps:

• Go to the page of the reference where the solution was proposed. In the bottom of the page you will see a table showing the datasets solved in the corresponding reference. Locate the dataset corresponding to the erroneous solution. In front of the alias of the dataset you will see a see results button; click on it. You will be shown a table with the solutions
• Locate the erroneous solution in the table and click on the objective function value; a pop-up window will show you the name of the solution owner
• Click on the name of the solution owner; you will be taken to the user’s profile page At the bottom of the page you will find a send message button; click on it
• Send a message to the solution owner reporting the problem. Don’t forget to provide the user with the key information to solve the problem: the alias and VRP-REP-ID of the dataset, the name of the instance, the method, etc.

For confidentiality reasons, the steering committee is not copied on the messages you send to other users. If after some reasonable time the problem persists, please contact the steering committee.

What is a BKS?
As you may guess BKS stands for best known solution. A BKS in VRP-REP is the best solution registered in the database for a given instance in the context of a given problem variant. Note that a dataset, and therefore an instance, may be used on different VRP variants.

I am the owner of a solution and I just realized I made a mistake on the objective function value. What can I do?
Don’t panic :). Go to your profile page, and click on the “solutions” tab. You will see a table listing all the solutions you have contributed to the VRP-REP platform. Look up the table or use the search bar on the top right of the table to find the erroneous solution. Click the objective function value (column O.F. in the table). A pop-up window will allow you to edit the value of the objective function. When you are done, just click on ´save´.

I contributed a solution some time ago. Back then I had no optimality proof for the solution, but there is a recent publication where my solution was proven optimal. Can I update the optimality status of my old solution?
Sure. Go to your profile page, and click on the “solutions” tab. You will see a table listing all the solutions you have contributed to the VRP-REP platform. Look up the table or use the search bar on the top right of the table to find the solution. Click the optimality status (column Optimality in the table). A pop-up window will allow you to edit the status of your solution. When you are done, just click on save.

If you become aware of a new publication reporting solutions for a dataset that is registered on the VRP-REP database, be a good community member and take the time to fill out and contribute the corresponding solution report ;).

I downloaded a dataset D and used it on problem variant P. Now, I cannot contribute my solutions because D is not linked to P or P does not even exist in the VRP-REP database. What can I do?
Before you can contribute a solution report for a new variant-dataset combination, the dataset must be linked to the problem variant in the VRP-REP database. Linking a dataset to a problem variant is a privilege reserved to the dataset owner and the system administrator. Here is what you should do: post a ticket in the page of the dataset asking for the link to be created. If the problem variant you want to link to the dataset is not registered in the VRP-REP database, please provide with your request all the information needed to create it: title, acronym, and brief description. On the other hand, if the variant is already in the database, you just need to provide its acronym (as it appears in the database of course). You will be notified when the ticket is closed so you can proceed to contribute your solution report.

Tickets

What is a ticket?
A ticket is a mechanism to let data owners know that something is wrong with their data and to suggest ways to correct the problems. For instance if you find a typo in the title of a problem variant, go to the page of the corresponding variant and add a new ticket reporting the typo. The platform will automatically send an email with your ticket to the owner of the problem variant and to the steering committee who will make sure that the problem gets solved. Tickets have two possible statuses: open (default) and closed. A ticket remains open until a member of the steering committee verifies that the problem was solved and manually closes it. Here are some example of useful tickets:

• If you find erroneous data in an instance file (e.g., customer A is suppose to have a demand of 10 but it has a demand of 20 instead), post a ticket in the page of the dataset to which the instance belongs.
• If you find that a dataset is incomplete (i.e., an instance file is missing), post a ticket in the page of the corresponding dataset.
• If you find that the name of an author is misspelled or missing, post a ticket in the page of the corresponding reference.

Bug reporting

I found a bug on the website. How do I report it?
Oups! Click on the “Contact us” link in the bottom of any page. You will be taken to a contact form. In the Service field, select Development team and fill out your bug report. Please try to be as specific as possible, and provide the development team with a sequence of steps to reproduce the bug. They will try to fix the problem ASAP.

Miscellanea

I do not find an answer to my question in this FAQ page. What can I do?
Post your question in the forum. The VRP-REP team will make their best attempt to answer it ASAP.

How do I change my personal data?
Go to your profile page (click on the little guy in the top right of any page).

• to change your name or affiliation, click on the corresponding values and do your editing
• to change your password, click on the “Change password” button
• to change your email and/or country, contact the steering committee

How do I get credit for my contributions
The contributors page is automatically generated from the contents of the database. If you have contributed either a dataset or a solution report to the platform, your name should appear in the list of contributors. If that is not the case, contact technical support.

Can other users see my contributions?
Yes! Your name is associated with all your contributions: datasets, references, and solutions. You can see a summary of any user’s contributions by clicking on the user’s name (shown in different pages depending on the type of contribution).

Guide for reviewers and editors