Implementing metaheuristic algorithms in Java

Teaching repository with Java code for studying and experimenting with metaheuristic techniques applied to combinatorial optimization problems.

It follows the same four problems through four implementation stages, from plain hand-written programs to a full, reusable metaheuristics framework (Mork). Each stage is a self-contained set of Maven projects, and the documentation explains the progression step by step.

Purpose

This repository is supporting material for:

• understanding the typical structure of a metaheuristic;
• comparing constructive methods and local improvement strategies;
• running reproducible experiments on benchmark instances;
• seeing how the same problems evolve from duplicated code to a shared framework and finally onto a full metaheuristics framework.

The problems

Problem	Metaheuristic
MMDP — MaxMin Diversity Problem	Multi-start local search
CWP — Cutwidth Problem	Multi-start local search
CPH — Capacitated p-hub Problem	Multi-start local search
MDP — Maximum Diversity Problem	Scatter Search

Repository structure

problems/              the code, one folder per implementation stage
  no-framework/        baseline: 4 independent Maven projects (CPH, CWP, MDP, MMDP)
  jmh/                 code reuse: a shared jmh framework + the 4 problem projects
  mork-experiments/    ported to Mork (infrastructure), algorithms hand-written (CPH, CWP, MDP, MMDP)
  mork-full/           algorithms rebuilt from Mork's components (CPH, CWP, MMDP)
docs/                  documentation — start at docs/README.md
  problems/            per-problem description + implementation notes
  mork/                high-level reference guide to the Mork framework

The four stages form a migration path:

1. problems/no-framework — each problem is an independent project; the three simple problems share the same architecture by duplication.
2. problems/jmh — the duplicated code is factored into one reusable jmh (Java MetaHeuristics) framework project that the four problems depend on. See docs/jmh.md.
3. problems/mork-experiments — the projects adopt the Mork framework for everything around the algorithm (instances, objective, time control, reports), while the algorithm stays a hand-written port. See docs/mork-experiments.md.
4. problems/mork-full — the hand-written algorithm is replaced by Mork's reusable components (Constructive, Neighborhood, Move, LocalSearch, MultiStartAlgorithm). MDP (Scatter Search) is left as future work here. See docs/mork-full.md.

Each stage folder has its own README.md (and, for no-framework, one per problem) with the full problem definition, the metaheuristic strategy, a class diagram, and a class-by-class guide.

Documentation

Start at docs/README.md — a guided index that walks through the problems (by increasing complexity) and then the migration stages, and links to the Mork library reference.

Technologies

The code targets Java 25 and is built with Maven.

• no-framework and jmh use only the standard Java API (no notable external dependencies).
• mork-experiments and mork-full depend on the Mork framework (Spring Boot based), which adds reproducibility, parallelization, automatic reports and a web dashboard.

How to run

Requirements

• JDK 25.
• Maven 3.x (the Mork stages also include the mvnw/mvnw.cmd wrapper).
• Optionally an IDE such as VS Code, IntelliJ IDEA, or Eclipse to launch the entry points.

Both no-framework and jmh are plain Java + Maven projects, and every problem is launched the same way: mvn clean compile builds the classes and exec:java runs the chosen mainClass on the project's classpath (Maven fetches exec-maven-plugin automatically on first use).

no-framework

Each problem is an independent Maven project with no external dependencies — just compile and run:

cd problems/no-framework/MMDP      # or CPH, CWP, MDP
mvn clean compile exec:java -Dexec.mainClass=mmdp.Experiment

Project	Entry point
CPH	cph.Experiment
CWP	cwp.Experiment
MMDP	mmdp.Experiment
MDP	ssmdp.Experiment

jmh

The four problem projects depend on the shared jmh framework, so publish it to your local Maven repository once before running any of them:

cd problems/jmh/jmh
mvn clean install

Then compile and run any problem project exactly as in no-framework:

cd problems/jmh/MMDP      # or CPH, CWP, MDP
mvn clean compile exec:java -Dexec.mainClass=mmdp.MMDPExperiment

Project	Entry point
CPH	cph.CPHExperiment
CWP	cwp.CWPExperiment
MMDP	mmdp.MMDPExperiment
MDP	mdp.MDPExperiment

In both stages every Experiment prints a comparison table to standard output and saves each run under an experiments/<datetime>/ folder (one text file per instance and algorithm plus an HTML report.html). These folders are git-ignored.

mork-experiments and mork-full (Mork applications)

These are Spring Boot / Mork applications: package the project and run its self-executable JAR (whose Main calls Mork.start):

cd problems/mork-experiments/MMDP    # any project under problems/mork-experiments or problems/mork-full
mvn clean package
java -jar target/*.jar

On start, Mork opens a live dashboard at http://localhost:8080/ and, when finished, writes an Excel report (plus optional CSV/JSON). See each stage's README.md for the exact Main class names and useful --key=value overrides (instance set, repetitions, time budget).