hone-python 0.9.0__py3-none-any.whl

hone/optimizers/genetic/optimizer.py

@@ -0,0 +1,184 @@
+import math
+from functools import partial
+from typing import Callable
+
+from hone.config import GeneticOptimizerConfig, SelectionMethod
+from hone.optimizers.base import Individual, Optimizer, _fitness, _key
+from hone.parameters import ChoiceParameter, FixedParameter, RangeParameter
+
+from . import selection
+from .variation import blend_crossover, mutate, uniform_crossover
+
+
+# Adaptive mutation: how much a child's mutation size varies from its parents', divided by the
+# square root of the number of variables, and the bounds on the size. Chosen on the benchmark.
+STEP_SPREAD = 0.5
+MIN_STEP = 1e-9
+MAX_STEP = 0.5
+# A child that repeats a point already asked for is mutated again, one gene at a time, up to this many times.
+REPEAT_TRIES = 10
+
+
+class GeneticOptimizer(Optimizer):
+    """Function optimizer that employs an implementation of the genetic algorithm.
+    The genetic algorithm is a metaheuristic inspired by the process of natural selection.
+    It is a population-based algorithm that uses the concepts of selection, crossover, and mutation
+    to evolve a population of individuals towards a solution to the objective function.
+
+    The first generation is any initial points, then random candidates. Each later generation
+    keeps the previous one's elites unchanged, then fills the rest of the population with
+    children: two parents are selected, crossed over, and mutated. Failed evaluations are
+    never elites or parents.
+
+    With blend crossover, each range value of a child is drawn from between its parents' values,
+    and a little beyond, rather than copied from one of them; choices and fixed values are
+    still copied.
+
+    With adaptive mutation, each individual carries its own mutation size, as in evolution
+    strategies: a child takes the geometric mean of its parents' sizes, varied at random, so
+    individuals with sizes that suit the problem's current scale breed more.
+
+    Without noise, a child that repeats a point already asked for, such as a copy of a parent
+    that no mutation touched, has one gene at a time mutated again until it is new, since
+    evaluating it again would only spend the budget. With noise, repeats stay: they refine
+    the point's average.
+
+    Args:
+        search_space: The parameters to optimize over, as a SearchSpace or a list of parameters.
+        config: A GeneticOptimizerConfig. Defaults are used if omitted.
+
+    Example:
+
+        >>> from hone import GeneticOptimizer, GeneticOptimizerConfig, RangeParameter
+        >>>
+        >>> def objective_function(x, y):
+        >>>     return x**2 + y**2
+        >>>
+        >>> x = RangeParameter("x", -5, 5)
+        >>> y = RangeParameter("y", -5, 5)
+        >>>
+        >>> optimizer = GeneticOptimizer(search_space=[x, y], config=GeneticOptimizerConfig(threshold=0.01))
+        >>> result = optimizer.optimize(objective_function)
+    """
+    config_class = GeneticOptimizerConfig
+    config: GeneticOptimizerConfig
+
+    def reset(self) -> None:
+        super().reset()
+        # The parameters a mutation can change.
+        self._movable = [
+            p.name for p in self.search_space.parameters
+            if not isinstance(p, FixedParameter)
+            and not (isinstance(p, RangeParameter) and p.maximum == p.minimum)
+            and not (isinstance(p, ChoiceParameter) and len(p.choices) == 1)
+        ]
+        variables = sum(
+            not isinstance(p, FixedParameter) and not (isinstance(p, RangeParameter) and p.maximum == p.minimum)
+            for p in self.search_space.parameters
+        )
+        if self.config.mutation_rate is not None:
+            self._mutation_rate = self.config.mutation_rate
+        else:
+            self._mutation_rate = 0.1 if self.config.noise else max(0.1, 1 / max(variables, 1))
+        self._adaptive = self.config.adaptive_mutation if self.config.adaptive_mutation is not None else not self.config.noise
+        self._step_spread = STEP_SPREAD / math.sqrt(max(variables, 1))
+        self._steps: dict[Individual, float] = {}  # each individual's mutation size, with adaptive mutation
+        self._asked: set[tuple] = set()  # every point put in a population, so children can avoid repeating one
+
+    def _select(self, individuals: list[Individual]) -> Individual:
+        select: Callable[..., Individual]
+        match self.config.selection_method:
+            case SelectionMethod.TOURNAMENT:
+                select = partial(selection.tournament, size=self.config.tournament_size, p=self.config.tournament_p)
+            case SelectionMethod.ROULETTE:
+                select = selection.roulette
+        return select(individuals, self.rng, maximize=self.config.maximize)
+
+    def _child(self, parents: list[Individual], generation: int, niche: dict | None = None) -> Individual:
+        """A child of two parents selected from parents. A niche fixes the child's choice parameters."""
+        first, second = self._select(parents), self._select(parents)
+        if self.config.blend_crossover:
+            params = blend_crossover(
+                first.params, second.params, self.search_space, self.rng, rate=self.config.crossover_rate, alpha=self.config.blend_alpha
+            )
+        else:
+            params = uniform_crossover(first.params, second.params, self.rng, rate=self.config.crossover_rate)
+        step = self.config.mutation_scale
+        if self._adaptive:
+            inherited = math.sqrt(self._step(first) * self._step(second))
+            step = min(max(inherited * math.exp(self.rng.normal(0, self._step_spread)), MIN_STEP), MAX_STEP)
+        params = mutate(params, self.search_space, self.rng, rate=self._mutation_rate, scale=step)
+        params = {**params, **(niche or {})}
+        if not self.config.noise:
+            params = self._new_point(params, step, niche)
+        child = Individual(params=params, generation=generation)
+        if self._adaptive:
+            self._steps[child] = step
+        return child
+
+    def _new_point(self, params: dict, step: float, niche: dict | None) -> dict:
+        """params, mutated again a gene at a time while they repeat a point already asked for.
+
+        Gives up after REPEAT_TRIES, which only happens when the space has few points left.
+        A niche's choices stay fixed.
+        """
+        movable = [name for name in self._movable if not niche or name not in niche]
+        for _ in range(REPEAT_TRIES):
+            if not movable or _key(params) not in self._asked:
+                break
+            name = movable[self.rng.integers(len(movable))]
+            params = {**params, name: self.search_space[name].mutate(params[name], self.rng, step)}
+        self._asked.add(_key(params))
+        return params
+
+    def _step(self, individual: Individual) -> float:
+        return self._steps.get(individual, self.config.mutation_scale)
+
+    def _niche_children(self, parents: list[Individual], count: int, generation: int) -> list[Individual]:
+        """Up to count children bred within niches: parents sharing every choice parameter's value.
+
+        Each niche gets an equal share, so every combination of choices still in the
+        population keeps tuning its own numbers instead of being outbred by the leader.
+        """
+        choices = [p.name for p in self.search_space.parameters if isinstance(p, ChoiceParameter) and len(p.choices) > 1]
+        if not choices or count == 0:
+            return []
+        niches: dict[tuple, list[Individual]] = {}
+        for parent in parents:
+            niches.setdefault(tuple(repr(parent.params[name]) for name in choices), []).append(parent)
+        # With more niches than children, the niches with the fittest members breed.
+        ranked = sorted(niches.values(), key=lambda members: _fitness(self._ranked(members)[0]), reverse=self.config.maximize)
+        per_niche = max(1, count // len(ranked))
+        children: list[Individual] = []
+        for members in ranked:
+            niche = {name: members[0].params[name] for name in choices}
+            for _ in range(min(per_niche, count - len(children))):
+                children.append(self._child(members, generation, niche))
+        return children
+
+    def _next_population(self, previous: list[Individual] | None, generation: int) -> list[Individual]:
+        size = self.config.population_size
+        if previous is None:
+            initial = self._initial_individuals(generation)
+            population = initial + [self._random_individual(generation) for _ in range(size - len(initial))]
+            self._asked.update(_key(individual.params) for individual in population)
+            return population
+        parents = [individual for individual in previous if not individual.failed]
+        if not parents:
+            # Every evaluation of the previous generation failed: start afresh.
+            population = [self._random_individual(generation) for _ in range(size)]
+            self._asked.update(_key(individual.params) for individual in population)
+            return population
+
+        if self.config.noise:
+            # A point bred again since it was evaluated has more evaluations now; rank by their average.
+            self._refresh_averages(parents)
+        # At least one child per generation, however the share rounds, so the search keeps moving.
+        elites = self._ranked(parents)[: min(round(size * self.config.elitism_rate), size - 1)] if self.config.elitism else []
+        niched = self._niche_children(parents, int(self.config.niche_share * (size - len(elites))), generation)
+        population = elites + niched + [self._child(parents, generation) for _ in range(size - len(elites) - len(niched))]
+        if self._adaptive:
+            # Keep the sizes of individuals that can still breed: this generation, and any still being evaluated.
+            keep = set(population) | set(self._outstanding())
+            self._steps = {individual: step for individual, step in self._steps.items() if individual in keep}
+        return population

hone/optimizers/genetic/selection.py

@@ -0,0 +1,28 @@
+"""Ways to pick a parent from an evaluated population."""
+import numpy as np
+
+from hone.optimizers.base import Individual
+
+
+def tournament(
+    individuals: list[Individual], rng: np.random.Generator, *, size: int, p: float, maximize: bool
+) -> Individual:
+    """Draw size individuals, with replacement, and return the fittest with probability p, else the least fit."""
+    indices = rng.choice(len(individuals), size=size)
+    contenders = sorted((individuals[i] for i in indices), key=lambda x: x.fitness, reverse=maximize)
+    return contenders[0] if rng.uniform(0, 1) < p else contenders[-1]
+
+
+def roulette(individuals: list[Individual], rng: np.random.Generator, *, maximize: bool) -> Individual:
+    """Pick an individual with probability proportional to its fitness.
+
+    Fitnesses are shifted so the worst individual has weight zero, which makes the
+    selection work for negative fitnesses and for minimization alike.
+    """
+    fitnesses = np.array([individual.fitness for individual in individuals], dtype=float)
+    weights = fitnesses - fitnesses.min() if maximize else fitnesses.max() - fitnesses
+    total = weights.sum()
+    if total == 0:
+        # Every individual is equally fit.
+        return individuals[rng.integers(len(individuals))]
+    return individuals[rng.choice(len(individuals), p=weights / total)]

hone/optimizers/genetic/variation.py

@@ -0,0 +1,47 @@
+"""Ways to make a child's parameters from its parents'."""
+from typing import Any
+
+import numpy as np
+
+from hone.parameters import RangeParameter, SearchSpace
+
+
+def uniform_crossover(
+    first: dict[str, Any], second: dict[str, Any], rng: np.random.Generator, *, rate: float
+) -> dict[str, Any]:
+    """Build a child gene by gene, taking each from the first parent with probability rate."""
+    return {name: first[name] if rng.uniform(0, 1) < rate else second[name] for name in first}
+
+
+def blend_crossover(
+    first: dict[str, Any], second: dict[str, Any], search_space: SearchSpace, rng: np.random.Generator, *, rate: float, alpha: float
+) -> dict[str, Any]:
+    """Uniform crossover, then each range gene drawn between its parents' values (BLX-alpha).
+
+    A range value is drawn uniformly from the span between the parents' values, widened by alpha
+    times that span on each side, measured on the range's own scale and clipped to it. Parents
+    with the same value pass it on. Other genes come from one parent, as in uniform_crossover.
+    """
+    params = uniform_crossover(first, second, rng, rate=rate)
+    for parameter in search_space.parameters:
+        if isinstance(parameter, RangeParameter) and parameter.maximum > parameter.minimum:
+            a, b = float(parameter.to_unit(first[parameter.name])), float(parameter.to_unit(second[parameter.name]))
+            low, high = min(a, b), max(a, b)
+            if high > low:
+                value = parameter.from_unit(rng.uniform(low - alpha * (high - low), high + alpha * (high - low)))
+                params[parameter.name] = int(value) if parameter.integer else float(value)
+    return params
+
+
+def mutate(
+    params: dict[str, Any], search_space: SearchSpace, rng: np.random.Generator, *, rate: float, scale: float
+) -> dict[str, Any]:
+    """Mutate each gene with probability rate, returning new parameters.
+
+    How a gene changes depends on its parameter: ranges are nudged by scale times their width,
+    choices switch to another value, and fixed parameters never change.
+    """
+    return {
+        name: search_space[name].mutate(value, rng, scale) if rng.uniform(0, 1) < rate else value
+        for name, value in params.items()
+    }

hone/optimizers/random_search.py

@@ -0,0 +1,13 @@
+from hone.optimizers.base import Individual, Optimizer
+
+
+class RandomSearch(Optimizer):
+    """Evaluates population_size random points per generation and keeps the best.
+
+    Useful as a baseline: a smarter optimizer should beat it for the same number of evaluations.
+    Any initial points take the place of random points in the first generation.
+    """
+
+    def _next_population(self, previous: list[Individual] | None, generation: int) -> list[Individual]:
+        initial = self._initial_individuals(generation) if previous is None else []
+        return initial + [self._random_individual(generation) for _ in range(self.config.population_size - len(initial))]

hone/parameters/__init__.py

@@ -0,0 +1 @@
+from .parameters import ChoiceParameter, FixedParameter, Parameter, RangeParameter, SearchSpace

hone/parameters/parameters.py

@@ -0,0 +1,237 @@
+import math
+import numbers
+from collections.abc import Sequence
+from typing import Annotated, Any, Literal
+
+import numpy as np
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+type Value = float | int | str
+
+
+class _Parameter(BaseModel):
+    """A named dimension of the search space, and the values it may take."""
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    name: str
+
+    def __init__(self, **data: Any) -> None:
+        # Each kind takes its own fields positionally and passes them all here as keywords.
+        super().__init__(**data)
+
+
+class RangeParameter(_Parameter):
+    """A number between minimum and maximum, optionally restricted to integers.
+
+    With log=True the range is searched on a logarithmic scale: values are drawn evenly in
+    their logarithm, so 0.001 to 0.01 gets as much attention as 100 to 1000. Use it for
+    settings that span orders of magnitude, such as learning rates and regularization
+    strengths. A log range needs a positive minimum.
+    """
+    kind: Literal["range"] = "range"
+    minimum: float
+    maximum: float
+    integer: bool = False
+    log: bool = False
+
+    def __init__(self, name: str, minimum: float, maximum: float, **data: Any) -> None:
+        super().__init__(name=name, minimum=minimum, maximum=maximum, **data)
+
+    @model_validator(mode="after")
+    def _check_bounds(self):
+        if self.minimum > self.maximum:
+            raise ValueError(f"{self.name}: minimum {self.minimum} is greater than maximum {self.maximum}")
+        if self.integer and math.ceil(self.minimum) > math.floor(self.maximum):
+            raise ValueError(f"{self.name}: no integer lies between {self.minimum} and {self.maximum}")
+        if self.log and self.minimum <= 0:
+            raise ValueError(f"{self.name}: a log range needs a positive minimum, got {self.minimum}")
+        return self
+
+    def _scale(self, value):
+        return np.log(value) if self.log else value
+
+    def to_unit(self, value: Any) -> Any:
+        """Where value lies in the range, from 0 at the minimum to 1 at the maximum, on the range's scale.
+
+        Accepts a number or an array of them.
+        """
+        low, high = self._scale(self.minimum), self._scale(self.maximum)
+        if high == low:
+            return np.zeros_like(np.asarray(value, dtype=float)) if np.ndim(value) else 0.0
+        return (self._scale(np.asarray(value, dtype=float)) - low) / (high - low)
+
+    def from_unit(self, unit: Any) -> Any:
+        """The value at position unit in the range, clipped to it, and rounded for an integer range.
+
+        The inverse of to_unit. Accepts a number, returning an int or float, or an array.
+        """
+        low, high = self._scale(self.minimum), self._scale(self.maximum)
+        value = low + np.clip(unit, 0, 1) * (high - low)
+        if self.log:
+            value = np.exp(value)
+        if self.integer:
+            value = np.clip(np.round(value), math.ceil(self.minimum), math.floor(self.maximum))
+        else:
+            value = np.clip(value, self.minimum, self.maximum)
+        if np.ndim(value):
+            return value
+        return int(value) if self.integer else float(value)
+
+    def sample(self, rng: np.random.Generator) -> float | int:
+        if self.log:
+            return self.from_unit(rng.uniform())
+        if self.integer:
+            return int(rng.integers(math.ceil(self.minimum), math.floor(self.maximum), endpoint=True))
+        return float(rng.uniform(self.minimum, self.maximum))
+
+    def check(self, value: Any) -> float | int:
+        """value as this parameter holds it, or ValueError if it isn't one of its values."""
+        if isinstance(value, bool) or not isinstance(value, numbers.Real):
+            raise ValueError(f"{self.name}: {value!r} is not a number")
+        number = float(value)
+        if not self.minimum <= number <= self.maximum:
+            raise ValueError(f"{self.name}: {value} is outside [{self.minimum}, {self.maximum}]")
+        if self.integer:
+            if not number.is_integer():
+                raise ValueError(f"{self.name}: {value} is not an integer")
+            return int(number)
+        return number
+
+    def mutate(self, value: float | int, rng: np.random.Generator, scale: float) -> float | int:
+        """Nudge value by Gaussian noise with a standard deviation of scale times the range width.
+
+        The result is clipped to the bounds. Integer ranges use a step of at least 1, so a
+        mutation can always move the value. A log range is nudged in its logarithm, so the
+        step is a proportion of the value rather than a fixed amount.
+        """
+        if self.log:
+            mutated = self.from_unit(self.to_unit(value) + rng.normal(0, scale))
+            if self.integer and mutated == value:
+                neighbour = min(max(value + rng.choice([-1, 1]), math.ceil(self.minimum)), math.floor(self.maximum))
+                mutated = int(neighbour)
+            return mutated
+        sigma = scale * (self.maximum - self.minimum)
+        if self.integer:
+            step = round(rng.normal(0, max(sigma, 1)))
+            return int(np.clip(value + step, math.ceil(self.minimum), math.floor(self.maximum)))
+        return float(np.clip(value + rng.normal(0, sigma), self.minimum, self.maximum))
+
+
+class FixedParameter(_Parameter):
+    """A parameter held at a single value."""
+    kind: Literal["fixed"] = "fixed"
+    value: Value
+
+    def __init__(self, name: str, value: Value, **data: Any) -> None:
+        super().__init__(name=name, value=value, **data)
+
+    def sample(self, rng: np.random.Generator) -> Value:
+        return self.value
+
+    def check(self, value: Any) -> Value:
+        """value as this parameter holds it, or ValueError if it isn't one of its values."""
+        if value != self.value:
+            raise ValueError(f"{self.name}: {value!r} is not its fixed value {self.value!r}")
+        return self.value
+
+    def mutate(self, value: Value, rng: np.random.Generator, scale: float) -> Value:
+        return self.value
+
+
+class ChoiceParameter(_Parameter):
+    """One value picked from a list of choices, or a list of choose_n distinct choices."""
+    kind: Literal["choice"] = "choice"
+    choices: list[Value] = Field(min_length=1)
+    choose_n: int | None = Field(default=None, ge=1)
+
+    def __init__(self, name: str, choices: list[Value], **data: Any) -> None:
+        super().__init__(name=name, choices=choices, **data)
+
+    @model_validator(mode="after")
+    def _check_choose_n(self):
+        if self.choose_n is not None and self.choose_n > len(self.choices):
+            raise ValueError(f"{self.name}: choose_n {self.choose_n} exceeds the {len(self.choices)} choices")
+        return self
+
+    def sample(self, rng: np.random.Generator) -> Value | list[Value]:
+        if self.choose_n is None:
+            return self.choices[rng.integers(len(self.choices))]
+        indices = rng.choice(len(self.choices), size=self.choose_n, replace=False)
+        return [self.choices[i] for i in indices]
+
+    def check(self, value: Any) -> Value | list[Value]:
+        """value as this parameter holds it, or ValueError if it isn't one of its values."""
+        if self.choose_n is None:
+            if value not in self.choices:
+                raise ValueError(f"{self.name}: {value!r} is not one of {self.choices}")
+            return value
+        if not isinstance(value, (list, tuple)) or len(value) != self.choose_n:
+            raise ValueError(f"{self.name}: expected a list of {self.choose_n} choices, got {value!r}")
+        if any(v not in self.choices for v in value) or len(set(map(repr, value))) != len(value):
+            raise ValueError(f"{self.name}: {value!r} must be {self.choose_n} different values from {self.choices}")
+        return list(value)
+
+    def mutate(self, value: Value | list[Value], rng: np.random.Generator, scale: float) -> Value | list[Value]:
+        """Draw a new value. A single choice switches to a different one when there is one to switch to.
+
+        Choices have no order, so scale does not apply.
+        """
+        if self.choose_n is not None or len(self.choices) == 1:
+            return self.sample(rng)
+        others = [choice for choice in self.choices if choice != value]
+        return others[rng.integers(len(others))] if others else self.sample(rng)
+
+
+type Parameter = Annotated[RangeParameter | FixedParameter | ChoiceParameter, Field(discriminator="kind")]
+
+
+class SearchSpace(BaseModel):
+    """The set of parameters an objective function is optimized over."""
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    parameters: list[Parameter] = Field(min_length=1)
+
+    def __init__(self, parameters: Sequence[Parameter], **data: Any) -> None:
+        super().__init__(parameters=list(parameters), **data)
+
+    @model_validator(mode="after")
+    def _check_unique_names(self):
+        names = [parameter.name for parameter in self.parameters]
+        duplicates = sorted({name for name in names if names.count(name) > 1})
+        if duplicates:
+            raise ValueError(f"each parameter needs a unique name; repeated: {', '.join(duplicates)}")
+        return self
+
+    @property
+    def names(self) -> list[str]:
+        return [parameter.name for parameter in self.parameters]
+
+    def sample(self, rng: np.random.Generator) -> dict[str, Any]:
+        """Draw one value for every parameter."""
+        return {parameter.name: parameter.sample(rng) for parameter in self.parameters}
+
+    def check(self, params: dict[str, Any]) -> dict[str, Any]:
+        """params as a complete point of this space, in parameter order, or ValueError if they aren't one.
+
+        Fixed parameters may be left out; every other parameter needs a value.
+        """
+        unknown = sorted(set(params) - set(self.names))
+        if unknown:
+            raise ValueError(f"unknown parameters: {', '.join(unknown)}")
+        missing = [p.name for p in self.parameters if p.name not in params and not isinstance(p, FixedParameter)]
+        if missing:
+            raise ValueError(f"missing values for: {', '.join(missing)}")
+        checked = {}
+        for p in self.parameters:
+            if p.name in params:
+                checked[p.name] = p.check(params[p.name])
+            else:
+                assert isinstance(p, FixedParameter)  # every other kind was found missing above
+                checked[p.name] = p.value
+        return checked
+
+    def __getitem__(self, name: str) -> Parameter:
+        for parameter in self.parameters:
+            if parameter.name == name:
+                return parameter
+        raise KeyError(name)

hone/result.py

@@ -0,0 +1,118 @@
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Self
+
+from pydantic import BaseModel, ConfigDict
+
+from hone.parameters import SearchSpace
+
+if TYPE_CHECKING:
+    from hone.optimizers import Optimizer
+
+
+class GenerationStats(BaseModel):
+    """Summary of one generation's fitness, over its successful evaluations.
+
+    The fitness fields are None when every evaluation in the generation failed.
+    """
+    model_config = ConfigDict(frozen=True)
+
+    generation: int
+    evaluations: int  # evaluations up to the end of this generation, failed ones included
+    failures: int = 0  # failed evaluations in this generation
+    best_fitness: float | None = None
+    best_params: dict[str, Any] | None = None
+    worst_fitness: float | None = None
+    mean: float | None = None
+    median: float | None = None
+    std: float | None = None
+
+
+class RunInfo(BaseModel):
+    """How a result was produced: enough to repeat the run, and to tell runs apart later."""
+    model_config = ConfigDict(frozen=True)
+
+    optimizer: str  # the optimizer's class name, such as "CMAES"
+    config: dict[str, Any]  # the optimizer's full config, seed included
+    search_space: SearchSpace
+    initial_points: list[dict[str, Any]] = []
+    objective: str | None = None  # the objective function's name; None when run with ask() and tell()
+    workers: int | None = None  # optimize()'s workers, which CMA-ES and Bayesian optimization size their batches by
+    timeout: float | None = None  # optimize()'s time limit per evaluation, in seconds
+    hone_version: str
+    python_version: str
+    numpy_version: str
+    started_at: datetime | None = None  # when the first candidate was handed out, in UTC
+    elapsed: float | None = None  # seconds from then until the run finished, or until the result was taken
+
+
+class Progress(BaseModel):
+    """What optimize() passes its callback after each generation."""
+    model_config = ConfigDict(frozen=True)
+
+    generation: GenerationStats  # the generation just finished
+    evaluations: int  # evaluations made so far, failed ones included
+    best_fitness: float | None  # the best value so far; None while every evaluation has failed
+    best_params: dict[str, Any] | None
+    elapsed: float  # seconds since the run started
+
+
+def print_progress(progress: Progress) -> None:
+    """A ready-made optimize() callback: print one line per generation."""
+    best = "none yet" if progress.best_fitness is None else f"{progress.best_fitness:.6g}"
+    print(
+        f"generation {progress.generation.generation}: {progress.evaluations:,} evaluations, "
+        f"best {best}, {progress.elapsed:.1f} s",
+        flush=True,
+    )
+
+
+class Result(BaseModel):
+    """Outcome of an optimization run. Save it with save() and read it back with load().
+
+    Two results are equal when they found the same things; their run records are not compared,
+    since a repeated run differs in its timing.
+    """
+    model_config = ConfigDict(frozen=True)
+
+    best_fitness: float
+    best_params: dict[str, Any]
+    generations: list[GenerationStats]  # completed generations; empty partway through the first
+    evaluations: int  # evaluations made, failed ones included
+    failures: int = 0  # evaluations that failed
+    reached_threshold: bool  # whether the run stopped early because it reached config.threshold
+    stopped: bool = False  # whether the run was stopped before it finished, by its callback or Ctrl+C
+    run: RunInfo | None = None  # how the result was produced; None in results saved before hone 0.7.1
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Result):
+            return NotImplemented
+        return self.model_dump(exclude={"run"}) == other.model_dump(exclude={"run"})
+
+    def rebuild_optimizer(self, optimizer_class: "type[Optimizer] | None" = None) -> "Optimizer":
+        """A new optimizer set up exactly as this result's was, to repeat or extend the run.
+
+        Running it gives the same result, given the same objective and, for CMA-ES and
+        Bayesian optimization, the same number of workers (run.workers). An optimizer that
+        isn't one of hone's own is rebuilt by passing its class.
+        """
+        from hone import optimizers
+
+        if self.run is None:
+            raise ValueError("this result has no record of its run: it was saved by a version of hone before 0.7.1")
+        if optimizer_class is None:
+            builtin = {cls.__name__: cls for cls in (
+                optimizers.GeneticOptimizer, optimizers.CMAES, optimizers.BayesianOptimizer, optimizers.RandomSearch
+            )}
+            if self.run.optimizer not in builtin:
+                raise ValueError(f"{self.run.optimizer} isn't one of hone's optimizers; pass its class to rebuild it")
+            optimizer_class = builtin[self.run.optimizer]
+        config = optimizer_class.config_class.model_validate(self.run.config)
+        return optimizer_class(self.run.search_space, config, initial_points=self.run.initial_points or None)
+
+    def save(self, filepath: str | Path) -> None:
+        Path(filepath).write_text(self.model_dump_json(indent=2))
+
+    @classmethod
+    def load(cls, filepath: str | Path) -> Self:
+        return cls.model_validate_json(Path(filepath).read_text())