Downloads & Quick Reference

Important

This repository is self-contained. After cloning with --recursive, run ./setup.sh to set up the environment automatically.

Setup Script

Run after cloning to set up the environment:

git clone --recursive https://github.com/NAICNO/wp7-UC6-multimodal-optimization.git
cd wp7-UC6-multimodal-optimization
./setup.sh
source activate-mmo.sh

Execution Modes

Mode	Description
Python API (Sequential)	`MultiModalMinimizer` – runs single-threaded
Python API (Parallel)	`MultiModalMinimizerParallel` – uses all CPU cores (3.2x speedup)
Interactive Notebook	`demonstrator.ipynb` – visual exploration with plots

Core API Parameters

from mmo.minimize_parallel import MultiModalMinimizerParallel
from mmo.domain import Domain

optimizer = MultiModalMinimizerParallel(
    f=function,              # Callable: array → scalar
    domain=domain,           # Domain(boundary=[[lb], [ub]])
    budget=50000,            # Max function evaluations
    max_iter=50,             # Max outer iterations
    n_jobs=-1,               # -1 = all cores
    verbose=1                # 0=silent, 1=summary, 2=GA, 3=CMA
)

Parameter	Type	Default	Description
`f`	callable	required	Objective function (d-dim array → scalar)
`domain`	Domain	required	Search space bounds
`budget`	int	inf	Maximum function evaluations
`max_iter`	int	inf	Maximum outer iterations
`n_jobs`	int	-1	CPU cores (-1 = all, >0 = specific)
`verbose`	int	0	Verbosity: 0=silent, 1=summary, 2=GA details

CEC2013 Benchmark Functions

ID	Name	Dim	Optima	Budget
1	Five-Uneven-Peak	1D	2	50k
2	Equal Maxima	1D	5	50k
4	Himmelblau	2D	4	50k
5	Six-Hump Camel Back	2D	2	50k
6	Shubert	2D	18	200k
7	Vincent	2D	36	200k
8-20	Higher dimensions	3-20D	6-216	400k

Load any function: CEC2013(id) where id = 1-20

Example Commands

Quick Test (Sequential)

from mmo.minimize import MultiModalMinimizer
from mmo.domain import Domain
from cec2013.cec2013 import CEC2013

f = CEC2013(4)  # Himmelblau
dim = f.get_dimension()
lb = [f.get_lbound(k) for k in range(dim)]
ub = [f.get_ubound(k) for k in range(dim)]
domain = Domain(boundary=[lb, ub])

optimizer = MultiModalMinimizer(f=f, domain=domain, budget=50000, verbose=1)

for result in optimizer:
    print(f"Iter {result.number}: {result.n_sol} solutions found")

Parallel Optimization (Recommended)

from mmo.minimize_parallel import MultiModalMinimizerParallel
from mmo.domain import Domain
from cec2013.cec2013 import CEC2013

f = CEC2013(10)  # Modified Rastrigin
dim = f.get_dimension()
lb = [f.get_lbound(k) for k in range(dim)]
ub = [f.get_ubound(k) for k in range(dim)]
domain = Domain(boundary=[lb, ub])

optimizer = MultiModalMinimizerParallel(
    f=f,
    domain=domain,
    budget=50000,
    n_jobs=-1,  # Use all CPU cores
    verbose=1
)

for result in optimizer:
    print(f"Solutions: {result.n_sol}, Evaluations: {result.n_fev}")

Run Test Scripts

# Verify installation
python test_mmo.py

# Benchmark parallel vs sequential (F4, F5, F10: ~5 minutes)
python test_parallel_comparison.py

# Full benchmark suite (F4-F14: ~15-20 minutes)
python test_full_benchmark_parallel.py

Interactive Jupyter Notebook

# Start Jupyter Lab in tmux
tmux new -s jupyter
cd ~/wp7-UC6-multimodal-optimization
source activate-mmo.sh
jupyter lab --no-browser --ip=0.0.0.0 --port=8888
# Detach with Ctrl+B, then D

# Create SSH tunnel (local machine)
ssh -v -N -L 8888:localhost:8888 -i /path/to/key.pem ubuntu@<VM_IP>

# Open: http://localhost:8888/lab/tree/demonstrator.ipynb

Performance

Parallelization Speedup (16-core NAIC VM):

Function	Speedup	Notes
Overall Average	3.2x	Across F4-F14
Himmelblau (F4)	1.95x	4 optima
Six-Hump Camel (F5)	1.21x	2 optima
Modified Rastrigin (F10)	4.08x	12 optima
Efficiency	20%	Of ideal 16x

Peak Ratio (PR): Percentage of global optima found (1.0 = perfect)

Common Issues

Issue	Solution
`ModuleNotFoundError: cec2013`	Use `source activate-mmo.sh` (sets PYTHONPATH)
`ModuleNotFoundError: mmo`	Use `source activate-mmo.sh` (sets PYTHONPATH)
Submodules not cloned	Run `git submodule update --init --recursive`
Import errors	Verify venv activated: `which python`

For AI Coding Assistants

If you’re using an AI coding assistant (Claude Code, GitHub Copilot, Cursor, etc.), the repository includes machine-readable instruction files:

AGENT.md – Markdown format (human and agent readable)
AGENT.yaml – YAML format (structured data for programmatic parsing)

These files contain step-by-step instructions that agents can follow to:

Set up the environment on the VM
Run the Jupyter notebook
Execute benchmark tests
Verify optimization results

Quick prompt for your AI assistant:

Read AGENT.md and help me run the multi-modal optimization
demonstrator on my NAIC VM.
VM IP: <your_vm_ip>
SSH Key: <path_to_your_key.pem>

The agent will execute the setup and run experiments based on the structured instructions.

References

Paper: Johannsen et al. (2022), “A scalable, hybrid genetic algorithm for continuous multimodal optimization in moderate dimensions”, Nordic Machine Intelligence

Algorithm: SHGA (Scalable Hybrid Genetic Algorithm) - combines Deterministic Crowding GA (global search) with CMA-ES (local refinement)