Tutorials

This page provides narrative walkthroughs of the main CUSTOMHyS workflows. Full interactive notebooks are available in the examples/ directory on GitHub.

Notebook	Language	Binder / GitHub
Tutorial_English.ipynb	English	Open on GitHub
Tutorial_Spanish.ipynb	Spanish	Open on GitHub
quickTest.ipynb	English	Open on GitHub

---

Tutorial 1 — Solving a Benchmark Function

Step 1: Choose a problem

CUSTOMHyS ships with dozens of N-dimensional benchmark functions. Each function is a class that exposes a uniform interface:

from customhys import benchmark_func as bf

# List all available functions
print(bf.__all__[:10])
# ['Ackley1', 'Ackley4', 'Alpine1', 'Alpine2', 'Bohachevsky', ...]

# Instantiate a 10-dimensional Sphere function
func = bf.Sphere(10)

# Get the problem dictionary expected by Metaheuristic / Hyperheuristic
prob = {
    "function": func.get_func_val,
    "is_constrained": True,
    "boundaries": func.get_search_range(),
}

Step 2: Pick search operators

Operators are specified as 3-tuples (name, parameters_dict, selector_name). You can inspect all available operators in customhys.operators.

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"),
]

Step 3: Create and run a metaheuristic

from customhys.metaheuristic import Metaheuristic

mh = Metaheuristic(
    prob,
    search_operators,
    num_agents=30,
    num_iterations=100,
    verbose=True,
)
mh.run()

position, fitness = mh.get_solution()
print(f"Best fitness found: {fitness:.6e}")

---

Tutorial 2 — Automatic Metaheuristic Design with the Hyper-heuristic

Instead of hand-picking operators, let the framework search the heuristic space for you.

Step 1: Prepare the problem (same as above)

from customhys import benchmark_func as bf

func = bf.Rastrigin(10)
prob = {
    "function": func.get_func_val,
    "is_constrained": True,
    "boundaries": func.get_search_range(),
}

Step 2: Configure the hyper-heuristic

from customhys.hyperheuristic import Hyperheuristic

parameters = {
    "cardinality": 3,            # max operators per metaheuristic
    "num_iterations": 100,       # iterations each candidate MH runs
    "num_agents": 30,            # population size
    "num_replicas": 30,          # evaluations per candidate
    "num_steps": 100,            # hyper-heuristic search steps
    "stagnation_percentage": 0.3,
    "max_temperature": 200,
    "cooling_rate": 0.05,
}

hh = Hyperheuristic(
    heuristic_space="default.txt",
    problem=prob,
    parameters=parameters,
)

Step 3: Run

hh.run()

The hyper-heuristic evaluates different operator sequences using a Simulated Annealing acceptance criterion and returns the best-performing metaheuristic.

---

Tutorial 3 — Batch Experiments

Use the Experiment class to run many hyper-heuristic searches across problems and dimensions.

Using a JSON configuration file

Configuration files live in customhys/exconf/. Here is a minimal example:

{
  "experiment_name": "my_experiment",
  "experiment_type": "default",
  "heuristic_collection_file": "default.txt",
  "weights_dataset_file": "operators_weights.json",
  "hh_config": {
    "cardinality": 3,
    "num_replicas": 30
  },
  "prob_config": {
    "dimensions": [2, 5, 10],
    "functions": ["Sphere", "Rastrigin", "Ackley1"]
  }
}

from customhys.experiment import Experiment

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

Programmatic configuration

exp = Experiment(
    exp_config={
        "experiment_name": "quick_test",
        "experiment_type": "default",
        "heuristic_collection_file": "default.txt",
    },
    hh_config={"cardinality": 3, "num_replicas": 30},
    prob_config={"dimensions": [2, 5], "functions": ["Sphere"]},
)
exp.run()

---

Tutorial 4 — Creating Custom Operator Collections

Operator collections are plain-text files in customhys/collections/, with one operator tuple per line:

('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')
('differential_mutation', {'expression': 'rand', 'num_rands': 1, 'factor': 0.7}, 'greedy')

You can also generate collections programmatically:

from customhys import operators as op

# Build all operator variants with 5 parameter discretisations
operators = op.obtain_operators(num_vals=5)
op.build_operators(operators, file_name="my_collection")

This writes my_collection.txt into collections/.