Using CPLEX Scala Library with Decision Optimization Center 4.0
The CPLEX Scala Library cplex-scala is an open-source library written in Scala to build optimization models for CPLEX. It is available on GitHub. This library combines functional programming, mathematical programming, and constraint programming allowing to model optimization problems with a syntax that is close to the standard presentation of these problems in textbooks and scientific papers. For instance, the following constraint:
can be written as:
model.add(sum (for (i <- 1 to n) yield a(i) * x(i)) <= c(j))
where a and x are respectively an array of constants (e.g. floating-point values) and an array of decision variables i.e. the unknowns of the mathematical equations.
This tiny example is a good illustration of how the syntax is concise and very close to what OR practitioners are used to.
The cplex-scala library allows us to build both mathematical programming models and constraint programming models.
Why Scala?
Scala is a general-purpose language like Java or C#. In a post, Alex Fleischer gives some pros and cons of a Domain Specific Language (DSL) like OPL versus a General Programming Language (GPL) such as Java or C#. With Scala, there is no need to choose anymore: programmers can create their own DSL, and this is what we did in the cplex-scala library.
In Scala you have similar constructs as in Python:
- Map and filtering
- Tuples
- Dictionaries and Sets
- Slicing
- List comprehensions
- Generators
- Operator overloading
- …
But unlike Python, Scala is very fast. The other main advantage of Scala compared to Python is it is a statically typed language. This is specifically important for building robust and industrial applications, while at the same time, type inference makes you feel it is dynamic.
Having said that, Scala has a longer learning curve than Python. Fortunately, Scala is a JVM language, any Java developer can learn Scala and use it gradually. First step would be to write Scala programs similar to a Java program and become gradually more proficient in functional programming.
There are excellent MOOC available in Scala. My recommendation is the one from Coursera Functional Programming in Scala Specialization from the Ecole Polytechnique Fédérale de Lausanne. Any Java developer should consider attending the first course of the specialization Functional Programming Principles in Scala.
There are plenty of resources available on the internet; however, I would start with this: https://www.scala-lang.org
Scala with CPLEX is a perfect combo for building a powerful optimization modeling language.
CPLEX Scala Library available as GitHub Packages
Since 1.7.0, to use the cplex-scala library in your project, you have three options:
- Check out the Git repository and build the library as described in the README file.
- Download the libraries from the section assets of the release page on GitHub:
- Use GitHub Package: this is a recent feature of GitHub which makes it even simpler to use in your projects
In the remaining section, we will give details on how to use GitHub Package and how to install the package using Maven or Gradle.
Firstly you will need to create a personal access token as described here. To install a public repo, the important scope and permission to specify when creating the token through is read:packages:
How to configure your DOC projects with Gradle
Now you have created your personal access token, you need to update the build.gradle files of your DOC project.
Adding GitHub Package Repository in Gradle
The first step is to add GitHub Package repository in the list of repositories to scan when a dependency is missing. To do so, search for the section allProjects in the build.gradle file in the root directory of your DOC 4.0 project and add a maven entry (see GitHubPackages below):
Note: you can have more than one maven section here.
The above declaration makes use of two Gradle properties (notice the $ sign):
- GITHUB_USER
- GITHUB_TOKEN
The values must be specified in a file gradle.properties. This file is either in the root directory of the project or in the directory .gradle in your home directory. Here is an example of a gradle.properties file:
Specify for these properties:
- GITHUB_USER = GitHub email address associated with your login
- GITHUB_TOKEN = personal access token created in your account.
The next step is to specify the dependencies to the cplex-scala library for your Gradle projects.
Adding Dependency to CPLEX Scala Library in Gradle
Now that the GitHub Package repository for cplex-scala has been specified, the next step is to update the file build.gradle of your optimization model.
In a DOC 4.0 application, after the project scaffolding, you get the typical file structure below:
Here the name of the DOC 4.0 project is aircraft-maintenance.
Open the file build.gradle in your <your-project-name>-libs/engine and add the dependency to cplex-scala library:
The version of the cplex-scala library can be specified above directly instead of using a Gradle property. In the case above, it is defined in the file versions.gradle in directory gradle/template of your DOC project:
For instance, the version of the cplex-scala library used in the DOC 4.0 project is version 1.7.0:
If you are using IntelliJ, refresh your Gradle project and you will now see the cplex-scala library in the list of External Libraries:
That’s it, you are ready to start implementing your optimization model using the cplex-scala library. As a bonus, you have access to the CPLEX Scala documentation right at your fingertips. With IntelliJ select either a method, a class, an object… and type CTRL-Q to get the corresponding documentation:
If you have any feedback and ideas on how to improve the cplex-scala library, please create an issue on GitHub. You are also welcome to contribute to this library by creating a pull request.
