├── .gitignore
├── LICENSE
├── README.md
├── docs
├── _config.yml
├── cplex_lecture.pdf
├── index.md
└── javadoc
│ ├── DirectedGraph.html
│ ├── DirectedGraphArc.html
│ ├── Item.html
│ ├── Main.html
│ ├── Model.html
│ ├── allclasses-frame.html
│ ├── allclasses-noframe.html
│ ├── class-use
│ ├── DirectedGraph.html
│ ├── DirectedGraphArc.html
│ ├── Item.html
│ ├── Main.html
│ └── Model.html
│ ├── constant-values.html
│ ├── deprecated-list.html
│ ├── help-doc.html
│ ├── index-files
│ ├── index-1.html
│ ├── index-10.html
│ ├── index-11.html
│ ├── index-2.html
│ ├── index-3.html
│ ├── index-4.html
│ ├── index-5.html
│ ├── index-6.html
│ ├── index-7.html
│ ├── index-8.html
│ └── index-9.html
│ ├── index.html
│ ├── overview-tree.html
│ ├── package-frame.html
│ ├── package-list
│ ├── package-summary.html
│ ├── package-tree.html
│ ├── package-use.html
│ ├── script.js
│ └── stylesheet.css
├── instance.txt
└── src
├── basic
├── DirectedGraph.java
├── DirectedGraphArc.java
├── Item.java
├── Main.java
└── Model.java
└── colgen
├── Instance.java
├── Main.java
├── MasterModel.java
├── Pattern.java
├── PricingModel.java
└── Solution.java
/.gitignore:
--------------------------------------------------------------------------------
1 | # Compiled class file
2 | *.class
3 |
4 | # Log file
5 | *.log
6 |
7 | # BlueJ files
8 | *.ctxt
9 |
10 | # Mobile Tools for Java (J2ME)
11 | .mtj.tmp/
12 |
13 | # Package Files #
14 | *.jar
15 | *.war
16 | *.ear
17 | *.zip
18 | *.tar.gz
19 | *.rar
20 |
21 | # virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
22 | hs_err_pid*
23 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2018 Paul Bouman
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Java and CPLEX example project: Precendence Constrained Knapsack Problem (basic package)
2 | This repository contains example code for a small Java Project that utilizes the [IBM ILOG CPLEX library](https://www.ibm.com/academic/topic/data-science) (*on that webpage you can access it under 'Software'*)
3 | to solve instances of the Precendence Constrained Knapsack Problem. This code is available in the `basic` package and folder of this repository.
4 |
5 | The Precendence Constrained Knapsack Problem is a variant of the regular Knapsack Problems where we have items *I*, where for each item *i* we have a profit *pi* and a weight *wi*.
6 | Furthermore, there is a capacity*b* and a directed graph *G = (I,A)* defined on the items. The objective is to select a set of items *S ⊆ I*, such that the sum of*pi* over *i ∈ S* is maximized,
7 | while the sum of *wi* over *i ∈ S* is smaller than or equal to *b*. Additionally, an item *i* can only be in *S* if all items *j* for which *A* contains an arc *(i,j)* are also in *S*.
8 |
9 | The code for the basic example consists of the following files:
10 | * `DirectedGraph.java` contains a general purpose data structure for directed graphs. It provides methods to add nodes and arcs, and allows us to attach arbitrary data types to the nodes and arcs.
11 | * `DirectedGraphArc.java` models the arcs that are created by the graph. These arcs contain the origin node of an arc, the destination node of an arc and the data associated with the arc.
12 | * `Item.java` models a knapsack item, without its precendence constraints (these are modelled in the project using a DirectedGraph object).
13 | * `Model.java` manages a CPLEX integer linear programming model, converting a directed graph with a precendence constrained knapsack problem and a capacity to a CPLEX model that can be solved.
14 | * `Main.java` is used to read in an instance of the problem from a text file, convert it to a directed graph, and call the `Model` class to solve the instance.
15 |
16 | More detailed documentation of these classes can be found in the [Javadocs of this project](https://pcbouman-eur.github.io/JavaCplexExample/javadoc/).
17 |
18 | For a general explanation of using CPLEX from Java the repository contains some [lecture slides](https://pcbouman-eur.github.io/JavaCplexExample/cplex_lecture.pdf).
19 | There is also a [series of four YouTube videos](https://www.youtube.com/watch?v=C4YDrVT3fcg&list=PLrX1UIgv0C_4V5Xx6IIWj0U8i-4JN6F1g) in which this project is implemented.
20 |
21 | # Java and CPLEX column generation project: Cutting Stock (colgen package)
22 | A second part of the example code covers column generation. This example is self contained, and implements a solution approach for the [Cutting Stock Problem](https://en.wikipedia.org/wiki/Cutting_stock_problem).
23 |
24 | The cutting stock problem consists of a number of orders of items *i ∈ I*, each with a unique size *si* and a demand *di*, as well as the capacity *C* of a single unit of base stock.
25 | The objective of the cutting stock problem is to select cutting patterns that specify how many items of the given sizes are cut from a unit of base stock, such that no more items are cut than the capacity of the base stock allowed.
26 | The patterns must be selected such that the demand *di* of each item is covered, while units of base stock that are required to cut the items is minimized. Note that a cutting pattern can be applied more than once.
27 |
28 | A classic approach for this problem is column generation, where we have a master problem that has decision variables to decide how many times each cutting pattern must be applied. As there are exponentially many cutting patterns,
29 | the master problem is initialized with a limited set of cutting patterns. Dual information from the master problem is then provided to a pricing problem, that is basically a knapsack problem that is used to generate new cutting patterns
30 | with positive reduced costs. These cutting patterns are added to the master problem, and this is resolved. This process is repeated iteratively as long as new cutting patterns with positive reduced costs are found. Finally, using the generated columns, the master problem is convereted to an integer programming problem and solved to find a heuristic solution.
31 |
32 | The code for the column generation example consists of the following classes:
33 | * `Instance.java` is used to model an instance of the cutting stock problem. It also contains a static method that can be used to generate a random instance.
34 | * `Main.java` contains a main method that generates random instances and solves them using the column generation approach.
35 | * `MasterModel.java` contains an implementation of the master problem and provides methods to solve the LP-relaxation and generate columns as long as new columns with negative reduced costs are found, as well as a method that solves an integer program with the columns generated while solving the LP-relaxation.
36 | * `Pattern.java` is used to model a cutting pattern, i.e. how to cut a single piece of stock into multiple items.
37 | * `PricingModel.java` implements an optimization model for the pricing problem. The objective can be updated based on the current duals of the master problem, and solving it gives a pattern with maximal reduced costs. Note that adding a pattern to the master problem only has effect if the reduced costs are in fact positive.
38 | * `Solution.java` represents a solution to a particular instance of the problem. The solution consists of utilized patterns, and how often each pattern must be applied to a piece of stock.
39 |
40 | Currently, all documentation of this example is only provided within the source code itself. In future updates to this repository, the Javadoc documentation may be added to the Github pages website.
41 |
42 | # Using CPLEX
43 |
44 | ## Obtaining CPLEX
45 |
46 | For this example to work, you need to have a working version of the CPLEX Java Library `cplex.jar` and the native library. The native libary is called `cplexYYYY.dll` on Windows, `libcplexYYYY.jnilib` on MacOS and `libcplexYYYY.so` on Linux, where `YYYY` is replaced by the version of your CPLEX library (e.g. 1263).
47 |
48 | Students who do not have these files can obtain the full [IBM ILOG CPLEX Optimization Studio](https://www.ibm.com/academic/topic/data-science) from IBM for free using a student account (*on that webpage you can access it under 'Software'*).
49 |
50 | After installing the IBM ILOG CPLEX Optimization Studio, you can find the .jar file in `cplex/lib` relative to the installation folder of the software. The native library can be found in `cplex/bin/x64_win64` on Windows installations, and similar locations on MacOS or Linux.
51 |
52 | ## Adding CPLEX to an Eclipse Project
53 |
54 | If you only need CPLEX, the easiest way to include it in an Eclipse project is to just add it is a library to the project. You can take the following steps to do this:
55 |
56 | 1. Create a directory `lib` in the root of your project and copy `cplex.jar` and the native library file there.
57 | 1. Go to the project properties, which can be access by right clicking on your project folder or via the Project menu in the menu bar.
58 | 3. Go to the Java Build Path option and select the `Libraries` tab.
59 | 4. Press `Add JARs` and select the `cplex.jar` file from the lib folder. For projects configured for Java versions up to 8, there is only a classpath to which the library will be automatically added. If you have a Java 9+ project, you need to take care it is added to the classpath (not the module path) and make sure your project has no `module-info.java` file (delete it if you created it).
60 | 5. Click on the `>` symbol in front of `cplex.jar`, select `Native Library Location` and click `Edit`. Click `Workspace` and select the `lib` folder that contains the native library.
61 |
62 | There is a [YouTube video](https://youtu.be/C4YDrVT3fcg) that shows these steps.
63 |
64 | ## Adding CPLEX via Maven
65 |
66 | If you have the full IBM ILOG CPLEX Optimization Studio installed, you can also add CPLEX as a [Maven](https://maven.apache.org/) dependency.
67 |
68 | ```
69 |
public class Item 111 | extends Object112 |
Constructor and Description | 133 |
---|
Item(int profit,
136 | int weight)
137 | Default constructor for a knapsack item
138 | |
139 |
Modifier and Type | 153 |Method and Description | 154 |
---|---|
int |
157 | getProfit()
158 | The profit of the current item.
159 | |
160 |
int |
163 | getWeight()
164 | The weight of the current item.
165 | |
166 |
String |
169 | toString() |
170 |
public Item(int profit, 200 | int weight)201 |
profit
- the profit for this item (we want to maximize this)weight
- the weight of the item (this consumes capacity)public int getProfit()224 |
public int getWeight()238 |
Modifier and Type | 86 |Method and Description | 87 |
---|---|
static DirectedGraph<Item,String> |
91 | Main.read(File f)
92 | Reads a Precedence Constrained Knapsack Problem as a directed graph from a file
93 | |
94 |
Constructor and Description | 101 |
---|
Model(DirectedGraph<Item,String> instance,
105 | int capacity)
106 | Constructor that takes a directed graph with the items and precedence constraints
107 | |
108 |
Modifier and Type | 86 |Method and Description | 87 |
---|---|
List<DirectedGraphArc<V,A>> |
91 | DirectedGraph.getArcs()
92 | Gives a list of all arcs currently in the graph
93 | |
94 |
List<DirectedGraphArc<V,A>> |
97 | DirectedGraph.getInArcs(V node)
98 | Gives all the arcs that enter a particular node in the graph.
99 | |
100 |
List<DirectedGraphArc<V,A>> |
103 | DirectedGraph.getOutArcs(V node)
104 | Gives all the arcs that leave a particular node in the graph.
105 | |
106 |
Modifier and Type | 86 |Method and Description | 87 |
---|---|
List<Item> |
91 | Model.getSolution()
92 | Create a list of the items for which the decision variables
93 | are one in the current solution of the mathematical program.
94 | |
95 |
static DirectedGraph<Item,String> |
98 | Main.read(File f)
99 | Reads a Precedence Constrained Knapsack Problem as a directed graph from a file
100 | |
101 |
Modifier and Type | 108 |Method and Description | 109 |
---|---|
void |
113 | Model.setItem(Item i,
114 | boolean enabled)
115 | Disable an item in the model (fix it to 0) or enable it (either 0 or 1)
116 | |
117 |
Constructor and Description | 124 |
---|
Model(DirectedGraph<Item,String> instance,
128 | int capacity)
129 | Constructor that takes a directed graph with the items and precedence constraints
130 | |
131 |
Each package has a page that contains a list of its classes and interfaces, with a summary for each. This page can contain six categories:
80 |Each class, interface, nested class and nested interface has its own separate page. Each of these pages has three sections consisting of a class/interface description, summary tables, and detailed member descriptions:
92 |Each summary entry contains the first sentence from the detailed description for that item. The summary entries are alphabetical, while the detailed descriptions are in the order they appear in the source code. This preserves the logical groupings established by the programmer.
112 |Each annotation type has its own separate page with the following sections:
116 |Each enum has its own separate page with the following sections:
127 |Each documented package, class and interface has its own Use page. This page describes what packages, classes, methods, constructors and fields use any part of the given class or package. Given a class or interface A, its Use page includes subclasses of A, fields declared as A, methods that return A, and methods and constructors with parameters of type A. You can access this page by first going to the package, class or interface, then clicking on the "Use" link in the navigation bar.
137 |There is a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces. The classes are organized by inheritance structure starting with java.lang.Object
. The interfaces do not inherit from java.lang.Object
.
The Deprecated API page lists all of the API that have been deprecated. A deprecated API is not recommended for use, generally due to improvements, and a replacement API is usually given. Deprecated APIs may be removed in future implementations.
149 |The Index contains an alphabetic list of all classes, interfaces, constructors, methods, and fields.
153 |These links take you to the next or previous class, interface, package, or related page.
157 |These links show and hide the HTML frames. All pages are available with or without frames.
161 |The All Classes link shows all classes and interfaces except non-static nested types.
165 |Each serializable or externalizable class has a description of its serialization fields and methods. This information is of interest to re-implementors, not to developers using the API. While there is no link in the navigation bar, you can get to this information by going to any serialized class and clicking "Serialized Form" in the "See also" section of the class description.
169 |The Constant Field Values page lists the static final fields and their values.
173 |Class | 70 |Description | 71 |
---|---|
DirectedGraph<V,A> | 75 |
76 | Simple class that can be used to model directed graphs, where
77 | arbitrary types of data are associated with the nodes and arcs
78 | of the graph.
79 | |
80 |
DirectedGraphArc<V,A> | 83 |
84 | Class that models arcs in the directed arcs.
85 | |
86 |
Item | 89 |
90 | Class that models a knapsack item with a profit and a weight
91 | |
92 |
Main | 95 |
96 | Main class for the Java/CPLEX example
97 | |
98 |
Model | 101 |
102 | Model class that converts a directed graph representing a
103 | precedence constrained knapsack problem into a mathematical programming
104 | model managed by CPLEX.
105 | |
106 |
Class and Description | 81 |
---|
DirectedGraph
85 | Simple class that can be used to model directed graphs, where
86 | arbitrary types of data are associated with the nodes and arcs
87 | of the graph.
88 | |
89 |