## Combean## JavaBeans for Combinatorial Optimizationincludes
Groovy mathematical modelling language |
hosted at |

About Combean Grooml License Features Environment Download Installation Documentation Support

**Mission Statement of Combean:** Combean is a Java framework (including some Groovy code) for combinatorial
structures like graphs or linear programs and optimization algorithms working
with these structures. The objective of Combean is to integrate existing
proven optimization packages as well as new implementations through a set of
lean Java interfaces. Using a JavaBeans-based configuration mechanism, solvers
for real-world optimization problems can be generated by plugging together the
best-performing components. Combean as 'glue' between optimization packages
leads to more interoperable, adaptable and flexible solutions.

You shall find Combean useful if you want to achieve one of the following objectives:

- You develop software that uses optimization technology. You would like to use existing optimization codes and you are looking for a possibility to easily integrate your code with them. You want to be flexible to exchange one solver with another as your project moves forward.
- You have written a library that provides data structures or algorithms for optimization problems (combinatorial optimization or mathematical programming). Now you are searching for a way to integrate your library with other existing frameworks and to improve the interoperability of your library.
- You want to use linear programming to solve a real world application and you would like to transform your optimization problem into a linear programming model that is easy to use and compatible with many existing solvers (both open source and commercial).
- You are teaching optimization algorithms and you are searching for a programming framework which integrates standard data structures and algorithms and a way that captures the essence of the optimization problem and results in clear code.

Combean works very well together with its sister project swIMP. swIMP makes existing C or C++ optimization codes available under Java and thus largely increases the set of available solvers for Combean. You can use swIMP if you are working on a POSIX-compatible UNIX platform. In particular, swIMP provides a Java-wrapper for the Open Solver Interface of the COIN-OR-project that allows access to numerous well-known solvers, like Cplex, XPRESS, GLPK or Clp.

*Keywords:* Combean, swIMP, Java, Groovy, Combinatorial Optimization, Interfaces, Framework, Graph Theory, Linear Programming, LP, Integer Programming, IP, MIP, Operations Research, Mathematical Modelling Language, Open Source.

Grooml is a part of Combean. It provides an interpreter for a simple algebraic modelling language (currently LP- and MIP-models are supported; in the future this may be extended to QPs etc.). The Grooml-models can be solved with all solvers that are supported by Combean.

Grooml is written in Groovy. It uses several dynamic object orientation features of Groovy (closures, pretended methods and properties, operator overloading, etc.) for defining a domain-specific language for modelling mathematical programs. Even though Grooml-models look very much like models in other mathematical modelling languages, they are pure Groovy code, which can be compiled to class-files for the Java virtual machine and which is fully interoperable with other Groovy and Java code. Thus, Grooml integrates mathematical programming with a modern general-purpose programming language and the wealth of tools and libraries in the Java and Groovy world.

To get started with Grooml, have a look at the Grooml manual (pdf-version)

Combean is distributed under the GNU General Public License.

The interfaces for combinatorial structures and optimization algorithms and some utility classes are also distributed binary form under a permissive license that allows you to redistribute it and to combine it with closed-source code. The purpose of this is to allow owners of commercial closed-source code to write wrappers based on the Combean interfaces, e.g., in order to provide access to commercial solvers for Combean users.

The documentation is distributed under the GNU Free Documentation License

One main contribution of Combean is a set of interfaces for combinatorial data structures, like various kinds of graphs, and optimization algorithms, like shortest paths, flows or linear programming. The classes in Combean collaborate only through these interfaces such that the actual implementation can be easily exchanged.

The interfaces for linear programming are already quite mature, whereas the interfaces for graph theoretic problems are still under ongoing development and likely to change.

Currently, Combean works together with the following libraries (in brackets you find the version with which the current release of Combean has been tested and a short description of the license):

- swIMP (0.9, LGPL),
- JGraph (5.9.2, GPL),
- OR-Objects (1.2.4, freeware),
- QSOpt (1.0, Java version, free for research or education purposes).

