Programming Assignment

Due:

Please make sure you adhere to the policies on academic honesty.

Please see the general programming webpage for details about the programming environment for this course, and specifically for directions in how to submit your programming assignment electronically.

The files you need for this assignment can be downloaded here.

Preface

Although each individual task we ask of you might not be so difficult, this assignment as a whole will be the most involved programming assignment as of yet. Needless to say, please start early and tackle the program in stages.

Overview

You have just taken an internship with an online grocer. You will be responsible for packing an order of groceries into 'bins' which will then get loaded onto a truck for delivery. Of course, the goal is to be able to pack the order into as few bins as possible. At the same time, you do not want to pack bins so heavily that they cannot be easily carried. In order to try to find a good solution for packing items, we will have you write a computer program. We will abstract the problem with the following model:

Each item has a weight which is somewhere between 0 and 1.
Each item must be assigned to a particular bin.
Each bin has a maximum capacity of 1.
The goal is to use as few bins as possible.

This setup can actually be used in modeling a variety of different applications, and it has been given the name "Bin Packing" in the literature. Unfortunately, minimizing the number of bins appears to be a very difficult problem to solve efficiently (there are too many possibilities!). Fortunately a number of heuristics have been studied, and some of these seem to get quite good results.

Heuristics

In this program, we ask you to implement two particular heuristics. The first heuristic, called "worst-fit," proceeds as follows. Items are considered one-at-a-time (in the original order presented). When an item is being considered, we look at the existing bin with the most available room. If the new item fits in this bin, we place it there; if it does not fit in this bin then it will not fit in any bin, so we place the item into a newly created bin. For example, on an instance with weights .29, .11, .81 and .68, this algorithm would pack the items into three bins (note that this is not the best possible).

A second heuristic is known as "worst-fit-decreasing." This heuristics considers items one-at-a-time, again placing each considered item into the bin with the most remaining space (if such a bin will hold the item). The difference between this heuristic and the last is that items are considered in order of decreasing weight, rather than in the original order. To do this, all items are initially placed into a priority queue and at each step the item with largest remaining weight is removed from this queue and then placed into a bin. (note that for this to work, you will have to adjust your view of priorities so that the "minKey" is the one with the largest weight). Looking at our previous example, the items would get considered in the order .81, .68, .29 and .11, and thus packed into two bins. By no means are these the only two approaches to bin packing. If anyone is interested in the history of the problem, we will be happy to provide references. But for this assignment, we will focus on these two heuristics.

The Driver

