jmh

jmh

Four classic combinatorial optimization problems implemented as four independent Maven projects on top of a single reusable framework project, jmh (Java MetaHeuristics), using code-reuse techniques (inheritance, generics, interfaces, strategy and template-method patterns).

It is the de-duplicated counterpart of ../no-framework, where the same four problems live as independent projects with heavy copy-paste. Here the duplicated code lives once in jmh and each problem depends on it. The full breakdown of how each duplication was removed is in ../../docs/jmh.md.

Projects

Project	Problem	Sense	Algorithm	Entry point
jmh	— (reusable framework)	—	—	—
CPH	Capacitated p-hub	minimize	multi-start local search	cph.CPHExperiment
CWP	Cutwidth	minimize	multi-start local search	cwp.CWPExperiment
MMDP	MaxMin Diversity	maximize	multi-start local search	mmdp.MMDPExperiment
MDP	Maximum Diversity	maximize	Scatter Search	mdp.MDPExperiment

CPH/CWP/MMDP are solved with the same multi-start local search (a random constructive plus first-/best-improvement). MDP is solved with Scatter Search (its own algorithm stack). All four reuse jmh's instance layer, the optimization sense (Objective) and the experiment reporting.

Layout

jmh/
  jmh/                          # the reusable framework (own Maven project → jar)
    src/main/java/jmh/
      instance/                 # Node, Instance<N>, InstanceFile<I>, InstanceParser<I>, InstancesManager<I>, FormatException
      algorithm/                # Objective, Solution, SwapSolution<N>, Constructive<I>, MultiStartSearch
      algorithm/improvement/    # ImprovementMethod, BestImprovement, FirstImprovement
      experiment/               # ExperimentManager
  CPH/  CWP/  MMDP/              # one project per simple problem, each depending on jmh
    src/main/java/<p>/          # <p>.XxxExperiment  +  <p>.instance.*  +  <p>.algorithm.*
    src/main/resources/instances/   # the problem's own benchmark instances
  MDP/                          # Scatter Search project (reuses jmh's instance + reporting layer,
    src/main/java/mdp/          #   keeps its own algorithm/ and util/ stack)
    src/main/resources/instances/

Each problem project mirrors the package layout of its no-framework counterpart (cph, cph.instance, cph.algorithm, ...); the classes that used to be copied into every problem now come from jmh.

Requirements

• JDK 25
• Maven 3.x

Build

jmh must be installed into the local Maven repository first, because the four problem projects declare it as a dependency:

cd jmh && mvn clean install      # publishes jmh-1.0-SNAPSHOT to ~/.m2
cd ../CPH && mvn clean compile   # or CWP, MMDP, MDP

Run

Each problem has a runnable main (see the table above). From an IDE, open the problem project and run its Experiment class. Each run prints a comparison table to standard output and writes an experiments/<datetime>/ folder in the working directory with one text file per instance and algorithm plus an HTML report (report.html). These outputs are git-ignored.

The CPH/CWP/MMDP Experiment classes use a 10-second timeout per configuration and iterate over every instance of a type, so a full run can take a while — especially CWP, whose objective is costly to evaluate on the larger graphs. (MDP's main is bounded to the first two instances with a shorter budget.)