A guided path through this repository, from plain hand-written implementations of four optimization problems to a full, reusable metaheuristics framework. Read the documents in the order below — each stage builds on the previous one.
The code that each document describes lives under ../problems, organized as one
folder per migration stage:
| Stage | Code | What it is |
|---|---|---|
| Baseline | problems/no-framework |
Four independent Maven projects, no shared code. |
| Code reuse | problems/jmh |
The duplication factored into a small reusable jmh framework. |
| Onto Mork (infrastructure) | problems/mork-experiments |
Ported to the Mork framework, algorithms still hand-written. |
| Onto Mork (components) | problems/mork-full |
Algorithms rebuilt from Mork's reusable components. |
Each problem has a description (problem definition, formulation and algorithm design) and an
implementation document (class diagram and code walk-through). They describe the
problems/no-framework baseline and are ordered from the simplest to
the most complex:
| # | Problem | Metaheuristic | Description | Implementation |
|---|---|---|---|---|
| 1 | MaxMin Diversity (MMDP) | Multi-start local search | mmdp-description.md | mmdp-implementation.md |
| 2 | Cutwidth (CWP) | Multi-start local search | cwp-description.md | cwp-implementation.md |
| 3 | Capacitated p-hub (CPH) | Multi-start local search | cph-description.md | cph-implementation.md |
| 4 | Maximum Diversity (MDP) | Scatter Search | mdp-description.md | mdp-implementation.md |
The first three share the same multi-start local search architecture (a random constructive plus best-/first-improvement local search); MDP is the most involved, solved with a full Scatter Search.
- Java MetaHeuristics framework (JMH) — how the
problems/jmhvariant removes, one duplication at a time, the code repeated across the four baseline projects by moving it into a reusablejmh(Java MetaHeuristics) framework, using inheritance, generics, the strategy pattern and template methods. Each step shows the before/after code.
- mork-experiments.md — From the
jmhproto-framework to Mork. How theproblems/mork-experimentsprojects adopt Mork for everything around the algorithm (instance loading, objective, reproducibility, time control, experiment runner, reports) while the algorithm stays a hand-written port. - mork-full.md — From hand-written algorithms to Mork's reusable components.
The next step: keeping the model identical, the
problems/mork-fullprojects replace the hand-written algorithm with Mork's components (Constructive,Neighborhood,Move,LocalSearch,MultiStartAlgorithm).
A high-level summary of the Mork framework itself, compiled from its source code and official documentation — useful background for stages 3 and 4:
- mork/README.md — overview, module architecture, requirements and the documentation map.
- 01 — Basic concepts — the domain model (
Instance,Solution,Objective,Move,Neighborhood, validation). - 02 — Algorithmic components —
Algorithm, constructives, improvers, shakes and the built-in metaheuristics. - 03 — Experimentation and features — experiments, configuration, reproducibility, reports, dashboard, autoconfig, instances.
- 04 — Getting-started guide — project generator, structure and a step-by-step tutorial.
Start here → MMDP — Description