In order to test your program and evaluate the bin packing heuristics, we are providing you with a driver which does the following. Given an integer N and a floating-point value u in [0...1], the driver generates N weights each chosen at random in the range [0...u). These weights are stored in an array of double-precision floating point numbers. The driver calculates S, the sum of all of the weights, and reports that any solution will require at least S^* bins, where S^* is the smallest integer at least as great as S. For example, if the weights sum to 20.3, then we know that no solution can pack these items into 20 bins or less. (Please note: this does not mean that there always exists a solution using exactly S^* bins - but it gives us a reasonable bound for which to aim when evaluating the heuristics' results.)

The driver accepts the following five command line arguments, as specified by the user. The first four of these are required; the fifth is optional.

N - a non-negative integer, specifying the number of items
u - a double in the range (0...1] specifying an upper limit on the range when choosing random weights.
0 or 1 - interpreted as a boolean specifying whether or not the program should give "verbose" output (explained later). 0 represents no verbose output, and 1 represents verbose.
0 or 1 - specifying which priority queue implementation to use (explained later). 0 means SlowPQ; 1 means FastPQ.
seed - an integer value used to seed the random number generator. If no argument is given, the seed is set based on the system clock.

At this point, the driver calls a routine worstFit which is written by you to simulate the worst-fit heuristic. This routine returns the overall number of bins used. Secondly, the driver calls a routine worstFitDecreasing written by you to simulate the worst-fit-decreasing heuristic.

Finally, although generating random data is useful for experiments, it is troublesome when developing and testing your program. The difficulty is that when a bug arises, you generally want to fix the bug and then re-test on the same data. But if data is generated at random, you will likely get a different data set when you re-test. For this reason, we will give you a way to set a "seed" which is used by the random number generator. In this way, you can re-test on a previous data set by providing the identical seed.

Your Tasks

priority queue implementations

We are providing you with the PriorityQueue interface based on the description in section 7.1.3 of the textbook. Specifically, you will notice that this interface is based on the abstraction where keys are Object's and where a Comparator is used to compare keys. You must give two different priority queue implementations. Both are based on creating an underlying array for representing the priority queue. To simplify matters, the priority queue constructor will accept a parameter maxsize which gives a predefined limit on the number of items which might be held (thus allowing you to initialize your array).
The first implementation, titled SlowPQ, should be based on keeping the items in an unordered array. This is quite similar to the discussion in Section 7.2.1, but even easier as we will use an array directly rather than a Sequence.
The second implementation, titled FastPQ, will be based on a heap as specified in Section 7.3.2. Although we intuitively think of a heap as a binary tree, we will ask you to design your implementation based on the array representation of a heap (equivalently the "vector" representation as discussed on page 305 of the text). Again, you will use an array of Item's, but rather than keep them unordered, you will partially order them based on the heap property. Section 7.3.3 of the text gives an implementation of a priority queue with a heap, based on using the BinaryTree interface. Though this is different syntactically than what you must do, you may choose to look closely in understanding the process.
bin packing heuristics

As we mentioned, your primary task is to correctly implement both of these heuristics. To get you going, we have provided you a template file Binpack.java which gives the two method definitions. As you start to think about the task you should realize that the concept of a priority queue will serve you in several ways. For instance, we already mentioned that the worst-fit-decreasing heuristic needs the use of a priority queue so that weights can be considered in decreasing order. But this is not the only use. Both heuristics should also make good use of a priority queue to keep track of all currently opened bins, always identifying the particular bin with the most remaining capacity. As you might see, these two uses of a priority queue are quite different. They hold different types of elements and they are based on a possibly different criteria for priorities. Fortunately, the abstraction provided by the PriorityQueue interface allows us this flexibility.
Each of the heuristics should be written as a routine taking three parameters:
- double[ ] values - this is the original list of weights (Please note this array has nothing to do with the array of Item's used within the priority queue implementation)
- boolean useFastPQ - if this variable is true then all priority queues should be constructed using the FastPQ implementation. If false, then the SlowPQ should be used.
- boolean verbose - (see below)
Please keep in mind that you do not want any unnecessary repeated code. For example, although the two routines are technically two different heuristics, there is quite a bit of common logic. Therefore a well written program will make use of some additional subroutines that are called from within both top-level routines. Similarly, although you must take into account the useFastPQ boolean, this does not mean that you should have two huge if/else clauses with repetitive code. The best way to declare a priority queue variable in this setting is as follows:
```
PriorityQueue myPQ;
if (useFastPQ)
  myPQ = new FastPQ(--parameters--);
else
  myPQ = new SlowPQ(--parameters--);
/* now you can start using it */
if (myPQ.isEmpty())  ...
```
Finally, the functionality required by the verbose flag must be a forethought in planning your overall program. The issue is the following. The routine is written to return a single int value stating the overall number of bins which were used in the solution. However in our original application, it does a person no good to simply say that the solution uses 59 bins - a program must give some sort of mapping to explain which items should be grouped in each such bin. So for this reason, we want your program to be able to produce verbose output which gives such a mapping. Going back to the earlier sample, possible verbose output for the worst-fit heuristic might read (though you are free to format the information as you wish):
```
Bin 1:  weight=0.40  [items: 0.29 0.11]
Bin 2:  weight=0.81  [items: 0.81]
Bin 3:  weight=0.68  [items: 0.68]
```
At the same time, we will want to perform some large experiments. Verbose output would be very distracting if packing 1000000 items and producing such output would skew the running times. Even more important, on large experiments memory will become scarce. The ideal student will realize that the structure used for representing a bin can be greatly simplified if one is not required to produce the verbose output. Streamlined code will allow significantly larger experiments to be performed.
experiments and readme file

We ask that you perform some experiments which will be reported in your 'readme' file. This will allow us to compare the quality of the solutions produced by the two heuristics as well as the efficiency of the two priority queue implementations.
You must submit a plain-text readme file with the following information:
- Show the output of your program, when run using "verbose" mode, for [N=20, u=.2, seed=9].
- Show the output of your program, when run using "verbose" mode, for [N=20, u=.7, seed=9].
- Give a table of results for u=.2, and as large of values of N as your program can handle from N=100, 1000, 10000, 100000, 1000000. Your table should contain the total sum S of the weights, the number of bins used by worst-fit, and the number of bins used by worst-fit decreasing. Furthermore, you should report the running times for both the FastPQ and SlowPQ implementations, when applicable. (even better is if you report the average over several random trials for each value of N).
- Give a second table, as above, for the value u=.7.
You have a choice in how to gather this information. One way is to sit at the computer for a while and gather piece after piece of information using our driver. A wise student might feel this is a mindless use of time and surely can be automated by a new or modified driver. For your benefit, we will tell you that our driver relies internally on the method BinpackDriver.runTrial() with parameters (int N, double u, boolean verbose, boolean fastPQ, long seed), the seed being optional. You could write a loop to call this method repeatedly with various parameter values.

Recommended Steps for Progress

This program might seem intimidating because of the many required tasks. Here is our suggestion for getting going:

Write SlowPQ.java -- the concept could not be simpler. Writing this implementation should be a relatively easy task as a warmup, but already it will help you get used to some of the subtleties of the Priority Queue interface such as using a Comparator. Furthermore, you will use the "composition" pattern as described in Section 7.1.4 with the Item class. The issue at hand is that items are presented to your queue as a pair of two separate objects: a key and an element. The questions arises as to what type of array you should use. The class Item provides you with a simple structure which holds the (key,element) pair as one object, and thus you can declare an array as Item[maxsize].
Go to the worst-fit-decreasing method and try to use a priority queue to get the initial list of weights into decreasing order. Temporarily write a loop which prints out the newly ordered values (though you should eventually remove or comment out this loop, since we do not want such extraneous print statements in your final code).
Writing this part of the code will give you a way already to make sure that your priority queue implementation works correctly. Furthermore, writing this code will already require you to get some practice in how to make use of a priority queue, perhaps how to use a Double as a key, and in creating a new class which implements a Comparator.
Write FastPQ.java -- This will take a bit more care in development than did SlowPQ. Fortunately, you should have code from the previous step which can be used to help test your implementation.
Go back and complete the task of implementing the worst-fit and worst-fit-decreasing heuristics. Before writing any code, you will want to think a bit about the logic. Decisions will need to be made as to how a "bin" will be represented, how bins are compared to each other, and how to make further use of the PriorityQueue abstraction. Generating verbose output will allow you to examine the behavior of your code on some very small examples which you might be able to compare to a hand simulation.
When you are confident that all of your code is written and working, start running the experiments.

Files you will need

The files you need for this assignment can be downloaded here.

Files to Submit

At minimum, you must submit the files: readme, Binpack.java, SlowPQ.java, and FastPQ.java. However, you will most likely need to define some additional classes (such as a Comparator, and an Object representing an individual bin). You may also free to use data structures from earlier in the class.

Please submit all source code which you use other than those files which were directly provided by us for this assignment.

Grading Standards

The assignment is worth 10 points. In general, we will try to apportion the points based on the following break down (though we will use some of our own judgment in the end):

unsorted array implementation (1 point)
array-based heap implementation (3 points)
correct implementations for worst-fit and worst-fit-decreasing (3 points)
correct verbose output (2 points)
experiments/readme (1 point)

Useful Java Hints

Along the way, there will be a few potential difficulties involving detailed use of Java. We will summarize some very useful advice here, and we hope that you will come back to it when needed.

static methods in Binpack.java - You will notice that we have asked you to write two methods in the class Binpack. Both of these methods are declared with the keyword static. We will leave the detailed explanation of this concept for comp272. What you will need to know is that if you choose to write any additional methods, you should probably declare them to be static as well.
double vs. Double - Our generic interfaces are based on Object's, and yet primitive data types are not technically objects. The original input for your bin packing methods are a list of item weights, represented as double's. It may seem, for instance in ordering the items, that this weight would make a perfect "key." But a key must be an Object. As we have seen with int's and Integer's, Java comes with a predefined class Double which provides a way to wrap a double as an Object. You may feel free to check the documentation for a larger list of supported methods, but the most basic are:
- Double D = new Double(double value); - which creates a new Double object from original primitive value.
- double val = D.doubleValue(); - takes a Double and produces the original primitive value.
NumberFormat object - When printing the double values in your verbose output, you will find that they appear with a great deal of accuracy. We want your program to use the full accuracy in its calculations. It is also fine if you wish to leave your output displaying such accuracy.
You will notice, however, that the driver prints out the list of original weights formatted so that they are rounded to the nearest three decimal places. If you are interested in a lesson on formatting numbers in Java, you may wish to change your output to match this convention. To do so is straightforward, but a bit cumbersome. Here is what the driver does:
```
// create an object which is able to format numbers for you
java.text.NumberFormat f = java.text.NuberFormat.getInstance();
f.setMaximumFractionDigits(3);
f.setMinimumFractionDigits(3);
// start printing out as many formatted numbers as you wish
System.out.print(f.format(sample_double));
System.out.print(f.format(another_double));
```

Last modified: 29 October 2002

Programming Assignment

Due:

Contents: