From 1084a39fe73f62cb6c02900306bcc24640224830 Mon Sep 17 00:00:00 2001
From: smilingprogrammer <abdulsoburoyewale@gmail.com>
Date: Sat, 24 Jan 2026 15:49:41 +0100
Subject: [PATCH] [ENH] Add example and docs for GFO union grids and array-like
 search spaces

---
 docs/source/user_guide/search_spaces.rst   | 23 ++++++++++++++
 examples/gfo/README.md                     |  1 +
 examples/gfo/search_space_union_example.py | 35 ++++++++++++++++++++++
 3 files changed, 59 insertions(+)
 create mode 100644 examples/gfo/search_space_union_example.py

diff --git a/docs/source/user_guide/search_spaces.rst b/docs/source/user_guide/search_spaces.rst
index d1ada0bc..daeba411 100644
--- a/docs/source/user_guide/search_spaces.rst
+++ b/docs/source/user_guide/search_spaces.rst
@@ -115,6 +115,29 @@ The spacing between values matters. Choose based on how the parameter affects yo
 
 ----
 
+Union Grids and Array-Like Inputs (GFO)
+---------------------------------------
+
+GFO optimizers accept array-like values (for example lists or tuples) and
+sklearn-style union grids.
+
+.. code-block:: python
+
+   from hyperactive.opt.gfo import GridSearch
+
+   # array-like values are coerced internally
+   search_space = {"x": [0, 1], "y": (0, 1)}
+
+   # union grids: list of dicts, each dict is a separate grid
+   search_space = [
+       {"x": [0], "y": [0]},
+       {"x": [1], "y": [2]},
+   ]
+
+   optimizer = GridSearch(search_space=search_space, n_iter=5, experiment=exp)
+
+----
+
 Granularity and Size
 --------------------
 
diff --git a/examples/gfo/README.md b/examples/gfo/README.md
index 6afea084..7a82297c 100644
--- a/examples/gfo/README.md
+++ b/examples/gfo/README.md
@@ -37,6 +37,7 @@ python bayesian_optimization_example.py
 | [BayesianOptimizer](bayesian_optimization_example.py) | Probabilistic | Expensive evaluations | Gaussian Process |
 | [TreeStructuredParzenEstimators](tree_structured_parzen_estimators_example.py) | Bayesian | Mixed parameters | TPE algorithm |
 | [ForestOptimizer](forest_optimizer_example.py) | Surrogate-based | Non-linear problems | Random Forest surrogates |
+| [Union Grid Search Space Example](search_space_union_example.py) | Utility | Grid unions | Union grids + array-like values |
 
 ## Algorithm Categories
 
diff --git a/examples/gfo/search_space_union_example.py b/examples/gfo/search_space_union_example.py
new file mode 100644
index 00000000..9f557782
--- /dev/null
+++ b/examples/gfo/search_space_union_example.py
@@ -0,0 +1,35 @@
+"""
+Union Grid Search Space Example
+
+Demonstrates GFO optimizers accepting:
+- array-like values (lists/tuples coerced to numpy arrays)
+- union grids (list of dicts)
+"""
+
+from hyperactive.experiment.func import FunctionExperiment
+from hyperactive.opt.gfo import GridSearch
+
+
+def objective(params):
+    return params["x"] + params["y"]
+
+
+experiment = FunctionExperiment(objective)
+
+# Array-like values are coerced internally (list + tuple shown here)
+grid_a = {"x": [0, 1], "y": (0, 1)}
+
+# Union grids: each dict is a separate grid; the optimizer runs all and keeps best
+search_space = [
+    grid_a,
+    {"x": [2], "y": [3]},
+]
+
+optimizer = GridSearch(
+    search_space=search_space,
+    n_iter=5,
+    experiment=experiment,
+)
+
+best_params = optimizer.solve()
+print("Best params:", best_params)