| Requirements:
The software is for academic use only. Is it distributed as a docker image in order to facilitate installation and usage. To install and run the solver, you need:
VRPSolver uses BaPCod, a C++ library implementing generic Branch-Cut-and-Price. You will need to download the file bapdock.img and request a free license for academic purposes. In order to do so, fill the form available here, you will then receive and email with a dowload link. |
These notes explain how to set up and run the VRPSolver on Linux and Windows/MacOS systems. While assuming the use of Cplex 12.10, this tutorial can be used in an equivalent way for installation with Cplex 12.9.
Linux
First, follow the instructions to manage Docker as a non-root user (without sudo).
Installation of bapdock.img
Import and run the Docker image:
docker import -c "ENTRYPOINT [\"/julia\"]" bapdock.img bapdock-init
docker run -it -d --name bapdock-cont bapdock-init
Run this command to get the container-ID:
docker ps
Enter the subdirectory of your cplex installation which contains the shared libraries (e.g. /opt/ibm/ILOG/CPLEX_Studio1210/cplex/bin/x86-64_linux) and create a copy of libcplex12100.so with the name libcplex12x.so
Copy your cplex folder to inside the container:
docker cp /ABSOLUTE_PATH_TO_CPLEX_ROOT/cplex bapdock-cont:/cplex
For example, if your CPLEX 12.10 is installed at /opt/ibm/ILOG/CPLEX_Studio1210 this command should be:
docker cp /opt/ibm/ILOG/CPLEX_Studio1210/cplex bapdock-cont:/cplex
Commit the modified container as an image named bapdock
docker commit container-ID bapdock
Stop and remove the bapdock-init container:
docker stop container-ID
docker rm container-ID
Running a Julia VRPSolver application through the docker
To run the application from your local machine command line, you must mount (-v) the user julia VRPSolver application folder under any name and the last arguments must be the main script .jl of the application, followed by the application arguments:
docker run --rm -v /ABSOLUTE_PATH_TO_VRPSOLVER_APP:/MyApp bapdock /MyApp/myapp.jl    arg1 arg2 ... argn
The VRPSolver application folder is mounted as /MyApp in the Docker container filesystem.
For example, for the Capacitated Vehicle Routing Problem (CVRP) demo (available here), we can call:
docker run --rm -v /ABSOLUTE_PATH_TO_CVRP_APP:/CVRP bapdock /CVRP/src/run.jl /CVRP/data/A/A-n37-k6.vrp -m 6 -M 6 -u 950 -o /CVRP/sol/A-n37-k6.sol
which solves the instance A-n37-k6.vrp using exactly 6 vehicles (-m and -M defines the minimum and maximum number of vehicles, respectively), an upper bound of 950 and writes the solution at /CVRP/sol/A-n37-k6.sol. Note that for the arguments after bapdock we need to consider the container filesystem (/CVRP) to access the application and I/O arguments. All changes into /CVRP and subdirectories will be reflected at /ABSOLUTE_PATH_TO_CVRP_APP.
When running from the local machine command line, Julia code will be compiled each time and thus building the model takes some time (like 30 seconds in a typical machine) even for small instances. The reported solution time, counted only after the code is compiled, is not affected.
To decrease recompilation time while creating/debugging the application, you can run the application in the interactive mode:
docker run -it --rm -v /ABSOLUTE_PATH_TO_VRPSOLVER_APP:/MyApp bapdock
For example, for CVRP demo, we can call:
docker run -it --rm -v /ABSOLUTE_PATH_TO_CVRP_APP:/CVRP bapdock
and to run the application inside the Julia environment, type (one at a time)
# load CVRP demo
include("/CVRP/src/run.jl")
# run CVRP demo
main(["/CVRP/data/A/A-n37-k6.vrp","-m","6","-M","6","-u","950","-o","/CVRP/sol/A-n37-k6.sol"])
# running another instance without writing the solution
main(["/CVRP/data/A/A-n37-k5.vrp","-m","5","-M","5","-u","670"])
# defining arguments before
args = ["/CVRP/data/A/A-n37-k5.vrp","-m","5","-M","5","-u","671"]
# running with predefined arguments
main(args)
You can edit the application on your local machine and load inside Julia environment in the docker to test you changes, using “include”. In this case, recompilation time will be minimized.
To quit the Julia environment, type
exit()
Other demos are available here.
Easier way of running a Julia VRPSolver application
There is a bash script called VRPSolver available for each demo application to avoid call Docker directly.
For example, for CVRP demo (see README.txt in the demo for more details), we can call:
./VRPSolver data/A/A-n37-k5.vrp -m 5 -M 5 -u 670
instead of:
docker run --rm -v /ABSOLUTE_PATH_TO_CVRP_APP:/CVRP bapdock /CVRP/src/run.jl /CVRP/data/A/A-n37-k5.vrp -m 5 -M 5 -u 670
Windows or MacOS
First, make sure the Docker is in running status. If you are using Docker Toolbox, please use the Docker QuickStart Terminal to run Docker.
How to extract CPLEX
Create a folder named cplexdocker.
Get CPLEX 12.10 installer file for Linux 64 from IBM ILOG (let’s assume the file name is cplex_studio1210.linux-x86-64.bin) and move it to the folder cplexdocker.
Also, move the bapdock.img to cplexdocker.
Create a text file named Dockerfile_extract_cplex.txt at cplexdocker folder with this content:
FROM ubuntu
RUN apt-get update ; apt-get install -y openjdk-8-jre
COPY cplex_studio1210.linux-x86-64.bin /
RUN (echo 2 ; echo ; echo 1 ; echo / ; echo y ; echo ; echo; echo; echo 2; echo ) | bash ./cplex_studio1210.linux-x86-64.bin
Run these commands at the directory cplexdocker:
docker build -t ubuntu_with_cplex -f Dockerfile_extract_cplex.txt .
docker create --name ubuntu_with_cplex ubuntu_with_cplex
Copy the installed cplex to cplexdocker folder:
docker cp ubuntu_with_cplex:/cplex .
Enter the folder cplex/bin/x86-64_linux/ and rename libcplex12100.so to libcplex12x.so
Installation of bapdock.img
Import and run the Docker image:
docker import -c "ENTRYPOINT [\"/julia\"]" bapdock.img bapdock-init
docker run -it -d --name bapdock-cont bapdock-init
Run this command to get the container-ID:
docker ps
Copy your cplex folder to inside the container:
docker cp cplex bapdock-cont:/cplex
Commit the modified container as an image named bapdock
docker commit container-ID bapdock
Stop and remove the bapdock-init container:
docker stop container-ID
docker rm container-ID
Running a Julia VRPSolver application through the docker
To run the application from your local machine command line, you must mount (-v) the user julia VRPSolver application folder under any name and the last arguments must be the main script .jl of the application, followed by the application arguments:
docker run --rm -v /ABSOLUTE_PATH_TO_VRPSOLVER_APP:/MyApp bapdock /MyApp/myapp.jl arg1 arg2 ... argn
The VRPSolver application folder is mounted as /MyApp in the Docker container filesystem.
For example, for the Capacitated Vehicle Routing Problem (CVRP) demo (available here), we can call:
docker run --rm -v /ABSOLUTE_PATH_TO_CVRP_APP:/CVRP bapdock /CVRP/src/run.jl /CVRP/data/A/A-n37-k6.vrp -m 6 -M 6 -u 950 -o /CVRP/sol/A-n37-k6.sol
which solves the instance A-n37-k6.vrp using exactly 6 vehicles (-m and -M defines the minimum and maximum number of vehicles, respectively), an upper bound of 950 and writes the solution at /CVRP/sol/A-n37-k6.sol. Note that for the arguments after bapdock we need to consider the container filesystem (/CVRP) to access the application and I/O arguments. All changes into /CVRP and subdirectories will be reflected at /ABSOLUTE_PATH_TO_CVRP_APP.
When running from the local machine command line, Julia code will be compiled each time and thus building the model takes some time (like 30 seconds in a typical machine) even for small instances. The reported solution time, counted only after the code is compiled, is not affected.
To decrease recompilation time while creating/debugging the application, you can run the application in the interactive mode:
docker run -it --rm -v /ABSOLUTE_PATH_TO_VRPSOLVER_APP:/MyApp bapdock
For example, for CVRP demo, we can call:
docker run -it --rm -v /ABSOLUTE_PATH_TO_CVRP_APP:/CVRP bapdock
and to run the application inside the Julia environment, type (one at a time)
# load CVRP demo
include("/CVRP/src/run.jl")
# run CVRP demo
main(["/CVRP/data/A/A-n37-k6.vrp","-m","6","-M","6","-u","950","-o","/CVRP/sol/A-n37-k6.sol"])
# running another instance without writing the solution
main(["/CVRP/data/A/A-n37-k5.vrp","-m","5","-M","5","-u","670"])
# defining arguments before
args = ["/CVRP/data/A/A-n37-k5.vrp","-m","5","-M","5","-u","671"]
# running with predefined arguments
main(args)
You can edit the application on your local machine and load inside Julia environment in the docker to test you changes, using “include”. In this case, recompilation time will be minimized.
To quit the Julia environment, type
exit()
Other demos are available here.
Easier way of running a Julia VRPSolver application
If you are using MacOS terminal or Docker QuickStart Terminal (available for Docker Toolbox on Windows and MacOS), it is possible to use the bash script VRPSolver available for each demo application to avoid call Docker directly.
For example, for CVRP demo (see README.txt in the demo for more details), we can call:
./VRPSolver data/A/A-n37-k5.vrp -m 5 -M 5 -u 670
instead of:
docker run --rm -v /ABSOLUTE_PATH_TO_CVRP_APP:/CVRP bapdock /CVRP/src/run.jl /CVRP/data/A/A-n37-k5.vrp -m 5 -M 5 -u 670
Troubleshooting
If you got the message “libcplex12x.so: cannot open shared object file: No such file or directory », it means that the cplex directory was not successfully mounted. Please verify:
- you created a copy of libcplex1210.so (or libcplex129.so) to libcplex12x.so
- that CPLEX version is 12.9 or 12.10
- that CPLEX 64-bit Linux distribution is used, even if you have MacOS or Windows