Getting Started

This guide walks you through your first steps with CUSTOMHyS β€” from solving a simple optimisation problem with a metaheuristic to running a full hyper-heuristic search.

Prerequisites

  • Python 3.10 or newer

  • Basic familiarity with continuous optimisation concepts

A Minimal Example

The simplest way to use CUSTOMHyS is to create a Metaheuristic that solves a benchmark function:

from customhys import benchmark_func as bf
from customhys.metaheuristic import Metaheuristic

# 1. Choose a benchmark problem (Sphere function in 5 dimensions)
problem = bf.Sphere(5)
prob = {
    "function": problem.get_func_val,
    "is_constrained": True,
    "boundaries": problem.get_search_range(),
}

# 2. Define a sequence of search operators
#    Each operator is a tuple: (name, parameters, selector)
search_operators = [
    ("random_search", {"scale": 0.01, "distribution": "uniform"}, "greedy"),
    ("swarm_dynamic", {
        "self_conf": 2.54,
        "swarm_conf": 2.56,
        "version": "inertial",
        "inertial_weight": 0.7,
    }, "all"),
]

# 3. Create and run the metaheuristic
mh = Metaheuristic(prob, search_operators, num_agents=30, num_iterations=100)
mh.run()

# 4. Retrieve the best solution found
position, fitness = mh.get_solution()
print(f"Best position: {position}")
print(f"Best fitness:  {fitness:.6e}")

Running a Hyper-Heuristic

Instead of manually choosing operators, let the Hyperheuristic class discover the best combination automatically:

from customhys import benchmark_func as bf
from customhys.hyperheuristic import Hyperheuristic

# Define the problem
problem = bf.Rastrigin(10)
prob = {
    "function": problem.get_func_val,
    "is_constrained": True,
    "boundaries": problem.get_search_range(),
}

# Configure the hyper-heuristic
parameters = {
    "cardinality": 3,
    "num_iterations": 100,
    "num_agents": 30,
    "num_replicas": 30,
    "num_steps": 100,
    "stagnation_percentage": 0.3,
    "max_temperature": 200,
    "cooling_rate": 0.05,
}

# Run the hyper-heuristic (uses the default operator collection)
hh = Hyperheuristic(
    heuristic_space="default.txt",
    problem=prob,
    parameters=parameters,
)
hh.run()

The hyper-heuristic will evaluate many candidate metaheuristics and return the best sequence of search operators for the given problem.

Running a Full Experiment

For batch experiments across multiple benchmark functions and dimensions, use the Experiment class with a JSON configuration file:

from customhys.experiment import Experiment

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

See the User Guide for a deeper dive into each module.

What’s Next?