Getting Started

This guide walks through local execution, artifact inspection, reporting, and dashboard usage with the current EDAF v3 stack.

1) Prerequisites

  • Java 21+
  • Maven 3.9+
  • Optional: Docker + Docker Compose (for containerized stack)

Verify:

java -version
mvn -version
docker --version
docker compose version

2) Build Everything

From repository root:

mvn -q clean test

If you only need CLI packaging quickly:

mvn -q -pl edaf-cli -am package

3) Understand the Wrapper

./edaf is the primary entrypoint.

  • It checks if edaf-cli/target/edaf-cli.jar exists.
  • If missing or stale relative to source changes, it rebuilds edaf-cli and dependencies.
  • It then launches the CLI jar.

Usage:

./edaf --help

4) Run Your First Experiment

Start with OneMax + UMDA:

./edaf run -c configs/umda-onemax-v3.yml

Expected console behavior:

  • banner with run id, algorithm, model, problem, seed
  • progress bar by iteration
  • periodic summary rows controlled by observability.metricsEveryIterations
  • final summary (best fitness, best genotype summary, artifacts)

5) Inspect Artifacts

Typical outputs:

  • results/<run-id>.csv (iteration metrics)
  • results/<run-id>.jsonl (event stream)
  • edaf-v3.log (rotating structured file log)
  • results/checkpoints/... (if checkpointing enabled)
  • DB rows (if db sink enabled)

Example quick checks:

ls -la results
head -n 5 results/umda-onemax-v3.csv
head -n 5 results/umda-onemax-v3.jsonl

6) Generate Reports

From persisted DB state:

./edaf report --run-id umda-onemax-v3 --out reports --db-url jdbc:sqlite:edaf-v3.db

Formats:

./edaf report --run-id umda-onemax-v3 --out reports --formats html,latex

7) Validate Config Before Running

./edaf config validate configs/umda-onemax-v3.yml
./edaf config validate configs/batch-v3.yml

Validation includes:

  • strict YAML field validation (unknown fields rejected)
  • bean constraints (required fields, min values)
  • semantic compatibility checks (representation/model/algorithm families)

8) Run Multiple Experiments via Batch

./edaf batch -c configs/batch-v3.yml
./edaf batch -c configs/batch-benchmark-core-v3.yml
./edaf batch -c configs/batch-benchmark-crypto-v3.yml
./edaf batch -c configs/batch-stat-sample-v3.yml

Batch file format:

experiments:
  - umda-onemax-v3.yml
  - gaussian-sphere-v3.yml
  - ehm-tsp-v3.yml

Paths are resolved relative to the batch file location.

configs/batch-benchmark-core-v3.yml runs the broader serious suite: OneMax, Knapsack, MAX-SAT, TSPLIB TSP, CEC2014, ZDT, DTLZ, Nguyen SR.

configs/batch-benchmark-crypto-v3.yml runs cryptographic boolean-function variants: truth-table, permutation-balanced, token-tree, and multi-objective.

configs/batch-stat-sample-v3.yml demonstrates 30-run style repetition campaigns per experiment using defaultRepetitions, seedStart, and automatic -rXX run-id suffixing.

9) Resume from Checkpoint

Enable checkpoints in config:

run:
  checkpointEveryIterations: 10

Then resume:

./edaf resume --checkpoint results/checkpoints/gaussian-sphere-v3-iter-50.ckpt.yaml

Checkpoint payload stores:

  • config snapshot
  • run/iteration/evaluation metadata
  • population
  • model state (for supported models)
  • RNG snapshot (deterministic replay)

10) Start Web Dashboard Locally

By default web uses SQLite DB at jdbc:sqlite:edaf-v3.db. Run this from a terminal in <repo-root>:

./scripts/run-web-local.sh

Stop the server with Ctrl+C in that terminal.

Open:

Alternative command if Maven prefix resolution fails:

EDAF_WEB_PORT=7080 EDAF_DB_PATH="$(pwd)/edaf-v3.db" ./scripts/run-web-local.sh

11) Run COCO Smoke Campaign

./edaf coco run -c configs/coco/bbob-smoke-v3.yml

Then inspect:

  • campaign rows in DB (coco_campaigns, coco_trials, coco_aggregates)
  • campaign pages in web UI (/coco, /coco/{campaignId})
  • generated campaign report in reports/coco/

12) Run Full Docker Stack

docker compose up --build

This starts:

  • PostgreSQL (db)
  • dashboard (web)
  • one runner process (runner) using configs/docker/umda-onemax-postgres-v3.yml

Stop:

docker compose down

Stop and remove volumes:

docker compose down -v

Visual Summary

flowchart LR
    A["EDAF"] --> B["getting started"]
    B --> C["Configure"]
    B --> D["Execute"]
    B --> E["Inspect"]
    E --> F["Iterate"]

Estimation of Distribution Algorithms Framework
Copyright (c) 2026 Dr. Karlo Knezevic
Licensed under the Apache License, Version 2.0.