-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Welcome to the HSDS documentation.
HSDS is a Python library for solving single- and multi-objective optimization problems using the Harmony Search metaheuristic. Its key strength is domain-aware search spaces: variables know their own feasibility rules, catalog lookups, and dependency constraints — the optimizer just calls sample, filter, and neighbor.
| Page | What you'll find |
|---|---|
| Getting Started | Installation, first example, 5-minute quickstart |
| Variable Types | Continuous, Discrete, Integer, Categorical — API and examples |
| Dependent Spaces | What dependent spaces are, when they help, benchmark evidence, decision guide |
| Engineering Spaces | ACIRebar, SteelSection, ConcreteGrade, SoilSPT, SeismicZoneTBDY |
| Optimizer Parameters | Every parameter explained with guidance on how to choose values |
| Advanced Features | Bandwidth narrowing, resume/checkpoint, evaluation cache, CSV logging |
| Custom Variables | Subclass, factory function, plugin registry |
| Algorithm Background | How Harmony Search works, enhancements, references |
| Contributing | How to contribute, run tests, write new spaces |
HSDS can be used as a drop-in Harmony Search optimizer with plain variables and penalty terms — no dependent spaces required. But when your problem has geometric constraints between variables (dimensional ratios, assembly laws, catalog membership), encoding those constraints directly into the search space rather than the objective function can make a measurable difference.
Instead of sampling blindly from the full hypercube and penalizing infeasible results after the fact, a dependent variable simply never produces an infeasible value. Every evaluation cycle is spent on a potentially useful design.
Across six classical engineering benchmarks, this approach reduced mean cost by 1–32% and eliminated solution variance entirely on problems where constraints could be fully embedded analytically. See Dependent Spaces for the full benchmark data, a frank discussion of the limitations, and a practical decision guide for when to use this feature — and when not to.
from hsds import DesignSpace, Continuous, Integer, Minimization
space = DesignSpace()
space.add("x", Continuous(-5.0, 5.0))
space.add("y", Continuous(-5.0, 5.0))
space.add("n", Integer(1, 10))
def objective(h):
fitness = h["x"]**2 + h["y"]**2 + h["n"]
return fitness, 0.0 # (fitness, penalty)
result = Minimization(space, objective).optimize(max_iter=3000)
print(result.best_harmony)
print(result.best_fitness)
pip install pyhsds
Requires Python 3.8+. No mandatory dependencies beyond the standard library.