Architecture

CUSTOMHyS is organised into a hierarchy of modules that mirror the three levels of the hyper-heuristic methodology: low, mid, and high level heuristics.

---

Module Overview

🤯 Benchmark Functions (benchmark_func)

A library of N-dimensional continuous benchmark functions used to evaluate optimisation methods. Every function is implemented as a class with a unified interface (get_func_val, get_search_range, get_optimal).

The catalogue includes classical families such as Ackley, Rastrigin, Rosenbrock, Schwefel, Griewank, and many more — plus the CEC 2005 suite when the optproblems package is available.

from customhys import benchmark_func as bf

func = bf.Rastrigin(10)          # 10-dimensional Rastrigin
bounds = func.get_search_range() # ([-5.12, ...], [5.12, ...])
f_opt  = func.get_optimal()      # known global minimum value

Source: customhys.benchmark_func

---

👯‍♂️ Population (population)

A Population object represents a set of agents in a search space. It manages positions, velocities, fitness values, and selection mechanisms. Populations do not decide how to move — that is the job of search operators — but they know when to accept a new position via a selector (greedy, metropolis, probabilistic, or all).

Key responsibilities:

• Initialise agents with different schemes (random, Sobol, Halton, LHS, …)

• Evaluate fitness for all agents

• Update global / particular / population best positions

• Constrain agents to the feasible domain

from customhys.population import Population

pop = Population(boundaries=([-5]*10, [5]*10), num_agents=30)
pop.initialise_positions("random")

Source: customhys.population

---

🦾 Search Operators (operators)

A collection of 13 search operators (perturbators) extracted from well-known metaheuristics. Each operator is a function that modifies the population’s positions in place. Operators are the building blocks that the hyper-heuristic combines to assemble new metaheuristics.

Available operators:

Operator	Alias	Origin
random_search	RS	Random Search
random_sample	RX	Random Sampling
random_flight	RF	Lévy Flights
local_random_walk	RW	Random Walk
central_force_dynamic	CF	Central Force Optimisation
differential_mutation	DM	Differential Evolution
firefly_dynamic	FD	Firefly Algorithm
genetic_crossover	GC	Genetic Algorithm
genetic_mutation	GM	Genetic Algorithm
gravitational_search	GS	Gravitational Search
spiral_dynamic	SD	Spiral Dynamics
swarm_dynamic	PS	Particle Swarm Optimisation
linear_system	LS	Linear System

Each operator is paired with a selector that decides how agents accept the proposed move: greedy, all, metropolis, or probabilistic.

("swarm_dynamic", {"self_conf": 2.54, "swarm_conf": 2.56, "version": "inertial"}, "greedy")

Source: customhys.operators

---

🤖 Metaheuristic (metaheuristic)

A Metaheuristic object takes a problem definition and a sequence of (operator, parameters, selector) tuples and runs a population-based search.

from customhys.metaheuristic import Metaheuristic

mh = Metaheuristic(prob, search_operators, num_agents=30, num_iterations=100)
mh.run()
position, fitness = mh.get_solution()

Internally, at each iteration the metaheuristic applies each operator in sequence, evaluates fitness, updates the population using the corresponding selector, and tracks historical data (best fitness, centroid, radius).

Source: customhys.metaheuristic

---

👽 Hyper-heuristic (hyperheuristic)

The Hyperheuristic class sits one level above metaheuristics. Given a collection of search operators (the heuristic space), it explores which combination — and in what order — produces the best metaheuristic for a specific problem.

The exploration is driven by a Simulated Annealing strategy that controls the acceptance of candidate metaheuristics. Key parameters include the number of replicas, the cooling schedule, and the stagnation criterion.

When TensorFlow is available, the hyper-heuristic can also leverage a neural-network model to predict promising operator sequences (see customhys.machine_learning).

Source: customhys.hyperheuristic

---

🏭 Experiment (experiment)

The Experiment class orchestrates batch runs of hyper-heuristic procedures across multiple benchmark functions and dimensionalities. Configuration is provided via JSON files stored in the exconf/ directory.

from customhys.experiment import Experiment

exp = Experiment(config_file="demo.json")
exp.run()

Experiments can be parallelised across CPU cores automatically.

Source: customhys.experiment

---

🗜️ Tools (tools)

Utility functions shared across the framework: JSON I/O, statistical summaries, meta-skeleton printing, operator weight processing, and more.

Source: customhys.tools

---

🧠 Machine Learning (machine_learning)

Wrappers for TensorFlow-based neural network models that learn to predict good operator sequences from historical hyper-heuristic data. This module provides:

• DatasetSequences — processes raw operator sequences and fitness data into training samples.

• ModelPredictor — a configurable feed-forward neural network for sequence prediction.

Source: customhys.machine_learning

---

🌡️ Characterisation (characterisation) — work in progress

Metrics for characterising benchmark function landscapes (e.g., via Lévy-walk sampling and kernel density estimation).

Source: customhys.characterisation

---

📊 Visualisation (visualisation) — work in progress

Plotting utilities for experiment results (violin plots of fitness distributions, performance overviews).

Source: customhys.visualisation