Combean provides a framework for the transformation of problems in a specific application domain into linear programming models that can then be loaded into and solved by standard linear programming solvers. The Combean documentation contains a detailed example how to use this feature.

An even more convenient way for modelling LPs and MIPs is provided by the modelling language Grooml that works on top of that framework.

This is what Ohloh has to say about Combean:

The Java-code has been compiled and tested under Version 1.5.0 of Sun Java 2 Platform, Standard Edition (J2SE) .

In addition to a Java runtime environment, you need some third-party jars in your CLASSPATH (some of which are not part of the Combean distribution for licensing reasons). Since the full list of dependencies is quite long, please read it first and decide which of them you really need. Typically, if you only want to use Combean and you are not going to modify the Combean source code, you only need very few additional software packages. In this case we recommend to install Groovy, Jakarta Commons, Log4j, as well as the mathematical programming software packages OR-Objects, QSOpt, swIMP and COIN-OR (for details please see below).

- The Groovy library (tested with version 1.5.6),
- The 'Collections' component (tested with 3.2), the 'Lang' component (tested with 2.0) and the 'Logging' component (tested with 1.0.4) of Jakarta Commons,
- Log4J (tested with 1.2.8)

- Pure Java solvers:
- OR-Objects (1.2.4, freeware),
- QSOpt (1.0, Java version, free for research or education purposes).
- It is strongly recommended to also install Since COIN is software written in C and C++, this will involve some more compiling and installation effort. However, without the MIP-solvers that come with COIN you cannot use all features of Combean.

- JUnit (tested with 3.8.1) to execute the automatic unit test suite.
- Ant jars (ant.jar and ant-launcher.jar tested with 1.7.0) - used by Groovy test suite
- The Combean distribution already comes with the following packages used by the test suite: Please consider the licenses that come with these packages when you are using or redistributing them together with Combean.
- The test suite (and so far also the build process for the jar files) currently depends on the solvers OR-Objects and QSOpt (see above)

- Apache Ant (tested with 1.7.0) for driving the whole build process,
- Cobertura (tested with 1.9) for test coverage,
- UMLGraph (tested with 4.8) for creating UML diagrams with Javadoc.

Combean is available for download at the Sourceforge project page.

There are two variants of the Combean release:

- The complete source distribution with all features (distributed under the GPL),
- A binary distribution of the Combean interfaces (distributed under a permissive license that allows the combination of the jars with closed-source software);

Combean is in alpha state. The code has been tested with a comprehensive automatic test suite and is supposed to run rather stable. The API may still be subject to heavy refactoring and major planned features (especially graph theoretic algorithms) are still missing. However, the part of the software that deals with LP models and the Grooml modelling language are already quite mature and usable by 'Non-Combean hackers'.

*Please note: Combean is distributed with ready-made jar files. So, if you do not change the Combean source, you can simple put the class files in your CLASSPATH and ignore the rest of this section.*

The Combean jar-file is generated by executing `ant build`

in the project root directory.

Combean automatically detects which packages that Combean provides wrappers for are installed (see the Features for a complete list). The command `ant showfeatures`

show you which packages Combean has detected and for which the wrappers have been compiled and included in the jar-file.

After `ant build`

has been executed, you find the jar-file in the dist-directory. It is ready for use. Make sure to include it in your CLASSPATH.

If some dependencies cannot be resolved during the build, please have a look at the paths defined in `project.properties`

and adjust them as needed.

If you have all packages installed that the automatic test suite depends on (see the list of dependencies), you can verify the content of the jar-file by running the automatic test suite. This is done by executing `ant testjar`

.

Combean comes with the following documentation:

- Javadoc for the Java code
- Groovydoc for the Groovy code
- JUnit test report
- Cobertura test coverage report

- Grooml manual (html-version)
- Slides for a href="http://meetings.informs.org/DC08">INFORMS 2008, Washington, DC
- A detailed description of the LP modelling feature and an example how to use this feature.
- More to come ...