Interactive Bin Packing

Publications About the Application
Packages and Releases
Build Status
JaCoCo Test Coverage
Security
DOI
Other Information

How to Cite

If you have reason to cite this application in an article, please cite the following:

Cicirello, V.A., (2022). Interactive Bin Packing: A Java Application for Learning Constructive Heuristics for Combinatorial Optimization. Journal of Open Source Education, 5(49), 140, https://doi.org/10.21105/jose.00140.

Overview

Interactive Bin Packing provides a self-guided
tutorial on combinatorial optimization, the bin packing problem,
and constructive heuristics for bin packing. It also enables the
user to interact with bin packing instances to explore their own
problem solving strategies, or to test their knowledge of the
various constructive heuristics covered by the tutorial. The
application is not a solver for bin packing. Interactive
Bin Packing is a tool for learning about the bin
packing problem, as well as for learning about heuristic
techniques for solving instances of the problem.

The objectives of Interactive Bin Packing include:

gaining an understanding of the bin packing problem,
and more generally how the bin packing problem is an
example of a combinatorial optimization problem;
learning about constructive heuristics;
learning about the most common constructive heuristics
for the bin packing problem, including first-fit, best-fit,
first-fit decreasing, and best-fit decreasing; and
serving as an interactive environment for students (whether
in the formal context of a class, or just for informal
self-guided learning) to explore potential problem solving
methods for combinatorial optimization.

In addition to the Interactive Bin Packing application source code,
this repository also contains example assignments. Specifically,
the assignments directory
contains example assignments that can either be used by
self-guided learners, or which can be adapted and used by
instructors in courses, such as within courses on discrete
mathematics, algorithms, or artificial intelligence.

First time users should start by taking a look at the
sections below on User Documentation
as well as Installing and Running the
Application.
We also recommend that first time users (whether students in courses
or self-learners) work through the
first of the example assignments.

Java 11+

The prebuilt jar of the application is built with the OpenJDK 11.

Example Assignments

In addition to the Interactive Bin Packing application, the
repository contains a directory of Example Assignments
that utilize the application. Self-directed learners may begin with
assignments/1; while course instructors may prefer
to assign their students assignments/2, which utilizes
the Session Log functionality introduced in version 3.1.0
to make it easy for instructors to validate students’ work.

User Documentation

All user documentation is contained within the application itself,
which you can access via two
commands in the Info menu:

The Tutorial command in the Info menu opens a self-guided tutorial
on combinatorial optimization, the bin packing problem, and
constructive heuristics for bin packing. It will also walk you through
using the application, and all of its functionality.
The Help command (also in the Info menu) provides documentation of all
menu functions and other user interface elements.
We recommend that instructors take a look at the documentation of the
commands of the Session menu (see the Help command), which enables having
students save session logs, and also provides functionality for validating
the session logs they submit to you to confirm successful completion of
assignments that utilize the application.

The first time that you use the application, we recommend that you
begin by choosing the Tutorial command from the Info menu, and working
your way through the self-guided tutorial.

Installing and Running the Application

Installing == Downloading

The Interactive Bin Packing application is available as a prebuilt, executable
jar file from a variety of sources. The filename of the jar is of the form
interactive-bin-packing-X.Y.Z.jar, where X.Y.Z is the version number.

To install, simply download the jar of the latest release by doing any of the
following:

From the command line via
Maven Central:

curl -O -J -L  "https://repository.sonatype.org/service/local/artifact/maven/content?r=central-proxy&g=org.cicirello&a=interactive-bin-packing&e=jar&v=LATEST"

From
Maven Central
repository website: Select versions tab, and then the browse link, and download the jar.
From the
GitHub Package Registry:
Select the most recent release, and download the jar of the application.
From GitHub releases:
Simply download the jar from the most recent release.
Building from the source: See the section on this below.

Running

The jar file that you downloaded above is an executable jar. To run, assuming
that you have a Java runtime environment (JRE version 11 or higher)
installed on your system, then do any of the following:

Simply double click the jar file.
From the command line (assuming your current directory is that of the
jar file), you can run with: interactive-bin-packing-X.Y.Z.jar.
Just replace the X.Y.Z with the version number that you downloaded.
Or from the command line, you can similarly run
with: java -jar interactive-bin-packing-X.Y.Z.jar.

Building and Testing the Application (with Maven)

The Interactive Bin Packing Application is built using Maven, which you
can download and install from the
official Apache Maven website.

The root of the repository contains a Maven pom.xml. To build the library,
execute mvn package at the root of the repository, which
will compile all classes, run all tests, and generate jar files of the
application, the sources, and the javadocs. The file names
make this distinction explicit. All build artifacts will then
be found in the directory target.

To include generation of a code coverage report during the build,
execute mvn package -Pcoverage at the root of the repository to
enable a Maven profile that executes JaCoCo during the test phase.

To run all static analysis tools (i.e., SpotBugs, Find Security Bugs,
refactor-first), execute mvn package -Panalysis to enable a Maven
profile that executes the various static analysis tools that we are
using. The SpotBugs html report will be found in the target directory,
or you can use the SpotBugs GUI with: mvn spotbugs:gui -Panalysis. The
refactor-first report will be found in the target/site directory.

To run all of the above: mvn package -P "analysis,coverage".

The jar file of the application is executable, so you then simply
double click it to run.

License

The Interactive Bin Packing Application is licensed under
the GNU General Public License 3.0.

Contribute

Report bugs, suggestions, feature requests, etc via
the issues tracker.
If you would like to contribute to Interactive Bin Packing in any way, such
as reporting bugs, suggesting new functionality, or code contributions
such as bug fixes or implementations of new functionality, then start
by reading
the contribution guidelines.
This project has adopted
the Contributor Covenant Code of Conduct.

Support and Discussion

To obtain support from the maintainers or from other community members, or to discuss ideas
for potential new functionality, we are
using GitHub Discussions. For
support, start a new discussion with the Q&A category. If you would like to discuss ideas for
new functionality before submitting an issue, you can start a discussion with the Ideas category.
You can use the General category for any other community discussions.