huanfachen / james

A JAva MEtaheuristics Search framework

JAMES

JAMES is a modern object-oriented Java framework for discrete optimization using local search metaheuristics. A wide range of generic optimization algorithms are provided that can be applied to any user-defined problem by plugging in a custom solution type and corresponding neighbourhood. Predefined components are included for subset selection.

Modules

The JAMES framework consists of several modules (managed as separate git submodules):

• JAMES Core Module: this module contains the core of the framework. It includes general components for both problem specification and search application. A wide range of generic local search algorithms are provided out-of-the-box, including random descent, steepest descent, tabu search, variable neighbourhood search and parallel tempering. Moreover, the core module contains implementations of specific components for subset selection as well as some specific subset sampling heuristics.

• JAMES Extensions Module: this module extends the core with additional tools for advanced problem specification and search customization. It also provides specific components for some other problem types besides subset selection (e.g. permutation problems) and an automated analysis workflow. Analysis results can be studied and visualized in R using the JAMES Analysis R package.

• JAMES Examples Module: this module provides a series of example problem implementations as described at the website.

Dependencies

JAMES requires Java 8 or later.

To perform logging, JAMES depends on the Simple Logging Facade for Java (SLF4J) which is a general logging API that provides bindings for several popular Java logging frameworks including log4j, JDK 1.4 logging and logback. To send all log messages generated by JAMES to your favorite logging framework, simply include the appropriate binding on your classpath as described in the SLF4J user manual. If no binding is found, a warning

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.

is printed to the console and all log messages are silently discarded. If you do not mind about log messages it is perfectly safe to ignore this warning.

Download and install

To get started with JAMES, read the instructions on the website.

Building from source code

To clone the project including submodules run

git clone --recursive https://github.com/hdbeukel/james.git

Alternatively, perform a regular non-recursive clone followed by

cd james
git submodule init
git submodule update

to fetch the submodules. JAMES is built using Maven, so compiling the source code should be as easy as running

mvn install

from inside the james subdirectory

|-- ...
|-- james
  |-- james-core
  |-- james-examples
  |-- james-extensions
  |-- pom.xml
|-- ...

assuming that Maven has been installed on your computer. This will compile the code, create jar packages and install them in your local Maven repository so that they can be added as dependencies in any other Maven project. After building JAMES, you can also grab the created jar packages from the target directory within each module.

For the examples module, an additional jar including all dependencies is created in james-examples/bin. To print an overview of the implemented examples and the corresponding usage information, execute

$ cd james-examples/bin
$ java -jar james-examples.jar

Documentation

More information, user documentation and examples of how to use the framework are provided at the website. Additional developer documentation is posted on the wiki.

License and copyright

All modules of the JAMES framework are licensed under the Apache License, Version 2.0, see http://www.apache.org/licenses/LICENSE-2.0 and the LICENSE and NOTICE files included with each module.

User forum

Users may post questions on the forum. Instructions for participating without a Google account are available at the website.

Developers

The JAMES framework is developed and maintained by

• Herman De Beukelaer ([email protected])

Please use the forum instead of directly mailing the developers whenever possible, so that others may benefit from or contribute to the discussion as well.